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 December 2, 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 -libxo 39.Op Fl f Ar device 40.Op Fl hov 41.Op Ar control Ns Oo = Ns Ar value Oc Ar ... 42.Sh DESCRIPTION 43The 44.Nm 45utility is used to set and display sound card properties, using a 46control-driven interface, in order to filter and/or set specific properties. 47.Pp 48The options are as follows: 49.Bl -tag -width "-f device" 50.It Fl -libxo 51Generate output via 52.Xr libxo 3 53in a selection of different human and machine readable formats. 54See 55.Xr xo_options 7 56for details on command line arguments. 57.It Fl f Ar device 58Choose a specific audio device 59.Pq see Sx FILES . 60Userland devices (e.g those registered by 61.Xr virtual_oss 8 62can also be selected. 63.It Fl h 64Print a help message. 65.It Fl o 66Print values in a format suitable for use inside scripts. 67.It Fl v 68Run in verbose mode. 69This option will print all of the device's channel properties. 70.El 71.Pp 72The device controls are as follows: 73.Bl -column xxxxxxxxxxxxxxx xxxxx xxxxxxxx xxxxxxxxxxxxxxxxxxx -offset indent 74.It Sy Name Ta Sy Type Ta Sy Read/Write Ta Sy Action 75.It name Ta String Ta Read Ta Device name 76.It desc Ta String Ta Read Ta Device description 77.It status Ta String Ta Read Ta Device status 78.It devnode Ta String Ta Read Ta Device node 79.It from_user Ta Boolean Ta Read Ta Userland device 80.It unit Ta Number Ta Read Ta Device unit 81.It caps Ta String Ta Read Ta Device OSS capabitilies 82.It bitperfect Ta Boolean Ta Read/Write Ta Bit-perfect mode enabled 83.It autoconv Ta Boolean Ta Read/Write Ta Auto-conversions enabled 84.It realtime Ta Boolean Ta Read/Write Ta Real-time mode enabled 85.It play Ta Group Ta Read Ta Playback properties 86.It play.format Ta String Ta Read/Write Ta Playback format 87.It play.rate Ta Number Ta Read/Write Ta Playback sample rate 88.It play.vchans Ta Boolean Ta Read/Write Ta Playback VCHANs (virtual channels) enabled 89.It play.min_rate Ta Number Ta Read Ta Minimum playback sample rate 90.It play.max_rate Ta Number Ta Read Ta Maximum playback sample rate 91.It play.min_chans Ta Number Ta Read Ta Natively supported minimum playback sample channels 92.It play.max_chans Ta Number Ta Read Ta Natively supported maximum playback sample channels 93.It play.formats Ta String Ta Read Ta Natively supported playback formats 94.It rec Ta Group Ta Read Ta Recording properties 95.It rec.format Ta String Ta Read/Write Ta Recording format 96.It rec.rate Ta Number Ta Read/Write Ta Recording sample rate 97.It rec.vchans Ta Boolean Ta Read/Write Ta Recording VCHANs (virtual channels) enabled 98.It rec.min_rate Ta Number Ta Read Ta Minimum recording sample rate 99.It rec.max_rate Ta Number Ta Read Ta Maximum recording sample rate 100.It rec.min_chans Ta Number Ta Read Ta Natively supported minimum recording sample channels 101.It rec.max_chans Ta Number Ta Read Ta Natively supported maximum recording sample channels 102.It rec.formats Ta String Ta Read Ta Natively supported recording formats 103.El 104.Pp 105The 106.Pa play.format , 107.Pa play.rate , 108.Pa rec.format and 109.Pa rec.rate 110controls will be read-only if VCHANs are disabled. 111.Pp 112The device channel controls are as follows: 113.Bl -column xxxxxxxxxxxxxxx xxxxx xxxxxxxx xxxxxxxxxxxxxxxxxxx -offset indent 114.It Sy Name Ta Sy Type Ta Sy Read/Write Ta Sy Action 115.It name Ta String Ta Read Ta Channel name 116.It parentchan Ta String Ta Read Ta Parent (primary) channel name 117.It unit Ta Number Ta Read Ta Channel unit 118.It caps Ta String Ta Read Ta Channel OSS capabilities 119.It latency Ta Number Ta Read Ta Channel latency 120.It format Ta String Ta Read Ta Channel format 121.It rate Ta Number Ta Read Ta Channel sample rate 122.It pid Ta Number Ta Read Ta PID of process consuming channel 123.It proc Ta String Ta Read Ta Name of process consuming channel 124.It interrupts Ta Number Ta Read Ta Number of interrupts since channel was opened 125.It xruns Ta Number Ta Read Ta Number of playback underruns/recoring overruns 126.It feedcount Ta Number Ta Read Ta Number of bytes fed to channel 127.It volume Ta Volume Ta Read Ta Channel left-right volume in normalized form (0.00 to 1.00). 128.It hwbuf Ta Group Ta Read Ta Hardware buffer properties 129.It hwbuf.format Ta String Ta Read Ta Hardware buffer format 130.It hwbuf.rate Ta String Ta Read Ta Hardware buffer sample rate 131.It hwbuf.size_bytes Ta Number Ta Read Ta Hardware buffer size in bytes 132.It hwbuf.size_frames Ta Number Ta Read Ta Hardware buffer size in frames 133.It hwbuf.blksz Ta Number Ta Read Ta Hardware buffer block size 134.It hwbuf.blkcnt Ta Number Ta Read Ta Hardware buffer block count 135.It hwbuf.free Ta Number Ta Read Ta Hardware buffer free space in bytes 136.It hwbuf.ready Ta Number Ta Read Ta Hardware buffer ready space in bytes 137.It swbuf Ta Group Ta Read Ta Software buffer properties 138.It swbuf.format Ta String Ta Read Ta Software buffer format 139.It swbuf.rate Ta String Ta Read Ta Software buffer sample rate 140.It swbuf.size_bytes Ta Number Ta Read Ta Software buffer size in bytes 141.It swbuf.size_frames Ta Number Ta Read Ta Software buffer size in frames 142.It swbuf.blksz Ta Number Ta Read Ta Software buffer block size 143.It swbuf.blkcnt Ta Number Ta Read Ta Software buffer block count 144.It swbuf.free Ta Number Ta Read Ta Software buffer free space in bytes 145.It swbuf.ready Ta Number Ta Read Ta Software buffer ready space in bytes 146.It feederchain Ta String Ta Read Ta Channel feeder chain 147.El 148.Sh FILES 149.Bl -tag -width /dev/dspX -compact 150.It Pa /dev/dsp 151The default audio device. 152.It Pa /dev/dspX 153The audio device file, where X is the unit of the device, for example 154.Ar /dev/dsp0 . 155.El 156.Sh EXAMPLES 157Disable auto-conversions and enable realtime mode to get as low latencies as 158possible: 159.Bd -literal -offset indent 160$ sndctl autoconv=0 realtime=1 161.Ed 162.Pp 163Set the playback sample format to 2-channel signed 24-bit low endian, and sample 164rate to 48000 Hz: 165.Bd -literal -offset indent 166$ sndctl play.format=s24le:2.0 play.rate=48000 167.Ed 168.Pp 169List the PIDs and process names of all channels for 170.Pa /dev/dsp1 : 171.Bd -literal -offset indent 172$ sndctl -f /dev/dsp1 pid proc 173.Ed 174.Pp 175Dump 176.Pa /dev/dsp0 177information to a file and retrieve back later: 178.Bd -literal -offset indent 179$ sndctl -f /dev/dsp0 -o > info 180\&... 181$ sndctl -f /dev/dsp0 `cat info` 182.Ed 183.Sh SEE ALSO 184.Xr sndstat 4 , 185.Xr sound 4 , 186.Xr xo_options 7 , 187.Xr mixer 8 , 188.Xr sysctl 8 189.Sh AUTHORS 190The 191.Nm 192utility was implemented by 193.An Christos Margiolis Aq Mt christos@FreeBSD.org 194under sponsorship from the 195.Fx 196Foundation. 197