tdemultimedia/doc/artsbuilder/midi.docbook

<!-- <?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>Overview</title>

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

<para>
The &MIDI; support in &arts; can do a number of things. First of all, it
allows <emphasis>communication</emphasis> between different pieces of
software that produce or consume &MIDI; events. If you for instance have
a sequencer and a sampler that are both &arts; aware, &arts; can send
the &MIDI; events from the sequencer to the sampler.
</para>

<para>
On the other hand, &arts; can also help applications to
<emphasis>interact with the hardware</emphasis>. If a piece of software
(for instance the sampler) works together with &arts;, it will be able
to receive the &MIDI; events from an external &MIDI; keyboard as well.
</para>

<para>
Finally, &arts; makes a great <emphasis>modular
synthesizer</emphasis>. It is designed to do exactly this. So you can
build instruments out of small modules using artsbuilder, and then use
these instruments to compose or play music.  Synthesis does not
necessarily mean pure synthesis, there are modules you can use to play
samples. So &arts; can be a sampler, synthesizer, and so on, and being
fully modular, it is very easy to extend, very easy to experiment with,
powerful and flexible.
</para>
</sect1>

<sect1 id="midi-manager">
<title>The &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>
The central component in &arts; that keeps track which applications are
connected and how midi events should be passed between them is the midi
manager. To see or influence what it does, start artscontrol. Then,
choose <menuchoice><guilabel>View</guilabel><guilabel>View Midi
Manager</guilabel> </menuchoice> from the menu.
</para>

<para>
On the left side, you will see <guilabel>Midi Inputs</guilabel>. There,
all objects that produce &MIDI; events, such as an external &MIDI; port
which sends data from a connected &MIDI; keyboard, a sequencer which
plays a song and so on will be listed. On the right side, you will see
<guilabel>Midi Outputs</guilabel>. There, all things that consume &MIDI;
events, such as a simulated sampler (as software), or the external
&MIDI; port where your hardware sampler outside your computer is
connected will be listed. New applications, such as sequencers and so on
will register themselves, so the list will be changing over time.
</para>

<para>
You can connect inputs and outputs if you mark the input on the left
side and the output on the right side, and choose
<guilabel>Connect</guilabel> with the button
below. <guilabel>Disconnect</guilabel> works the same. You will see what
is connected as small lines between the inputs and outputs, in the
middle of the window. Note that you can connect one sender to more than
one receiver (and the other way round).
</para>

<para>
Programs (like the Brahms sequencer) will add themselves when they start
and be removed from the list when they are terminated. But you can also
add new things in the <guilabel>Add</guilabel> menu:
</para>

<variablelist>
<varlistentry>
<term><guimenuitem>System Midi Port (OSS)</guimenuitem></term>
<listitem>
<para>
This will create a new &arts; object that talks to an external midi
port.
</para>

<para>
As external midi ports can do both, send and receive data, choosing this
option will add a midi input and a midi output. Under &Linux;, you
should either have an <acronym>OSS</acronym> (or
<acronym>OSS</acronym>/Free, the thing that comes with your &Linux;
kernel) or an <acronym>ALSA</acronym> driver for your soundcard
installed, to make it work. It will ask for the name of the
device. Usually, this is <filename
class="devicefile">/dev/midi</filename> or <filename
class="devicefile">/dev/midi00</filename>.
</para>

<para>
However, if you have more than one &MIDI; device or a &MIDI; loopback
driver installed, there might be more choices. To see information about
your midi ports, start the &kcontrolcenter;, and choose
<menuchoice><guilabel>Information</guilabel>
<guilabel>Sound</guilabel></menuchoice>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>aRts Synthesis Midi Output</guimenuitem></term>
<listitem>
<para>
This will add a new &MIDI; output with an &arts; synthesis
instrument. If you choose the menu item, a dialog will pop up, and allow
you to choose an instrument. You can create new instruments using
artsbuilder. All <literal role="extension">.arts</literal> files with a
name that starts with <filename>instrument_</filename> will appear here.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

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

<para>
Actually, getting started is quite easy. You need a &kde; 2.1-aware
version of &brahms;, which can be found in the <literal>kmusic</literal>
<acronym>CVS</acronym> module.  There is also information on how to get
&brahms; on the <ulink url="http://www.arts-project.org/">aRts
Homepage</ulink> in the Download section.
</para>

<para>
When you start it, it will show up in the &MIDI; manager. If you want to
do synthesis, simply add a synthesis &MIDI; instrument via
<menuchoice><guilabel>Add</guilabel><guilabel>aRts Synthesis Midi
Output</guilabel></menuchoice>.
</para>

<para>
Choose an instrument (for instance <guilabel>organ2</guilabel>). Connect
them using the <guilabel>Connect</guilabel> button. Finally, you can
start composing in &brahms;, and the output will be synthesized with
&arts;.
</para>

<para>
It is usually a good idea to have the &artscontrol; window open, and see
that the volume is not too loud (quality gets bad when the bars hit the
upper limit). Now you can start working on a new &arts; demosong, and if
you are done, you can get it published on 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> is a small application that will allow you
to send &MIDI; events from 
the shell. It will register as client like all other applications. The most
simple way to use it is to do

<screen><prompt>&percnt;</prompt> <userinput><command>midisend</command> <option>-f</option> <parameter><replaceable>/dev/midi00</replaceable></parameter></userinput> </screen>

which will achieve about the same as adding a system &MIDI; port in
&artscontrol;. (Not quite, because <command>midisend</command> only sends events). The difference is that it is
easy for instance to start <command>midisend</command> on different computers (and like that,
use network transparency).
</para>

<para>
It is also possible to make <command>midisend</command> send data from
<filename class="devicefile">stdin</filename>, which you can use to pipe
data from non-&arts;-aware applications to &arts;, like this:

<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>Creating Instruments</title>
 
<para>
The way &arts; does midi synthesis is this: you have a structures which
has some input ports, where it gets the frequency, velocity (volume) and
a parameter which indicates whether the note is still pressed.  The
structure should now synthesize exactly that note with that volume, and
react on the pressed parameter (where pressed = 1 means the user still
holds down that key and pressed = 0 means the user has released that
key).
</para>

<para>
When &MIDI; events arrive, &arts; will create new structures for the
notes as needed, give them the parameters, and clean them up once they
are done.
</para>

<para>
To create and use such a structure, you should do the following:
</para>

<itemizedlist>
<listitem>
<para>
To get started, the most convenient way is to open
<filename>template_Instrument.arts</filename> in &arts-builder;.
</para>

<para>
This can be achieved by using
<menuchoice><guimenu>File</guimenu><guimenuitem>Open
Example...</guimenuitem></menuchoice> and choosing
<guimenuitem>template_Instrument</guimenuitem> in the file
selector. This will give you an empty structure with the required
parameters, which you only need to <quote>fill out</quote>.
</para>
</listitem>

<listitem>
<para>
To process the pressed parameter, it is convenient to use
Synth&lowbar;ENVELOPE&lowbar;ADSR, or, in case of playing some drum wav,
just play it anyway, and ignore the pressed parameter.
</para>
</listitem>

<listitem>
<para>
The structure should indicate when it is no longer needed on the
<quote>done</quote> output. If done is <returnvalue>1</returnvalue>,
&arts; assumes that it can delete the structure. Conveniently, the ADSR
envelope provides a parameter when it is done, so you just need to
connect this to the done output of the structure. 
</para>
</listitem>

<listitem>
<para>
You should rename your structure to some name starting with
<filename>instrument_</filename>, like
<filename>instrument_piano.arts</filename> - you should save the file
under the same name, in your <filename
class="directory">$<envar>HOME</envar>/arts/structures</filename>
folder (which is where artsbuilder wants to save files normally).
</para>
</listitem>

<listitem>
<para>
Finally, once you saved it, you will be able to use it with &artscontrol;
in the &MIDI; manager <!-- todo link to midimanager -->.</para>
</listitem>

<listitem>
<para>
Oh, and of course your structure should play the audio data it generates
to the left and right output of the structure, which will then be played
via audio manager (you can see that in &artscontrol;), so that you
finally can hear it (or postprocess it with effects).
</para>
</listitem>
</itemizedlist>

<para>
A good way to learn how to do instruments is to open an existing
instrument via <menuchoice><guilabel>File</guilabel><guilabel>Open
Example</guilabel> </menuchoice> and see how it works ;)
</para>
</sect1>

<sect1 id="mapped-instruments">
<title>Mapped Instruments</title>

<para>
Mapped instruments are instruments, that behave differently depending on
the pitch, the program, the channel or the velocity. You could for
instance build a piano of 5 octaves, using one sample for each octave
(pitchshifting it accordingly). That sounds a whole lot better than only
using one sample.
</para>

<para>
You could also build a drum map, that plays one specific drum sample per
key.
</para>

<para>
Finally, it is very useful if you put quite some different sounds into
one mapped instrument on different programs. That way, you can use your
sequencer, external keyboard or other &MIDI; source to switch between
the sounds without having to tweak &arts; as you work.
</para>

<para>
A good example for this is the instrument <filename>arts_all</filename>,
which just puts together all instruments that come with &arts; in one
map. That way, you just need to setup once in &artscontrol; to use this
<quote>instrument</quote>, and then, you can compose a whole song in a
sequencer without ever bothering about &arts;. Need another sound?
Simply change the program in the sequencer, and &arts; will give you
another sound.
</para>

<para>
Creating such maps is pretty straightforward. You just need to create a
textfile, and write rules which look like this:
</para>

<programlisting>
ON <replaceable>[ conditions ...]</replaceable> DO structure=<replaceable>somestructure</replaceable>.arts
</programlisting>

<para>
The conditions could be one or more than one of the following:
</para>

<variablelist>

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

<listitem>
<para>
The pitch that is being played. You would use this if you want to split
your instrument depending on the pitch. In our initial examples, a piano
which uses different samples for different octaves would use this as
condition. You can specify a single pitch, like
<userinput><option>pitch</option>=<parameter>62</parameter></userinput>
or a range of pitches, like
<userinput><option>pitch</option>=<parameter>60</parameter>-<parameter>72</parameter></userinput>.
The possible pitches are between <parameter>0</parameter> and
<parameter>127</parameter>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>program</option></term>
<listitem>
<para>
The program that is active on the channel that the note is being sent
on. Usually, sequencers let you choose the <quote>instrument</quote> via
the program setting.  Single programs or ranges are allowed, that is
<userinput><option>program</option>=<parameter>3</parameter></userinput>
or
<userinput><option>program</option>=<parameter>3</parameter>-<parameter>6</parameter></userinput>.
The possible programs are between <parameter>0</parameter> and
<parameter>127</parameter>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>channel</option></term>
<listitem>
<para>
The channel that that the note is being sent on.  Single channels or
ranges are allowed, that is
<userinput><option>channel</option>=<parameter>0</parameter></userinput>
or
<userinput><option>channel</option>=<parameter>0</parameter>-<parameter>8</parameter></userinput>.
The possible channels are between <parameter>0</parameter> and
<parameter>15</parameter>.  
</para>
</listitem>

</varlistentry>
<varlistentry>
<term><option>velocity</option></term>
<listitem>
<para>
The velocity (volume) that that the note has.  Single velocities (who
would use that?) or ranges are allowed, that is
<userinput><option>velocity</option>=<parameter>127</parameter></userinput>
or
<userinput><option>velocity</option>=<parameter>64</parameter>-<parameter>127</parameter></userinput>.
The possible velocities are between <parameter>0</parameter> and
<parameter>127</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
A complete example for a map would be (this is taken from the current
<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>
As you see, the structure is chosen depending on the program. On
program 11, you see a <quote>drum map</quote> (with two entries), which
would play a <quote>deepdrum</quote> on C-5 (pitch=60), and a
<quote>chirpdrum</quote> on C#5 (pitch=61).
</para>
 
<para>
To make map files automatically appear in &artscontrol; as choice for
the instrument, they have to be called
<filename>instrument_<replaceable>something</replaceable>.arts-map</filename>
and reside either in your Home Folder, under <filename
class="directory">$<envar>HOME</envar>/arts/structures</filename>, or in the
&kde; folder under <filename
class="directory">$<envar>KDEDIR</envar>/usr/local/kde/share/apps/artsbuilder/examples</filename>. Structures
that are used by the map can either be given with an absolute path, or
relative to the folder the map file resides in.
</para>

<para>
Extending the arts_all map or even making a complete general &MIDI; map
for &arts; is a good idea for making &arts; easier to use
out-of-the-box.  Please consider contributing interesting instruments
you make, so that they can be included in further version of &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>