1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" $NetBSD: uaudio.4,v 1.15 2002/02/12 19:53:57 jdolecek Exp $ 5.\" 6.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 7.\" All rights reserved. 8.\" 9.\" This code is derived from software contributed to The NetBSD Foundation 10.\" by Lennart Augustsson. 11.\" 12.\" Redistribution and use in source and binary forms, with or without 13.\" modification, are permitted provided that the following conditions 14.\" are met: 15.\" 1. Redistributions of source code must retain the above copyright 16.\" notice, this list of conditions and the following disclaimer. 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in the 19.\" documentation and/or other materials provided with the distribution. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 23.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 24.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 25.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 26.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 29.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31.\" POSSIBILITY OF SUCH DAMAGE. 32.\" 33.Dd July 17, 2025 34.Dt SND_UAUDIO 4 35.Os 36.Sh NAME 37.Nm snd_uaudio 38.Nd USB audio and MIDI device driver 39.Sh SYNOPSIS 40.Cd "device sound" 41.Cd "device usb" 42.Cd "device snd_uaudio" 43.Pp 44In 45.Xr rc.conf 5 : 46.Cd kld_list="snd_uaudio" 47.Pp 48In 49.Xr sysctl.conf 5 : 50.Cd hw.usb.uaudio.buffer_ms 51.Cd hw.usb.uaudio.default_bits 52.Cd hw.usb.uaudio.default_channels 53.Cd hw.usb.uaudio.default_rate 54.Cd hw.usb.uaudio.handle_hid 55.Cd hw.usb.uaudio.debug 56.Sh DESCRIPTION 57A USB audio device consists of a number of components: input terminals (e.g.\& 58USB digital input), output terminals (e.g.\& speakers), and a number of units 59in between (e.g.\& volume control). 60.Pp 61If the device supports multiple configurations, and there have been no 62user-supplied values specified through the 63.Xr sysctl 8 64interface, the driver will select the best matching configuration supported by 65the device during attach. 66"Best" means the configuration with the most channels and highest quality in 67sample rate and sample size. 68.Pp 69Refer to the 70.Ql USB Audio Class Specification 71for more information. 72.Sh HARDWARE 73The 74.Nm 75driver provides support for USB audio class devices and 76USB MIDI class devices. 77.Sh SYSCTL VARIABLES 78The following settings can be entered at the 79.Xr loader 8 80prompt or in 81.Xr loader.conf 5 82and can also be changed at runtime with the 83.Xr sysctl 8 84command. 85For a change to take effect during runtime, the device has to be re-attached. 86.Bl -tag -width indent 87.It Va hw.usb.uaudio.buffer_ms 88Period of audio data processed at once, in milliseconds, from 1 to 8 (default 89is 4). 90Lower values mean less latency, but this can result in audible gaps due to 91frequent CPU wakeups. 92.It Va hw.usb.uaudio.default_bits 93Preferred sample size in bits, from 0 to 32 (default is 0). 94A value of 0 sets the sample size to the maximum supported sample size. 95.Pp 96Set this to select a smaller sample size if the device supports multiple sample 97sizes. 98.It Va hw.usb.uaudio.default_channels 99Preferred number of sample channels, from 0 to 64 (default is 0). 100USB 1.1 devices are limited to 4 channels due to bandwidth constraints, unless 101a higher value is explicitly requested. 102A value of 0 sets the sample channels to the maximum supported channel number. 103.Pp 104Set this to select a smaller channel number if the device supports multiple 105channel configurations. 106.It Va hw.usb.uaudio.default_rate 107Preferred sample rate in Hz (default is 0). 108If set to 0, the device's highest supported sample rate will be used. 109.Pp 110Note that if VCHANs are enabled, the sample rate will be overridden by 111.Pa dev.pcm.%d.[play|rec].vchanrate 112(see 113.Xr sound 4 ) , 114which can also be used to adjust the sample rate during runtime. 115.Pp 116If 117.Pa hw.usb.uaudio.default_rate 118is non-zero, 119.Pa dev.pcm.%d.[play|rec].vchanrate 120will use it as its maximum allowed value. 121.It Va hw.usb.uaudio.handle_hid 122Let 123.Nm 124handle HID volume keys, if any (default is 1). 125.Bl -tag -width 2n 126.It 0 127Disabled. 128.It 1 129Enabled. 130.El 131.El 132.Pp 133If 134.Xr usb 4 135has been compiled with 136.Va USB_DEBUG 137on, the following setting is also available: 138.Bl -tag -width indent 139.It Va hw.usb.uaudio.debug 140Debug output level (default is 0). 141.El 142.Sh SEE ALSO 143.Xr sound 4 , 144.Xr usb 4 , 145.Xr loader.conf 5 , 146.Xr loader 8 , 147.Xr sysctl 8 148.Rs 149.%T "USB Audio Class Specifications" 150.%U http://www.usb.org/developers/docs/devclass_docs/ 151.Re 152.Sh HISTORY 153The 154.Nm 155driver first appeared in 156.Fx 4.7 . 157.Sh AUTHORS 158This manual page was adopted from 159.Nx 1.6 160and modified for 161.Fx 162by 163.An Hiten Pandya Aq Mt hmp@FreeBSD.org . 164.Sh BUGS 165The PCM framework in 166.Fx 167currently does not support the full set of USB audio mixer controls. 168Some mixer controls are only available as 169.Va dev.pcm.%d.mixer 170sysctls. 171