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