SNDCTL(8)

NAME
sndctl - list and modify soundcard properties

SYNOPSIS
sndctl [--libxo] [-f device] [-hov] [control[=value] ...]

DESCRIPTION
The sndctl utility is used to set and display sound card properties, using a control-driven interface, in order to filter and/or set specific properties.

The options are as follows:

--libxo
    Generate output via libxo(3) in a selection of different human and machine readable formats. See xo_options(7) for details on command line arguments.

-f device
    Choose a specific audio device (see FILES). Userland devices (e.g those registered by virtual_oss(8) can also be selected.

-h  Print a help message.

-o  Print values in a format suitable for use inside scripts.

-v  Run in verbose mode. This option will print all of the device's channel properties.

The device controls are as follows:
Name | Type | Read/Write | Action
name | String | Read | Device name
desc | String | Read | Device description
status | String | Read | Device status
devnode | String | Read | Device node
from_user | Boolean | Read | Userland device
unit | Number | Read | Device unit
caps | String | Read | Device OSS capabitilies
bitperfect | Boolean | Read/Write | Bit-perfect mode enabled
autoconv | Boolean | Read/Write | Auto-conversions enabled
realtime | Boolean | Read/Write | Real-time mode enabled
play | Group | Read | Playback properties
play.format | String | Read/Write | Playback format
play.rate | Number | Read/Write | Playback sample rate
play.vchans | Boolean | Read/Write | Playback VCHANs (virtual channels) enabled
play.min_rate | Number | Read | Minimum playback sample rate
play.max_rate | Number | Read | Maximum playback sample rate
play.min_chans | Number | Read | Natively supported minimum playback sample channels
play.max_chans | Number | Read | Natively supported maximum playback sample channels
play.formats | String | Read | Natively supported playback formats
rec | Group | Read | Recording properties
rec.format | String | Read/Write | Recording format
rec.rate | Number | Read/Write | Recording sample rate
rec.vchans | Boolean | Read/Write | Recording VCHANs (virtual channels) enabled
rec.min_rate | Number | Read | Minimum recording sample rate
rec.max_rate | Number | Read | Maximum recording sample rate
rec.min_chans | Number | Read | Natively supported minimum recording sample channels
rec.max_chans | Number | Read | Natively supported maximum recording sample channels
rec.formats | String | Read | Natively supported recording formats

The play.format, play.rate, rec.format and rec.rate controls will be read-only if VCHANs are disabled.

The device channel controls are as follows:
Name | Type | Read/Write | Action
name | String | Read | Channel name
parentchan | String | Read | Parent (primary) channel name
unit | Number | Read | Channel unit
caps | String | Read | Channel OSS capabilities
latency | Number | Read | Channel latency
format | String | Read | Channel format
rate | Number | Read | Channel sample rate
pid | Number | Read | PID of process consuming channel
proc | String | Read | Name of process consuming channel
interrupts | Number | Read | Number of interrupts since channel was opened
xruns | Number | Read | Number of playback underruns/recoring overruns
feedcount | Number | Read | Number of bytes fed to channel
volume | Volume | Read | Channel left-right volume in normalized form (0.00 to 1.00).
hwbuf | Group | Read | Hardware buffer properties
hwbuf.format | String | Read | Hardware buffer format
hwbuf.rate | String | Read | Hardware buffer sample rate
hwbuf.size_bytes | Number | Read | Hardware buffer size in bytes
hwbuf.size_frames | Number | Read | Hardware buffer size in frames
hwbuf.blksz | Number | Read | Hardware buffer block size
hwbuf.blkcnt | Number | Read | Hardware buffer block count
hwbuf.free | Number | Read | Hardware buffer free space in bytes
hwbuf.ready | Number | Read | Hardware buffer ready space in bytes
swbuf | Group | Read | Software buffer properties
swbuf.format | String | Read | Software buffer format
swbuf.rate | String | Read | Software buffer sample rate
swbuf.size_bytes | Number | Read | Software buffer size in bytes
swbuf.size_frames | Number | Read | Software buffer size in frames
swbuf.blksz | Number | Read | Software buffer block size
swbuf.blkcnt | Number | Read | Software buffer block count
swbuf.free | Number | Read | Software buffer free space in bytes
swbuf.ready | Number | Read | Software buffer ready space in bytes
feederchain | String | Read | Channel feeder chain

FILES
/dev/dsp
    The default audio device.
/dev/dspX
    The audio device file, where X is the unit of the device, for example /dev/dsp0.

EXAMPLES
Disable auto-conversions and enable realtime mode to get as low latencies as possible:

    $ sndctl autoconv=0 realtime=1

Set the playback sample format to 2-channel signed 24-bit low endian, and sample rate to 48000 Hz:

    $ sndctl play.format=s24le:2.0 play.rate=48000

List the PIDs and process names of all channels for /dev/dsp1:

    $ sndctl -f /dev/dsp1 pid proc

Dump /dev/dsp0 information to a file and retrieve back later:

    $ sndctl -f /dev/dsp0 -o > info
    ...
    $ sndctl -f /dev/dsp0 `cat info`

SEE ALSO
sndstat(4), sound(4), xo_options(7), mixer(8), sysctl(8)

AUTHORS
The sndctl utility was implemented by Christos Margiolis <christos@FreeBSD.org> under sponsorship from the FreeBSD Foundation.