Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdemultimedia@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

2 files changed, 1342 insertions, 0 deletions

diff --git a/doc/kmid/Makefile.am b/doc/kmid/Makefile.am
new file mode 100644
index 00000000..085981d9
--- /dev/null
+++ b/doc/kmid/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/kmid/index.docbook b/doc/kmid/index.docbook
new file mode 100644
index 00000000..6670dd54
--- /dev/null
+++ b/doc/kmid/index.docbook
@@ -0,0 +1,1338 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+ <!ENTITY kappname "&kmid;">
+ <!ENTITY package "kdemultimedia">
+ <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+ <!ENTITY % addindex "IGNORE">
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &kmid; Handbook</title>
+<authorgroup>
+<author>
+<firstname>Antonio</firstname>
+<surname>Larrosa Jim&eacute;nez</surname>
+<affiliation>
+<address><email>larrosa@kde.org</email></address>
+</affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>1999</year><year>2001</year>
+<holder>Antonio Larrosa Jim&eacute;nez</holder>
+</copyright>
+
+<date>2002-02-05</date>
+<releaseinfo>2.00.00</releaseinfo>
+
+<abstract>
+<para>
+&kmid; is a midi/karaoke multimedia player
+</para>
+</abstract>
+
+<keywordset>
+<keyword>KMid</keyword>
+<keyword>midi</keyword>
+<keyword>karaoke</keyword>
+<keyword>multimedia</keyword>
+<keyword>mid</keyword>
+<keyword>kar</keyword>
+<keyword>player</keyword>
+<keyword>music</keyword>
+<keyword>sound</keyword>
+<keyword>fm</keyword>
+<keyword>awe</keyword>
+<keyword>gus</keyword>
+</keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>
+&kmid; is &kde;'s midi and karaoke multimedia player. It features some
+features not found in any other &UNIX; midi player, such as realtime
+graphics and karaoke text highlighting among others.
+</para>
+
+<para>
+&kmid; has been reported to run on &Linux; and FreeBSD operating
+systems. It uses the <acronym>OSS</acronym> sound driver, so it should
+run on every system where &kde; and <acronym>OSS</acronym>
+compile. &kmid; also supports the &Linux; Ultrasound Project Driver ,
+which is required to get sound in <acronym>GUS</acronym> cards. I plan
+to support the <acronym>ALSA</acronym> driver as soon as it supports a
+sequencer device.
+</para>
+
+<para>
+&kmid; shows the lyrics in the screen changing its color at the same
+time the music is playing, so it is very easy to follow the tune of the
+songs.
+</para>
+
+<para>
+Hope you find &kmid; as fun to use as I found developing it.
+</para>
+
+<para>
+Antonio Larrosa Jim&eacute;nez <email>larrosa@kde.org</email>
+</para>
+
+<sect1 id="kmids-features">
+<title>&kmid;'s features</title>
+
+<para>
+These are some of &kmid;'s main features:
+</para>
+      
+<itemizedlist>
+<listitem>
+<para>
+It has a very <emphasis>friendly user interface</emphasis> to display karaoke
+text with <emphasis>realtime highlighting</emphasis> of lyrics.
+</para>
+</listitem>
+<listitem>
+<para>
+It features a graphical view of what is being played on each midi channel, by
+highlighting the keys pressed in (virtual) keyboards.
+</para>
+</listitem>
+<listitem>
+<para>
+The most powerful <emphasis>Midi Mapper</emphasis> that you will ever find in
+any operating system.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>Drag &amp; drop</emphasis> so you can drop in &kde; any midi file from a
+&konqueror; window.
+</para>
+</listitem>
+<listitem>
+<para>
+You can <emphasis>change the tempo</emphasis> of songs to play them slower or
+faster at your wish.
+</para>
+</listitem>
+<listitem>
+<para>
+It shows lights to follow the rhythm of the song.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>Customizable fonts</emphasis> for karaoke text to be displayed.
+</para>
+</listitem>
+<listitem>
+<para>
+Supports the two standards to introduce lyrics in midi files, that is, lyrics or
+text events (and guess which one a song uses automatically).
+</para>
+</listitem>
+<listitem>
+<para>
+Session Management. If a song is playing while you logout from &kde;, the next
+time you login, the same song will start playing.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>Adjustable volume</emphasis> in realtime.
+</para>
+</listitem>
+<listitem>
+<para>
+It can play broken midi files which make other players core dump!
+</para>
+</listitem>
+<listitem>
+<para>
+It can open <emphasis>gzipped midi/karaoke files</emphasis> just as any other
+file.
+</para>
+</listitem>
+<listitem>
+<para>
+Consumes approximately <emphasis>0.1&percnt;</emphasis> of my
+<acronym>CPU</acronym> (depends on the complexity of the song).
+</para>
+</listitem>
+<listitem>
+<para>
+Supports external midi synths, <acronym>AWE</acronym>, <acronym>FM</acronym> and
+<acronym>GUS</acronym> cards (for the latter you need the <acronym>LUP</acronym>
+driver and gusd installed).
+</para>
+</listitem>
+<listitem>
+<para>
+Runs on &Linux; and FreeBSD (maybe also other unices ...).
+</para>
+</listitem>
+</itemizedlist>
+
+</sect1>
+</chapter>
+
+<chapter id="general-usage">
+<title>General usage</title>
+
+<sect1 id="opening-songs">
+<title>Opening songs</title>
+
+<para>
+You can open a song several different ways.
+</para>
+
+<para>
+First, you can select <guimenuitem>Open...</guimenuitem> from the
+<guimenu>File</guimenu> menu, then you are presented with a standard
+open dialog, with which you can select the song you wish to open.
+</para>
+
+<para>
+You can drag a file from a &konqueror; window and drop it in the &kmid; window.
+You can also Drag &amp; Drop multiple songs at the same time.
+</para>
+
+<para>
+If you specify a song in the command line when running &kmid;, it will also be
+opened.
+</para>
+
+<para>
+And the final way is by selecting the song from the list of songs of the active
+collection.
+</para>
+
+</sect1>
+
+<sect1 id="playing-songs">
+<title>Playing songs</title>
+
+<para>
+To play a song, first open it, and then press on the
+<guiicon>Play</guiicon> button of the toolbar, choose the
+<guimenuitem>Play</guimenuitem> entry of the <guimenu>Song</guimenu>
+menu, or just press the <keycap>Space</keycap> key.
+</para>
+
+<para>
+Note that when you open a file using Drag &amp; Drop, &kmid; will start
+playing it automatically (if you drop more than one file, they will be
+added to a collection and they will be played sequentially).
+</para>
+
+<para>
+Once &kmid; is playing a song, you can move the time slider, by pressing
+with the &MMB; mouse button, to go to a specified position.
+</para>
+
+<para>
+If a song is playing too fast or too slow for you, you can press on the
+arrows at both sides of the tempo <acronym>LCD</acronym> and make it
+play faster or slower. To get back to the default tempo, just do a
+double click on the tempo <acronym>LCD</acronym>.
+</para>
+
+<para>
+The <keycap>Space</keycap> key is used for two things, when music is
+playing, and you press the <keycap>Space</keycap> key, it will act as
+when you press on the <guiicon>pause</guiicon> button or the
+<guimenuitem>Pause</guimenuitem> entry of the <guimenu>Song</guimenu>
+menu, that is, it will pause music.  If you press the
+<keycap>Space</keycap> key when no music is being played, &kmid; will
+play it.
+</para>
+
+</sect1>
+
+<sect1 id="displaying-lyrics">
+<title>Displaying lyrics</title>
+
+<para>
+There are two methods to store lyrics in a song, by using
+<guimenuitem>Text events</guimenuitem> or <guimenuitem>Lyrics
+events</guimenuitem>, some songs use the first, some the second, some
+use both of them, and some don't include lyrics :-)
+</para>
+
+<para>
+&kmid; lets you choose which events to display, and even better, it has
+an option to automatically select the type of events that a song uses,
+so that you don't have to change the type manually . That way, if you
+activate the <guimenuitem>Automatic Text Chooser</guimenuitem> entry of
+the <guimenu>Settings</guimenu> menu, the karaoke text will be
+automatically selected, but you can still change them if you prefer to
+see the other type.
+</para>
+
+<para>
+To select which type to see, you can use the appropriate entries in the
+<guimenu>Settings</guimenu> menu, or just press the <keycap>1</keycap>
+and <keycap>2</keycap> keys of your keyboard to see the
+<guimenuitem>Text events</guimenuitem> or <guimenuitem>Lyrics
+events</guimenuitem> respectively.
+</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="collections">
+<title>Collections</title>
+
+<para>
+A collection is a list of midi files that you put in a set, and which
+are played one after another. This section will help you to use them,
+and will give you some useful tips to make a good use of them.
+</para>
+
+<sect1 id="creating-a-collection">
+<title>Creating a collection</title>
+
+<para>
+To create a collection, first open the <guilabel>Collections
+Manager</guilabel> dialog, by selecting the <guimenuitem>Organize
+...</guimenuitem> entry of the <guimenu>Collections</guimenu> menu .
+Then click on the <guibutton>New</guibutton> button, and enter the name
+you want the collection to have.
+</para>
+
+<para>
+You can also copy a complete collection by selecting it and then
+pressing the <guibutton>Copy</guibutton> button, which will ask you for
+the name of the new collection that will have initially the same songs
+as the selected collection.
+</para>
+
+<para>
+Once you have more than one collection, you can change the active
+collection from the <guilabel>Collections Manager</guilabel>, by
+selecting it.
+</para>
+
+</sect1>
+<sect1 id="the-temporary-collection">
+<title>The Temporary Collection</title>
+
+<para>
+The Temporary Collection is a collection that is used to hold songs you
+want to play but that you don't want to add to any collection.
+</para>
+
+<para>
+This collection is <emphasis>not saved</emphasis> on exit of the
+application, so keep it in mind when you add lots of songs to it.
+</para>
+
+<para>
+Keep on reading this section for a better understanding of the Temporary
+Collection.
+</para>
+
+</sect1>
+
+<sect1 id="adding-songs-to-a-collection">
+<title>Adding songs to a collection</title>
+<subtitle>How to use <guimenuitem>AutoAdd to a
+collection</guimenuitem></subtitle>
+
+<para>
+There are some different ways to add a song to a collection.
+</para>
+
+<para>
+First of all in each method, you must have selected the collection you
+want to add songs to in the <guilabel>Collections Manager</guilabel>.
+Then you can press on the <guibutton>Add</guibutton> button to add a
+song, there will appear an open file dialog so that you can choose which
+song to add.
+</para>
+
+<para>
+The other methods to add a song depend on the state of the
+<guimenuitem>AutoAdd to Collection</guimenuitem> option.
+</para>
+
+<para>
+If <guimenuitem>AutoAdd to Collection</guimenuitem> is enabled, when
+you open a song (using <menuchoice><guimenu>File</guimenu>
+<guimenuitem>Open...</guimenuitem></menuchoice> or Drag &amp; Drop) it
+(they) will be added to the active collection without user intervention.
+</para>
+
+<para>
+If <guimenuitem>AutoAdd to Collection</guimenuitem> is not enabled,
+when you open a song the Temporary Collection will be activated and
+cleared, and the opened songs will be added to it.
+</para>
+
+</sect1>
+
+<sect1 id="removing-songs-from-collections">
+<title>Removing songs from collections</title>
+
+<para>
+To delete a song from a collection, just open the <guilabel>Collection
+Manager</guilabel>, select the appropriate collection, and the song you
+wish to delete, and then click on the <guibutton>Remove</guibutton>
+button.
+</para>
+
+</sect1>
+
+<sect1 id="playing-order">
+<title>Playing in order or at random</title>
+
+<para>
+You can select the order in which songs will be played . When you select
+<guimenuitem>In order</guimenuitem> mode from the <guisubmenu>Play
+Order</guisubmenu> submenu of the <guimenu>Collections</guimenu> menu,
+songs will be played in the same order in which they were added to the
+collection.
+</para>
+
+<para>
+When you select <guimenuitem>Shuffle</guimenuitem> mode, &kmid; will
+generate a random variable with a discrete uniform distribution to
+really play randomly the songs in the collection .  It will give values
+to that random variable while generating the list in which order the
+songs will be played (you surely want to play random songs, but don't
+want to play twice the same song, and you want to play the last played
+song when you press on the <guibutton>Previous Song</guibutton> button,
+don't you ? :-) ).
+</para>
+
+<para>
+The random list in which the collection will be played will be
+regenerated each time you add or remove a file in the active collection,
+and when you press on the <guimenuitem>Shuffle mode</guimenuitem> entry
+of the menu.
+</para>
+
+</sect1>
+
+<sect1 id="selecting-from-a-collection">
+<title>Selecting a song from a collection</title>
+
+<para>
+You can select a song to play in the <literal>Collection
+Manager</literal>, or by using the combo box over the karaoke text.
+</para>
+
+<para>
+You can also change to the next song by using the <literal>Next
+Song</literal> entry of the <literal>Song</literal> menu, the
+<literal>Next Song</literal> button of the toolbar, or pressing the
+<literal>right arrow</literal> key.
+</para>
+
+<para>
+To change to the previous song, use the <guimenuitem>Previous
+Song</guimenuitem> entry of the <guimenu>Song</guimenu> menu, the
+<guimenuitem>Previous Song</guimenuitem> button of the toolbar, or press
+the <keycap>left arrow</keycap> key of your keyboard.
+</para>
+
+</sect1>
+
+<sect1 id="deleting-a-collection">
+<title>Deleting a collection</title>
+
+<para>
+To delete a collection, simply open the <guilabel>Collection
+Manager</guilabel>, select the collection you want to delete, and click
+on <guibutton>Delete</guibutton>. Easy, it isn't?  </para>
+
+<para>
+Please keep in mind that you cannot delete the Temporary Collection, but
+it doesn't matter as it is not saved when you quit &kmid;.
+</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="midi-maps">
+<title>Midi Maps</title>
+
+<sect1 id="what-is-a-midimap">
+<title>What is a midi map ?</title>
+
+<para>
+A Midi Map is something that maps midi events in other midi events.
+</para>
+
+<para>
+This is totally needed if a synthesizer doesn't understand the standard
+events (that is, if a synthesizer is not General Midi compliant), in
+this case, a midi map will translate General Midi events in the events
+that that synthesizer understands.
+</para>
+
+<para>
+For example you can make a midi map that converts all the
+<literal>Change patch to Bright Piano</literal> events, to
+<literal>Change patch to Trumpet</literal> events, and so when a song
+tries to play a piano, it will play a trumpet instead.
+</para>
+
+<para>
+This may sound odd, (why playing a trumpet when the song is made to play
+a piano?), but it is very useful. The <acronym>GM</acronym> standard
+specifies that when a midi keyboard receives an event to change patch to
+<literal>0</literal>, it will change the current patch to <literal>Grand
+Piano</literal>, but older synthesizer will change for example to a
+<literal>Electric Guitar</literal> when it receives a
+<literal>0</literal>. This old keyboard, needed to receive a
+<literal>3</literal> (for example) to change to a
+<literal>Piano</literal>. And here comes the midi map in action,
+changing all <literal>change patch to 0</literal> to <literal>change
+patch to 3</literal> and thus really playing the correct instrument when
+it has to.
+</para>
+
+</sect1>
+
+<sect1 id="do-i-need-a-midi-map">
+<title>Do I need a midi map ?</title>
+
+<para>
+In short, if you don't have an external synth, <emphasis>no</emphasis>!
+</para>
+
+<para>
+If you only have a sound card, midi maps are not needed because all the
+sound cards are <acronym>GM</acronym> compliant (this include AWE cards,
+<acronym>GUS</acronym> cards, <acronym>FM</acronym> devices and so on).
+</para>
+
+<para>
+If you are playing music through an external synthesizer, and it is not
+GM compliant, you will need to make a midi map for your midi keyboard .
+Although you will perhaps be a whole afternoon doing your map file and
+trying different values for all the options, you will be fully rewarded
+when you finish it, because then you will find all the hidden
+possibilities of your keyboard. For example, I have a low-cost Yamaha
+PSS-790, which is not <acronym>GM</acronym> compatible, and doesn't has
+as many instruments as a <acronym>GM</acronym> synthesizer, but with
+&kmid;'s midi mapper, it sounds even better than many soundcards
+(including AWE :-)), due to the sound quality found in external synths
+(even on non <acronym>GM</acronym> compliant ones).
+</para>
+
+</sect1>
+
+<sect1 id="creating-a-midi-map">
+<title>Creating a midi map</title>
+
+<para>
+There isn't any program to generate midi maps, so you will have to edit a file
+by hand (using your favorite text editor).
+</para>
+
+<para>
+A Midi map is a text file that keeps all the needed translations there will be
+made when playing music.
+</para>
+
+<para>
+It consist of four sections: <literal>PATCHMAP</literal>,
+<literal>KEYMAP</literal>, <literal>CHANNELMAP</literal> and
+<literal>OPTIONS</literal>.
+</para>
+
+<para>
+Each section must appear only once, except the <literal>KEYMAP</literal> section
+that can appear as many times as needed, provided that each appearance use a
+different TextID (continue reading for details).
+</para>
+
+<para>
+The general structure of a map file is:
+</para>
+
+<screen>DEFINE PATCHMAP
+...
+END
+
+DEFINE KEYMAP "Name of Keymap"
+...
+END
+
+DEFINE KEYMAP "Another Keymap"
+...
+END
+
+DEFINE CHANNELMAP
+...
+END
+
+OPTIONS
+...
+END
+</screen>
+
+<para>
+You can see that the <literal>DEFINE</literal> word is used to specify
+which section is going to be started (except for
+<literal>OPTIONS</literal>), and <literal>END</literal> is put at the
+end of each section.  </para>
+
+<para>
+You can put comments by starting the line with a
+<literal>&num;</literal> character.
+</para>
+
+<para>
+Please, don't forget to send me your map file by email, so that future
+releases of &kmid; will include support for more non General Midi
+compliant keyboards.
+</para>
+
+<sect2 id="the-patchmap-section">
+<title>The <literal>PATCHMAP</literal> section</title>
+
+<para>
+This section is used to specify how patches are going to be mapped, from
+GM to your keyboard specs . The general usage is:
+</para>
+
+<screen>(Name of GM Patch name)=(<replaceable>N</replaceable>) [AllKeysTo M]
+</screen>
+
+<para>
+Where <replaceable>N</replaceable> is the number that you keyboard needs to
+receive to change the patch to the same that the GM standard does .
+</para>
+
+<para>
+Please note that the left side of the equal sign is ignored, so
+<acronym>GM</acronym> patches are supposed to be in order (from 0 to 127) , and
+so you are not allowed to change the order of the lines nor to omit any of the
+128 instruments.
+</para>
+
+<para>
+The optional <literal>AllKeysTo M</literal> is used to map all notes
+that use that instrument to the <literal>M</literal> key . For example,
+suppose that your midi keyboard doesn't have a Gun Shot sound (GM patch
+127) so you want to map it to a percussion drum (i.e. key 60), which
+sounds similar to a gun shot, then you can put in the 127th line of the
+<literal>PATCHMAP</literal> section:
+</para>
+
+<screen>Gunshot       =100 AllKeysTo 60</screen>
+
+
+<para>
+So when a midi file tries to play a note with the patch 127 (gun shot), it will
+be mapped to the patch 100 (your keyboard's percussion patch) and play the note
+60 (independently of the key that was going to be played).
+</para>
+
+<para>
+Please note that when I use the expression <quote>Percussion patch</quote>, I
+mean the patch in which each key plays a different drum, cymbal, tom, maracas
+and so on, and not to a possible sound which some keyboards have and which plays
+a different tone of the same drum with each key.
+</para>
+
+</sect2>
+
+<sect2 id="The-keymap-section">
+<title>The <literal>KEYMAP</literal> section</title>
+
+<para>
+The <literal>KEYMAP</literal> section is used to specify how keys are
+going to be mapped, within a given channel or instrument . The usage is:
+</para>
+
+<screen>DEFINE KEYMAP "Name of Keymap"
+C 0 =0
+C#0 =1
+D 0 =2
+...
+END
+</screen>
+
+<para>
+As with the <literal>PATCHMAP</literal> section, it is very important
+the order of the lines, and that they are all there (the 128 keys).
+</para>
+
+<para>
+As you can define multiple keymaps for different channels and instruments,
+you must give a different name to each one in the first line.
+</para>
+
+<para>
+Keymaps are mainly used to map keys in the percussion channel . Have a
+look at the distributed maps to see some examples.
+</para>
+
+</sect2>
+
+<sect2 id="the-channelmap-section">
+<title>The <literal>CHANNELMAP</literal> section</title>
+
+<para>
+This section can be used to map some channels to different ones . For
+example, if you want to swap the first and second channels, you can
+easily do it within the <literal>CHANNELMAP</literal> section.
+</para>
+
+<para>
+However it is more useful for keyboards that need the percussion
+channel to be in a given channel (the GM standard use the channel 10,
+others use the channel 16 and others use channel 9).
+</para>
+
+<para>
+Note that midi devices use 16 channels, so the <literal>CHANNELMAP</literal>
+section, has 16 lines, from 0 to 15 , as this one:
+</para>
+
+<screen>(N) = (M) [Keymap "Name"] [ForcePatch x]
+</screen>
+
+<para>
+Where <literal>N</literal> is the channel which is mapped to the
+<literal>M</literal> channel .  If the <literal>Keymap</literal> option
+is used, the Keymap with name <literal>Name</literal> will be used in
+this channel (this Keymap should be defined earlier in the map file !) .
+If the <literal>ForcePatch</literal> option is used, all events that try
+to change the patch which is used in this channel will be ignored, and
+patch <literal>x</literal> will be used instead.
+</para>
+
+<para>
+The <literal>ForcePatch</literal> option may be useful for example to
+always use the percussion patch on the percussion channel.
+</para>
+
+</sect2>
+
+<sect2 id="the-options-section">
+<title>The <literal>OPTIONS</literal> section</title>
+
+<para>
+The <literal>OPTIONS</literal> section has some general options that can
+be very useful:
+</para>
+
+<screen>OPTIONS
+PitchBenderRatio = r
+MapExpressionToVolumeEvents
+END
+</screen>
+
+<para>
+You can specify both options, only one, or none of them.
+</para>
+
+<para>
+The <literal>PitchBenderRatio r</literal> value, has the ratio by which
+pitch bender events will be multiplied . That is, when a midi file tries
+to send a pitch bender event with a <literal>n</literal> value, the real
+value that will be sent is <literal>n*(r/4096)</literal> (the
+<literal>4096</literal> value is for not having to put decimal points in
+the map file).
+</para>
+
+<para>
+This is used because the <acronym>GM</acronym> standard says that when a
+midi keyboard receives a Pitch Bender event with a 4096 data value, it
+should bend the note to a higher one , but some midi keyboards try to
+bend the initial note by two or more higher notes (even an octave
+higher!) when they receive a 4096 .  This can be easily fixed by trying
+different values so that instead of sending a 4096, KMid sends the
+appropriate value.
+</para>
+
+<para>
+When the <literal>MapExpressionToVolumeEvents</literal> option is set in
+the map file, and a midi file try to send an expression event, KMid will
+send a volume event which is understood by more non-GM keyboards, and
+which has a similar effect .  There are many midi files which use
+expression events to fade out at the end of a song, so if you feel that
+music should be heard softer and softer, you can turn on this option and
+see if this is what you need, because your midi synthesizer could be
+ignoring the expression events because it doesn't understand them.
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="using-midimaps">
+<title>Using midi maps</title>
+
+<para>
+To use a midi map, simply open the <guilabel>Midi Setup</guilabel>
+dialog by selecting the <guimenuitem>Midi Setup ...</guimenuitem> entry
+of the <guimenu>Settings</guimenu> menu.
+</para>
+
+<para>
+Then click on <guilabel>Browse ...</guilabel>, select the map file within the open
+file dialog and enjoy the music ! :-)
+</para>
+</sect1>
+</chapter>
+
+<chapter id="advanced-features">
+<title>Advanced features</title>
+
+<sect1 id="the-channel-view">
+<title>The Channel View</title>
+
+<para>
+The Channel view is a window where you are shown a heap of keyboards (one for
+each midi channel). In these keyboards, the notes that are being played with
+each instrument are highlighted so that you can see what is each instrument
+playing.
+</para>
+
+<sect2 id="changing-instruments">
+<title>Changing instruments</title>
+
+<para>
+You can use the Channel View to change the instrument that each channel is
+playing. In each channel there is a combo box where you can select it. Once you
+change it, the green button next to it will change to red to indicate that this
+is not the default instrument.
+</para>
+
+<para>
+If you want to set again the default instrument, click on the red button, and it
+will be automatically set.
+</para>
+
+</sect2>
+
+<sect2 id="changing-the-look">
+<title>Changing the look mode</title>
+
+<para>
+The Channel View has two different ways (for now) to display the played notes,
+you can select them from the <guimenuitem>Channel View Options...</guimenuitem>
+item in the <guimenu>Settings</guimenu> menu.
+</para>
+
+<para>
+You can choose between a mode in which played keys are pressed, as if it were a
+normal piano (<guilabel>3D look</guilabel>), or a mode in which keys are also
+filled with red color, so that pressed keys are easily recognized (<guilabel>3D
+- filled</guilabel>). If you play the piano, or any other music instrument, you
+can use this view to learn to play a song by yourself. I've used this technique
+and it (along with a tempo reduction) is great to 
+learn new compositions.
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="the-tempo-lcd">
+<title>The Tempo <acronym>LCD</acronym></title>
+
+<para>
+This shows the tempo in which a song is played, that is, the velocity of the
+song. The higher this number is, the faster the song will play.
+</para>
+
+<para>
+You can also change the tempo of the song, so if a song plays too fast for you
+to follow the lyrics, you can make it play slower. To change the tempo, you can
+use the arrows that appear at each sides of the <acronym>LCD</acronym>.
+</para>
+
+<para>
+Once you have changed the tempo, you can get back the default one by doing a
+double click on the <acronym>LCD</acronym>.
+</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="key-bindings">
+<title>Key bindings</title>
+
+<informaltable>
+<tgroup cols="2">
+<thead>
+<row>
+<entry>Key</entry>
+<entry>Action</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><keycap>Space</keycap></entry>
+<entry>Play the loaded song, if it isn't playing, or pause it, if it's already
+playing.</entry>
+</row>
+<row>
+<entry><keycap>Backspace</keycap></entry>
+<entry>Stop playing</entry>
+</row>
+<row>
+<entry><keycap>Right Arrow</keycap></entry>
+<entry>Next song in current collection</entry>
+</row>
+<row>
+<entry><keycap>Left Arrow</keycap></entry>
+<entry>Previous song in current collection</entry>
+</row>
+<row>
+<entry><keycap>Up Arrow</keycap></entry>
+<entry>Scroll lyrics one line up</entry>
+</row>
+<row>
+<entry><keycap>Down Arrow</keycap></entry>
+<entry>Scroll lyrics one line down</entry>
+</row>
+<row>
+<entry><keycap>Page Up</keycap></entry>
+<entry>Scroll lyrics one page up</entry>
+</row>
+<row>
+<entry><keycap>Page Down</keycap></entry>
+<entry>Scroll lyrics one page down</entry>
+</row>
+<row>
+<entry><keycap>1</keycap></entry>
+<entry>Display text events</entry>
+</row>
+<row>
+<entry><keycap>2</keycap></entry>
+<entry>Display lyric events</entry>
+</row>
+<row>
+<entry><keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo></entry>
+<entry>Open a song</entry>
+</row>
+<row>
+<entry><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></entry>
+<entry>Quit &kmid;</entry>
+</row>
+<row>
+<entry><keycap>F1</keycap></entry>
+<entry>Open this document</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+</chapter>
+
+<chapter id="frequently-asked-questions">
+<title>Frequently Asked Questions (FAQ)</title>
+
+<qandaset>
+<qandaentry>
+<question>
+<para>
+What is exactly a midi file?
+</para>
+</question>
+
+<answer>
+<para>A Midi file is a file that contains the information on how to play
+a song, that is, it contains simply the notes, the rhythm,
+velocity,&etc; This implies that the same midi file, when played in two
+different devices, can produce very different results, as well as a
+given staff can be played very differently by two different musicians.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+I can get better sound with a mp3/wav player, why should I use &kmid;?
+</para>
+</question>
+<answer>
+<para>
+Well, I cannot force anyone to use &kmid;, but a typical midi file
+occupies 50 Kb. while a typical mp3 file occupies 4 Mb. (and that is a
+1:80 compression ratio :-) . And with a good synthesizer device, you can
+get a comparable sound quality. Even more, with a midi file, you can
+change individual instruments, change the velocity of a song, &etc; so
+you have more overall control.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+I can't get my AWE card to work with KMid, what can I do?
+</para>
+</question>
+<answer>
+<para>
+This can happen when you get a binary distribution (rpm, deb) of &kmid;. It
+happens because &kmid; was compiled without awe support. If it doesn't 
+work, then you must download a source code distribution (for example, from
+<ulink url="http://www.arrakis.es/~rlarrosa/kmid.html">&kmid;'s homepage</ulink>)
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+I want to add a whole folder to a collection, but having to add the midi
+files one by one is not funny.
+</para>
+</question>
+
+<answer>
+<para>
+I agree, that's why &kmid; supports Drag &amp; Drop. Just open, in &konqueror;,
+the folder you want to add, select all the files, drag them and drop them in
+&kmid;.
+</para>
+<para>
+Be sure to set the <guimenuitem>AutoAdd to Collection</guimenuitem> option before, so that the
+files will be added to the current collection. If you don't do this, files will
+be added to the Temporary Collection.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+I can't follow the lyrics, it's playing too fast!
+</para>
+</question>
+<answer>
+<para>
+You can press the left arrow of the tempo <acronym>LCD</acronym> to make it play
+slower. Remember that you can do a double click on the <acronym>LCD</acronym> to
+get the default tempo.
+</para> 
+</answer>
+</qandaentry>
+</qandaset>
+
+</chapter>
+
+<chapter id="final-notes">
+<title>Final notes</title>
+
+<sect1 id="some-tips-and-tricks">
+<title>Some tips and tricks</title>
+
+<para>
+I will include some tips so that you can take fully advantage from all
+the features of &kmid;:
+</para>
+
+<variablelist>
+<varlistentry>
+<term>Opening files</term>
+<listitem>
+<para>I always keep a &kde; desktop with a &konqueror; window in my root
+midi folder, and &kmid; in this desktop (if playing a midi file) or
+sticky (if playing a karaoke file :-)). This way, when the active
+collection finishes, or I want to play some file, I just go to the
+konqueror; window, select the desired files and Drag &amp; Drop to the
+&kmid;'s window.
+</para>
+
+<para>
+Suppose that you want to play some midi files, but don't want to add
+them to any collection, well, just turn off the <guimenuitem>AutoAdd to
+Collection</guimenuitem> option in the <guimenu>Collections</guimenu>
+menu, and open the files, they will be added to the Temporary
+Collection.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Another method to create a new Collection</term>
+<listitem>
+<para>
+Suppose that you have midi files <filename>A.mid</filename>,
+<filename>B.mid</filename> and <filename>C.mid</filename>. At first you
+only want to play the first midi file, so you unselect
+<guimenuitem>AutoAdd</guimenuitem> and open
+<filename>A.mid</filename>. You get then a Temporary Collection with
+only one midi file.
+</para>
+<para>
+Then you decide to play also B and C, and make a collection with all them, what
+do you do?
+</para>
+<para>
+Easy, select <guimenuitem>AutoAdd</guimenuitem> and open
+<filename>B.mid</filename> and <filename>C.mid</filename> (by any of the
+multiple methods), they will be automatically added to the Temporary
+Collection, that will then have <filename>A.mid</filename>,
+<filename>B.mid</filename> and <filename>C.mid</filename>. At this
+point, you can open the <guilabel>Organize Collections</guilabel>
+dialog, select the Temporary Collection, and click on the
+<literal>Copy</literal> button, enter the name of the new collection,
+and you are done .  You already have a new collection, which holds the
+A,B and C midi files, and that is not deleted when you close &kmid;.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="hall-of-kmids-friends">
+<title>Hall of &kmid;'s friends</title>
+
+<para>
+These are some folks who have sent me midi files or a postcard, thanks
+to everyone!  Hearing those songs and watching those postcards will keep
+me programming more and more on &kmid;.
+</para>
+
+<itemizedlist>
+<listitem>
+<para>Ola Sigurdson  - <literal>Taking Care of Business</literal> (Bachman
+Turner Overdrive)</para>
+</listitem>
+<listitem>
+<para>EG Lim - A really very nice postcard from Penang.</para>
+</listitem>
+<listitem>
+<para>Guenther Starnberger - <literal>Amadeus</literal> (Falco) and
+<literal>Schrei Nach Liebe</literal> (Die Aerzte)</para>
+</listitem>
+<listitem>
+<para>Leandro Terr&eacute;s - <literal>All That She Wants</literal> and
+<literal>The Sign</literal> (Ace of Base)</para>
+</listitem>
+<listitem>
+<para>Nick Stoic - Two midi files</para>
+</listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="about-the-author">
+<title>About the author</title>
+
+<para>
+&kmid; has been made by Antonio Larrosa Jim&eacute;nez, in M&aacute;laga
+(Spain).  I am a student of Mathematics at the University of
+M&aacute;laga, currently I'm doing the third course, so I don't have
+much free time for my hobbies, but I always try to get some :-) . My
+hobbies include : Programming, collecting midi files, playing music and
+proving theorems ;-).
+</para>
+
+<para>
+If you  want to know where to  download midi/karaoke files, you have any
+question,  a bug to report, an  idea or a feature  you'd  like to see in
+&kmid; or just want to make me happy, feel free  to send me an email to:
+<email>larrosa@kde.org</email> or <email>antlarr@arrakis.es</email>
+</para>
+
+<para>or write to me by snail-mail at:
+</para>
+
+<literallayout> Antonio Larrosa Jimenez
+Rio Arnoya 10 5B
+Malaga (Spain)
+</literallayout>
+
+<para>
+You will really make me happy if you send me a postcard from where you
+live, or a midi/karaoke file from a local music group of your country
+. Everyone who sends me a postcard or a midi file will have his/her name
+in the Hall of &kmid;'s friends of this file (provided they don't oppose
+to this). Please contact me before sending me any midi files because I
+may have it already.
+</para>
+
+<para>
+I'd like stress that &kmid; has been done completely on free time,
+without any monetary support from any company nor particular. So please
+keep in mind when you use it, that the only think that keep me working
+on this is getting some feedback from its users (a postcard, or just an
+email).
+</para>
+
+<para>
+I would like to thanks the following persons their help in developing &kmid;:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>
+Paul J. Leonard <email>P.J.Leonard@bath.ac.uk</email> - Support for AWE
+cards
+</para>
+</listitem>
+<listitem>
+<para>
+Sebestyen Zoltan <email>szoli@digo.inf.elte.hu</email>- FreeBSD port and
+AWE testing
+</para>
+</listitem>
+<listitem>
+<para>
+Christian Esken <email>esken@kde.org</email> - For organizing the KDE
+multimedia efforts
+</para>
+</listitem>
+<listitem>
+<para>
+Stephan Kulow <email>coolo@kde.org</email>- Configure scripts and help
+with <command>automake</command> and <command>CVS</command>
+</para>
+</listitem>
+<listitem>
+<para>
+Jaroslav Kysela - Help in doing the &Linux; Ultrasound Project driver
+support
+</para>
+</listitem>
+<listitem>
+<para>
+Takashi Iwai and Joseph H. Buehler    - Fix for AWE cards pitch being
+too high 
+</para>
+</listitem>
+<listitem>
+<para>
+Adrian Knoth     - For giving me good news and many suggestions
+</para>
+</listitem>
+<listitem>
+<para>
+Kevin Street     - Patch to support FreeBSD 3.0
+</para>
+</listitem>
+<listitem>
+<para>
+Thanks go also to Jose Luis Sanchez for his testing of GUS support,
+Ignacio Garcia for testing the AWE support, Hans Petter Bieker, Ola
+Sigurdson, Marc Diefenbruch, Peter Gritsch, Magnus Pfeffer, Urko Lusa,
+Peter-Paul Witta, Thorsten Westheider, Ulrich Cordes and everyone that
+sent me a patch, bug report or just an email to give me encouragement.
+</para>
+</listitem>
+<listitem>
+<para>
+And of course to all the fabulous musicians over the net that keep giving
+us those wonderful midi and karaoke files.
+</para>
+</listitem>
+</itemizedlist>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+</sect1>
+
+<sect1 id="copyright-and-license">
+<title>Copyrights and License</title>
+
+<para>&kmid; is copyright Antonio Larrosa Jim&eacute;nez, 1999-2001</para>
+
+<para>Documentation is copyright Antonio Larrosa Jim&eacute;nez 1999,
+2001</para>
+
+&underFDL;
+&underGPL;
+
+</sect1>
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="how-to-obtain-kmid">
+<title>How to obtain &kmid;</title>
+
+&install.intro.documentation;
+
+<para>
+Additionally, &kmid; can be found on its homepage, which is at <ulink
+url="http://www.arrakis.es/~rlarrosa/kmid.html">
+http://www.arrakis.es/~rlarrosa/kmid.html</ulink>.  In the homepage, you can
+follow its development, see some information about it, some screenshots, a list
+of sites from where you can download more karaoke songs, &etc;
+</para>
+
+</sect1>
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<para>&kmid; requires to work:</para>
+
+<itemizedlist>
+<listitem>
+<para>
+&kde;.  Well, you probably already have this :-)
+</para>
+</listitem>
+<listitem>
+<para>
+A sound card.  A good soundcard and/or external synthesizer are
+recommended, as the sound quality depends greatly in your soundcard,
+it's not the same to play the music using an FM device, than using an
+AWE card.
+</para>
+
+<para>
+If you don't have a soundcard, you can still compile &kmid; with
+<literal>MODE_DEMO_ONLYVISUAL</literal> defined and it will run as if
+you had one (but you'll get no music, of course :-( ).
+</para>
+</listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="compilation-and-installation">
+<title>Compilation and Installation</title>
+
+&install.compile.documentation;
+
+<para>
+I've included some examples that are installed in <filename
+class="directory">$dollar;<envar>KDEDIR</envar>/share/apps/kmid</filename>
+</para>
+
+<para>
+If you run into any problem, don't hesitate to contact any of the &kde; mailing
+list, or send a report directly to me.
+</para>
+
+</sect1>
+
+</appendix>
+
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-omittag: nil
+sgml-shorttag: t
+End:
+-->