Instructions for using ossmix
=============================

ossmix is a simple mixer utility which is designed to replace the
mixer applet originally included with OSS (it's still included).
OSS version 3.9 has extended mixer API which supports some device
specific features that are not accessible using other mixers. These
extensions can be used to switch between external and internal MIDI
ports of some soundcards (Soundscape) or to mute the direct connection
from cd/mic/linein to the speakers with SB16/32/64.

NOTICE! The extended mixer API is still under constructions and it may
change in OSS 4.0. For this reason documentation of the API will not
be made available before OSS 4.0. It's also possible that functionality
and/or usage of ossmix changes in OSS 4.0.

Using ossmix
------------

ossmix -h displays short instructions for using ossmix.

ossmix without any arguments displays the current settings of the
first mixer device (mixer number 0 shown by cat /dev/sndstat). This
printout can also be used to find out the supported control names and
their possible values. Currently all controls accept an ON/OFF value, a
mono value (0 to 100) or a stereo value (left:right where both channel
volumes can be between 0 and 100). The following is a sample printout
produced by ossmix:

# ossmix
Selected mixer 0/Ensoniq AudioPCI
Known controls are:
vol [:] (currently 50:50)
pcm [:] (currently 50:50)
speaker (currently 21)
line [:] (currently 32:32)
line.rec ON|OFF (currently OFF)
mic (currently 16)
mic.rec ON|OFF (currently ON)
cd [:] (currently 100:100)
cd.rec ON|OFF (currently OFF)
pcm2 [:] (currently 75:75)
line1 [:] (currently 32:32)
line1.rec ON|OFF (currently OFF)
line2 (currently 32)
line2.rec ON|OFF (currently OFF)
line3 (currently 0)
line3.rec ON|OFF (currently OFF)
mic.micboost ON|OFF (currently ON)
mic.micbias ON|OFF (currently ON)
mute.pcmmute ON|OFF (currently OFF)
mute.pcm2mute ON|OFF (currently OFF)
mute.micmute ON|OFF (currently OFF)
mute.cdmute ON|OFF (currently OFF)
mute.linemute ON|OFF (currently OFF)
mute.line1mute ON|OFF (currently OFF)
mute.line2mute ON|OFF (currently OFF)
mute.line3mute ON|OFF (currently OFF)

Selecting the mixer device
--------------------------

It's possible to select the mixer device by using the -d
command line argument. This argument (when used) should be the first one
on the command line. By default the mixer number 0 will be accessed.

Changing the mixer settings
---------------------------

Changing the values is done just like with the original "mixer" applet.
For example:

ossmix pcm 50:60

The above sets the pcm control (audio playback volume) so that the left
channel volume is 50 and the right channel volume is 60. With just
"ossmix pcm 50" the both channel volumes will be set to 50.

In addition to the old mixer there are now some new (usually ON/OFF) settings
which were not supported before OSS 3.9. These settings are device specific
and don't work with all soundcards. The easiest way to find them out is
to start ossmix without command line arguments (other than -d#).

Some control names contain a dot ("."). This dot is required when changing
the value. For example: "ossmix -d0 mic.micboost ON".

Using ossmix as a MIDI controlled mixer
---------------------------------------

The ossmix program has capability to listen MIDI main volume controller
messages from a MIDI port. You can assign a ossmix control to each MIDI
channel. After receiving a channel main volume change message ossmix will then
change the mixer level of the volume control assigned to the channel. In this
mode ossmix will not exit (you need to kill it manually).

This mode is very usefull if you need to make several rapid mixer changes
simultaneously.

To use this mode you need to give the MIDI device file and a list of the
volume sliders on command line. For example:

ossmix -d1 -m/dev/midi00 vol mic pcm line gain.out1/2 gain.in3/4

After that the MIDI channels will be assigned in the following way:

Ch 0 = "vol"
Ch 1 = "mic"
Ch 2 = "pcm"
Ch 3 = "line"
Ch 4 = "gain.out1/2"
Ch 5 = "gain.in3/4"

Other MIDI channels (6 to 15) will be ignored.

Only mono and stereo slider type controls can be assigned to MIDI channels.
Both stereo channels will be set to the same volume (there is no balance
support).

After starting ossmix you should move the sliders on the external fader box
so that ossmix can figure out their current settings.

At this moment only MIDI fader boxes that send only main volume change messages
are supported (any other MIDI data will make ossmix to behave incorrectly).
For example the FM3 MIDI Mixer (AKA "FaderBaby") by JLCooper is compatible
with ossmix.