VIRTUAL_OSS(8) FreeBSD System Manager's Manual VIRTUAL_OSS(8)
NAME
virtual_oss - daemon to multiplex and demultiplex an OSS device
SYNOPSIS
virtual_oss [-h]
DESCRIPTION
virtual_oss is an audio mixing application that multiplexes and
demultiplexes a single OSS device into multiple customizable OSS
compatible devices using character devices from userspace. These devices
can be used to record played back audio and mix the individual channels
in multiple ways.
virtual_oss requires the cuse(3) kernel module. To load the driver as a
module at boot time, place the following line in loader.conf(5):
cuse_load="YES"
All channel numbers start at zero. Left channel is zero and right
channel is one.
The following options are available:
-B Run program in background.
-S Enable automatic DSP rate resampling.
-Q quality
Set resampling quality: 0=best, 1=medium and 2=fastest (default).
-b bits
Set sample depth to bits for the subsequent commands. Valid
values are 8, 16, 24 and 32.
-r rate
Set default sample-rate for the subsequent commands.
-s value
Set default buffer size to value. If the argument is suffixed by
"ms" it is interpreted as milliseconds. Else the argument gives
number of samples. The buffer size specified is per channel. If
there are multiple channels, the total buffer size will be
larger.
-i priority
Set real-time priority to priority. Refer to rtprio(1) for more
information.
-a log2_amp
Set the default DSP output and input device amplification to
log2_amp. The specified amplification is logarithmic. Valid
values range from -63 to 63 inclusivly. The device input
amplification gets set to minus log2_amp and the device output
amplification gets set to log2_amp.
-a i,log2_amp
Set the default DSP input device amplification to log2_amp. The
specified amplification is logarithmic. Valid values range from
-63 to 63 inclusivly.
-a o,log2_amp
Set default DSP output device amplification to log2_amp. The
specified amplification is logarithmic. Valid values range from
-63 to 63 inclusivly.
-p polarity
Set default polarity of DSP device. A value of zero means normal
polarity. A value of one means negative polarity.
-e rx_mute,tx_mute
Set default mute state of DSP device. A value of zero means
unmuted. A value of one means muted.
-m rx_ch,tx_ch,....
Set default channel mapping of DSP device, as a comma separated
list of integers. The first integer selects the receive channel,
the second value selects the transmit channel and then it
repeats. A value of zero indicates the first receive or transmit
channel.
-C num Set the maximum number of mix channels to num.
-c num Set mix channels for the subsequent commands.
-M type,src_ch,dst_ch,pol,mute,log2_gain
Add a monitoring filter. The filter consists of a list of comma
separated arguments. The first argument indicates the type of
monitoring filter:
i Feedback one mix input channel into another mix output
channel, for remote feedback.
o Add one mix output channel into another mix output
channel, for creating a mix of multiple output channels.
x Feedback one mix output channel into another mix input
channel, for local feedback.
The second argument gives the source mix channel. The third
argument gives the destination mix channel. The fourth argument
gives the polarity, default is zero. The fifth argument gives
the mute state, default is one or muted. The sixth argument
gives the amplitude, default is zero or no gain.
-t devname
Set control device name.
-P devname
Set playback DSP device only. Specifying /dev/null is magic and
means no playback device. Specifying a sndio(7) device
descriptor prefixed by /dev/sndio/ is also magic, and will use a
sndio backend rather than an OSS device. Specifying path
prefixed by /dev/bluetooth/ is also magic, and will use Bluetooth
audio backend rather than an OSS device. Suffix after
/dev/bluetooth/ is Bluetooth device address or alias as
configured in bluetooth.hosts(5).
-O devname
Set playback DSP device only which acts as a master device. This
option is used in conjunction with -R /dev/null.
-R devname
Set recording DSP device only. Specifying /dev/null is magic and
means no recording device. Specifying path prefixed by
/dev/bluetooth/ is also magic, and will use Bluetooth audio
backend rather than an OSS device. Suffix after /dev/bluetooth/
is Bluetooth device address or alias as configured in
bluetooth.hosts(5).
-f devname
Set both playback and recording DSP device. Specifying path
prefixed by /dev/bluetooth/ is magic, and will use Bluetooth
audio backend rather than an OSS device. Suffix after
/dev/bluetooth/ is Bluetooth device address or alias as
configured in bluetooth.hosts(5).
-w name
Create a WAV file format compatible companion device by given
name. This option should be specified before the -d and -l
options.
-d name
Create an OSS device by given name.
-l name
Create a loopback OSS device by given name. Users have to be
part of the audio group to access this device. This is a
security measure to avoid unintended snooping by unprivileged
users.
-L name
Create a loopback OSS device which acts as a master device. This
option is used in conjunction with -f /dev/null.
-F size
Set receive filter size in number of samples or <milliseconds>ms
for the next device to be created.
-G size
Set transmit filter size in number of samples or <milliseconds>ms
for the next device to be created.
-D file
Write process ID of virtual_oss to file.
-g knee,attack,decay
Enable device compressor in receive direction. See description
of -x option.
-x knee,attack,decay
Enable output compressor and set knee, attack and decay. Knee is
in the range 0..255, while attack and decay are between 0 and 62.
Samples having an absolute value lower than the knee are
transmitted unchanged. Sample values over the knee are lowered
"a little bit". You can think about attack and decay as a
measure of how fast or slow the gain of the compressor will work.
It is advised that attack is low, so it reacts fast once too high
sample values appear. It is also advised that the decay value is
higher than the attack value so that the gain reduction is
gradually removed. The reasoning behind this is that the
compressor should react almost immediately when high volume
signals arrive to protect the hardware, but it slowly changes
gain when there are no loud signals to avoid distorting the
signal. The default values are 85,3,20 .
-E enable_recording
If the value passed is non-zero, recording is enabled. Else
recording is disabled. This can be used to synchronize multiple
recording streams.
-h Show usage and all available options.
EXAMPLES
Split a 2-channel OSS compatible sound device into multiple subdevices:
virtual_oss \
-S \
-c 2 -r 48000 -b 16 -s 4ms -f /dev/dspX \
-a 0 -b 16 -c 2 -m 0,0,1,1 -d vdsp.zyn \
-a 0 -b 16 -c 2 -m 0,0,1,1 -d vdsp.fld \
-a 0 -b 16 -c 2 -m 0,0,1,1 -d dsp \
-a 0 -b 16 -c 2 -m 0,0,1,1 -w vdsp.jack.wav -d vdsp.jack \
-a 0 -b 16 -c 2 -m 0,0,1,1 -w vdsp.rec.wav -l vdsp.rec \
-M i,0,0,0,1,0 \
-M i,0,0,0,1,0 \
-M i,0,0,0,1,0 \
-M i,0,0,0,1,0 \
-t vdsp.ctl
Split an 8-channel 24-bit OSS compatible sound device into multiple
subdevices:
sysctl dev.pcm.X.rec.vchanformat=s24le:7.1
sysctl dev.pcm.X.rec.vchanrate=48000
sysctl dev.pcm.X.play.vchanformat=s24le:7.1
sysctl dev.pcm.X.play.vchanrate=48000
sysctl dev.pcm.X.bitperfect=1
mixer vol.volume=1 pcm.volume=1
virtual_oss \
-S \
-i 8 \
-x 85,3,20 \
-C 16 -c 8 -r 48000 -b 32 -s 4ms -f /dev/dspX \
-a 12 -b 16 -c 2 -m 0,4,1,5 -d dsp \
-a 12 -b 16 -c 2 -m 8,8,9,9 -d vdsp \
-a 13 -b 16 -c 2 -m 10,10,11,11 -d vdsp.fld \
-a 0 -b 32 -c 4 -m 4,2,5,3,6,4,7,5 -d vdsp.jack \
-a -3 -b 32 -c 2 -m 14,14,15,15 -d vdsp.zyn \
-e 0,1 \
-a 0 -b 32 -c 8 -m 0,8,1,9,2,8,3,9,4,8,5,9,6,8,7,9 -w vdsp.rec.mic.wav -d vdsp.rec.mic \
-a 0 -b 32 -c 2 -m 0,8,1,9 -w vdsp.rec.master.wav -d vdsp.master.mic \
-a 0 -b 32 -c 2 -m 10,10,11,11 -w vdsp.rec.fld.wav -l vdsp.rec.fld \
-a 0 -b 32 -c 2 -m 12,12,13,13 -w vdsp.rec.jack.wav -l vdsp.rec.jack \
-a 0 -b 32 -c 2 -m 14,14,15,15 -w vdsp.rec.zyn.wav -l vdsp.rec.zyn \
-M o,8,0,0,0,0 \
-M o,9,1,0,0,0 \
-M o,10,0,0,0,0 \
-M o,11,1,0,0,0 \
-M o,12,0,0,0,0 \
-M o,13,1,0,0,0 \
-M o,14,0,0,0,0 \
-M o,15,1,0,0,0 \
-M i,14,14,0,1,0 \
-M i,15,15,0,1,0 \
-M x,8,0,0,1,0 \
-M x,8,1,0,1,0 \
-t vdsp.ctl
Create a secondary audio device sending its output audio into both input
and output channels of the main DSP device.
virtual_oss \
-C 4 -c 2 \
-r 48000 \
-b 24 \
-s 4ms \
-f /dev/dsp3 \
-c 2 \
-d dsp \
-m 2,2,3,3 \
-d dsp.speech \
-M o,2,0,0,0,0 \
-M o,3,1,0,0,0 \
-M x,2,0,0,0,0 \
-M x,3,1,0,0,0
Connect to a bluetooth audio headset, playback only:
virtual_oss \
-C 2 -c 2 -r 48000 -b 16 -s 4ms \
-R /dev/null -P /dev/bluetooth/xx:xx:xx:xx:xx:xx -d dsp
Connect to a bluetooth audio headset, playback and recording:
virtual_oss \
-C 2 -c 2 -r 48000 -b 16 -s 4ms \
-f /dev/bluetooth/xx:xx:xx:xx:xx:xx -d dsp
Create recording device which outputs a WAV-formatted file:
virtual_oss \
-C 2 -c 2 -r 48000 -b 16 -s 4ms \
-f /dev/dspX -w dsp.wav -d dsp
Create a device named dsp.virtual which mix the samples written by all
clients and outputs the result for further processing into
dsp.virtual_out:
virtual_oss \
-S -Q 0 -b 16 -c 2 -r 96000 -s 100ms -i 20 \
-f /dev/null -d dsp.virtual -L dsp.virtual_out
Create a playback-only audio device which sends its output to a remote
sndio(7) server:
virtual_oss \
-b 16 -c 2 -r 44100 -s 50ms \
-R /dev/null -O /dev/sndio/snd@remotehost/0 -d dsp
Create a full-duplex audio device exchanging audio using the default
sndio(7) server:
virtual_oss -S -b 16 -C 2 -c 2 -r 48000 -s 4ms \
-f /dev/sndio/default -d dsp
NOTES
All character devices are created using the 0666 mode which gives
everyone in the system access.
SEE ALSO
cuse(3), sound(4), loader.conf(5), sndio(7), mixer(8), sysctl(8),
virtual_bt_speaker(8), virtual_equalizer(8), virtual_oss_cmd(8)
AUTHORS
virtual_oss was written by Hans Petter Selasky hselasky@freebsd.org.
FreeBSD 15.1-STABLE-HBSD June 24, 2026 VIRTUAL_OSS(8)