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`

AUTHORS

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