VIRTUAL_OSS(8)

🌸 NAME 🌸

virtual_oss — the daemon that multiplexes and demultiplexes an OSS device, bestie 💅

✨ SYNOPSIS ✨

virtual_oss [-h]

💖 DESCRIPTION 💖

Okay so picture this: virtual_oss is an audio mixing application, and what it does — no cap — is multiplex and demultiplexes a single OSS device into multiple customizable OSS compatible devices using character devices from userspace. Like one physical thing going in, a whole little squad of devices coming out. Iconic behavior honestly 🦋

And those devices? They can be used to record played back audio and mix the individual channels in multiple ways. So you've got options, you've got range, you've got main character energy ✨

🫶 Heads up: virtual_oss requires the cuse(3) kernel module. Not optional. Not a vibe suggestion. It needs it.

To load the driver as a module at boot time, drop this line into loader.conf(5):

cuse_load="YES"

Also super important, don't skip this: all channel numbers start at zero. Left channel is zero and right channel is one. That's it, that's the rule, memorize it 💀

---

🎀 OPTIONS 🎀

The following options are available — and yes, we're going through all of them, grab a snack 🍓

• -B — Run the program in the background. Set it and forget it, she's independent now 💅
• -S — Enable automatic DSP rate resampling. Let the machine handle the math ✨
• -Q quality — Set the resampling quality: 0=best, 1=medium and 2=fastest (that last one's the default, fyi).
• -b bits — Set the sample depth to bits for the subsequent commands. Valid values are 8, 16, 24 and 32. Those four, no others, don't try it 🙈
• -r rate — Set the default sample-rate for the subsequent commands.
• -s value — Set the default buffer size to value. If the argument is suffixed by "ms" it's interpreted as milliseconds, otherwise the argument gives the number of samples. And lowkey important: the buffer size specified is per channel — so if there are multiple channels, the total buffer size will be larger. Math is math 🧚
• -i priority — Set the real-time priority to priority. Refer to rtprio(1) for more information if you wanna get into it.
• -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. Both at once, she's doing double duty 👑
• -a i,log2_amp — Just the input side this time: set the default DSP input device amplification to log2_amp. Logarithmic again, valid values range from -63 to 63 inclusivly.
• -a o,log2_amp — And just the output side: set the default DSP output device amplification to log2_amp. Logarithmic, valid values range from -63 to 63 inclusivly.
• -p polarity — Set the default polarity of the DSP device. A value of zero means normal polarity, a value of one means negative polarity. Flip it and reverse it 🔥
• -e rx_mute,tx_mute — Set the default mute state of the DSP device. A value of zero means unmuted, a value of one means muted. Simple as that, no notes 💜
• -m rx_ch,tx_ch,.... — Set the default channel mapping of the 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. So it's like a lil pattern that keeps going 🌀
• -C num — Set the maximum number of mix channels to num. Set the ceiling, bestie.
• -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.

Then the rest of the args: 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. And the sixth argument gives the amplitude, default is zero or no gain. Yes, those are the defaults, don't come for me 🙈

• -t devname — Set the control device name.
• -P devname — Set the playback DSP device only. Here's the magic trick though: specifying /dev/null is magic and means no playback device ✨. And specifying a sndio(7) device descriptor prefixed by "/dev/sndio/" is also magic — that one will use a sndio backend rather than an OSS device. Two whole magics.
• -O devname — Set the playback DSP device only, but this one acts as a master device. This option is used in conjunction with -R /dev/null. They're a package deal, iykyk 🫶
• -R devname — Set the recording DSP device only. Specifying /dev/null is magic and means no recording device.
• -f devname — Set both playback and recording DSP device. Two birds, one flag 🦋
• -w name — Create a WAV file format compatible companion device by the given name. Oh and heads up: this option should be specified before the -d and -l options. Order matters, bestie 💀
• -d name — Create an OSS device by the given name. Making devices out of thin air, we love to see it.
• -l name — Create a loopback OSS device by the given name.
• -L name — Create a loopback OSS device which acts as a master device. This option is used in conjunction with -f /dev/null. Again, package deal 🤝
• -F size — Set the receive filter size in number of samples or <milliseconds>ms for the next device to be created.
• -G size — Set the transmit filter size in number of samples or <milliseconds>ms for the next device to be created.
• -D file — Write the process ID of virtual_oss to file. So you can find her later 💅
• -g knee,attack,decay — Enable the device compressor in the receive direction. See the description of the -x option for what these three actually do.
• -x knee,attack,decay — Enable the output compressor and set knee, attack and decay. Let me break this down because it's a lot:
  • 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. Protect the hardware, don't wreck the signals, everybody wins 🛡️
  • 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. Sync her up ⭐
• -h — Show usage and all available options. The classic little help flag, she ate 🎀

🌸 EXAMPLES 🌸

Okay bestie, this is the part where it all clicks — real setups, real flags, copy-paste energy. Let's go 💅

---

🎀 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

One pipe, many vibes. Splitting the 2-channel device into a whole little friend group of subdevices, each with its own job 🫶

---

🦋 Split an 8-channel 24-bit OSS compatible sound device into multiple subdevices

First, the sysctl warm-up — get the hardware speaking the right language:

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

Then crank the mixer levels:

mixer vol.volume=1 pcm.volume=1

And now the main character:

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

Eight channels, zero chill. This is the full send: a 24-bit 8-channel monster chopped into subdevices, WAV recorders, a control device, and a whole wall of matrix routing ✨

---

💖 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

Loop it right back around, bestie — output flows into both the input and output channels of the main DSP device 🔁

---

🎧 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

Headphones go brr, recording stays at /dev/null — not a single mic in sight 🙈

---

🎧 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

Full duplex era 💅 Both directions, one device, iconic.

---

🍓 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

You're literally writing straight to dsp.wav — record it and keep it, periodt ✨

---

🧚 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

A mixing hub with main character energy — everyone writes in, the mix goes out to dsp.virtual_out for whatever you wanna do next 👑

---

🌈 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

Remote server? No cap, we're streaming straight to it over sndio 🦋

---

⭐ 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

Both directions, default sndio server, zero extra drama 💜

---

💀 NOTES 💀

Okay so heads up: all character devices are created using the 0666 mode, which gives everyone in the system access. Yes, everyone. That's the whole system, bestie. Not a drill 🙈

---

👑 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)

Go read the whole friend group, they're all iconic fr fr 📚

---

🫶 AUTHORS 🫶

virtual_oss was written by Hans Petter Selasky hselasky@freebsd.org. Shoutout to the legend, we stan 🎀

---

Debian, April 17, 2026 — VIRTUAL_OSS(8) 💖 That's the page, bestie — go make some beautiful audio happen 🌸