<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kmidimon "<application>KMidimon</application>">
  <!ENTITY kappname "&kmidimon;"><!-- Do *not* replace kappname-->
  <!ENTITY package "kmidimon">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<!-- The language must NOT be changed here. -->
<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The &kmidimon; Handbook</title>

<authorgroup>
<author>
<firstname></firstname>
<othername></othername>
<surname>Pedro Lopez&#45;Cabanillas</surname>
<affiliation>
<address><email>plcl&#64;users&#46;sourceforge&#46;net</email></address>
</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2005</year>
<year>2009</year>
<holder>Pedro Lopez&#45;Cabanillas</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>

<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (YYYY-MM-DD) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>2009-06-24</date>
<releaseinfo>0&#46;7&#46;0</releaseinfo>

<abstract>
<para>
&kmidimon; is a MIDI monitor for Linux using ALSA sequencer and KDE user interface.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kmidimon</keyword>
<keyword>ALSA</keyword>
<keyword>Monitoring</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>
There's no exhaustive documentation yet. The provisional homepage can currently 
be found at <ulink url="http://kmidimon.sourceforge.net">
http://kmidimon.sourceforge.net</ulink>.
</para>

<para>
&kmidimon; monitors events coming from a MIDI external port or application via the ALSA sequencer, or stored as Standard MIDI Files. It is especially useful if you want to debug MIDI software or your MIDI setup. It features a nice graphical  user interface,  customizable event filters and sequencer parameters, support for all MIDI messages and some ALSA messages, and saving the recorded event list to a text file or SMF.</para>
</chapter>

<chapter id="getting-started">
<title>Getting Started</title>

<sect1 id="kmidimon-mainwin">
<title>Main Window</title>

<para>The program starts in recording state, registering all incoming MIDI events until you press the stop button. There are also buttons to play, pause, rewind and forward, with the usual behavior of any other media player.</para>

<para>Above the events list grid you can find a set of tabs, one for each track defined in a SMF. You can add new tabs or close tabs without losing the recorded events, because they are only views or event filters.</para>

<para>You can control the ALSA sequencer MIDI connections to programs and devices from inside &kmidimon;. To do so, use the options under the menu "Connections" in the main menu. There are options to connect and disconnect every available input port to &kmidimon;, and also a dialog box where you can choose the ports to be monitored and the output one.</para>

<para>You can also use a MIDI connection tool like <ulink url="http://qjackctl.sourceforge.net/">QJackCtl</ulink> to connect the application or MIDI port to monitor with &kmidimon;</para>
<para>

<screenshot>
<screeninfo>Here's a screenshot of the MIDI Connections window in <command>qjackctl</command></screeninfo>
<mediaobject>
	<imageobject>
	<imagedata fileref="qjackctl.png" format="PNG"/>
	</imageobject>
	<textobject>
	<phrase>MIDI Connections in qjackctl</phrase>
	</textobject>
</mediaobject>
</screenshot>
</para>

<para>When a MIDI OUT port has been connected to the input port of &kmidimon; in recording state, it will show incoming MIDI events if everything is correct.</para>

<para>
<screenshot>
<screeninfo>Here's a screenshot of the main window of &kmidimon; with some MIDI events in it</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kmidimon1.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>MIDI events in the main window of &kmidimon;</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>

<para>
Each received MIDI event is shown in a single row. The columns have the following meaning.
</para>

<itemizedlist>
<listitem>
<para>Ticks: The musical time of the event arrival</para>
</listitem>
<listitem>
<para>Time: The real time in seconds of the event arrival</para>
</listitem>
<listitem>
<para>Source: the ALSA identifier of the MIDI device originating the event. You will be able to recognize what event belongs to which device if you have several connected simultaneously. There is a configuration option to show the ALSA client name instead of a number</para>
</listitem>
<listitem>
<para>Event Kind: The event type: note on / off, control change, ALSA, and so on</para>
</listitem>
<listitem>
<para>Chan: The MIDI channel of the event (if it is a channel event). It is also used to show the Sysex channel.</para>
</listitem>
<listitem>
<para>Data 1: It depends on the type of the received event. For a Control Change event or a Note, it is the control number, or the note number</para>
</listitem>
<listitem>
<para>Data 2: It depends on the type of the received event. For a Control Change it will be the value, and for a Note event it will be the velocity</para>
</listitem>
</itemizedlist>

<para>
You can hide or show any column using the contextual menu. To open this menu, press the secondary mouse button over the event list. You can also use the Configuration dialog to choose the visible columnns.
</para>

<para>The event list always shows newer recorded events at the bottom of the grid.</para>

<para>&kmidimon; can save the recorded events as a text file (in CSV format) or a Standard MIDI File (SMF). </para>

</sect1>

<sect1 id="kmidimon-configuration">
<title>Configuration Options</title>

<para>

<screenshot>
<screeninfo>Here's a screenshot of the Configuration dialog of &kmidimon;</screeninfo>
<mediaobject>
	<imageobject>
	<imagedata fileref="kmidimon2.png" format="PNG"/>
	</imageobject>
	<textobject>
	<phrase>Display settings tab</phrase>
	</textobject>
</mediaobject>
</screenshot>

<screenshot>
<screeninfo>Here's another screenshot of the Configuration dialog of &kmidimon;</screeninfo>
<mediaobject>
    <imageobject>
    <imagedata fileref="kmidimon3.png" format="PNG"/>
    </imageobject>
    <textobject>
    <phrase>Filter settings tab</phrase>
    </textobject>
</mediaobject>
</screenshot>

</para>

<para>To open the Configuration dialog go to Settings -> Configure &kmidimon; or click on the corresponding icon on the toolbar.
</para>

<para>
This is a list of the configuration options.
<itemizedlist>
  <listitem>
    <para>
	Sequencer tab. The Queue Default Settings affect to the event's time precision.
    </para>
  </listitem>
  <listitem>
    <para>
	Filters tab. Here you can check several event families to be displayed in the event list.
    </para>
  </listitem>
  <listitem>
    <para>
	Display tab. The first group of checkboxes allows to show/hide the corresponding columns of the events list. 
    </para>
  </listitem>

  <listitem>
    <para>
	Misc. tab. Miscellaneous options include:
	<itemizedlist>
	  <listitem>
	    <para>
		Translate ALSA Client IDs into names. If checked, ALSA client names are used instead of ID numbers in the "Source" column for all king of events, and the data columns for the ALSA events.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
		Translate Universal System Exclusive messages. If checked, Universal System Exclusive messages (real time, non real time, MMC, MTC and a few other types) are interpreted and translated. Otherwise, the hexadecimal dump is shown.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
		Use fixed font. By default &kmidimon; uses the system font in the event list. If this option is checked, a fixed font is used instead.
	    </para>
	  </listitem>
    </itemizedlist>
    </para>
  </listitem>

</itemizedlist>
</para>

</sect1>
</chapter>

<chapter id="credits">

<!-- Include credits for the programmers, documentation writers, and
contributors here. The license for your software should then be included below
the credits with a reference to the appropriate license file included in the KDE
distribution. -->

<title>Credits and License</title>

<para>Program copyright 2005-2009 Pedro Lopez&#45;Cabanillas <email>plcl&#64;users&#46;sourceforge&#46;net</email></para>
<para>Documentation copyright 2005 Christoph Eckert <email>christeck&#64;users&#46;sourceforge&#46;net</email></para>
<para>Documentation copyright 2008-2009 Pedro Lopez&#45;Cabanillas <email>plcl&#64;users&#46;sourceforge&#46;net</email></para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove -->

<!-- Determine which license your application is licensed under, 
     and delete all the remaining licenses below:

     (NOTE:  All documentation are licensed under the FDL, 
     regardless of what license the application uses) -->

&underGPL;        	 <!-- GPL License -->

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kmidimon">
<title>How to obtain &kmidimon;</title>

<para>
Here you can find the last version:
<ulink
url="http://sourceforge.net/projects/kmidimon">Project home page</ulink>
</para>

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>
In order to successfully use &kmidimon;, you need &kde; 4.X. and ALSA
drivers and library.
</para>

<para>
The build system requires <ulink url="http://www.cmake.org">CMake</ulink> 
2.4.4 or newer.
</para>

<para>
ALSA library, drivers and utilities can be found at
<ulink url="http://www.alsa-project.org">ALSA home page</ulink>.
</para>

<para>
You can find a list of changes at
<ulink
url="http://kmidimon.sourceforge.net">http://kmidimon.sourceforge.net
</ulink>
</para>
</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<para>
In order to compile and install &kmidimon; on your system, type the following 
in the base directory of the &kmidimon; distribution:
<screen>
% cmake .
% make
% make install
</screen>
Since &kmidimon; uses <command>cmake</command> and <command>make</command> 
you should have no trouble compiling it. Should you run into problems please 
report them to the author or the project's bug tracking system.
</para>

</sect1>

</appendix>

&documentation.index;
</book>

<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab 
-->

