Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdemultimedia@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 474 insertions, 0 deletions

diff --git a/doc/artsbuilder/midi.docbook b/doc/artsbuilder/midi.docbook
new file mode 100644
index 00000000..611b457c
--- /dev/null
+++ b/doc/artsbuilder/midi.docbook
@@ -0,0 +1,474 @@
+<!-- <?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>