summaryrefslogtreecommitdiffstats
path: root/doc/kmix/index.docbook
blob: baeb926d8a637b65039113931f6a6db0150d82b8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
<?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 "tdemultimedia">
  <!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>&Matt.Johnston.mail;</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>&Lauri.Watts.mail;</address></affiliation>
<contrib>Reviewer</contrib>
</othercredit>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>1996</year><year>2005</year>
<holder>Christian Esken &amp; &Matt.Johnston;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2007-01-05</date>
<releaseinfo>2.6.1</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>tdemultimedia</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:</para>

<itemizedlist>
<listitem><para> The ALSA soundcard driver.</para></listitem>
<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> &HP-UX; based machines.</para></listitem>
</itemizedlist>

<para>If you have both ALSA and Open Sound System drivers installed, &kmix; will use the ALSA driver.</para>

</chapter>

<chapter id="working-with-kmix">
<title>Working with &kmix;</title>

<sect1 id="basic-usage">
<title>Basics</title>

<para>&kmix; usage is straightforward. Every mixer control that your
soundcard provides is represented by a volume slider. Mono controls
have a single slider, stereo controls 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 more than one soundcard, a list will be displayed on the top of the window, where you can choose between your soundcards.

<screenshot>
<screeninfo>The &kmix; Main Window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kmix-window.png" format="PNG"/></imageobject>
<textobject><phrase>The &kmix; Main Window</phrase></textobject>
</mediaobject>
</screenshot>

</para>


<para>The Window can have up to three sections with different soundcard controls: 
<guilabel>Output</guilabel>, <guilabel>Input</guilabel> and <guilabel>Switches</guilabel>.
Those sections contain volume sliders, switches for enabling/disabling record or playback, and multiple-choice selectors.

<simplelist>
<member><guilabel>Output</guilabel>: This holds the controls that are most likely playback related, like the <guilabel>Master</guilabel> volume control.</member>
<member><guilabel>Input</guilabel>: This holds all controls that are most likely record related, like <guilabel>Capture</guilabel>.</member>
<member><guilabel>Switches</guilabel>: This holds all controls, that allows only to switch some functionality ON or OFF (like "Mic Boost (+20dB)"), and multiple-choice controls (like <guilabel>Mic Select</guilabel>: <guilabel>Mic1</guilabel> or <guilabel>Mic2</guilabel>).</member>
</simplelist>
</para>

<para>Besides volumes controls, &kmix; also features LED's. The general coloring rule is:</para>
<simplelist>
<member>Green: A LED dealing with playback</member>
<member>Red: A LED dealing with recording</member>
<member>Yellow: A LED dealing with special soundcard capabilities</member>
</simplelist>
<para>These 3 colors come in two flavours: A lit LED means ON, a non-lit LED means OFF.</para>
</sect1>

<sect1 id="volume-sliders">
<title>Volume controls</title>

<para>The volume controls in section <guilabel>Output</guilabel> and <guilabel>Input</guilabel> consist of (top to bottom):
<screenshot>
<screeninfo>Volume control (<guilabel>Input</guilabel> Section)</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kmix-channel-playback.png" format="PNG"/></imageobject>
<textobject><phrase>Volume control (<guilabel>Input</guilabel> Section)</phrase></textobject>
</mediaobject>
</screenshot>

<simplelist>
<member>An icon, representing the function of the control.</member>
<member>A volume value indicator (optional).</member>
<member>A Green Mute LED, that allows you to mute a control (light goes off/gets dark) or unmute it again (light goes on/gets bright).</member>
<member>A slider, for volume control (Hint: You can hide the label on the slider, for example if the mixer takes too much of your screen space).</member>
<member>If a control supports recording, there will be a red Record LED. If the LED is lit (bright red), the control is selected for recording. If it is not lit (dark red), the control is NOT selected for recording.</member>
</simplelist>

<screenshot>
<screeninfo>Volume control with Recording Switch (<guilabel>Output</guilabel> Section)</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kmix-channel-record.png" format="PNG"/></imageobject>
<textobject><phrase>Volume control with Recording Switch (<guilabel>Output</guilabel> Section)</phrase></textobject>
</mediaobject>
</screenshot>

</para>


<para>
Most of these controls have a context menu, accessible by right clicking on the control or device icon. Several entries are possible in the context menu, but only those applicable are shown.
</para>

<variablelist>
<varlistentry>
<term><guimenuitem>Split Channels</guimenuitem></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><guimenuitem>Muted</guimenuitem></term>
<listitem><para>Mute or unmute the device</para></listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Hide</guimenuitem></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 <guimenuitem>Channels</guimenuitem> option (see below)</para></listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Configure Global Shortcuts...</guimenuitem></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><guimenuitem>Channels</guimenuitem></term>
<listitem><para>You will get a dialog box where you can configure per section (<guilabel>Output</guilabel>, <guilabel>Input</guilabel>, <guilabel>Switches</guilabel>), which channels you want to see.</para></listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Show/Hide Menubar</guimenuitem></term>
<listitem><para>This option is not device specific, but affects the mixer window. You can hide and show the menubar with this option. You can also do this by pressing the shortcut (usually <keycombo action="simul">&Ctrl;<keycap>M</keycap></keycombo>)</para></listitem>
</varlistentry>

</variablelist>
</sect1>

<sect1 id="switches">
<title>Switches and Multiple-Choice selectors</title>

<para>The controls in the section <guilabel>Switches</guilabel> consist of a LED and a short label describing the function. The <guilabel>Switches</guilabel> section can also contain Multiple-Choice selectors. Please note that these controls are often very special and usually don't need to be changed by the average user. The context menu contains the <guimenuitem>Channels</guimenuitem> and <guimenuitem>Show/Hide Menubar</guimenuitem> entries already described.

<screenshot>
<screeninfo>Switches and Multiple-Choice selectors (<guilabel>Switches</guilabel> Section)</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kmix-channel-switches.png" format="PNG"/></imageobject>
<textobject><phrase>Switches and Multiple-Choice selectors (<guilabel>Switches</guilabel> Section)</phrase></textobject>
</mediaobject>
</screenshot>

Please remember, red LED's are recording related, yellow LED's control special soundcard capabilities.

The screenshot above shows from left to right an unlit <guilabel>IEC958 Output</guilabel> LED (yellow = special control), a lit <guilabel>Mix</guilabel> LED (red = Recording related), an unlit recording related LED, a lit special control and one multiple-choice selector (<guilabel>PCM Out Path &amp; Mute</guilabel>).

If you are uncertain about the meaning of a control, please ask your soundcard driver supplier (for most current &Linux; distributions this is <ulink url="http://www.alsa-project.org">ALSA</ulink>).
</para>

</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 the Master Volume.
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>
<para>For Surround Systems please be aware that the <guilabel>Master</guilabel> device often regulates only the Front Speakers. 
This is a limitation of your Soundcard driver.</para> 
<para>If your soundcard has no <guilabel>Master</guilabel> device, some other device might get picked by &kmix; - for most people this is the <guilabel>Wave</guilabel> (or <guilabel>PCM</guilabel>) control.</para>

</sect1>

<sect1 id="configuration-options">
<title>Configuration options</title>

<para>Use <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kmix;...</guimenuitem></menuchoice>
from the menubar to choose preferences. These items are:</para>

<variablelist>
<varlistentry>
<term><guilabel>Dock into panel</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>Enable system tray volume control</guilabel></term>
<listitem><para>If enabled, a left-clicking the &kmix; dock icon will show a popup window with a volume control for the preferred device (Hint: currently you cannot change this device - it is selected by &kmix; instead). If the option is disabled, the &kmix; Main Window will be shown on a left-click on the &kmix; dock icon.</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>
<varlistentry>
<term><guilabel>Restore volumes on login</guilabel></term>
<listitem><para>Let &kde; restore the volumes when you Login: This restores your personal volume levels, stored when you last logged out. If your Operating System saves the volume levels,  you might not need this option (but on a computer with multiple users it is still needed).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Volume Values:</guilabel></term>
<listitem><para>Select if and how volume values are displayed: <guilabel>None</guilabel>, <guilabel>Absolute</guilabel> or <guilabel>Relative</guilabel>.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Slider Orientation</guilabel></term>
<listitem><para>With this option you can turn the &kmix; main window content by 90 degrees. Sliders, texts and everything else (if applicable) is rotated. There are some exclusions to this rule, most notably the menubar, the mixer selector (if shown at all), the panning slider and the multiple-choice selectors.</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 selecting <guimenuitem>Add Applet to Panel...</guimenuitem> in the <guimenu>Panel Menu</guimenu> or context menu.
Choose <guilabel>Sound Mixer</guilabel> and click the <guibutton>Add to Panel</guibutton> or double click <guilabel>Sound Mixer</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; with
<menuchoice><guimenu>K-Menu</guimenu><guisubmenu>Multimedia</guisubmenu><guimenuitem>&kmix; Sound Mixer</guimenuitem></menuchoice>.</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>
<member>No automatic volume saving. If you want your volumes saved when you logout for later restauration, you must also start &kmix; from the K-Menu.</member>
</simplelist>

</para>
</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 <userinput><command>dcop kmix</command></userinput> to start exploring the &kmix; &DCOP; interface.
The &kmix; specific interfaces are:</para>

<variablelist>
<varlistentry>
<term><userinput><command>Mixer0</command></userinput></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 <userinput><command>dcop kmix Mixer0</command></userinput> if you want to explore all the features. There are more entries like <userinput><command>Mixer1</command></userinput> in case multiple soundcards are installed.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput><command>kmix-mainwindow#1</command></userinput></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 <userinput><command>dcop kmix kmix-mainwindow#1</command></userinput> if you want to explore all the features.</para></listitem>
</varlistentry>
</variablelist>

</sect1>


<sect1 id="dcop-examples">
<title>&DCOP; Examples</title>

<variablelist>
<varlistentry>
<term><userinput><command>dcop kmix kmix-mainwindow#1 hide</command></userinput></term>
<listitem><para>Hides the &GUI; window. Use <userinput><command>dcop kmix kmix-mainwindow#1 show</command></userinput> or the dock icon to show it again.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput><command>dcop kmix kmix-mainwindow#1 resize 1 1</command></userinput></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><userinput><command>dcop kmix Mixer0 mixerName</command></userinput></term>
<listitem><para>Tells the name of the first Mixer, for example <computeroutput>Sound Fusion CS46xx</computeroutput>.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput><command>dcop kmix Mixer1 setVolume 0 10</command></userinput></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 <userinput><command>dcop kmix Mixer1 setMasterVolume 0</command></userinput></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 <envar>DCOPSERVER</envar> environment variable (as seen in the first line of your <filename>~/.DCOPserver_hostname_:0</filename> file), for example:</para>

<programlisting>
#!/bin/sh
DCOPSERVER=`cat /home/yourhome/.DCOPserver_yourhostname_:0 | grep local`
export DCOPSERVER
dcop kmix Mixer0 setMasterVolume 0
</programlisting>
</sect1>

<sect1 id="tips-and-tricks">
<title>Tips and Tricks</title>
<sect2>
<title>Using ALSA and OSS driver at the same time</title>
<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 <filename>kmixrc</filename> file in the global configuration section.</para>
<programlisting>MultiDriver=true</programlisting>
<para>Start &kmix; again. If you click <menuchoice><guimenu>Help</guimenu><guimenuitem>Hardware Information</guimenuitem></menuchoice> you should see <guilabel>Sound drivers used: ALSA0.9 + OSS</guilabel> and <guilabel>Experimental multiple-Driver mode activated</guilabel>.</para>

<warning><para>You will probably see all of your mixers doubled.</para>
<para>There is no support for this kind of configuration.</para></warning>
</sect2>

</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 &amp; Stefan Schimanski</para></listitem>
<listitem><para>Copyright 2003-2005 Christian Esken &amp; 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;
&Matt.Johnston.mail;</para>

<para>Updated 2003 to match &kmix; V1.91 by Christian Esken
<email>esken@kde.org</email></para>

<para>Updated 2005 to match &kmix; V2.2 by Christian Esken
<email>esken@kde.org</email></para>

<para>Updated 7/2005 to match &kmix; V2.6 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>