1.\" 2.\" Copyright (c) 2017-2022 Hans Petter Selasky <hselasky@freebsd.org> 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" 26.Dd September 3, 2024 27.Dt VIRTUAL_OSS 8 28.Os 29.Sh NAME 30.Nm virtual_oss 31.Nd daemon to multiplex and demultiplex an OSS device 32.Sh SYNOPSIS 33.Nm 34.Op Fl h 35.Sh DESCRIPTION 36.Nm 37is an audio mixing application that multiplexes and demultiplexes a 38single OSS device into multiple customizable OSS compatible devices 39using character devices from userspace. 40These devices can be used to record played back audio and mix the individual 41channels in multiple ways. 42.Pp 43.Nm 44requires the 45.Xr cuse 3 46kernel module. 47To load the driver as a module at boot time, place the following line in 48.Xr loader.conf 5 : 49.Pp 50 cuse_load="YES" 51.Pp 52All channel numbers start at zero. 53Left channel is zero and right channel is one. 54.Pp 55The following options are available: 56.Bl -tag -width indent 57.It Fl B 58Run program in background. 59.It Fl S 60Enable automatic DSP rate resampling. 61.It Fl Q Ar quality 62Set resampling quality: 0=best, 1=medium and 2=fastest (default). 63.It Fl b Ar bits 64Set sample depth to 65.Fa bits 66for the subsequent commands. 67Valid values are 8, 16, 24 and 32. 68.It Fl r Ar rate 69Set default sample-rate for the subsequent commands. 70.It Fl s Ar value 71Set default buffer size to 72.Fa value . 73If the argument is suffixed by "ms" it is interpreted as milliseconds. 74Else the argument gives number of samples. 75The buffer size specified is per channel. 76If there are multiple channels, the total buffer size will be larger. 77.It Fl i Ar priority 78Set real-time priority to 79.Fa priority . 80Refer to 81.Xr rtprio 1 82for more information. 83.It Fl a Ar log2_amp 84Set the default DSP output and input device amplification to 85.Fa log2_amp . 86The specified amplification is logarithmic. 87Valid values range from -63 to 63 inclusivly. 88The device input amplification gets set to minus 89.Fa log2_amp 90and the device output amplification gets set to 91.Fa log2_amp . 92.It Fl a Ar i,log2_amp 93Set the default DSP input device amplification to 94.Fa log2_amp . 95The specified amplification is logarithmic. 96Valid values range from -63 to 63 inclusivly. 97.It Fl a Ar o,log2_amp 98Set default DSP output device amplification to 99.Fa log2_amp . 100The specified amplification is logarithmic. 101Valid values range from -63 to 63 inclusivly. 102.It Fl p Ar polarity 103Set default polarity of DSP device. 104A value of zero means normal polarity. 105A value of one means negative polarity. 106.It Fl e Ar rx_mute,tx_mute 107Set default mute state of DSP device. 108A value of zero means unmuted. 109A value of one means muted. 110.It Fl m Ar rx_ch,tx_ch,.... 111Set default channel mapping of DSP device, as a comma separated list of 112integers. 113The first integer selects the receive channel, the second value selects the 114transmit channel and then it repeats. 115A value of zero indicates the first receive or transmit channel. 116.It Fl C Ar num 117Set the maximum number of mix channels to 118.Fa num . 119.It Fl c Ar num 120Set mix channels for the subsequent commands. 121.It Fl M Ar type,src_ch,dst_ch,pol,mute,log2_gain 122Add a monitoring filter. 123The filter consists of a list of comma separated arguments. 124The first argument indicates the type of monitoring filter: 125.Bl -tag -width indent 126.It i 127Feedback one mix input channel into another mix output channel, for remote 128feedback. 129.It o 130Add one mix output channel into another mix output channel, for creating a mix 131of multiple output channels. 132.It x 133Feedback one mix output channel into another mix input channel, for local 134feedback. 135.El 136The second argument gives the source mix channel. 137The third argument gives the destination mix channel. 138The fourth argument gives the polarity, default is zero. 139The fifth argument gives the mute state, default is one or muted. 140The sixth argument gives the amplitude, default is zero or no gain. 141.It Fl t Ar devname 142Set control device name. 143.It Fl P Ar devname 144Set playback DSP device only. 145Specifying /dev/null is magic and means no playback device. 146Specifying a 147.Xr sndio 7 148device descriptor prefixed by "/dev/sndio/" is also magic, and will use a sndio 149backend rather than an OSS device. 150.It Fl O Ar devname 151Set playback DSP device only which acts as a master device. 152This option is used in conjunction with -R /dev/null . 153.It Fl R Ar devname 154Set recording DSP device only. 155Specifying /dev/null is magic and means no recording device. 156.It Fl f Ar devname 157Set both playback and recording DSP device 158.It Fl w Ar name 159Create a WAV file format compatible companion device by given name. 160This option should be specified before the -d and -l options. 161.It Fl d Ar name 162Create an OSS device by given name. 163.It Fl l Ar name 164Create a loopback OSS device by given name. 165.It Fl L Ar name 166Create a loopback OSS device which acts as a master device. 167This option is used in conjunction with -f /dev/null . 168.It Fl F Ar size 169Set receive filter size in number of samples or <milliseconds>ms for the next 170device to be created. 171.It Fl G Ar size 172Set transmit filter size in number of samples or <milliseconds>ms for the next 173device to be created. 174.It Fl D Ar file 175Write process ID of virtual_oss to file. 176.It Fl g Ar knee,attack,decay 177Enable device compressor in receive direction. 178See description of -x option. 179.It Fl x Ar knee,attack,decay 180Enable output compressor and set knee, attack and decay. 181Knee is in the range 0..255, while attack and decay are between 0 and 62. 182Samples having an absolute value lower than the knee are transmitted 183unchanged. 184Sample values over the knee are lowered "a little bit". 185You can think about attack and decay as a measure of how fast or slow the 186gain of the compressor will work. 187It is advised that attack is low, so it reacts fast once too high 188sample values appear. 189It is also advised that the decay value is higher than the attack value so 190that the gain reduction is gradually removed. 191The reasoning behind this is that the compressor should react almost 192immediately when high volume signals arrive to protect the hardware, 193but it slowly changes gain when there are no loud signals to avoid 194distorting the signal. 195The default values are 85,3,20 . 196.It Fl E Ar enable_recording 197If the value passed is non-zero, recording is enabled. 198Else recording is disabled. 199This can be used to synchronize multiple recording streams. 200.It Fl h 201Show usage and all available options. 202.El 203.Sh EXAMPLES 204Split a 2-channel OSS compatible sound device into multiple subdevices: 205.Bd -literal -offset indent 206virtual_oss \\ 207 -S \\ 208 -c 2 -r 48000 -b 16 -s 4ms -f /dev/dspX \\ 209 -a 0 -b 16 -c 2 -m 0,0,1,1 -d vdsp.zyn \\ 210 -a 0 -b 16 -c 2 -m 0,0,1,1 -d vdsp.fld \\ 211 -a 0 -b 16 -c 2 -m 0,0,1,1 -d dsp \\ 212 -a 0 -b 16 -c 2 -m 0,0,1,1 -w vdsp.jack.wav -d vdsp.jack \\ 213 -a 0 -b 16 -c 2 -m 0,0,1,1 -w vdsp.rec.wav -l vdsp.rec \\ 214 -M i,0,0,0,1,0 \\ 215 -M i,0,0,0,1,0 \\ 216 -M i,0,0,0,1,0 \\ 217 -M i,0,0,0,1,0 \\ 218 -t vdsp.ctl 219.Ed 220.Pp 221Split an 8-channel 24-bit OSS compatible sound device into multiple subdevices: 222.Bd -literal -offset indent 223sysctl dev.pcm.X.rec.vchanformat=s24le:7.1 224sysctl dev.pcm.X.rec.vchanrate=48000 225sysctl dev.pcm.X.play.vchanformat=s24le:7.1 226sysctl dev.pcm.X.play.vchanrate=48000 227sysctl dev.pcm.X.bitperfect=1 228 229mixer vol.volume=1 pcm.volume=1 230 231virtual_oss \\ 232 -S \\ 233 -i 8 \\ 234 -x 85,3,20 \\ 235 -C 16 -c 8 -r 48000 -b 32 -s 4ms -f /dev/dspX \\ 236 -a 12 -b 16 -c 2 -m 0,4,1,5 -d dsp \\ 237 -a 12 -b 16 -c 2 -m 8,8,9,9 -d vdsp \\ 238 -a 13 -b 16 -c 2 -m 10,10,11,11 -d vdsp.fld \\ 239 -a 0 -b 32 -c 4 -m 4,2,5,3,6,4,7,5 -d vdsp.jack \\ 240 -a -3 -b 32 -c 2 -m 14,14,15,15 -d vdsp.zyn \\ 241 -e 0,1 \\ 242 -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 \\ 243 -a 0 -b 32 -c 2 -m 0,8,1,9 -w vdsp.rec.master.wav -d vdsp.master.mic \\ 244 -a 0 -b 32 -c 2 -m 10,10,11,11 -w vdsp.rec.fld.wav -l vdsp.rec.fld \\ 245 -a 0 -b 32 -c 2 -m 12,12,13,13 -w vdsp.rec.jack.wav -l vdsp.rec.jack \\ 246 -a 0 -b 32 -c 2 -m 14,14,15,15 -w vdsp.rec.zyn.wav -l vdsp.rec.zyn \\ 247 -M o,8,0,0,0,0 \\ 248 -M o,9,1,0,0,0 \\ 249 -M o,10,0,0,0,0 \\ 250 -M o,11,1,0,0,0 \\ 251 -M o,12,0,0,0,0 \\ 252 -M o,13,1,0,0,0 \\ 253 -M o,14,0,0,0,0 \\ 254 -M o,15,1,0,0,0 \\ 255 -M i,14,14,0,1,0 \\ 256 -M i,15,15,0,1,0 \\ 257 -M x,8,0,0,1,0 \\ 258 -M x,8,1,0,1,0 \\ 259 -t vdsp.ctl 260 261.Ed 262.Pp 263Create a secondary audio device sending its output audio into both 264input and output channels of the main DSP device. 265.Bd -literal -offset indent 266virtual_oss \\ 267 -C 4 -c 2 \\ 268 -r 48000 \\ 269 -b 24 \\ 270 -s 4ms \\ 271 -f /dev/dsp3 \\ 272 -c 2 \\ 273 -d dsp \\ 274 -m 2,2,3,3 \\ 275 -d dsp.speech \\ 276 -M o,2,0,0,0,0 \\ 277 -M o,3,1,0,0,0 \\ 278 -M x,2,0,0,0,0 \\ 279 -M x,3,1,0,0,0 280.Ed 281.Pp 282Connect to a bluetooth audio headset, playback only: 283.Bd -literal -offset indent 284virtual_oss \\ 285 -C 2 -c 2 -r 48000 -b 16 -s 4ms \\ 286 -R /dev/null -P /dev/bluetooth/xx:xx:xx:xx:xx:xx -d dsp 287.Ed 288.Pp 289Connect to a bluetooth audio headset, playback and recording: 290.Bd -literal -offset indent 291virtual_oss \\ 292 -C 2 -c 2 -r 48000 -b 16 -s 4ms \\ 293 -f /dev/bluetooth/xx:xx:xx:xx:xx:xx -d dsp 294.Ed 295.Pp 296Create recording device which outputs a WAV-formatted file: 297.Bd -literal -offset indent 298virtual_oss \\ 299 -C 2 -c 2 -r 48000 -b 16 -s 4ms \\ 300 -f /dev/dspX -w dsp.wav -d dsp 301.Ed 302.Pp 303Create a device named dsp.virtual which mix the samples written by all 304clients and outputs the result for further processing into 305dsp.virtual_out: 306.Bd -literal -offset indent 307virtual_oss \\ 308 -S -Q 0 -b 16 -c 2 -r 96000 -s 100ms -i 20 \\ 309 -f /dev/null -d dsp.virtual -L dsp.virtual_out 310.Ed 311.Pp 312Create a playback-only audio device which sends its output to a remote 313.Xr sndio 7 314server: 315.Bd -literal -offset indent 316virtual_oss \\ 317 -b 16 -c 2 -r 44100 -s 50ms \\ 318 -R /dev/null -O /dev/sndio/snd@remotehost/0 -d dsp 319.Ed 320.Pp 321Create a full-duplex audio device exchanging audio using the default 322.Xr sndio 7 323server: 324.Bd -literal -offset indent 325virtual_oss -S -b 16 -C 2 -c 2 -r 48000 -s 4ms \\ 326 -f /dev/sndio/default -d dsp 327.Ed 328.Pp 329How to set intel based CPUs in performance mode: 330.Bd -literal -offset indent 331sysctl -aN | fgrep dev.hwpstate | fgrep epp | \ 332while read OID 333do 334sysctl ${OID}=0 335done 336 337sysctl kern.sched.preempt_thresh=224 338.Ed 339.Sh NOTES 340All character devices are created using the 0666 mode which gives 341everyone in the system access. 342.Sh SEE ALSO 343.Xr cuse 3 , 344.Xr sound 4 , 345.Xr loader.conf 5 , 346.Xr sndio 7 , 347.Xr mixer 8 , 348.Xr sysctl 8 , 349.Xr virtual_bt_speaker 8 , 350.Xr virtual_equalizer 8 , 351.Xr virtual_oss_cmd 8 352.Sh AUTHORS 353.Nm 354was written by 355.An Hans Petter Selasky hselasky@freebsd.org . 356