<!-- <?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
>Introducción</title>

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

<para
>El soporte de &MIDI; en &arts; puede hacer una serie de cosas. La primera de todas, permite la <emphasis
>comunicación</emphasis
> entre diferentes elementos de software que producen o consumen eventos &MIDI;. Si, por ejemplo, usted tiene un secuenciador y un generador de muestras que son compatibles con &arts;, &arts; puede enviar los eventos &MIDI; desde el secuenciador al generador de muestras. </para>

<para
>Por otro lado, &arts; también puede ayudar a las aplicaciones a <emphasis
>interaccionar con el hardware</emphasis
>. Si un elemento de software (por ejemplo, el generador de muestras) trabaja con &arts;, podrá recibir los eventos &MIDI; desde un teclado externo. </para>

<para
>Por último, &arts; es un gran <emphasis
>sintetizador modular</emphasis
>. Está diseñado para ser exactamente eso. Así que puede construir instrumentos a partir de pequeños módulos utilizando artsbuilder, y después utilizar esos instrumentos para componer o reproducir música. Síntesis no tiene por qué significar síntesis pura, hay módulos que se pueden utilizar para reproducir muestras. Así que &arts; puede ser un generador de muestras, un sintetizador, etc., y al ser totalmente modular, es muy fácil de extender, muy sencillo para experimentar con él, potente y flexible. </para>
</sect1>

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

<para
>El componente central en &arts; que mantiene el registro de qué aplicaciones están conectadas y cómo se deben intercambiar los eventos midi, es el administrador midi. Para verlo o influir en su comportamiento, abra artscontrol. Después seleccione en el menú la opción <menuchoice
><guilabel
>Ver</guilabel
><guilabel
>Administrador MIDI</guilabel
> </menuchoice
>. </para>

<para
>En la parte izquierda, verá <guilabel
>Entradas MIDI</guilabel
>. En ese lugar se mostrarán todos los objetos que produzcan eventos &MIDI;, como un puerto &MIDI; externo que envía datos a un teclado &MIDI; conectado, un secuenciador que reproduce una canción, etc. En el lado derecho, verá <guilabel
>Salidas MIDI</guilabel
>. En ese recuadro estarán todos los elementos que consumen eventos &MIDI;, como un generador de muestras simulado (por software), o el puerto &MIDI; externo donde se puede conectar un generador de muestras por hardware. Las nuevas aplicaciones como secuenciadores, etc., se registrarán a sí mismas, así que las listas van cambiando con el tiempo. </para>

<para
>Es posible conectar las entradas con las salidas seleccionando la entrada en la lista izquierda y la salida en la derecha y pulsando sobre el botón <guilabel
>Conectar</guilabel
>. <guilabel
>Desconectar</guilabel
> funciona de la misma manera. Verá las conexiones como pequeñas líneas, entre las entradas y las salidas, en el centro de la ventana. Tenga en cuenta que un mismo origen se puede conectar con varios destinos (y viceversa). </para>

<para
>Los programas (como el secuenciador Brahms) se añadirán automáticamente al iniciarse y se eliminarán de la lista al cerrarse. Pero también se pueden añadir nuevos elementos utilizando el menú <guilabel
>Añadir</guilabel
>: </para>

<variablelist>
<varlistentry>
<term
><guimenuitem
>Puerto MIDI del sistema (OSS)</guimenuitem
></term>
<listitem>
<para
>Esto creará un nuevo objeto de &arts; que se comunicará con un puerto midi externo. </para>

<para
>Como los puertos midi externos pueden tanto enviar como recibir datos, esta opción añadirá una entrada y una salida. Bajo &Linux;, debería tener su tarjeta instalada bajo un controlador <acronym
>OSS</acronym
> (o <acronym
>OSS</acronym
>/Free, que viene incluído en el núcleo de &Linux;) o <acronym
>ALSA</acronym
>, para hacer que funcione. Se le pedirá el nombre del dispositivo. Normalmente será <filename class="devicefile"
>/dev/midi</filename
> o <filename class="devicefile"
>/dev/midi00</filename
>. </para>

<para
>Sin embargo, si tiene más de un dispositivo &MIDI; o un controlador de retorno de &MIDI; instalado, puede haber más opciones. Para obtener información sobre sus puertos midi, inicie el &kcontrolcenter;, y seleccione <menuchoice
><guilabel
>Información</guilabel
> <guilabel
>Sonido</guilabel
></menuchoice
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>Salida de síntesis MIDI de aRts</guimenuitem
></term>
<listitem>
<para
>Esto añadirá una nueva salida &MIDI; a un instrumento de síntesis de &arts;. Si elige el elemento del menú, se abrirá un diálogo que le permitirá escoger un instrumento. Puede crear nuevos instrumentos utilizando artsbuilder. Podrá elegir cualquiera de los archivos <literal role="extension"
>.arts</literal
> cuyo nombre comience por <filename
>instrument_</filename
>. </para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="brahms">
<title
>Uso de &arts; y Brahms</title>

<para
>En realidad, ponerlo en funcionamiento es muy sencillo. Se necesita una versión de &brahms; preparada para &kde; 2.1, que se puede encontrar en el módulo <acronym
>CVS</acronym
> de <literal
>kmusic</literal
>. También hay información de cómo obtener &brahms; en la <ulink url="http://www.arts-project.org/"
>página web de aRts</ulink
>, en la sección de descargas. </para>

<para
>Al iniciarlo, se mostrará el administrador &MIDI;. Si desea realizar síntesis, añada simplemente un instrumento de síntesis &MIDI; a través de <menuchoice
><guilabel
>Añadir</guilabel
><guilabel
>Salida de síntesis MIDI de aRts</guilabel
></menuchoice
>. </para>

<para
>Elija un instrumento (por ejemplo, <guilabel
>organ2</guilabel
>). Conéctelos utilizando el botón <guilabel
>Conectar</guilabel
>. Por último, puede comenzar a componer en &brahms;, y la salida será sintetizada por &arts;. </para>

<para
>En general, es una buena idea mantener la ventana de &artscontrol; abierta, y comprobar que el volumen no es excesivamente alto (la calidad empeora cuando las barras alcanzan el límite superior). Ahora puede comenzar a trabajar en una nueva canción con &arts;, y si ya ha terminado, puede publicarla en la página web aRts-project.org. </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
> es una pequeña aplicación que le permite enviar eventos &MIDI; desde la línea de órdenes. Se registrará como un cliente como cualquiera de las otras aplicaciones. La manera más sencilla de utilizarlo es <screen
><prompt
>&percnt;</prompt
> <userinput
><command
>midisend</command
> <option
>-f</option
> <parameter
><replaceable
>/dev/midi00</replaceable
></parameter
></userinput
> </screen
> que hará más o menos lo mismo que añadir un puerto &MIDI; del sistema en &artscontrol;. (No del todo, ya que <command
>midisend</command
> sólo envía eventos). La diferencia es que resulta sencillo, por ejemplo, iniciar <command
>midisend</command
> en varios ordenadores (y, de esa manera, utilizar la transparencia de red). </para>

<para
>También es posible hacer que <command
>midisend</command
> envíe datos desde <filename class="devicefile"
>stdin</filename
>, lo que se puede utilizar para reenviar información desde programas no compatibles con &arts;, de esta manera: <screen
><prompt
>&percnt;</prompt
> <userinput
><command
><replaceable
>aplicación_que_produce_eventos_midi_en_stdout</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
>Construcción de instrumentos</title>
 
<para
>La forma en la que &arts; hace síntesis midi es la siguiente: hay unas estructuras que tienen puertos de entrada, de donde se obtiene la frecuencia, la velocidad (volumen) y un parámetro que indica si la nota está aún pulsada. La estructura debe ahora sintetizar exactamente esa nota con ese volumen, y reaccionar en el parámetro de pulsación (donde 'pressed' = 1 significa que el usuario aún mantiene la tecla pulsado y 'pressed' = 0 significa que ya la ha soltado). </para>

<para
>Cuando lleguen los eventos &MIDI;, &arts; creará nuevas estructuras para las notas según sea vayan necesitando, dándoles los parámetros, y eliminándolas una vez haya terminado su cometido. </para>

<para
>Para crear un utilizar una de esas estructuras, debe hacer lo siguiente: </para>

<itemizedlist>
<listitem>
<para
>Para comenzar, la forma más cómoda es abrir <filename
>template_Instrument.arts</filename
> en &arts-builder;. </para>

<para
>Puede hacerlo usando <menuchoice
><guimenu
>Archivo</guimenu
><guimenuitem
>Abrir ejemplo...</guimenuitem
></menuchoice
> y escogiendo <guimenuitem
>template_Instrument</guimenuitem
> en el selector de archivos. Ésto proporcionará una estructura vacía con los parámetros requeridos, que solo necesitarán «rellenarse». </para>
</listitem>

<listitem>
<para
>Para procesar la falta de parámetros, es conveniente utilizar Synth&lowbar;ENVELOPE&lowbar;ADSR, o, en caso de reproducir alguna onda de percusión, hágalo sin más, ignorando los parámetros que falten. </para>
</listitem>

<listitem>
<para
>La propia estructura debería indicar cuándo ya no es necesaria a través de la salida «done». Si done vale <returnvalue
>1</returnvalue
>, &arts; asume que se puede borrar la estructura. El envoltorio ADSR proporciona un parámetro que llamado «done», no siendo necesario conectarse a la salida de la estructura. </para>
</listitem>

<listitem>
<para
>Debe renombrar su estructura a algún nombre que empiece por <filename
>instrument_</filename
>, como <filename
>instrument_piano.arts</filename
>. Debe guardar el archivo bajo el mismo nombre en su carpeta <filename class="directory"
>$<envar
>HOME</envar
>/arts/structures</filename
> (que es dónde artsbuilder guarda los archivos normalmente). </para>
</listitem>

<listitem>
<para
>Finalmente, una vez lo haya guardado será capaz de usarlo con &artscontrol; en el administrador &MIDI;.</para>
</listitem>

<listitem>
<para
>Oh, y por supuesto su estructura debería reproducir los datos de audio que genera para las salidas izquierda y derecha de la estructura, que se reproducirán entonces a través del administrador de audio (puede verlo en &artscontrol;), por lo que finalmente podrá oírlo (o postprocesarlo con efectos). </para>
</listitem>
</itemizedlist>

<para
>Un buen método para aprender cómo hacer instrumentos es abrir un instrumento existente a través de <menuchoice
><guilabel
>Archivo</guilabel
><guilabel
>Abrir ejemplo </guilabel
></menuchoice
> y mirar cómo funciona ;) </para>
</sect1>

<sect1 id="mapped-instruments">
<title
>Instrumentos mapeados</title>

<para
>Los instrumentos mapeados son instrumentos que se comportan de forma diferente dependiendo del tono, del programa, del canal o de la velocidad. Puede, por ejemplo, construir un piano de 5 octavas, utilizando una muestra para cada octava (desplazamiento del tono correspondiente). Esto suena mucho mejor que utilizar una única muestra. </para>

<para
>Puede también construir un mapa de tambores, que reproduce una muestra de tambor específica por cada tecla. </para>

<para
>Finalmente, es muy útil si coloca varios sonidos en un instrumento mapeado en diferentes programas. De esta manera, puede usar su secuenciador, teclado externo u otra fuente &MIDI; para cambiar entre los sonidos sin tener que tocar &arts; mientras trabaja. </para>

<para
>Un buen ejemplo de esto es el instrumento <filename
>arts_all</filename
>, que incluye todos los instrumentos que vienen con &arts; en un solo mapa. De esta manera, solo necesita establecerse una vez en &artscontrol; para usar este «instrumento», y así, puede componer una cancion entera en un secuenciador sin preocuparse de &arts;. ¿Necesita otro sonido? Simplemente cambie el programa del secuenciador, y &arts; le dará otro sonido. </para>

<para
>Crear estos mapas es muy fácil. Sólo necesita crear un archivo de texto y escribir reglas similares a éstas: </para>

<programlisting
>ON <replaceable
>[ condiciones ...]</replaceable
> DO structure=<replaceable
>estructura</replaceable
>.arts
</programlisting>

<para
>Las condiciones pueden ser una o más de entre las siguientes: </para>

<variablelist>

<varlistentry>
<term
><option
>pitch</option
></term>

<listitem>
<para
>El tono es lo que se reproduce. Debería utilizar esto si desea dividir su instrumento dependiendo del tono. En nuestros ejemplos iniciales, un piano que usa diferentes muestras para diferentes octavas debería utilizar esta condición. Puede especificar un solo tono, de forma similar a <userinput
><option
>pitch</option
>=<parameter
>62</parameter
></userinput
> o un rango de tonos, como <userinput
><option
>pitch</option
>=<parameter
>60</parameter
>-<parameter
>72</parameter
></userinput
>. Los posibles tonos se encuentran entre <parameter
>0</parameter
> y <parameter
>127</parameter
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>program</option
></term>
<listitem>
<para
>El programa está activo en el canal al que se envía la nota. Normalmente, los secuenciadores le permiten seleccionar el «instrumento» a través de la configuración del programa. Están permitidos los programas sencillos o los rangos, esto es, <userinput
><option
>program</option
>=<parameter
>3</parameter
></userinput
> o <userinput
><option
>program</option
>=<parameter
>3</parameter
>-<parameter
>6</parameter
></userinput
>. Los posibles programas se encuentran entre <parameter
>0</parameter
> y <parameter
>127</parameter
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><option
>channel</option
></term>
<listitem>
<para
>El canal al que se enviará la nota. Están permitidos los canales simples o los rangos, esto es <userinput
><option
>channel</option
>=<parameter
>0</parameter
></userinput
> o <userinput
><option
>channel</option
>=<parameter
>0</parameter
>-<parameter
>8</parameter
></userinput
>. Los posibles canales están entre <parameter
>0</parameter
> y <parameter
>15</parameter
>. </para>
</listitem>

</varlistentry>
<varlistentry>
<term
><option
>velocity</option
></term>
<listitem>
<para
>La velocidad (volumen) que tiene la nota. Se permiten velocidades simples (¿quién querría usar esto?) o los rangos, esto es, <userinput
><option
>velocity</option
>=<parameter
>127</parameter
></userinput
> o <userinput
><option
>velocity</option
>=<parameter
>64</parameter
>-<parameter
>127</parameter
></userinput
>. Las posibles velocidades están entre <parameter
>0</parameter
> y <parameter
>127</parameter
>. </para>
</listitem>
</varlistentry>
</variablelist>

<para
>Un ejemplo completo de un mapa puede ser (esto aparece en el actual <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
>Como puede ver, la estructura elegida depende del programa. En el programa 11, podrá ver un «mapa de batería» (con dos entradas), que reproducirá un «bombo» en C-5 (pitch=60), y un «platillo» en C#5 (pitch=61). </para>
 
<para
>Para hacer que los archivos de mapa aparezcan automáticamente en &artscontrol; como elección para el instrumento, deben llamarse <filename
>instrument_<replaceable
>algo</replaceable
>.arts-map</filename
> y residir en su carpeta, bajo <filename class="directory"
>$<envar
>HOME</envar
>/arts/structures</filename
>, o en la carpeta &kde; bajo <filename class="directory"
>$<envar
>KDEDIR</envar
> usr/local/kde/share/apps/artsbuilder/examples</filename
>. Las estructuras que usa el mapa pueden darse con una ruta absoluta, o con una ruta relativa a la carpeta en la que se encuentra. </para>

<para
>Extender el mapa arts_all e incluso hacer un mapa completo general de &MIDI; para &arts; es buena idea para hacer &arts; sencillo de utilizar tras instalarlo. Por favor, contribuya creando instrumentos interesantes que puedan ser incluídos en futuras versiones de &arts;. </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>
