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