LBMix v.0.04. A universal mixer for IOCTL90 and pipe mixer APIs.


This is free software. It is distributed under GNU General Public License.
See file COPYING for details. There is NO WARRANTY. Use it at your own risk.
This program uses some parts from free IOCTL 90 API demonstration program.


			    INTRO

This is a mixer front end. It does not communicate with hardware directly, it
communicates with other software that works with hardware. It can work with
two kinds of such software: audio device drivers that support IOCTL90 Mixer
API and pipe mixer backends. The IOCTL90 mixer API was originaly implemented
in Crystal Semiconductor drivers, however some other drivers support it as
well, see "Driver Compatibility" section below. The pipe mixer backend is an
easy to write mixer that runs as a detached process and accepts commands as a
text strings sent through a named pipe.


			INSTALLATION

Unpack the archive into a directory. Run install.cmd script and it will
create an LBMix object on desktop. Then you can move the object wherever you
want (including the shredder). You don't need to run the script if you're
upgrading from the previous version.

The default user ini application name used to store mixer's data is "LBMix".


				USAGE

There are several controls on the screen. Each has one or two sliders
and up to three checkboxes. Most of the sliders set volume (left and right if
there are two sliders), "Mute" checkbox mutes the input/output, if "Both" is
checked tracking one slider changes both channels. "Lock" checkbox appear at
controls overriding MMOS/2 per stream controls and shows that it is controlled
by the mixer rather than apps. The sliders of 3D control set space (left) and
center (right). The sliders of tone control set bass (left) and treble (right)
levels. An input selector control has a listbox rather than sliders. You can
select one or several inputs in the list box (depends on driver capabilities).

The pop-up menu can be accessed by right mouse button click. The window can
be moved by dragging it with left or right mouse buttons. The window can be
minimized by left mouse button click.

Selecting "Info" menu item brings up a box with info returned by the driver.
"Settings" brings up a settings notebook.

NOTE1: You'd better keep all the unused inputs muted to minimize the noise
       level.
NOTE2: Audio chips have several equivalent inputs named Line, CD, etc. Despite
       of these naming a card manufacturer may use different inputs assignment.
       Because of this an ability to rename controls was added. See "Settings
       notebook" section for more info.


			COMMAND LINE OPTIONS

-mv		- Use IOCTL category 80 call for master volume control.
		  (see more info below in "Master volume control" section).
-x		- Exit after initialization. Useful together with "Restore
                  mixer state at startup" for setting initial mixer state at
		  system startup or with batch commands.

-i <INI file app name>		- Specify User INI file application name
                                  (case sensitive, default: LBMix).
-d <Audio device driver>	- Specify audio device driver name
				  (default: MMOS/2 default audio driver)

-p		- Use pipe mixer API instead of IOCTL 90 (on default the mixer
		  tries IOCTL 90 API first and then pipe mixer API).
-ps		- Enable built-in pipe mixer API server (supported only while
                  working via IOCTL 90, useful to control the mixer by REXX
                  or remotely). For more information about pipe mixer API and
                  some REXX examples see pipe mixer pack readme.
-pn <pipe name>	- Change default pipe name for pipe mixer API.
                  (default: \PIPE\MIXER)


			SETTINGS NOTEBOOK

Available settings:
"Active controls" tab:
      - Set mono mode for each stereo control (mono mode means one slider
        controls both channels).
      - Enable/disable each control.
      - Rename each control (useful to match your sound card wiring or to save
        window space by using short names).
"Appearance" tab:
      - Rename each dialog control (useful to save window space by using short
        names).
      - set maximum number of controls in a row (1-16). If more controls are
        active they are displayed in two rows.
      - enable or disable menu.
      - enable or disable title bar.
      - enable or disable short sliders.
      - enable or disable narrow sliders (useful with small fonts, a bit
        tricky, may not work in all cases).
"Other" tab:
      - set additional name for this mixer instance that will be displayed in
        the window title and in task list.
      - set icon for this mixer instance.
      - set whether the current mixer settings will be left as is on startup
        or restored to saved values,
      - set whether the mixer will minimize automatically when you select
        another window.

NOTE1: If a control is grey in the Settings dialog then this control is
       not supported by the driver. The same driver may support different
       controls with different cards.


			DRAG'N'DROP

A color or font can be dropped on the window. If a font is dropped then control
layouts are re-calculated to match the font size. If a color is dropped on the
window inside a mixer control then the color is changed for that mixer control
individually. If a color is dropped on the window background outside mixer
controls then the color is changed globally for all mixer controls except ones
having individual color settings. Drag a color holding down Ctrl key to change
foreground color.

Dropping a color on a listbox changes its background color. Dragging a color
holding down Ctrl key and dropping it on a listbox changes its foreground
color. Dragging a color holding down Ctrl key and dropping it on a slider
changes the slider color.

Disable "Minimize on losing focus" option before drag'n'dropping color or
font, you can re-enable it later.

NOTE1: It can be hard to drop a color on window background when the font size
       is too small and thus the unused window background area is small as
       well. Drop a larger font before dropping the color in this case. You
       can drop smaller font after you've changed the colors.
NOTE2: If you drop a color on a window frame instead of window background
       you can change the default colors of child dialogs. So if you suddenly
       discover that a child dialog changed it's colors then you've probably
       missed the window background when dropping a color on it. 


			BATCH COMMANDS

One or more batch commands can be entered in a command line. They are processed
after the mixer state is restored or queried but before the -x option is
processed. A batch command format:

<name>:<ll>:<rr>:<f>:<f>

Where <name> is a control name. It is matched case insensitively against
user defined control names. You may specify first characters (enough to match
only one name) instead of a full control name.

<ll> and <rr> are values for left and right in one of the following formats:
+nn - increase the value by nn,  -nn - decrease the value by nn, nn - set the
velue to nn.  You may omit either of these values or both if you do not want
to change them.

<f> is a flag: +M - to mute the control, -M to unmute the control,
+L to lock the control, -L to unlock the control. You may use +MUTE, -MUTE,
+LOCK, -LOCK as well.

Some examples:
LBMix DAC:100:100:+LOCK:-MUTE ADC:::+LOCK Mic:::+MUTE Line:-30
- set both DAC volumes to 100, lock the DAC control and unmute it. Lock ADC
control. Mute microphone input. Decrease line left channel volume by 30.

LBMix Line:::+MUTE Mic:::+MUTE Aux:::+MUTE Mono:::+MUTE -x
- mute Line, Mic, Aux and Mono inputs and exit. This command can be placed in
startup folder to mute unused inputs to reduce noise.

LBMix Master:-20 -x
- reduce master volume (via MMOS/2) and exit.

LBMix Master:+20 -x
- increase master volume (via MMOS/2) and exit.

NOTE1: Batch commands can set unactive controls as well.
NOTE2: If a stereo control has "Both" turned on then left or right values of a
       batch command affect both left and right settings of the control. If
       both left and right values are specified in this case then left value
       is processed first and right value is processed after that.
NOTE3: batch commands increasing or decreasing master volume will not work
       correctly if -mv option is specified.
NOTE4: If "Restore mixer state after startup" option is enabled then the
       increments and decrements in batch commands are specified relative to
       restored values.
NOTE5: For 3D processing control Space is considered as left value, Center
       is considered as right value. For tone control Bass is considered
       as left value, Treble is considered as right value.
NOTE6: For input source selector the left value sets the input source:
       16 = Mic, 32 = CD, 64 = Video, 128 = Aux, 256 = Line, 2048 = Phone.
       These values can be added in case the input source selector is a mixer,
       e.g. 48 = Mic(16) + CD(32). The right value is ignored.



			MASTER VOLUME CONTROL

The master volume control is implemented in two different ways. Both are
somewhat tricky. On default master volume control works via MMOS/2 in exactly
the same way as standard MMOS/2 master volume control does. Only single mono
control is available in this case. If the -mv option is specified then master
volume is controlled either by calling the driver IOCTL 80 API or by a function
of pipe mixer backend. In this case the control is stereo but this may be
unsupported by some drivers. Please do not run the MMOS/2 master volume control
concurrently with the mixer if master volume control is enabled.


		  USING SEVERAL INSTANCES OF A MIXER

Sometimes it is convenient to use several instances of a mixer. E.g. to control
different cards or to use one instance as a basic mixer with only the most
frequently used controls enabled and another one as an extended mixer with
all controls enabled. In this case the different instances should use different
INI file application name to have their own settings. One of the instances can
use the default name and another one should have a different name specified by
-i <name> command line option. Also you should give the different instances
different instance names and assign different instance icons so you can easily
distinguish between them in the task list or minimized window viewer.


                      DRIVER COMPATIBILITY

Crystal 2.08, v.3.03 (API level 1) - "Features":
        Mixer status is not updated on changes made by other app (or other
        instance of mixer). Once ADC setting is modified it is locked and
        can't be controlled in a normal way by the app.

        Bugs (found in v.2.08 but probably present in v.3.02 as well):
        Line left volume does not work, it is always set the same as the right
        volume. Mic is muted initially and can't be unmuted.


Crystal 2.09, v.3.06 (API level 2):
        Returns empty driver info unless the driver is loaded with /v option.
        DAC volume does not increase continuously (at least in 2.09).

SB Live! beta 0.25:
        Sometimes no supported controls are detected.
	Master volume setting via IOCTL80 (with -mv switch) does not work.


			CONTACT

You can send your bug reports and suggestions to e-mail
boga@inbox.ru or FIDO 2:5095/9.  The lastest version of the mixer can be
downloaded from http://www.podolsk.ru/~boga/OS2Programs.html where you can
also find a couple of other useful OS/2 programs.

IOCTL 90 API and IOCTL 90 API demonstration program were developed
by Joe Nord <nord@crystal.cirrus.com>. API definition is available at
http://www.pompano.net/~joenord/ioctl90/


			FUTURE PLANS

I'm not certain if it's really nessesary to implement these features.

- Move settings to separate ini file.
- Setting: Volume-Balance mode for each stereo control
- Allow user to set the order of controls
- User configurable background bitmaps


			HISTORY

0.01	- Initial version.
0.02	- Defaults button in Settings dialog does not have immediate effect.
	- ADC gain control fixed.
	- Added support for new API features: DAC output gain control,
          3D processing control, input selector control, driver info, tone
	  control, releasing of locked controls.
	- Option to minimize on losing focus.
	- Added ability to change INI file application name and audio device
          driver name with command line parameters (support for multiple
	  cards).
	- Added support for pipe mixer interface.
0.03	- Added unactive controls to input source selector.
	- Only active controls are displayed.
	- Removed limitation on number of mixer instances accessing the same
          device.
	- Added additional instance name that is displayed in the window
	  title and in the task list.
	- Added master volume control.
	- Added exit after initialization option.
	- Fixed problems with ADC gain control and API level 1.
0.04	- Added settings to hide menu and titlebar.
	- Added: double clicking on the window with left mouse button to
	  minimize, dragging with left or right mouse button to move.
	- Added a user selectable icon of an instance.
	- Fixed: no supported controls were listed in driver info dialog
	  in case driver did not return info.
	- Empty driver info now is treated in the same way as no driver info.
	- Dynamic layout based on font metrics
	- User configurable names for dialog controls.
	- Added polling mixer state on receiving focus
	- Changed behaviour of -pn switch
	- Added batch commands
	- Only supported controls are now saved in INI file
	- Added "Mono" settings for each stereo control.
	- Colors/fonts dropped on dialog controls are now passed to the
          parent windows.
	- Individual background/foreground color settings for each mixer
          control + color settings for sliders and listbox
	- Added narrow sliders and short sliders options.
	- Added built-in pipe mixer server
	- Fixed endless loop when trying to control input source selector
 	  if it is a multiplexer rather than mixer (SB Live).