<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd">
To validate or process this file as a standalone document, uncomment
this prolog. Be sure to comment it out again when you are done -->

<chapter id="midi">
<title
>&MIDI;</title>

<sect1 id="midi-overview">
<title
>Überblick</title>

<!-- what-to-say-here: aRts has three roles
  * moving midi events around between applications
  * abstracting the hardware
  * synthesizer -->

<para
>Die &MIDI;-Unterstützung in &arts; hat verschiedene Aufgaben. Erstens ermöglicht sie die <emphasis
>Kommunikation</emphasis
> von verschiedenen Programmteilen, die &MIDI;-Ereignisse erzeugen oder verarbeiten. Wenn Sie z.B. über einen Sequenzer und einen Sampler verfügen, die beide &arts; unterstützen, kann &arts; &MIDI;-Ereignisse vom Sequenzer zum Sampler senden. </para>

<para
>Auf der anderen Seite kann &arts; für ein Programm die <emphasis
>Interaktion mit Geräten</emphasis
> übernehmen. Wenn ein Programm (z.B. ein Sampler) &arts; unterstützt, kann es genau so gut &MIDI;-Ereignisse von einem externen &MIDI;-Keyboard empfangen. </para>

<para
>Schließlich ist &arts; ein hervorragender <emphasis
>modularer Synthesizer</emphasis
>. Er ist genau dafür entworfen worden. Sie können mit artsbuilder aus den kleinen Modulen Instrumente zusammenstellen und diese Instrumente dann für Kompositionen oder zum Abspielen von Musik verwenden. Synthese heißt nicht notwendigerweise reine Synthese, es gibt Module, die Sie zum Abspielen von Samples verwenden können. Also kann &arts; ein Sampler, ein Synthesizer und mehr sein; &arts; ist vollständig modular, also leicht zum Erweitern und Experimentieren geeignet, mächtig und flexibel. </para>
</sect1>

<sect1 id="midi-manager">
<title
>Der &MIDI;-Manager</title>
<!-- what-to-say-here:
  * how to use artscontrol - view midimanager
  * what does autorestore do? (not yet implemented - so not yet documented) -->

<para
>Die zentrale Komponente für Midi-Ereignisse innerhalb von &arts; ist der Midi-Manager. Er kontrolliert, welche Anwendungen verbunden sind und wie Midi-Ereignisse zwischen ihnen übertragen und verarbeitet werden sollen. Der Midi-Manager wird durch artscontrol gesteuert. Wählen Sie dazu <menuchoice
><guilabel
>Ansicht</guilabel
><guilabel
>Midi-Manager</guilabel
> </menuchoice
> im Menü. </para>

<para
>Auf der linken Seite sehen Sieh <guilabel
>Midi-Eingänge</guilabel
>. Hier werden alle Geräte aufgelistet, die &MIDI;-Ereignisse produzieren. Das können externe &MIDI;-Kanäle sein, die mit einem externen Keyboard verbunden sind, ein Sequenzer, der ein Musikstück abspielt, oder eine andere &MIDI;-Quelle. Auf der rechten Seite sehen Sie <guilabel
>&MIDI;-Ausgänge</guilabel
>. Alle Geräte oder Programme, die &MIDI;-Ereignisse verarbeiten, sind hier aufgelistet. Das können simulierte Sampler (als Programme) oder externe &MIDI;-Kanäle, an denen ein Hardware-Sampler angeschlossen ist, sein. Neue Programme, wie z.B. Sequenzer, registrieren sich bei dem Midi-Manager, daher kann sich der Listeninhalt von Zeit zu Zeit ändern. </para>

<para
>Sie können Ein- und Ausgänge verbinden, indem Sie den gewünschten Eingang auf der linken und den Ausgang auf der rechten Seite markieren und auf <guilabel
>Verbinden</guilabel
> klicken. Eine Trennung erreichen Sie mit dem Knopf <guilabel
>Trennen</guilabel
>. Die bestehenden Verbindungen werden durch günne Linien zwischen den Listen angezeigt. Sie können einen Midi-Eingang mit mehreren Midi-Ausgängen verbinden und umgekehrt. </para>

<para
>Programme (wie der Sequenzer Brahms) fügen sich beim Start selbstständig zur entsprechenden Liste hinzu und entfernen sich beim Beenden selbstständig. Sie können aber auch von Hand Einträge hinzufügen, indem Sie im Menü <guilabel
>Hinzufügen</guilabel
> wählen. </para>

<variablelist>
<varlistentry>
<term
><guimenuitem
>System-Midi-Kanal (OSS)</guimenuitem
></term>
<listitem>
<para
>Dadurch wird ein neues &arts;-Objekt erzeugt, das einen externen Midi-Kanal repräsentiert. </para>

<para
>Da externe Midi-Kanäle sowohl senden als auch empfangen können, wird zu beiden Listen ein Eintrag hinzugefügt. Unter &Linux; benötigen Sie entweder einen <acronym
>OSS</acronym
>- (<acronym
>OSS/Free</acronym
> liegt Ihrem &Linux;-Kernel bei) oder einen <acronym
>ALSA</acronym
>-Treiber für Ihre Soundkarte installiert haben. Sie werden nach dem Gerätenamen gefragt. Er lautet normalerweise <filename class="devicefile"
>/dev/midi</filename
> oder <filename class="devicefile"
>/dev/midi00</filename
>. </para>

<para
> Wenn Sie allerdings mehr als ein &MIDI;-Gerät oder einen &MIDI;-Loopback-Treiber installiert haben, ist die Auswahl größer. Informationen über die verfügbaren Midi-Kanäle finden Sie im &kcontrolcenter; unter <menuchoice
><guilabel
>Information</guilabel
> <guilabel
>Klänge</guilabel
></menuchoice
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>aRts Synthese Midi-Ausgang</guimenuitem
></term>
<listitem>
<para
>Fügt einen neuen &MIDI;-Ausgang mit einem &arts;-Synthese-Instrument hinzu. Wenn Sie diesen Menüeintrag wählen, erscheint ein Dialog, der Ihnen die Wahl eines Instrumentes ermöglicht. Mit artsbuilder können Sie neue Instrumente erstellen. Alle <literal role="extension"
>.arts</literal
>-Dateien, die mit <filename
>instrument_</filename
> beginnen, werden hier aufgelistet. </para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="brahms">
<title
>Verwendung von &arts; &amp; Brahms</title>

<para
>Zuerst benötigen Sie eine &kde; 2.1-taugliche Version von &brahms;. Sie finden Sie im <literal
>kmusic</literal
> <acronym
>CVS</acronym
>-Modul. Weitere Informationen zu &brahms; finden Sie auf der <ulink url="http://www.arts-project.org/"
>aRts-Internetseite</ulink
> im Bereich Download. </para>

<para
>Wenn man die Anwendung startet, wird zunächst der &MIDI;-Manager angezeigt. Wenn man Klänge synthetisieren will, fügt man ein &MIDI;-Synthesizerinstrument über <menuchoice
><guilabel
>Hinzufügen</guilabel
><guilabel
>aRts Synthese Midi-Ausgang</guilabel
> </menuchoice
> hinzu. </para>

<para
>Man wählt ein Instrument (zum Beispiel <guilabel
>organ2</guilabel
>). Man verbindet das Instrument über den Knopf <guilabel
>Verbinden</guilabel
>. Danach kann man mit &brahms; komponieren und die Ausgabe wird durch &arts; synthetisiert. </para>

<para
>Man sollte das &artscontrol;-Fenster geöffnet lassen und die Lautstärkeeinstellung kontrollieren (die Qualität wird schlecht, wenn die Lautstärkeanzeige an die obere Grenze stösst). Nun kann man einneues Demolied für &arts; erstellen und es, wenn es fertig ist, unter aRts-project.org veröffentlichen ;-). </para>

<!-- TODO: how to do more than one instrument in Brahms (hm, not implemented
     yet, not documented yet), how to use samples, mapping and so on. These
  	 things need to be implemented, too. -->

</sect1>

<sect1 id="midisend">
<title
>midisend</title>

<para
><command
>midisend</command
> ist ein kleines Programm, das &MIDI;-Ereignisse von der Kommandozeile senden kann. Es registriert sich als &MIDI;-Eingang wie alle anderen Anwendungen. Um es zu verwenden, geben Sie <screen
><prompt
>&percnt;</prompt
> <userinput
><command
>midisend</command
> <option
>-f</option
> <parameter
><replaceable
>/dev/midi00</replaceable
></parameter
></userinput
> </screen
> ein. Damit wird etwa das gleiche erreicht, wie durch das Hinzufügen eines System-Midikanals in artscontrol (nicht ganz, da midisend nur &MIDI;-Ereignisse senden aber nicht empfangen kann). Der Unterschied ist, das midisend auf unterschiedlichen Computern gestartet werden kann (und damit Netzwerktransparenz ermöglicht). </para>

<para
>Sie können <command
>midisend</command
> auch Daten von <filename class="devicefile"
>stdin</filename
> senden lassen. Mit dem folgenden Befehl können sie Daten von Anwendungen, die &arts; nicht unterstützen, an &arts; weiterleiten: <screen
><prompt
>&percnt;</prompt
> <userinput
><command
><replaceable
>applicationwhichproducesmidieventsonstdout</replaceable
></command
> | <command
>midisend</command
> <option
>-f</option
> <option
><replaceable
>-</replaceable
></option
></userinput
></screen>
<!-- TODO: document all options -->
</para>

</sect1>

<sect1 id="midi-creating-instruments">
<title
>Instrumente erstellen</title>
 
<para
>&arts; synthetisiert Midi-Klänge auf folgende Weise. Es gibt eine Struktur, die einige Eingabekanäle, aus denen Frequenz und Lautstärke (velocity) und ein Parameter gelesen wird. Der Parameter zeigt an, ob die Taste noch heruntergedrückt ist. Die Struktur soll nun diese eine Note mit dieser Lautstärke und Frequenz erzeugen. Außerdem soll die Struktur auf den Wert des Parameters gedrückt reagieren (dabei bedeutet gedrückt=1 der Benutzer drückt die Taste immer noch herunter und gedrückt=0 die Taste wurde losgelassen). </para>

<para
>Eingehende &MIDI;-Ereignisse veranlassen &arts;, neue Strukturen für jede gedrückte Taste zu generieren, ihnen die entsprechenden Parameter mitzugeben und sie wieder zu entfernen, sobald sie nicht mehr benötigt werden. </para>

<para
>Eine Struktur wird auf folgende Art erzeugt und verwendet: </para>

<itemizedlist>
<listitem>
<para
>Zum Beginn ist es am einfachsten, ein <filename
>template_Instrument.arts</filename
> in &arts-builder; zu öffnen.  </para>

<para
>Wählen Sie dazu <menuchoice
><guimenu
>Datei</guimenu
><guimenuitem
>Beispiel öffnen ...</guimenuitem
></menuchoice
> im Menü und im Dateidialog wählen Sie template_Instrument. Damit haben Sie eine leere Struktur mit den erforderlichen Parametern erzeugt, die Sie nur noch "ausfüllen" müssen. </para>
</listitem>

<listitem>
<para
>Für den Parameter pressed(gedrückt) benutzen Sie entweder Synth&lowbar;ENVELOPE&lowbar;ADSR oder, für eine Schlagzeug wav-Datei, spielen sie einfach ab und ignorieren den Parameter. </para>
</listitem>

<listitem>
<para
>Die Struktur sollte am Ausgang <quote
>done</quote
> anzeigen, das Sie nicht mehr benötigt wird. Wenn doneauf 1 gesetzt wird, nimmt &arts; an, das er die Struktur löschen kann. Angenehmerweise stellt das ADSR-Hüllkurven-Modul einen Parameter bereit, der anzeigt, wenn das Modul fertig ist. Sie müssen diesen Ausgang lediglich mit dem done-Ausgang Ihrer Struktur verbinden. </para>
</listitem>

<listitem>
<para
>Sie sollten die Struktur in die Form <filename
>instrument_*</filename
> wie z.B. <filename
>instrument_piano.arts</filename
> umbenennen - unter diesem Namen sollten Sie die Struktur unter <filename class="directory"
>$<envar
>HOME</envar
>/arts/structures</filename
> speichern (dort speichert artsbuilder normalerweise Strukturen). </para>
</listitem>

<listitem>
<para
>Schließlich, nachdem die Struktur gespeichert ist, können Sie sie im &MIDI;-Manager von artscontrol verwenden.</para>
</listitem>

<listitem>
<para
>Und Sie müssen natürlich die Struktur so einrichten, das Sie ihre Audiodaten an den linken und rechten Ausgangskanal sendet, so dass sie schließlich durch den Audio-Manager (ein Teil von &artscontrol;) hörbar werden (oder sie mit Effekten weiterverarbeiten). </para>
</listitem>
</itemizedlist>

<para
>Um zu lernen, wie Sie selbst ein Instrument erstellen, können Sie ein bereits vorhandenes Instrument analysieren (wählen Sie im Menü <menuchoice
><guimenu
>Datei</guimenu
><guimenuitem
>Beispiel öffnen</guimenuitem
></menuchoice
>). </para>
</sect1>

<sect1 id="mapped-instruments">
<title
>gemappte Instrumente</title>

<para
>Gemappte Instrumente sind Instrumente, die sich abhängig von der Tonhöhe (pitch), dem Programm, dem Kanal und der Lautstärke (velocity) unterschiedlich verhalten. Sie könnten z.B. einen Klavierklang von 5 Oktaven bilden, indem Sie ein Sample für jede Oktave verwenden (entsprechende Höhenverschiebungen (pitchshifting) vorausgesetzt). Dieser Klang wird besser klingen als ein Sample für alle Oktaven. </para>

<para
>Sie können auch eine Schlagzeug-Map bilden, die jeder Taste ein bestimmtes Schlaginstrument zuordnet. </para>

<para
>Es ist sehr nützlich, wenn Sie einige unterschiedliche Klänge in ein gemapptes Instrument für verschiedene Programme zusammenfügen. Auf diese Weise können Sie Ihren Sequenzer, externes Keyboard oder andere &MIDI;-Quelle verwenden, um zwischen den Klängen umzuschalten, ohne das Sie &arts; umändern müssen.  </para>

<para
>Ein gutes Beispiel dafür ist das Instrument <filename
>arts_all</filename
>. Es fügt alle Instrumente in einer Map zusammen. Auf diese Weise müssen Sie lediglich einmal in &artscontrol; dieses <quote
>instrument</quote
> registrieren und schon können Sie ein komplettes Musikstück in einem Sequenzer komponieren, ohne &arts; umzuschalten. Wenn Sie einen anderen Klang benötigen, wechseln Sie einfach im Sequenzer das Programm und &arts; erzeugt einen anderen Klang. </para>

<para
>Solche Maps können Sie auf einfache Weise erstellen. Sie müssen lediglich eine Textdatei anlegen, die einige Regeln enthält: </para>

<programlisting
>ON <replaceable
>[ Bedingungen ...]</replaceable
> DO structure=<replaceable
>irgendeine Struktur</replaceable
>.arts
</programlisting>

<para
>Die Bedingungen können eine oder mehrere der folgenden sein: </para>

<variablelist>

<varlistentry>
<term
><option
>pitch (Tonhöhe)</option
></term>

<listitem>
<para
>Beim pitch handelt es sich um die gespielte Tonhöhe. Diese Bedingung verwenden Sie, wenn Sie den Instrumentenklang abhängig von der Tonhöhe aufteilen wollen. Von den Anfangsbeispielen würde ein Piano, das verschiedene Klänge für verschiedene Oktaven verwendet, mit einer solchen Bedingung erstellt. Sie können eine bestimmte Tonhöhe angeben, wie z.B. pitch=<parameter
>62</parameter
> oder einen Bereich wie pitch=<parameter
>60</parameter
>-<parameter
>72</parameter
>. Die möglichen Tonhöhen liegen zwischen <parameter
>0</parameter
> und <parameter
>127</parameter
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>program (Programm)</option
></term>
<listitem>
<para
>Das Programm, das auf dem Midi-Kanal aktiv ist, auf dem die Note gesendet wird. Üblicherweise kann man bei einem Sequenzer das <quote
>Instrument</quote
> über die Programmeinstellung auswählen. Einzelne Programme oder Bereiche sind erlaubt, also <userinput
><option
>program</option
>=<parameter
>3</parameter
></userinput
> oder <userinput
><option
>program</option
>=<parameter
>3</parameter
>-<parameter
>6</parameter
> </userinput
>. Die möglichen Programmeinstellungen reichen von <parameter
>0</parameter
> bis <parameter
>127</parameter
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>channel (Kanal)</option
></term>
<listitem>
<para
>Der Kanal, auf dem die Note gesendet wird. Einzelne Kanäle oder Kanalbereiche sind möglich, z.B. <userinput
><option
>channel</option
>=<parameter
>0</parameter
></userinput
> oder <userinput
><option
>channel</option
>=<parameter
>0</parameter
>-<parameter
>8</parameter
> </userinput
>. Die möglichen Werte liegen zwischen <parameter
>0</parameter
> und <parameter
>15</parameter
>. </para>
</listitem>

</varlistentry>
<varlistentry>
<term
><option
>velocity (Lautstärke)</option
></term>
<listitem>
<para
>Die Lautstärke, die die Note hat. Einzelne Lautstärken (wofür eigentlich) oder Bereiche sind möglich, also <userinput
><option
>velocity</option
>=<parameter
>127</parameter
></userinput
> oder <userinput
><option
>veclocity</option
>=<parameter
>64</parameter
>-<parameter
>127</parameter
> </userinput
>. Die möglichen Werte liegen zwischen <parameter
>0</parameter
> und <parameter
>127</parameter
>. </para>
</listitem>
</varlistentry>
</variablelist>

<para
>Ein komplettes Beispiel für eine Map sieht folgendermaßen aus (das Beispiel stammt aus <filename
>instrument_arts_all.arts-map</filename
>): </para>

<programlisting
>ON program=0 DO structure=instrument_tri.arts
ON program=1 DO structure=instrument_organ2.arts
ON program=2 DO structure=instrument_slide1.arts
ON program=3 DO structure=instrument_square.arts
ON program=4 DO structure=instrument_neworgan.arts
ON program=5 DO structure=instrument_nokind.arts
ON program=6 DO structure=instrument_full_square.arts
ON program=7 DO structure=instrument_simple_sin.arts
ON program=8 DO structure=instrument_simple_square.arts
ON program=9 DO structure=instrument_simple_tri.arts
ON program=10 DO structure=instrument_slide.arts
ON program=11 pitch=60 DO structure=instrument_deepdrum.arts
ON program=11 pitch=61 DO structure=instrument_chirpdrum.arts
</programlisting>

<para
>Wie Sie sehen, wird die Struktur abhängig vom Programm ausgewählt, beispielsweise sehen Sie als Programm 11 eine <quote
>Schlagzeug-Map</quote
> (mit zwei Einträgen), die eine <quote
>tiefe Trommel</quote
> auf C-5 (pitch=60) und eine <quote
>Snare-Trommel</quote
> auf C#-5 (pitch=61) spielt. </para>
 
<para
>Um Map-Dateien in &artscontrol; als Instrumente zur Wahl erscheinen zu lassen, müssen Sie nach der Konvention <filename
>instrument_<replaceable
>irgendetwas</replaceable
>.arts-map</filename
> benannt werden und sich entweder unter Ihrem Persönlichen Verzeichnis in <filename class="directory"
>$<envar
>HOME</envar
>/arts/structures</filename
> oder im &kde;-Verzeichnis unter <filename class="directory"
>$<envar
>KDEDIR</envar
>/share/apps/artsbuilder/examples</filename
> befinden. Strukturen, die von dieser Map verwendet werden, können mit einem absoluten Pfad oder relativ zur Position der Map-Datei angegeben werden. </para>

<para
>Es ist eine gute Ide, die arts_all.map zu erweitern oder vielleicht sogar eine General-&MIDI;-Map für &arts; zu erstellen. Das würde die Verwendung von &arts; vereinfachen. Bitte denken Sie darüber nach, ob Sie nicht interessante Instrumente für zukünftige Versionen von &arts; zur Verfügung stellen können. </para>
</sect1>

<!-- TODO: Maybe helpful
 * using an external keyboard
 * loopback midi device

<sect1 id="quick-start">
<title
>Quick Start</title>
 
</sect1>
<sect1 id="internal-details">
<title
>More Internal Details</title>
 
</sect1>

<sect1 id="other-considerations">
<title
>Other Considerations</title>
 
</sect1>
-->

</chapter>
