diff options
Diffstat (limited to 'doc/artsbuilder/midi.docbook')
| -rw-r--r-- | doc/artsbuilder/midi.docbook | 474 |
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; & 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>%</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>%</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_ENVELOPE_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> |