<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!ENTITY kappname "&kmix;">
<!ENTITY package "kdemultimedia">
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
<!ENTITY % addindex "IGNORE">
]>
<book lang="&language;">
<bookinfo>
<title>The &kmix; Handbook</title>
<authorgroup>
<author>
<firstname>Matt</firstname>
<surname>Johnston</surname>
<affiliation>
<address><email>mattj@flashmail.com</email></address>
</affiliation>
</author>
<othercredit role="developer">
<firstname>Christian</firstname>
<surname>Esken</surname>
<affiliation><address><email>esken@kde.org</email></address></affiliation>
<contrib>Developer</contrib>
</othercredit>
<othercredit role="developer">
<firstname>Helio</firstname>
<surname>Chissini de Castro</surname>
<affiliation><address><email>helio@kde.org</email></address></affiliation>
<contrib>Developer</contrib>
</othercredit>
<othercredit role="developer">
<firstname>Stefan</firstname>
<surname>Schimanski</surname>
<affiliation><address><email>1Stein@gmx.de</email></address></affiliation>
<contrib>Developer</contrib>
</othercredit>
<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation><address><email>lauri@kde.org</email></address></affiliation>
<contrib>Reviewer</contrib>
</othercredit>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<copyright>
<year>1996</year><year>2003</year>
<holder>Christian Esken & Matt Johnston</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
<date>2003-04-24</date>
<releaseinfo>1.91.00</releaseinfo>
<abstract><para>&kmix; is an application to allow you to change the volume of
your sound card.</para></abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>KMix</keyword>
<keyword>kdemultimedia</keyword>
<keyword>sound</keyword>
<keyword>volume</keyword>
<keyword>mixer</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<para>&kmix; is &kde;'s soundcard mixer program. Though small, it is
full-featured. The program should give controls for each of your
soundcards.</para>
<para>&kmix; supports several platforms and sound drivers. Version 1.91 works with:</para>
<itemizedlist>
<listitem><para> All Open Sound System platforms. Explicitly tested
are &Linux;, FreeBSD, NetBSD and BSDI.</para></listitem>
<listitem><para> &Solaris; based machines.</para></listitem>
<listitem><para> &IRIX; based machines.</para></listitem>
<listitem><para> The ALSA soundcard driver.</para></listitem>
<listitem><para> &HP-UX; based machines.</para></listitem>
</itemizedlist>
</chapter>
<chapter id="working-with-kmix">
<title>Working with &kmix;</title>
<para>&kmix; usage is straightforward. Every mixer device that your
soundcard provides is represented by a volume slider. Mono devices
have a single slider, stereo devices can have either one or two
sliders, depending on your choice. Additionally there is a panning
slider at the bottom of the &kmix; window. If you have multiple
soundcards, they will each have their own tab.</para>
<sect1 id="volume-sliders">
<title>Volume sliders</title>
<para>The volume sliders have a context menu, accessible by right clicking on
the slider or device icon (at the top). Several entries are possible, but only
those applicable are shown.</para>
<variablelist>
<varlistentry>
<term><guilabel>Split Channels</guilabel></term>
<listitem><para>Show either one or two sliders. This is only applicable to
stereo devices. The right slider controls right side volume, and the left
controls left side volume.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Muted</guilabel></term>
<listitem><para>Mute or unmute the device</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Hide</guilabel></term>
<listitem><para>If you are not interested in regulating this device you can hide it with this option. If you want to show it again, you can only do this by selecting the <guilabel>Show All</guilabel> option (see below)</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Define Keys</guilabel></term>
<listitem><para>You can control a device with your keyboard. Use this menu option to show the KDE <guilabel>Configure Shortcuts</guilabel> dialog. Here you can define keys for increasing and decreasing volume and for muting the device. The keys are global and operate also when &kmix; is iconified or docked.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Show All</guilabel></term>
<listitem><para>If you have hidden devices via the <guilabel>Hide</guilabel> option (see above), you can show them all again with this option.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Show Menubar</guilabel></term>
<listitem><para>This option is not device specific, but affects the mixer window. You can hide and show the menu bar with this option. You can also do this by pressing the Shortcut (usually CTRL-m)</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="panning-slider">
<title>Panning slider</title>
<para>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. Of course, these might be swapped if your speakers aren't
positioned correctly.</para>
</sect1>
<sect1 id="configuration-options">
<title>Configuration options</title>
<para>If the &kmix; icon is docked into the system tray, you can right click it
to choose preferences. These items are:</para>
<variablelist>
<varlistentry>
<term><guilabel>Dock into panel</guilabel></term>
<listitem><para>minimize to an icon in the system tray</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Enable system tray volume control</guilabel></term>
<listitem><para>If checked, &kmix; will dock in the systray when pressing the window close button. If not checked, &kmix; will quit on pressing the window close button. Attention: After quitting you will not be able to control the volume if you have assigned keys for this.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Show tickmarks</guilabel></term>
<listitem><para>Show lines to mark positions on the sliders.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Show labels</guilabel></term>
<listitem><para>Display labels for each of the sound devices. Wether this item
is checked or not, by holding the mouse over the icon for each device, you can see this information.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="working-with-kmixapplet">
<title>The &kmix; panel applet</title>
<para>
The &kmix; panel applet is an alternative interface to &kmix;.
You can add it to the KDE panel by using the panel menu (<guilabel>Panel Menu</guilabel> -> <guilabel>Add</guilabel> -> <guilabel>Applet</guilabel> -> <guilabel>KMix Applet</guilabel>).
</para>
<para>
You can work with the &kmix; applet as described for the <link linkend="working-with-kmix">main window</link> - including the context menu.
Due to the limited space in the panel there are differences:
<simplelist>
<member>No main menu available.</member>
<member>If you have multiple soundcards, you cannot change the selected mixer after the initial selection.</member>
<member>No dock icon. If you want to use the dock item you must additionally start &kmix; from the K-Menu (usually installed under <guilabel>K-Menu</guilabel> -> <guilabel>Multimedia</guilabel> -> <guilabel>Sound Mixer</guilabel>).</member>
<member>Icons only available when panel is big enough.</member>
<member>No device name labels available.</member>
<member>Configuration is done via panel menu - you can configure colors and slider direction there.</member>
</simplelist>
</para>
</chapter>
<chapter id="control-panel">
<title>&kcontrol; Settings</title>
<sect1 id="config-opt">
<title>Configuration options</title>
<para>In the <guimenuitem>Mixer</guimenuitem> item, under
<guimenu>Sound</guimenu> in &kcontrol;, you can set
various options for &kmix;:</para>
<variablelist>
<varlistentry>
<term><guilabel>Save current volumes</guilabel></term>
<listitem><para>Save the current sound settings to load later.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Load volumes</guilabel></term>
<listitem><para>Load sound settings which were previously
saved.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Load volumes on login</guilabel></term>
<listitem><para>Automatically load the previous settings when you start
&kde;.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Maximum number of probed mixers</guilabel></term>
<listitem><para>How many different soundcards &kmix; should look for when
starting. Set this low to speed up &kmix;'s startup time.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Maximum number of probed devices per mixer</guilabel></term>
<listitem><para>How many devices to look for per soundcard. Again, set this low
to speed up &kmix;.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="advanced-kmix">
<title>Advanced KMix features</title>
<warning><para>This chapter describes &kmix; functionality that is targeted at the experienced user. Most users will never have a need for this functionality, so you can safely skip this chapter</para></warning>
<sect1 id="dcop-overview">
<title>The DCOP Interface</title>
<para>
Sometimes you want to do specialized things.
Things like controlling the mixer from another application or muting the master device every day at 10pm.
&kmix; has a DCOP interface that allows you to achieve much with minimal work.
You can start a shell and type <guilabel>dcop kmix</guilabel> to start exploring the &kmix; DCOP interface.
The &kmix; specific interfaces are:</para>
<variablelist>
<varlistentry>
<term><guilabel>Mixer0</guilabel></term>
<listitem><para>Allows manipulating the first mixer. You can set volume levels, mute the device, change balance, retrieve the mixer name and much more. Type <guilabel>dcop kmix Mixer0</guilabel> if you want to explore all the features. There are more entries like <guilabel>Mixer1</guilabel> in case multiple soundcards are installed.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>kmix-mainwindow#1</guilabel></term>
<listitem><para>The GUI window can be controlled with this command. You can hide and show the window, resize it and much more. Type <guilabel>dcop kmix kmix-mainwindow#1</guilabel> if you want to explore all the features.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="dcop-examples">
<title>DCOP Examples</title>
<variablelist>
<varlistentry>
<term><guilabel>dcop kmix kmix-mainwindow#1 hide</guilabel></term>
<listitem><para>Hides the GUI window. Use <guilabel>dcop kmix kmix-mainwindow#1 show</guilabel> or the dock icon to show it again.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>dcop kmix kmix-mainwindow#1 resize 1 1</guilabel></term>
<listitem><para>Resizes the GUI window to the smallest size possible. This is the size so that all sliders (and other GUI elements) will fit into the window.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>dcop kmix Mixer0 mixerName</guilabel></term>
<listitem><para>Tells the name of the first Mixer, for example <guilabel>Sound Fusion CS46xx</guilabel></para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>dcop kmix Mixer1 setVolume 0 10</guilabel></term>
<listitem><para>Sets the volume on the second mixer, device 0 to 10 percent. Device 0 is often the master device, but not always. If you want to quiet down the (first) master device on your second soundcard, you can use <guilabel>dcop kmix Mixer1 setMasterVolume 0</guilabel></para></listitem>
</varlistentry>
</variablelist>
<para> You can directly execute these commands from a shell that you started from inside KDE. If you need to execute dcop commands from somewhere else, for example from a crontab script, you need to define the <guilabel>DCOPSERVER</guilabel> environment variable (as seen in the first line of your ~/.DCOPserver_hostname_:0 file), for example: </para>
<!-- Don't know a better way to format code - esken -->
<simplelist>
<member>#!/bin/sh</member>
<member>DCOPSERVER=`cat /home/yourhome/.DCOPserver_yourhostname_:0 | grep local`</member>
<member>export DCOPSERVER</member>
<member>dcop kmix Mixer0 setMasterVolume 0</member>
</simplelist>
</sect1>
<sect1 id="tips-and-tricks">
<title>Tips and Tricks</title>
<variablelist>
<varlistentry>
<term><guilabel>Using ALSA and OSS driver at the same time></guilabel></term>
<listitem>
<para>KMix on Linux can use either the ALSA driver or the OSS driver, not both. If you really need to use both drivers at the same time (a very rare situation), you can do it as follows: Quit KMix and add the following line to your <guilabel>kmixrc</guilabel> file in the global configuration section.</para>
<para><guilabel>MultiDriver=true</guilabel></para>
<para>Start KMix again. If you click <guilabel>Help->Hardware Information</guilabel> you should see "<guilabel>Sound drivers used: ALSA0.9 + OSS</guilabel>" and "<guilabel>Experimental multiple-Driver mode activated</guilabel>"</para>
<warning><para>Warning: You will probably see all of your mixers doubled.</para><para>There is no support for this kind of configuration.</para></warning>
</listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="credits">
<title>Credits and License</title>
<para>Main developers</para>
<itemizedlist>
<listitem><para>Copyright 1996-2000 Christian Esken</para></listitem>
<listitem><para>Copyright 2000-2003 Christian Esken & Stefan Schimanski</para></listitem>
<listitem><para>Copyright 2003 Christian Esken & Helio Chissini de Castro</para></listitem>
</itemizedlist>
<para>Contributors:</para>
<itemizedlist>
<listitem><para>Christian Esken <email>esken@kde.org</email></para></listitem>
<listitem><para>Stefan Schimanski <email>1Stein@gmx.de</email></para></listitem>
<listitem><para>Paul Kendall <email>paul@orion.co.nz</email> - SGI
Port</para></listitem>
<listitem><para>Sebestyen Zoltan <email>szoli@digo.inf.elte.hu</email> - FreeBSD
Fixes</para></listitem>
<listitem><para>Faraut Jean-Louis <email>jlf@essi.fr</email> - Solaris
Fixes</para></listitem>
<listitem><para>Nick Lopez <email>kimo_sabe@usa.net</email> - ALSA
Port</para></listitem>
<listitem><para>Helge Deller <email>deller@gmx.de</email> - HP-UX
Port</para></listitem>
<listitem><para>Lennart Augustsson <email>augustss@cs.chalmers.se</email> - *BSD
Fixes</para></listitem>
</itemizedlist>
<para>Documentation copyright 2000 Matt Johnston
<email>mattj@flashmail.com</email></para>
<para>Updated 2003 to match &kmix; V1.91 by Christian Esken
<email>esken@kde.org</email></para>
<para>Based on documentation by Christian Esken
<email>esken@kde.org</email></para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
&underGPL;
</chapter>
<appendix id="installation">
<title>Installation</title>
<sect1 id="getting-kmix">
<title>How to obtain &kmix;</title>
&install.intro.documentation;
</sect1>
<sect1 id="requirements">
<title>Requirements</title>
<para>Obviously, &kmix; is only of use if you have a soundcard.
&kmix; supports several platforms and sound drivers:</para>
<itemizedlist>
<listitem><para> All Open Sound System platforms. Explicitly tested
are &Linux;, FreeBSD, NetBSD and BSDI.</para></listitem>
<listitem><para> &Solaris; based machines.</para></listitem>
<listitem><para> &IRIX; based machines.</para></listitem>
<listitem><para> The ALSA soundcard driver.</para></listitem>
<listitem><para> &HP-UX; based machines.</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="compilation">
<title>Compilation and Installation</title>
&install.compile.documentation;
</sect1>
</appendix>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
