." Text automatically generated by txt2man
.TH vmixctl 8 "09 March 2015" "" "OSS System Administration Commands"
.SH NAME
\fBvmixctl \fP- Open Sound System utility to control the vmix subsystem.
\fB
.SH SYNOPSIS
.nf
.fam C
\fBo\fP       \fIvmixctl\fP \fIattach\fP [attach_options\.\.\.] \fIaudiodev\fP [\fIinputdev\fP]
\fBo\fP       \fIvmixctl\fP \fIdetach\fP [attach_options\.\.\.] \fIaudiodev\fP
\fBo\fP       \fIvmixctl\fP \fIrate\fP \fIaudiodev\fP \fIsamplerate\fP
\fBo\fP       \fIvmixctl\fP \fIremap\fP \fIaudiodev\fP \fIchannels\fP

.fam T
.fi
.fam T
.fi
.SH DESCRIPTION
The \fIvmixctl\fP program can be used to \fIattach\fP or \fIdetach\fP the virtual mixer subsystem
(vmix) to/from audio devices. In addition it can be used to control vmix 
related parameters such as the sampling \fIrate\fP to be used with the device.
.PP
By default most OSS drivers will \fIattach\fP virtual mixer to the primary audio device
of the sound card (or motherboard audio chip) when the device is attached.
However possible secondary audio devices (engines) will not have vmix
attached by default. In additional professional audio devices will be
attached without vmix because mixing may cause some unwanted distortion
to the signal.
.SH ATTACHING VMIX TO AN AUDIO DEVICE
There are two forms of \fIvmixctl\fP \fIattach\fP command:
.TP
.B
\fBo\fP
\fIvmixctl\fP \fIattach\fP \fIaudiodev\fP
This alternative is to be used with devices that support only output or
have a single audio device file that supports full duplex.
.TP
.B
\fBo\fP
\fIvmixctl\fP \fIattach\fP \fIaudiodev\fP \fIinputdev\fP
The second form is to be used with devices that have separate output and
input device files. The "\fIaudiodev\fP" parameter defines the output device and 
the "\fIinputdev\fP" parameter is the device file to be used for input direction.
Note that both device files must belong to the same "physical" sound card.
In some cases it might be possible to use one sound card for playback and
another for recording. However this configuration is not supported and the
result may not be functional.
.PP
To find out the right device file names (\fIaudiodev\fP and \fIinputdev\fP) you can use
the "ossinfo \fB-a\fP" command.
.SS ATTACH OPTIONS
.TP
.B
\fBo\fP
\fB-r\fP      Disable recording functionality. By default vmix will support
recording if the master \fBdevice\fP(s) support it.
.TP
.B
\fBo\fP
\fB-p\fP      Do not preallocate client engines. By default vmix will
preallocate first 4 (out of 8) client engines when attaching
to the device. The remaining engines will be allocated 
on-demand if there are more concurrent applications that
use the device.
.TP
.B
\fBo\fP
\fB-M\fP      Make vmix use more fragments.
.TP
.B
\fBo\fP
\fB-V\fP      Make client devices visible (have private device nodes under /dev).
.TP
.B
\fBo\fP
\fB-c\fP <n>  Preallocate <n> client engines instead of 4. However \fB-p\fP
option makes this option ineffective.
.SS EXAMPLES
.TP
.B
\fBo\fP
\fIvmixctl\fP \fIattach\fP /dev/oss/oss_envy240/pcm0
.TP
.B
\fBo\fP
\fIvmixctl\fP \fIattach\fP /dev/oss/oss_envy240/pcm0 /dev/oss/oss_envy240/pcmin0
.SH SETTING THE SAMPLING RATE USED BY VMIX
The virtual mixer subsystem will set the physical audio \fBdevce\fP(s) to use
fixed sampling \fIrate\fP that is 48000 Hz by default. It is possible to use
"\fIvmixctl\fP \fIrate\fP \fIaudiodev\fP" to switch vmix to use some different \fIrate\fP with this
device (pair). You should use "ossinfo \fB-a\fP \fB-v2\fP" to verify that the sampling \fIrate\fP
is actually supported by the device. Otherwise the actual device may enforce
vmix to use the nearest supported \fIrate\fP (or some default \fIrate\fP).
.PP
The "\fIaudiodev\fP" parameter is the device file name (see ossinfo \fB-a\fP) that is
used for playback. The input device name doesn't need to be specified.
.PP
Note that some professional audio devices may be locked to external sampling
\fIrate\fP or some fixed \fIrate\fP (defined in ossmix/ossxmis). In such case the \fIrate\fP is
not changeable by \fIvmixctl\fP.
.SS EXAMPLE
.TP
.B
\fBo\fP
\fIvmixctl\fP \fIrate\fP /dev/oss/oss_envy240/pcm0 44100
.SH CHANGING THE VMIX CHANNEL MAP
The vmix subsystem can \fIremap\fP \fIchannels\fP, so that all output sent to a channel via
vmix will end up being played on a different channel. The syntax uses a list of
\fIchannels\fP, where typically 0=default, 1=left, 2=right, 3=center, 4=lfe,
5=left surround, 6=right surround, 7=left rear and 8=right rear.
Note that vmix-\fIchannels\fP should be set first to Multich if vmix is to recognize
the extra \fIchannels\fP.
.SS EXAMPLES
.TP
.B
\fBo\fP
\fIvmixctl\fP \fIremap\fP /dev/dsp 2 1 #switch left and right
.TP
.B
\fBo\fP
\fIvmixctl\fP \fIremap\fP /dev/dsp 0 0 0 0 6 5 #switch left and right surround
.SH DETACHING VMIX FROM AN AUDIO DEVICE
It is possible to \fIdetach\fP vmix from an audio device if it causes problems
with applications by using "vmix \fIdetach\fP \fIaudiodev\fP". 
.PP
It is not possible to \fIdetach\fP and (re)\fIattach\fP vmix to the same device more
than few times. Use the vmix-enable setting in the control panel
(ossxmix or ossmix) to disable/re-enable vmix if you need to do it
repeatedly. Use vmix \fIdetach\fP only if you need to \fIattach\fP virtual mixer using
different parameters.
.SS EXAMPLE
.TP
.B
\fBo\fP
vmix \fIdetach\fP /dev/oss/oss_envy240/pcm0
.SH POSSIBLE BUGS
.TP
.B
\fBo\fP
The control panel elements related with vmix are not removed from the
mixer API when vmix is detached. This may be somehow confusing.
.SH SEE ALSO
\fBsoundoff\fP(1), \fBsoundon\fP(1), \fBossmix\fP(1), \fBossxmix\fP(1)
.SH FILES
/usr/sbin/vmixct
.SH AUTHOR
4Front Technologies