# &MIDI;

## Overview

The &MIDI; support in &arts; can do a number of things. First of all, it allows communication 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.

On the other hand, &arts; can also help applications to interact with the hardware. 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.

Finally, &arts; makes a great modular synthesizer. 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.

## The &MIDI; Manager

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 View View Midi Manager from the menu.

On the left side, you will see Midi Inputs. 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 Midi Outputs. 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.

You can connect inputs and outputs if you mark the input on the left side and the output on the right side, and choose Connect with the button below. Disconnect 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).

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 Add menu:

System Midi Port (OSS)

  This will create a new &arts; object that talks to an external midi port.

  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 OSS (or OSS/Free, the thing that comes with your &Linux; kernel) or an ALSA driver for your soundcard installed, to make it work. It will ask for the name of the device. Usually, this is `/dev/midi` or `/dev/midi00`.

  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 Information Sound.

aRts Synthesis Midi Output

  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 `.arts` files with a name that starts with `instrument_` will appear here.

## Using &arts; & Brahms

Actually, getting started is quite easy. You need a &kde; 2.1-aware version of &brahms;, which can be found in the `kmusic` CVS module. There is also information on how to get &brahms; on the aRts Homepage in the Download section.

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 Add aRts Synthesis Midi Output.

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

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 ;-).

## midisend

`midisend` 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

    % midisend -f /dev/midi00

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

It is also possible to make `midisend` send data from `stdin`, which you can use to pipe data from non-&arts;-aware applications to &arts;, like this:

    % applicationwhichproducesmidieventsonstdout | midisend -f -

## Creating Instruments

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).

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.

To create and use such a structure, you should do the following:

- To get started, the most convenient way is to open `template_Instrument.arts` in &artsbuilder;.

  This can be achieved by using File Open Example... and choosing template_Instrument in the file selector. This will give you an empty structure with the required parameters, which you only need to fill out.

- 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.

- The structure should indicate when it is no longer needed on the done output. If done is 1, &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.

- You should rename your structure to some name starting with `instrument_`, like `instrument_piano.arts` - you should save the file under the same name, in your `$`HOME`/arts/structures` directory (which is where artsbuilder wants to save files normally).

- Finally, once you saved it, you will be able to use it with &artscontrol; in the &MIDI; manager .

- 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).

A good way to learn how to do instruments is to open an existing instrument via File Open Example and see how it works ;)

## Mapped Instruments

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.

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

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.

A good example for this is the instrument `arts_all`, 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 instrument, 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.

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

    ON [ conditions ...] DO structure=somestructure.arts

The conditions could be one or more than one of the following:

`pitch`

  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 ``pitch`=62` or a range of pitches, like ``pitch`=60-72`. The possible pitches are between 0 and 127.

`program`

  The program that is active on the channel that the note is being sent on. Usually, sequencers let you choose the instrument via the program setting. Single programs or ranges are allowed, that is ``program`=3` or ``program`=3-6`. The possible programs are between 0 and 127.

`channel`

  The channel that that the note is being sent on. Single channels or ranges are allowed, that is ``channel`=0` or ``channel`=0-8`. The possible channels are between 0 and 15.

`velocity`

  The velocity (volume) that that the note has. Single velocities (who would use that?) or ranges are allowed, that is ``velocity`=127` or ``velocity`=64-127`. The possible velocities are between 0 and 127.

A complete example for a map would be (this is taken from the current `instrument_arts_all.arts-map`):

    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

As you see, the structure is choosen depending on the program. On program 11, you see a drum map (with two entries), which would play a deepdrum on C-5 (pitch=60), and a chirpdrum on C#5 (pitch=61).

To make map files automatically appear in &artscontrol; as choice for the instrument, they have to be called `instrument_something.arts-map` and reside either in your Home Directory, under `$`HOME`/arts/structures`, or in the &kde; directory under `$`KDEDIR`/usr/local/kde/share/apps/artsbuilder/examples`. Structures that are used by the map can either be given with an absolute path, or relative to the directory the map file resides in.

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;.