<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1.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
>Aperçu</title>

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

<para
> La gestion du &MIDI; dans &arts; permet de faire beaucoup de choses. Tout d'abord, elle permet la <emphasis
>communication</emphasis
> entre différentes parties d'un logiciel qui produit ou utilise des événements &MIDI;. Si par exemple vous avez un séquenceur et un échantillonneur qui sont compatibles avec &arts;, &arts; peut envoyer des événements &MIDI; du séquenceur vers l'échantillonneur. </para>

<para
> D'un autre côté, &arts; peut aussi aider des applications à <emphasis
>interagir avec le matériel</emphasis
>. Si une partie d'un logiciel (par exemple l'échantillonneur) travaille avec &arts;, il sera capable de recevoir des événements &MIDI; depuis un clavier &MIDI; externe aussi. </para>

<para
> Finalement, &arts; constitue un <emphasis
>synthétiseur modulaire</emphasis
> sympathique. Il est exactement conçu pour cela. Vous pouvez donc construire des instruments à partir de petits modules en utilisant artsbuilder, puis ensuite les réutiliser pour composer et jouer de la musique. Synthèse ne signifie pas forcément synthèse pure, il y a des modules qui vous permettent de jouer des échantillons. &arts; peut donc être un échantillonneur, un synthétiseur, etc. et étant entièrement modulaire, il est très facile de l'étendre, facile à prendre en main, puissant et flexible. </para>
</sect1>

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

<para
> Le composant central de &arts; qui garde une trace de quelles applications sont connectées et comment les événements midi doivent circuler entre elles est le gestionnaire midi. Pour voir ou modifier ce qu'il fait, démarrez artscontrol. Ensuite, choisissez <menuchoice
><guilabel
>Affichage</guilabel
><guilabel
>Voir le gestionnaire Midi</guilabel
></menuchoice
> dans le menu. </para>

<para
> Sur la gauche, vous verrez <guilabel
>Entrées Midi</guilabel
>. Ici, tous les objets qui produisent des événements &MIDI;, comme un port &MIDI; externe qui envoie des données depuis un clavier &MIDI;, un séquenceur qui joue un morceau, etc. sont listés. Sur la droite, vous verrez <guilabel
>Sorties Midi</guilabel
>. Ici, vous trouverez la liste de tous ce qui utilise les événements &MIDI;, comme un échantillonneur logiciel, ou un port &MIDI; externe sur lequel un échantillonneur matériel peut être connecté. Les nouvelles applications, comme les séquenceurs, s'enregistrent toutes seules de telle sorte que cette liste est susceptible de changer au cours du temps. </para>

<para
> Vous pouvez connecter les entrées aux sorties si vous marquez l'entrée à droite et la sortie à gauche, et choisissez <guilabel
>Connecter...</guilabel
> avec le bouton en bas. <guilabel
>Déconnecter</guilabel
> fonctionne de la même manière. Vous verrez ce qui est connecté grâce à de petites lignes entre les entrées et les sorties, au milieu de la fenêtre. Notez que vous pouvez connecter un émetteur vers plus d'un récepteur (et vice versa). </para>

<para
> Certains programmes (comme le séquenceur Brahms) s'ajouteront d'eux même lorsqu'ils démarrent et seront enlevés de la liste lorsqu'ils s'arrêtent. Vous pouvez toutefois ajouter de nouveaux éléments avec le menu <guilabel
>ajouter</guilabel
>&nbsp;: </para>

<variablelist
> <varlistentry
> <term
><guimenuitem
>Port Midi (OSS)</guimenuitem
></term
> <listitem
> <para
> Ceci créera un nouvel objet &arts; qui communique avec un port midi externe. </para
> <para
> Comme les ports midi peuvent à la fois envoyer et recevoir des données, choisir cette option ajoutera une entrée midi et une sortie midi. Sous &Linux;, vous devriez avoir soit un <acronym
>OSS</acronym
> (ou <acronym
>OSS</acronym
>/Free, qui est fourni avec le noyau de &Linux;) ou un pilote <acronym
>ALSA</acronym
> permettant de faire fonctionner votre carte son. On vous demandera le nom du périphérique. Habituellement, il s'agit de <filename class="devicefile"
>/dev/midi</filename
> ou <filename class="devicefile"
>/dev/midi00</filename
>. </para
> <para
> Cependant, si vous avez plus d'un périphérique &MIDI;ou un pilote &MIDI; loopback installé, vous devriez avoir plus de choix. Pour voir les informations sur les ports midi, démarrez le &kcontrolcenter;, et choisissez <menuchoice
><guilabel
>Information</guilabel
><guilabel
>Son</guilabel
></menuchoice
>. </para
> </listitem
> </varlistentry
> <varlistentry
> <term
><guimenuitem
>Sortie Midi du synthétiseur aRts</guimenuitem
></term
> <listitem
> <para
> Ceci va ajouter une nouvelle sortie &MIDI; avec un instrument synthétisé par &arts;. Si vous choisissez cette entrée du menu, une boîte de dialogue va apparaître, vous permettant de choisir un instrument. Vous pouvez créer de nouveaux instruments en utilisant artsbuilder. Tous les fichiers <literal role="extension"
>.arts</literal
> dont le nom commence par <filename
>instrument_</filename
> apparaîtront ici. </para
> </listitem
> </varlistentry
> </variablelist>

</sect1>

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

<para
> En réalité, c'est facile de débuter. Vous avez besoin d'une version de &brahms; pour &kde; 2.1, qui se trouve dans le module <acronym
>CVS</acronym
> <literal
>kmusic</literal
>. Il y a aussi des informations sur la façon de se procurer &brahms; sur le <ulink url="http://www.arts-project.org/"
>site web de aRts</ulink
> dans la section Download. </para>

<para
> Lorsque vous le démarrez, il affiche le gestionnaire &MIDI;. Si vous voulez faire de la synthèse, ajoutez simplement un instrument &MIDI; de synthèse via <menuchoice
><guilabel
>Ajouter</guilabel
><guilabel
>Sortie Midi du synthétiseur aRts</guilabel
></menuchoice
>. </para>

<para
> Choisissez un instrument (par exemple <guilabel
>organ2</guilabel
>). Connectez-les en utilisant le bouton <guilabel
>Connect</guilabel
>. Enfin, vous pouvez commencer à composer avec &brahms;, et la sortie sera synthétisée avec &arts;. </para>

<para
> Il est conseillé d'ouvrir une fenêtre du &artscontrol;, et de vérifier que le volume n'est pas trop fort (la qualité est moins bonne lorsque les bargraphs atteignent la limite supérieure). Maintenant, vous pouvez commencer à travailler sur un nouveau morceau de démo de &arts;, et lorsque ce sera fait, vous pouvez le publier sur aRts-project.org&nbsp;! </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
>  est une petite application qui vous permet d'envoyer des événements &MIDI; en utilisant le shell. Il va s'enregistrer comme client comme toutes les autres applications. La façon la plus simple de l'utiliser est de faire <screen
><prompt
>&percnt;</prompt
> <userinput
><command
>midisend</command
> <option
>-f</option
> <parameter
><replaceable
>/dev/midi00</replaceable
></parameter
></userinput
> </screen
> qui fera en gros la même chose que d'ajouter un port &MIDI; système dans le &artscontrol;. (pas tout à fait, puisque <command
>midisend</command
> ne fait qu'envoyer des événements). La différence est qu'il est facile par exemple de démarrer <command
>midisend</command
> sur plusieurs machines (et de cette façon, utiliser la transparence réseau). </para>

<para
> <command
>midisend</command
> peut aussi envoyer des données depuis <filename class="devicefile"
>stdin</filename
>. Vous pouvez utiliser ceci dans des tubes pour envoyer des données provenant d'applications non-&arts; vers &arts;, comme ceci&nbsp;: <screen
><prompt
>&percnt;</prompt
> <userinput
><command
><replaceable
>applicationwhichproducesmidieventsonstdout</replaceable
></command
> | <command
>midisend</command
> <option
>-f</option
> <option
><replaceable
>-</replaceable
></option
></userinput
></screen
> </para>

</sect1>

<sect1 id="midi-creating-instruments">
<title
>Création d'instruments</title>
 
<para
> La façon dont &arts; réalise la synthèse midi est la suivante&nbsp;: vous avez une structure qui contient des ports d'entrée, où elle récupère la fréquence, la vélocité (volume) et un paramètre qui indique si la note est toujours enfoncée. La structure devrait alors synthétiser exactement telle note avec tel volume, et réagir au paramètre "pressed" (ou pressed = 1 signifie que l'utilisateur appuie toujours cette touche, et 0 signifie que l'utilisateur a relâché la touche). </para>

<para
> Lorsqu'un événement &MIDI; arrive, &arts; crée de nouvelles structures pour les notes suivant les besoins, leur passe les paramètres, et les efface une fois qu'elles ont terminé leur travail. </para>

<para
> Pour créer et utiliser une telle structure, vous devez faire les choses suivantes&nbsp;: </para>

<itemizedlist
> <listitem
> <para
> Pour démarrer, la façon la plus simple est d'ouvrir <filename
>template_Instrument.arts</filename
> dans &artsbuilder;. </para
> <para
> Allez dans <menuchoice
><guimenu
>Fichier</guimenu
><guimenuitem
>Ouvrir un exemple...</guimenuitem
></menuchoice
> et choisissez <guimenuitem
>template_Instrument</guimenuitem
> dans la zone de sélection de fichier. Vous obtiendrez alors une structure vide avec les paramètres requis, que vous devrez simplement <quote
>remplir</quote
>. </para
> </listitem
> <listitem
> <para
> Pour traiter le paramètre pressed, il est préférable d'utiliser Synth&lowbar;ENVELOPE&lowbar;ADSR, ou s'il s'agit d'un son de percussions, jouez-le simplement sans vous soucier du paramètre pressed. </para
> </listitem
> <listitem
> <para
> La structure devrait indiquer lorsqu'elle n'est plus utile avec la sortie <quote
>done</quote
>. Si done est égal à <returnvalue
>1</returnvalue
>, &arts; supprime alors les structures. Très pratique, l'enveloppe ADSR fournit un paramètre lorsqu'elle se termine, donc vous devez simplement le connecter à la sortie done de la structure. </para
> </listitem
> <listitem
> <para
> Renommez votre structure avec un nom commençant par <filename
>instrument_</filename
>, comme par exemple <filename
>instrument_piano.arts</filename
> - enregistrez le fichier avec le même nom, dans votre dossier <filename class="directory"
>$<envar
>HOME</envar
>/arts/structures</filename
> (qui est le dossier ou enregistre arts par défaut). </para
> </listitem
> <listitem
> <para
> Enfin, une fois que vous l'avez enregistré, vous pourrez l'utiliser avec le &artscontrol; dans le gestionnaire &MIDI;.</para
> </listitem
> <listitem
> <para
> Oh, et bien sûr, votre structure devrait jouer les données audio qu'elle génère sur les sorties droite et gauche de la structure, qui sera joué ensuite par le gestionnaire audio (visible depuis le &artscontrol;), ou vous pouvez enfin les entendre (ou leur ajouter un post-traitement avec des effets). </para
> </listitem
> </itemizedlist>

<para
> Une bonne façon d'apprendre à créer un instrument est d'ouvrir un instrument déjà existant via  <menuchoice
><guilabel
>Fichier</guilabel
><guilabel
>Ouvrir un exemple</guilabel
></menuchoice
> et de regarder comment ça marche&nbsp;!  </para>
</sect1>

<sect1 id="mapped-instruments">
<title
>Instruments mappés</title>

<para
> Les instruments mappés sont des instruments qui se comportent différemment suivant la hauteur, le programme (son), le canal ou la vélocité. Vous pourriez par exemple construire un piano sur 5 octaves, en utilisant un échantillon pour chaque octave (en le transposant en conséquence). Ça sonne beaucoup mieux qu'avec l'utilisation d'un seul échantillon. </para>

<para
> Vous pourriez aussi construire un "drum map" qui joue un échantillon de batterie spécifique par touche. </para>

<para
> Enfin, il est très utile de placer différents sons dans un instrument mappé. De cette façon, vous pouvez utiliser votre séquenceur, clavier externe ou autre source &MIDI; pour basculer entre les sons sans avoir à revenir à &arts; lorsque vous travaillez. </para>

<para
> Un bon exemple pour ceci est l'instrument <filename
>arts_all</filename
>, qui place simplement tous les instruments fournis avec &arts; dans une même map. De cette façon, vous avez juste à paramétrer le &artscontrol; une seule fois pour utiliser cet <quote
>instrument</quote
>, et ensuite, vous pouvez composer un morceau entier avec un séquenceur sans vous soucier de &arts;. Vous avez besoin d'un autre son&nbsp;? Changez simplement de programme dans le séquenceur, et &arts; vous donnera un autre son. </para>

<para
> La création de telles maps est relativement facile. Créez simplement un fichier texte, et écrivez des règles qui ressemblent à&nbsp;: </para>

<programlisting>
ON <replaceable
>[ conditions...]</replaceable
> DOstructure=<replaceable
>une_structure</replaceable
>.arts
</programlisting>

<para
> Les conditions peuvent être une ou plusieurs des valeurs suivantes&nbsp;: </para>

<variablelist
> <varlistentry
> <term
><option
>pitch</option
></term
> <listitem
> <para
> Hauteur du son qui doit être joué. Vous utiliserez ceci si vous voulez découper votre instrument en fonction de la hauteur. Dans nos exemples initiaux, un piano qui utilise différents échantillons pour différentes octaves utiliserait cette condition. Vous pouvez spécifier une hauteur unique, comme <userinput
><option
>pitch</option
>=<parameter
>62</parameter
></userinput
> ou une plage de hauteur, comme <userinput
><option
>pitch</option
>=<parameter
>60</parameter
>-<parameter
>72</parameter
></userinput
>. Les valeurs possibles sont comprises entre <parameter
>0</parameter
> et <parameter
>127</parameter
>. </para
> </listitem
> </varlistentry
> <varlistentry
> <term
><option
>program</option
></term
> <listitem
> <para
> Le programme actif sur le canal sur lequel est envoyée la note. Habituellement, les séquenceurs vous permettent de choisir l'<quote
>instrument</quote
> par un réglage du programme. Des programmes uniques ou une plage de programmes sont permis, comme <userinput
><option
>program</option
>=<parameter
>3</parameter
></userinput
> ou <userinput
><option
>program</option
>=<parameter
>3</parameter
>-<parameter
>6</parameter
></userinput
>. Les programmes possibles sont compris entre <parameter
>0</parameter
> et <parameter
>127</parameter
>. </para
> </listitem
> </varlistentry
> <varlistentry
> <term
><option
>channel</option
></term
> <listitem
> <para
> Le canal sur lequel la note est envoyée. Des canaux uniques ou une plage de canaux sont permis, comme <userinput
><option
>channel</option
>=<parameter
>0</parameter
></userinput
> ou <userinput
><option
>channel</option
>=<parameter
>0</parameter
>-<parameter
>8</parameter
></userinput
>. Les valeurs possibles sont comprises entre <parameter
>0</parameter
> et <parameter
>15</parameter
>. </para
> </listitem
> </varlistentry
> <varlistentry
> <term
><option
>velocity</option
></term
> <listitem
> <para
> La vélocité (volume) de la note. Des vélocités uniques (qui utiliserait ça&nbsp;?) ou une plage de vélocités sont permises, comme<userinput
><option
>velocity</option
>=<parameter
>127</parameter
></userinput
> ou <userinput
><option
>velocity</option
>=<parameter
>64</parameter
>-<parameter
>127</parameter
></userinput
>. Les valeurs possibles sont comprises entre <parameter
>0</parameter
> et <parameter
>127</parameter
>. </para
> </listitem
> </varlistentry
> </variablelist>

<para
> Un exemple complet de map serait (ceci est extrait de la map <filename
>instrument_arts_all.arts</filename
>)&nbsp;: </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
> Comme vous pouvez le voir, la structure est choisie en fonction du programme. Pour le programme 11, vous voyez un <quote
>drum map</quote
> (avec deux entrées), qui devrait jouer un son de <quote
>deepdrum</quote
> sur C-5 (hauteur=60), et un son de <quote
>chirpdrum</quote
> on C#5 (pitch=61). </para>
 
<para
> Pour que les fichiers map apparaissent automatiquement dans le &artscontrol; en tant qu'instruments, ils doivent être nommés <filename
>instrument_<replaceable
>quelque_chose</replaceable
>.arts-map</filename
> et résider soit dans votre dossier utilisateur, dans <filename class="directory"
>$<envar
>HOME</envar
>/arts/structures</filename
>, soit dans le dossier de &kde;, dans <filename class="directory"
>$<envar
>KDEDIR</envar
>/usr/local/kde/share/apps/artsbuilder/examples</filename
>. Les structures qui sont utilisées par les maps peuvent être données soit avec un chemin absolu, soit relativement au dossier contenant le fichier map. </para>

<para
> Étendre la map arts_all ou même faire une map au format general &MIDI; complète pour &arts; est une bonne idée pour faciliter l'utilisation de &arts; pour une utilisation en dehors du cadre de &arts;. N'hésitez pas à contribuer au projet par la création d'instruments, de façon à les inclure dans les versions futures de &arts;. </para>
</sect1>

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

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

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

</chapter>

