From e2de64d6f1beb9e492daf5b886e19933c1fa41dd Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: 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 --- doc/artsbuilder/midi.docbook | 474 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 474 insertions(+) create mode 100644 doc/artsbuilder/midi.docbook (limited to 'doc/artsbuilder/midi.docbook') 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 @@ + + + +&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 ViewView 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 +AddaRts 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 /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 + + + + + + +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 &arts-builder;. + + + +This can be achieved by using +FileOpen +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 +folder (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 FileOpen +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: + + + + + + + + + +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 +=62 +or a range of pitches, like +=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 +=3 +or +=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 +=0 +or +=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 +=127 +or +=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 chosen 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 Folder, under $HOME/arts/structures, or in the +&kde; folder 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 folder 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;. + + + + + + -- cgit v1.2.1