1.\"- 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2024-2025 The FreeBSD Foundation 5.\" 6.\" Portions of this software were developed by Christos Margiolis 7.\" <christos@FreeBSD.org> under sponsorship from the FreeBSD Foundation. 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 AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd May 5, 2025 31.Dt SNDCTL 8 32.Os 33.Sh NAME 34.Nm sndctl 35.Nd list and modify soundcard properties 36.Sh SYNOPSIS 37.Nm 38.Op Fl f Ar device 39.Op Fl hov 40.Op Ar control Ns Oo = Ns Ar value Oc Ar ... 41.Sh DESCRIPTION 42The 43.Nm 44utility is used to set and display sound card properties, using a 45control-driven interface, in order to filter and/or set specific properties. 46.Pp 47The options are as follows: 48.Bl -tag -width "-f device" 49.It Fl f Ar device 50Choose a specific audio device 51.Pq see Sx FILES . 52Userland devices (e.g those registered by 53.Xr virtual_oss 8 54can also be selected. 55.It Fl h 56Print a help message. 57.It Fl o 58Print values in a format suitable for use inside scripts. 59.It Fl v 60Run in verbose mode. 61This option will print all of the device's channel properties. 62.El 63.Pp 64The device controls are as follows: 65.Bl -column xxxxxxxxxxxxxxx xxxxx xxxxxxxx xxxxxxxxxxxxxxxxxxx -offset indent 66.It Sy Name Ta Sy Type Ta Sy Read/Write Ta Sy Action 67.It name Ta String Ta Read Ta Device name 68.It desc Ta String Ta Read Ta Device description 69.It status Ta String Ta Read Ta Device status 70.It devnode Ta String Ta Read Ta Device node 71.It from_user Ta Boolean Ta Read Ta Userland device 72.It unit Ta Number Ta Read Ta Device unit 73.It caps Ta String Ta Read Ta Device OSS capabitilies 74.It bitperfect Ta Boolean Ta Read/Write Ta Bit-perfect mode enabled 75.It autoconv Ta Boolean Ta Read/Write Ta Auto-conversions enabled 76.It realtime Ta Boolean Ta Read/Write Ta Real-time mode enabled 77.It play Ta Group Ta Read Ta Playback properties 78.It play.format Ta String Ta Read/Write Ta Playback format 79.It play.rate Ta Number Ta Read/Write Ta Playback sample rate 80.It play.vchans Ta Boolean Ta Read/Write Ta Playback VCHANs (virtual channels) enabled 81.It play.min_rate Ta Number Ta Read Ta Minimum playback sample rate 82.It play.max_rate Ta Number Ta Read Ta Maximum playback sample rate 83.It play.min_chans Ta Number Ta Read Ta Natively supported minimum playback sample channels 84.It play.max_chans Ta Number Ta Read Ta Natively supported maximum playback sample channels 85.It play.formats Ta String Ta Read Ta Natively supported playback formats 86.It rec Ta Group Ta Read Ta Recording properties 87.It rec.format Ta String Ta Read/Write Ta Recording format 88.It rec.rate Ta Number Ta Read/Write Ta Recording sample rate 89.It rec.vchans Ta Boolean Ta Read/Write Ta Recording VCHANs (virtual channels) enabled 90.It rec.min_rate Ta Number Ta Read Ta Minimum recording sample rate 91.It rec.max_rate Ta Number Ta Read Ta Maximum recording sample rate 92.It rec.min_chans Ta Number Ta Read Ta Natively supported minimum recording sample channels 93.It rec.max_chans Ta Number Ta Read Ta Natively supported maximum recording sample channels 94.It rec.formats Ta String Ta Read Ta Natively supported recording formats 95.El 96.Pp 97The 98.Pa play.format , 99.Pa play.rate , 100.Pa rec.format and 101.Pa rec.rate 102controls will be read-only if VCHANs are disabled. 103.Pp 104The device channel controls are as follows: 105.Bl -column xxxxxxxxxxxxxxx xxxxx xxxxxxxx xxxxxxxxxxxxxxxxxxx -offset indent 106.It Sy Name Ta Sy Type Ta Sy Read/Write Ta Sy Action 107.It name Ta String Ta Read Ta Channel name 108.It parentchan Ta String Ta Read Ta Parent (primary) channel name 109.It unit Ta Number Ta Read Ta Channel unit 110.It caps Ta String Ta Read Ta Channel OSS capabilities 111.It latency Ta Number Ta Read Ta Channel latency 112.It format Ta String Ta Read Ta Channel format 113.It rate Ta Number Ta Read Ta Channel sample rate 114.It pid Ta Number Ta Read Ta PID of process consuming channel 115.It proc Ta String Ta Read Ta Name of process consuming channel 116.It interrupts Ta Number Ta Read Ta Number of interrupts since channel was opened 117.It xruns Ta Number Ta Read Ta Number of playback underruns/recoring overruns 118.It feedcount Ta Number Ta Read Ta Number of bytes fed to channel 119.It volume Ta Volume Ta Read Ta Channel left-right volume in normalized form (0.00 to 1.00). 120.It hwbuf Ta Group Ta Read Ta Hardware buffer properties 121.It hwbuf.format Ta String Ta Read Ta Hardware buffer format 122.It hwbuf.rate Ta String Ta Read Ta Hardware buffer sample rate 123.It hwbuf.size_bytes Ta Number Ta Read Ta Hardware buffer size in bytes 124.It hwbuf.size_frames Ta Number Ta Read Ta Hardware buffer size in frames 125.It hwbuf.blksz Ta Number Ta Read Ta Hardware buffer block size 126.It hwbuf.blkcnt Ta Number Ta Read Ta Hardware buffer block count 127.It hwbuf.free Ta Number Ta Read Ta Hardware buffer free space in bytes 128.It hwbuf.ready Ta Number Ta Read Ta Hardware buffer ready space in bytes 129.It swbuf Ta Group Ta Read Ta Software buffer properties 130.It swbuf.format Ta String Ta Read Ta Software buffer format 131.It swbuf.rate Ta String Ta Read Ta Software buffer sample rate 132.It swbuf.size_bytes Ta Number Ta Read Ta Software buffer size in bytes 133.It swbuf.size_frames Ta Number Ta Read Ta Software buffer size in frames 134.It swbuf.blksz Ta Number Ta Read Ta Software buffer block size 135.It swbuf.blkcnt Ta Number Ta Read Ta Software buffer block count 136.It swbuf.free Ta Number Ta Read Ta Software buffer free space in bytes 137.It swbuf.ready Ta Number Ta Read Ta Software buffer ready space in bytes 138.It feederchain Ta String Ta Read Ta Channel feeder chain 139.El 140.Sh FILES 141.Bl -tag -width /dev/dspX -compact 142.It Pa /dev/dsp 143The default audio device. 144.It Pa /dev/dspX 145The audio device file, where X is the unit of the device, for example 146.Ar /dev/dsp0 . 147.El 148.Sh EXAMPLES 149Disable auto-conversions and enable realtime mode to get as low latencies as 150possible: 151.Bd -literal -offset indent 152$ sndctl autoconv=0 realtime=1 153.Ed 154.Pp 155Set the playback sample format to 2-channel signed 24-bit low endian, and sample 156rate to 48000 Hz: 157.Bd -literal -offset indent 158$ sndctl play.format=s24le:2.0 play.rate=48000 159.Ed 160.Pp 161List the PIDs and process names of all channels for 162.Pa /dev/dsp1 : 163.Bd -literal -offset indent 164$ sndctl -f /dev/dsp1 pid proc 165.Ed 166.Pp 167Dump 168.Pa /dev/dsp0 169information to a file and retrieve back later: 170.Bd -literal -offset indent 171$ sndctl -f /dev/dsp0 -o > info 172\&... 173$ sndctl -f /dev/dsp0 `cat info` 174.Ed 175.Sh SEE ALSO 176.Xr sndstat 4 , 177.Xr sound 4 , 178.Xr mixer 8 , 179.Xr sysctl 8 180.Sh AUTHORS 181The 182.Nm 183utility was implemented by 184.An Christos Margiolis Aq Mt christos@FreeBSD.org 185under sponsorship from the 186.Fx 187Foundation. 188