RealICQClient/Includes/2007_MMTools/Help/Doc/MIXER/README.TXT

1. Mixer architecture
2. Mixer components architecture

-----------------------------------------------------------------------------
1. Mixer architecture
-----------------------------------------------------------------------------

What is hided under simple volume control application that you're starting by
double-clicking on the speaker icon? Where is complex construction which
provides device-independent access to different audio flow controlling
capabilities of different sound cards.
All sound comes from some kind of _source audio line_. I.e. sound from CD comes
to soundcard through CD source line. After inside sound card's mixer it combines
with other sound which comes from another source lines and they all fall into
_destination audio line_. One of destination line is playing on the speaker
system, sound from another is recorded by sound recorders. Also in any place
(depending on sound card's capabilities) there are different _mixer controls_ at
sound lines. For example there is master volume control on the destination line
which leads to speaker. There are several types of controls which can be present
at the sound card:

Fader   - faders are different volume, bass, treble and other controls of such
          type. Mostly you are controlling such a control with some kind of
          vertical scrollbar.

Meter   - this is not controller, this is measure control. I.e. you got values
          from it, which are calculated from sound. For example on most cards
          you can see VU-meter on Wave source or Recording target, this is meter
          control.

Slider  - this is like a fader, but mostly present with horizontal scrollbar.
          For example pan control.

Switch  - this is just a switch of some type. For example mutes or automatic
          gain control.

Time,
Number  - controls of such type mostly represent some kind of numeric data.

List    - this is interesting kind of control. It will be described later in
          section describing line mixing.

Custom  - this is not a type, it means that sound card contains something very
          uncommon, and should be controlled in some unknown way. You can
          operate on low-level with controls of such type using MMMixer stuff.

So what about line mixing? You see that you're not hearing all possible source
audio lines because it will be not eligible. Instead you select which line to
hear, and which not. Or you select which line to mute. And this covers two
different types of mixing: selection and muting. Different destination audio
lines can differently mix their source lines, or different methods can be used
even on one destination line. On recording destination line mostly used
selection method. I.e. there is _Mixer control_ on the destination line which
selects which line to hear. Do not confuse with different "mixer controls",
we'll name control which selects source lines with capital letter, and ordinal
mixer control with lower letter. So then you _select_ lines in volume control
application you're using such Mixer control. But if you mute lines then you use
another technique: each source line contains mute control which can disable
sound to go to destination. Also there can be special type of selection: then
only one line can be connected to destination line - this is done by mux control
which is works like a switch.
Each control can operate with several channels independently or uniform. So you
can mute only one left channel, or set right channel more loud than left. Also
some kind of controls (like Mixer control) allows to set values independently
for different items (i.e. different lines in Mixer control, different bands in
Equalizer and so on).
If you have seen different sound card, you can see that there is as much mixer
construction as much sound cards and card drivers. To allow you more independent
controlling of sound flow you can use several features. Each audio line has type
of component to/from which it connected. For example destination line which
leads to speaker has DstSpeaker component type, and source line which leads from
CD has SrcCD component type. Also each control has control type (like Volume,
Bass, Mute), and system allows you to ask controls with specified types, and
lines with specified component types.
So to control anything you should get needed audio lines, find needed controls
and change their values. Also system allows you to reflect changes in controls
which made by another programs.

-----------------------------------------------------------------------------
2. Mixer components architecture
-----------------------------------------------------------------------------

MMMixer components organised as wrappers for logical mixer architecture.

MMMixerDevice represents mixer device. Mostly where is one mixer device on
each sound card. To select which device to use you should use DeviceId property.
Number of devices is present in DeviceCount property. DeviceCaps property can
be used to obtain different information about mixer device. There is two
interesting properties: Active and Destinations. Destinations shows how many
destination audio lines present in mixer. they can be accessed by property
Destination[i]. Setting Active property to True allow component to reflect
changes in mixer controls made by another applications. In such a case all
components connected to MMMixerDevice will reflect these changes. There are
three events: OnChange, OnLineChange and OnControlChange. They are fired then
any change occured, change in some audio line occured or change in some audio
control occured.

MMAudioLine component is used to work with both destination and source audio
lines. At first it should be connected to MixerDevice component by Mixer
property. After you have a task to select one of different audio lines. The
target is to obtain a line id. This can be done by setting line id directly
using property LineId. This is usable in run-time if get it from some other
place. But in device-independent case this is not good. If you want to select
source audio line you should connect AudioLine component to another AudioLine
component which represents destination audio line. This will allow you to select
some kinds of audio lines in the set of lines connected to destination line.
But do not forget to connect both source and destination lines to mixer device
component. To select line you can use ComponentType property. Using it you can
say that you want SrcCD type of line. So if you've just audio line component
connected to mixer device you'll commonly get first source CD line present in
the card. It is mostly source line connected to speaker output. If you want to
be more exact you should connect one audio line component to speaker or recorder
(this can be done by using ComponentType too, but for destination line it is no
problem to determine which to use), and after connect needed audio line to it
and specify ComponentType. In such a case there will be found CD source line
which is falls to specified destination. If it will not be found, than line id
becomes badLineId and line becomes unavailable. In another case line id will be
set to valid line identifier. After setting valid audio line you can obtain
different information from LineInfo property. There are two events: OnChange and
OnControlChange. They occurs than specified line changed or one of line's
control is changed.

MMMixerControl component is used to communicate with sound card's audio line's
control. I.e. it does not provide visual representation of control's data, but
allows you to connect different kinds of visual controls to it. You should
connect it to audio line on which you want operate using property AudioLine.
After you should to select control which resides on the line. This can be done
by using ControlId property, but it is device-dependent. Instead of this you can
use ControlType property which allows you to select type of control which you
want to find on the selected line. For example if you connect mixer control to
AudioLine which is connected to CD source line, and set ControlType to ctVolume
you will get volume control for CD. If CD source line does not exist, or volume
control is not present on it, control becomes unavailable, and all visual
controls connected to it reflects it by setting their visual representation to
appropriate state. After connecting control you can access various information
from ControlInfo property. MixerControl has one event - OnChange which is fired
then control's value or state is changed.

MMVolumeControl and MMPanControl - this is special cases of MMMixerControl
specially designed to control volume and pan. On most sound cards there is no
hardware pan controlling. This is done in software. To simulate pan control you
can use MMPanControl component, and this component to work correctly with
corresponding volume controls should be connected to MMVolumeControl.

MMMixerSlider is a visual control which can be used to operate any mixer control
which allow to set numeric values (such as sliders, faders, numbers e.t.c). You
can select control by using Control property, channel on which to operate using
Channel property (left, right or both) and item using Item property (or NoItem
if just ordinary control). Slider will automatically accept min and max values,
step count and will reflect actual value of control if MixerDevice's property
Active is set to True.

MMMixerWheel just as MMMixerSlider, but provides different visual
representation. By the way: you can set any number of visual controls connected
to non-visual mixer control.

MMMixerCheck is provided to display values for switch-type controls. In addition
to standart properties (see MMMixerSlider), it has property AutoCaption which
allows control to automatically set caption using name of sound card's control
(btw: it is often really descriptive name). If you use MixerCheck to control
Mixer control (here we talk about control which controls which source lines to
flow into destination line) you will need to switch just an item not whole
control. To set MixerCheck to control item which corresponds to some audio line
you can point ItemLine property to this line. Also to select which name to use
for caption (there is allways present short and long name) you can use property
Short.

MMMixerConnector is used to show values for controls which is non-controlling
but measures some values. After specified time interval it requests current
value from control and post it to connected visual controls (like Meters and
Levels). So you can connect Peak meters to it to show VU-meter for user.
(btw: you can even connect volume control to it and you'll see visual
representation for current volume).

MMMixerLabelConnector is used to set caption of any component which has Caption
property to name of some mixer control.

MMDeviceSpin and MMDeviceComboBox can be used to simply select different
mixer devices to use.

MMMixerBlock is special component to easily create Volume Control like mixer
panels. You can put different controls on it and automatically arrange and size
them. See Mix and Block app for examples. You should put on it special versions
of mixer visual controls: MixerBlockSlider, MixerBlockCheck, e.t.c. Then you
put such component it automatically jumps to corresponding location. After you
can change its "role" by setting its Role property. For example you can put
first slider and it will become pan control. If you want you can make it left
volume control by changing its Role property. The purpose of block is that you
operate only with block, you should not think about each control. To turn auto
arrangement off you should set AutoArrange property to False, or you can just
set AutoSize property to false - it will only disable auto resizing of controls.
You should connect Block directly to AudioLine using property Line. If mute of
audio line will be available then it automatically will be accessible through
MixerCheck, but if you want to allow selection of audio line you will need to
connect block to MixerControl component connected to sound card's Mixer control
(which selects audio lines). So if in run-time destination audio line will
allow selection of audio lines when block automatically will select audio line,
if there is will be only mute, then it will be available, if no kind of
selection/muting will be available checkbox will be disabled.

So to setup mixer-enabled app you should set MixerDevice component, several
audio lines component for needed destinations, all needed source lines connected
to destinations, possible mixer control components on different lines and visual
controls to control these controls.