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/artsbuilder.docbook | 864 ++++++++++++++++++++++++++++++++++++ 1 file changed, 864 insertions(+) create mode 100644 doc/artsbuilder/artsbuilder.docbook (limited to 'doc/artsbuilder/artsbuilder.docbook') diff --git a/doc/artsbuilder/artsbuilder.docbook b/doc/artsbuilder/artsbuilder.docbook new file mode 100644 index 00000000..b5f4f68c --- /dev/null +++ b/doc/artsbuilder/artsbuilder.docbook @@ -0,0 +1,864 @@ + +&arts-builder; + + +Overview + + +First of all, when trying to run &arts-builder; , you should also be +running the sound server (&artsd;). Usually, when you use &kde; 2.1, +this should already be the case. If not, you can configure the automatic +sound server startup in &kcontrol; under +SoundSound +Server. + + + +When you are running &arts;, it always runs small modules. &arts-builder; +is a tool to create new structures of small connected modules. You +simply click the modules inside the grid. To do so, choose them from the +Modules menu, and then click somewhere in the +green-gray plane. + + + +Modules usually have ports (where usually audio signals are flowing in +or out). To connect two ports, click on the first, which causes it to +turn orange, and then click on the second. You can only connect an input +port (on the upper side of a module) with an output port (on the lower +side of a module). If you want to assign a fixed value to a port (or +disconnect it), do so by double clicking on the port. + + + + + +Tutorial + + +Step 1 + + +Start &arts-builder;. + + + +You need a Synth_AMAN_PLAY-module to hear the output you +are creating. So create a Synth_AMAN_PLAY-module by +selecting Modules +Synthesis SoundIO +Synth_AMAN_PLAY and +clicking on the empty module space. Put it below the fifth line or so, +because we'll add some stuff above. + + + +The module will have a parameter title (leftmost +port), and autoRestoreID (besides the leftmost +port) for finding it. To fill these out, doubleclick on these ports, +select constant value and type tutorial in the +edit box. Click OK to apply. + + + +Select FileExecute +structure . You will hear absolutely +nothing. The play module needs some input yet... ;) If you have listened +to the silence for a while, click OK and go to +Step 2 + + + + +Step 2 + +Create a Synth_WAVE_SIN module (from +Modules Synthesis +Waveforms) +and put it above the Synth_AMAN_PLAY module. (Leave one line +space in between). + + + +As you see, it produces some output, but requires a +pos as input. First lets put the output to the +speakers. Click on the out port of the +Synth_WAVE_SIN and then on the left +port of Synth_AMAN_PLAY. Voila, you have connected two +modules. + + + +All oscillators in &arts; don't require a frequency as input, but a +position in the wave. The position should be between 0 and 1, which maps +for a standard Synth_WAVE_SIN object to the range +0..2*pi. To generate oscillating values from a frequency, a +Synth_FREQUENCY modules is used. + + + +Create a Synth_FREQUENCY module (from +Modules Synthesis +Oscillation & Modulation ) and +connect it's pos output to the pos input +of your Synth_WAVE_SIN. Specify the frequency port of the +FREQUENCY generator as constant value 440. + + + + +Select FileExecute +structure. You will hear a sinus wave at 440 +Hz on one of your speakers. If you have listened to it for a while, +click OK and go to Step 3. + + + + + +Step 3 + + +Ok, it would be nicer if you would hear the sin wave on both speakers. +Connect the right port of Synth_PLAY to the outvalue of the +Synth_WAVE_SIN as well. + + +Create a Synth_SEQUENCE object (from +Modules +SynthesisMidi & +Sequencing). It should be at the top of the +screen. If you need more room you can move the other modules by +selecting them (to select multiple modules use &Shift;), and dragging +them around. + + + +Now connect the frequency output of Synth_SEQUENCE to the +frequency input of the Synth_FREQUENCY module. Then specify the +sequence speed as constant value 0.13 (the speed is the leftmost port). + + + +Now go to the rightmost port (sequence) of Synth_SEQUENCE and +type in as constant value A-3;C-4;E-4;C-4; this +specifies a sequence. More to that in the Module Reference. + + + +Synth_SEQUENCE really needs a sequence +and the speed. Without that you'll perhaps get core dumps. + + + + +Select FileExecute +Structure. You will hear a nice sequence +playing. If you have enjoyed the feeling, click +OK and go to Step 4. + + + + +Step 4 + +Create a Synth_PSCALE module (from +Modules +Synthesis Envelopes +). Disconnect the outvalue of the SIN wave by doubleclicking it +and choosing not connected. Connect + + + +The SIN outvalue to the PSCALE invalue + + +The PSCALE outvalue to the AMAN_PLAY left + + +The PSCALE outvalue to the AMAN_PLAY right + + +The SEQUENCE pos to the PSCALE pos + + + + +Finally, set the PSCALE top to some value, for instance 0.1. + + + +How that works now: The Synth_SEQUENCE gives additional +information about the position of the note it is playing right now, +while 0 means just started and 1 means finished. The Synth_PSCALE +module will scale the audio stream that is directed through it from a +volume 0 (silent) to 1 (original loudness) back to 0 (silent). According +to the position. The position where the peak should occur can be given +as pos. 0.1 means that after 10% of the note has been played, the +volume has reached its maximum, and starts decaying afterwards. + + + +Select FileExecute +Structure. You will hear a nice sequence +playing. If you have enjoyed the feeling, click +OK and go to Step 5. + + + + + +Step 5: Starting to beam data around ;) + +Start another &arts-builder; + + +Put a Synth_AMAN_PLAY into it, configure it to a sane +name. Put a Synth_BUS_DOWNLINK into it and: + + + + +Set Synth_BUS_DOWNLINK bus to audio (that is just a name, +call it fred if you like) + + + + +Connect Synth_BUS_DOWNLINK left to +Synth_AMAN_PLAY left + + + + +Connect Synth_BUS_DOWNLINK right to +Synth_AMAN_PLAY right + + + + + +Start executing the structure. As expected, you hear nothing, ... not +yet. + + + +Go back to the structure with the Synth_WAVE_SIN stuff and +replace the Synth_AMAN_PLAY module by an +Synth_BUS_UPLINK, and configure the name to audio (or fred +if you like). Deleting modules works with selecting them and choosing +Edit +delete from the menu (or +pressing the Del key). + + + +Hit File Execute +structure. You will hear the sequence with +scaled notes, transported over the bus. + + + +If you want to find out why something like this can actually be useful, +click OK (in the &arts-builder; that is executing +the Synth_SEQUENCE stuff, you can leave the other one running) +and go to Step 6. + + + + +Step 6: Beaming for advanced users + + +Choose FileRename + structure from the menu of the artsbuilder which +contains the Synth_SEQUENCE stuff, and call it tutorial. Hit +OK. + + + +Choose File Save + + + + +Start yet another &arts-builder; and choose +FileLoad +, and load the tutorial again. + + + +Now you can select +FileExecute +structure in both &arts-builder;s having that +structure. You'll now hear two times the same thing. Depending on the +time when you start it it will sound more or less nice. + + + +Another thing that is good to do at this point in time is: start +&noatun;, and play some mp3. Start +&artscontrol;. Go to +ViewView audio +manager. What you will see is &noatun; and +your tutorial playback structure playing something. The +nice thing you can do is this: doubleclick on &noatun;. You'll now get a +list of available busses. And see? You can assign &noatun; to send it's +output via the audio bus your tutorial playback structure provides. + + + + +Step 7: Midi synthesis + + +Finally, now you should be able to turn your sin wave into an real +instrument. This only makes sense if you have something handy that could +send &MIDI; events to &arts;. I'll describe here how you can use some +external keyboard, but a midibus aware sequence like &brahms; will work +as well. + + + +First of all, clean up on your desktop until you only have one +&arts-builder; with the sine wave structure running (not executing). +Then, three times go to Ports +Create IN audio signal, and three +times to Ports Create OUT +audio signal. Place the ports somewhere. + + + +Finally, go to Ports Change +positions and names and call the ports +frequency, velocity, pressed, left, right, done. + + + +Finally, you can delete the Synth_SEQUENCE module, and rather +connect connect the frequency input port of the structure to the +Synth_FREQUENCY frequency port. Hm. But what do do about +pos? We don't have this, because with no algorithm in the +world, you can predict when the user will release the note he just +pressed on the midi keyboard. So we rather have a pressed parameter +instead that just indicates wether the user still holds down the +key. (pressed = 1: key still hold down, pressed = 0: key +released) + + + +That means the Synth_PSCALE object also must be replaced +now. Plug in a Synth_ENVELOPE_ADSR instead (from +Modules +Synthesis Envelopes +). Connect: + + + + +The pressed structure input to the ADSR active + + +The SIN outvalue to the ADSR invalue + + +The ADSR outvalue to the left structure output + +The ADSR outvalue to the right structure output + + + + +Set the parameters attack to 0.1, decay to 0.2, sustain to 0.7, release +to 0.1. + + + +Another thing we need to think of is that the instrument structure +somehow should know when it is ready playing and then be cleaned up, +because otherwise it would be never stopped even if the note has been +released. Fortunately, the ADSR envelope knows when the will be nothing +to hear anymore, since it anyway scales the signal to zero at some point +after the note has been released. + + + +This is indicated by setting the done output to 1. So connect this to +the done output of the structure. The structure will be removed as soon +as done goes up to 1. + + + +Rename your structure to instrument_tutorial (from +File Rename +structure. Then, save it using save as (the +default name offered should be instrument_tutorial +now).Start artscontrol, and go to +ViewMidi +Manager, and choose +AddaRts Synthesis Midi +Output. Finally, you should be able to +select your instrument (tutorial) here. + + + +Open a terminal and type +midisend. You'll see that +midisend and the instrument are listed now in the +&arts; &MIDI; manager. After selecting both and hitting +connect, we're finally done. Take your keyboard +and start playing (of course it should be connected to your computer). + + + + +Suggestions + + +You now should be able to work with &arts;. Here are a few tips what you +could try to improve with your structures now: + + + + + +Try using other things than a SIN wave. When you plug in a TRI wave, you +will most likely think the sound is not too nice. But try appending a +SHELVE_CUTOFF filter right after the TRI wave to cut the +frequenciesabove a certain frequency (try something like 1000 Hz, or +even better two times the input frequency or input frequency+200Hz or +something like that). + + + + +Try using more than one oscillator. Synth_XFADE can be used to +cross fade (mix) two signals, Synth_ADD to add them. + + + + +Try setting the frequencies of the oscillators to not exactly the same +value, that gives nice oscillations. + + + + +Experiment with more than one envelope. + + + + +Try synthesizing instruments with different output left and right. + + + + +Try postprocessing the signal after it comes out the bus downlink. You +could for instance mix a delayed version of the signal to the original +to get an echo effect. + + + + +Try using the velocity setting (its the strength with which the note has +been pressed, you could also say volume). The special effect is always +when this not only modifies the volume of the resulting signal, but as +well the sound of the instrument (for instance the cutoff frequency). + + + +... + + + + +If you have created something great, please consider providing it for +the &arts; web page. Or for inclusion into the next release. + + + + + + +Examples + + +&arts-builder; comes with several examples, which can be opened through +FileOpen +Example... . Some of them are in the +folder, some of them (which for some reason don't work with the +current release) are left in the todo folder. + + +The examples fall into several categories: + + + + + +Standalone examples illustrating how to use each of the built-in +arts modules (named example_*.arts). These +typically send some output to a sound card. + + + + + +Instruments built from lower level arts modules (named +instrument_*.arts). These following a standard +convention for input and output ports so they can be used by the &MIDI; +manager in &artscontrol;. + + + + + +Templates for creating new modules (names +template_*.arts). + + + + + +Effects which can be used as reusable building blocks (named +effect_*.arts) [ all in todo ] + + + + + +Mixer elements used for creating mixers, including graphical +controls (named mixer_element_*.arts). [ all in todo ] + + + + + +Miscellaneous modules that don't fit into any of the above categories. + + + + + +Detailed Description Of Each Module: + +example_stereo_beep.arts + + +Generates a 440Hz sine wave tone in the left channel and an 880Hz sine +wave tone in the right channel, and sends it to the sound card +output. This is referenced in the &arts; documentation. + + + + + +example_sine.arts + + +Generates a 440 Hz sine wave. + + + + + +example_pulse.arts + + +Generates a 440 Hz pulse wave with a 20% duty cycle. + + + + + +example_softsaw.arts + + +Generates a 440 Hz sawtooth wave. + + + + + +example_square.arts + + +Generates a 440 Hz square wave. + + + + + +example_tri.arts + + +Generates a 440 Hz triangle wave. + + + + + +example_noise.arts + + +Generates white noise. + + + + + +example_dtmf1.arts + + +Generates a dual tone by producing 697 and 1209 Hz sine waves, scaling +them by 0.5, and adding them together. This is the DTMF tone for the +digit "1" on a telephone keypad. + + + + + +example_atan_saturate.arts + + +Runs a triangle wave through the atan saturate filter. + + + + + +example_autopanner.arts + + +Uses an autopanner to pan a 400 Hz sine wave between the left and right +speakers at a 2 Hz rate. + + + + + +example_brickwall.arts + + +Scales a sine wave by a factor of 5 and then runs it through a brickwall +limiter. + + + + + +example_bus.arts + + +Downlinks from a bus called Bus and uplinks to the bus +out_soundcard with the left and right channels reversed. + + + + + +example_cdelay.arts + + +Downlinks from a bus called Delay, uplinks the right +channel through a 0.5 second cdelay, and the left channel unchanged. You +can use &artscontrol; to connect the effect to a sound player and +observe the results. + + + + + +example_delay.arts + + +This is the same as example_cdelay.arts but used +the delay effect. + + + + + +example_capture_wav.arts + + +This uses the Synth_CAPTURE_WAV to save a 400 Hz sine wave as a wav +file. Run the module for a few seconds, and then examine the file +created in /tmp. You can play the +file with a player such as kaiman. + + + + + +example_data.arts + + +This uses the Data module to generate a constant stream of the value +3 and sends it to a Debug module to periodically display +it. It also contains a Nil module, illustrating how it can be used to do +nothing at all. + + + + + +example_adsr.arts + + +Shows how to create a simple instrument sound using the Envelope Adsr +module, repetitively triggered by a square wave. + + + + + +example_fm.arts + + +This uses the FM Source module to generate a 440 Hz sine wave which is +frequency modulated at a 5 Hz rate. + + + + + +example_freeverb.arts + + +This connects the Freeverb effect from a bus downlink to a bus +outlink. You can use artscontrol to connect the effect to a sound player +and observe the results. + + + + + +example_flanger.arts + + +This implements a simple flanger effect (it doesn't appear to work yet, +though). + + + + + +example_moog.arts + + +This structure combines the two channels from a bus into one, passes it +though the Moog VCF filter, and sends it out the out_soundcard bus. + + + + + +example_pitch_shift.arts + + +This structure passes the left channel of sound card data through the +Pitch Shift effect. Adjust the speed parameter to vary the effect. + + + + + +example_rc.arts + + +This structure passes a white noise generator though an RC filter and +out to the sound card. By viewing the FFT Scope display in artscontrol +you can see how this varies from an unfiltered noise waveform. + + + + + +example_sequence.arts + + +This demonstrates the Sequence module by playing a sequence of notes. + + + + + +example_shelve_cutoff.arts + + +This structure passes a white noise generator though a Shelve Cutoff +filter and out to the sound card. By viewing the FFT Scope display in +artscontrol you can see how this varies from an unfiltered noise +waveform. + + + + + +example_equalizer.arts + + +This demonstrates the Std_Equalizer module. It boosts the low and high +frequencies by 6 dB. + + + + + +example_tremolo.arts + + +This demonstrates the Tremolo effect. It modulates the left and right +channels using a 10 Hz tremolo. + + + + + +example_xfade.arts + + +This example mixes 440 and 880 Hz sine waves using a cross fader. +Adjust the value of the cross fader's percentage input from -1 to 1 to +control the mixing of the two signals. + + + + + +example_pscale.arts + + +This illustrates the Pscale module (I'm not sure if this is a +meaningful example). + + + + + +example_play_wav.arts + + +This illustrates the Play Wave module. You will need to +enter the full path to a .wav file +as the filename parameter. + + + + + +example_multi_add.arts + + +This shows the Multi Add module which accepts any number of inputs. It +sums three Data modules which produce inputs of 1, 2, and 3, and +displays the result 6. + + + + + + + -- cgit v1.2.1