<!doctype linuxdoc system>

<!-- The KMix Handbook.

 -->

<article>

<!-- Title information -->

<title>The KMix Handbook
<author>Christian Esken, <tt/esken@kde.org/
<date>Version 1.0, 4.11.1998
<abstract>This Handbook describes KMix Version 1.0

<!-- Table of contents -->
<toc>

<!-- Begin the document -->


<sect>Introduction
<p>

KMix is KDE's soundcard mixer program. It is thought as a convinient tool.
Though small, it is full-featured. There are regulators for each device:
One for mono devices,
and as to your liking one or two for stereo devices. Single devices may
be muted and the record source can be set.

KMix supports several platforms and sound drivers. Version 1.0 works with:

<itemize>
<item> All Open Sound System platforms. Explicitly tested are Linux,
FreeBSD, NetBSD and BSDI.
<item> Solaris based machines.
<item> IRIX based machines.
<item> The ALSA soundcard driver.
</itemize>



<P>
Much fun with KDE's multimedia application wishes
<p>
<tt>Christian Esken</tt>
<p>
<htmlurl url="mailto:esken@kde.org" name="esken@kde.org">
<p>


<sect>Working with kmix
<p>

KMix usage is straightforward. Every mixer device that your soundcard
provides, is represented by a volume slider. Mono devices have only
one slider, Stereo devices have two sliders. You are able to merge
the two sliders of a stereo device to a single slider.
Additionaly there is a panning slider at the bottom of the KMix window.


<p>

<sect1>Volume sliders
<p>

The volume sliders show the volume of the selected device. Top is
maximum, bottom is minimum volume. The slider can have three background
colors:
<itemize>
<item><tt/Normal/ No special situation applies to this device.
<item><tt/Black/ The device is muted.
<item><tt/Red/ The device is the current record source. The device
may be muted as well.
</itemize>

The volume sliders have a context menu. Three entries are possible,
but only the applicable are shown.

<itemize>
<item><tt/Mute [On,Off]/ Mute and unmute the the device.
<item><tt/(Un-)Split/ Show either one or two sliders. Only applicable to
stereo devices.
<item><tt/Record Source/ Set this device as record source. Only applicable to
recordable devices.
</itemize>


<sect1>Panning slider
<p>

With this slider you can control the volume distribution between left
and right speaker. This slider is an overall regulator, which
affects all stereo devices (Mono devices are ignored).
The middle position is the default. Dragging the slider to the left
lowers the volume of the right speaker, dragging it to the right
vice versa. The panning slider has a context menu which you can
reach with the right mouse button. You can set the slider to some
prominent positions with this menu.



<sect1>Configuration options
<p>

The following options are automatically saved when you quit kmix
or end your session.<p>

<itemize>
<item><tt/Menu/ If switched off, the menu bar will disappear. You can
get the menu bar by pressing <tt/Control-M/.
<item><tt/Tickmarks/ Switches the Tickamrks on and off.
<item><tt/Docking on the KDE Panel/ If switched on, kmix will dock
itself on the KDE Panel, when pressing the close button. If switched
off, kmix will quit, when you press the close button.
</itemize>



<p>
<sect1> Key Bindings
<p>

KMix honors the following key bindings.


<itemize>
<item><tt/Up Arrow/ Increase volume by 1% 
<item><tt/Down Arrow/ Decrease volume by 1% 
<item><tt/Page Up/ Increase volume by 10% 
<item><tt/Page Down/ Decrease volume by 10% 
<item><tt/Control-M/ Switch the menu bar on and off 
</itemize>

<sect>The Menu Entries
<p>
<sect1>File
<p>
<sect2>Show,Hide Menu
<p>
Switch the menu bar on and off
<sect2>Tickmarks On,Off
<p>
Switches the tick marks on the volume sliders on and off
<sect2>Options
<p>
Opens the KMix options menu

<sect2>Quit
<p>
Quits the Mixer.
<p>



<sect1>Help
<p>
<sect2>Help
<p>
Invokes the KDE help system with the KMix help pages displayed.
<sect2>About 
<p>
Displays informations about KMix.



<sect>Advanced features
<p>

<sect1>Mixer layout and stored Profiles
<p>

This is one of the advanced features of kmix. If you have a standard
layout you like, you can save this layout. A layout stores for each
channel four configuration options.

<p>
<itemize>
<item> The volume of the channel
<item> If the channel is shown
<item> If the channels slider is split (for stereo channels)
<item> If the channel are muted.
</itemize>

If you want to save the current layout, just press <tt/Control-1/
to save the layout as profile <tt/1/.
Likewise you can save profile <tt/2/, <tt/3/ and <tt/4/ by pressing
<tt/Control-2/, <tt/Control-3/ or <tt/Control-4/.

You can restore a profile by pressing <tt/1/, <tt/2/, <tt/3/ and
<tt/4/ respectively. If you want to start kmix with a certain
layout directly set up, you must pass a command line argument.

<sect1>Command line arguments
<p>

You can pass some parameters to kmix, to have influence on
kmix's initial settings.


<p>
<itemize>
<item> <tt/-r/ will restore the default set (set 1), that you saved
by pressing<tt/Control-1/.
<item> <tt/-R n/ will restore the given set.
<item> With passing <tt/-devnum n/, kmix will use the n'th mixer
device on your system.
</itemize>



<sect1>Multiple Soundcards
<p>

KMix is prepared for multiple sound cards. If called via the KDE Panel,
the default mixer is used. For the Open Sound System, this is
<tt>/dev/mixer</tt>. For other operating systems or sound drivers,
this may vary.

If you want KMix to use a specific soundcard (primary, secondary, ...),
you must tell this KMix on startup.
You can start the mixer with a device number, using the <tt/-devnum n/
parameter. <tt/-devnum 0/ means the default
device, 1 your primary mixer, 2 your secondary mixer and so on. If
you use this regulary, you should create a new program kdelnk (using kfm
or the menu editor). This should just call kmix with the appropriate
device number as parameter, for example "kmix -devnum 2".









<sect>Installation
<p>

Normally you don't need to care about the installation of KMix.
KMix is shipped with nearly all Linux distributions. On other
platforms you need to download KMix

<sect1>How to obtain KMix
<p>
KMix is a core application of the KDE project <url url="http://www.kde.org">.
KMix can be found on <url url="ftp://ftp.kde.org/pub/kde/">, the main ftp
site of the KDE project.


<sect1>Requirements
<p>
In order to successfully compile KMix, you need an installed KDE1.0 or
KDE1.1. These releases can be found
on <url url="ftp://ftp.kde.org/pub/kde/">.
Look for a stable KDE release, KMix is contained
in the kdemultimedia package. Mirrors can be found under
<url url="http://www.kde.org/mirrors.html">.


<sect1>Compilation and installation
<p>

In order to compile and install KMix on your system, type the following in
the base
directory of the KMix distribution:
<tscreen><verb>
% ./configure
% make
% make install
</verb></tscreen>


Since KMix uses <tt>autoconf</tt> you should have not trouble compiling it.
Should you run into problems please report them to the <sf/KDE/ mailing
lists.



<sect>Questions and answers
<p>
<itemize>
<item><tt/Q:/ I have switched the menu bar off. Do I have to hack the
config file to get it back?<p>
<tt/A:/ No, just press <tt/Control-M/

<item><tt/Q:/ When I leave kmix, and restart it, the mixer does
not restore the "split" settings of the channels.<p>
<tt/A:/ This is intended. kmix determinates on startup automatically,
  whether a "split" is neccesary. It splits the sliders, if both
  channels have different volume settings.


<item><tt/Q:/ The program does not save any options.<p>
<tt/A:/ The "Menu", "Tickmarks" and "Docking" option are saved
  automatically. The layout is saved manually in profiles.
</itemize>



<p>
</article>
