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:
1 ON [ conditions ...] DO structure=somestructure.arts
The conditions could be one or more than one of the following
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.
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.
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.
The velocity (volume) that that the note has. Single velocities (who would use that?) or ranges are allowed, that is velocity=127 or veclocity=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):
1 ON program=0 DO structure=instrument_tri.arts 2 ON program=1 DO structure=instrument_organ2.arts 3 ON program=2 DO structure=instrument_slide1.arts 4 ON program=3 DO structure=instrument_square.arts 5 ON program=4 DO structure=instrument_neworgan.arts 6 ON program=5 DO structure=instrument_nokind.arts 7 ON program=6 DO structure=instrument_full_square.arts 8 ON program=7 DO structure=instrument_simple_sin.arts 9 ON program=8 DO structure=instrument_simple_square.arts 10 ON program=9 DO structure=instrument_simple_tri.arts 11 ON program=10 DO structure=instrument_slide.arts 12 ON program=11 pitch=60 DO structure=instrument_deepdrum.arts 13 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.