User Guide - Plugin Reference

Plugin Reference

This section deals with the inputs, outputs, and signals associated with each class of component. Most component classes are implemented within a single plugin file - and most plugins contain only one component class.

If the documentation doesn't explain something you think should be explained, or if it's not the clearest way of expressing it, please contact me and let me know what needs changing or adding. If you're really confused about something, reading the source code is a very good way of getting a feel for what's really going on with the job a plugin is doing.

Note that if you can't remember which connector does what, just click with the right-hand mouse button while hovering over the connector you want to find out about. The "Disconnect" menu option will appear, including as part of its name the name of the connector that it refers to.

Sources/Simple Oscillator
This plugin generates a waveform on its signal output. The three event inputs are Trigger, Frequency, and Oscillator Kind, respectively. Trigger resets the oscillator, causing the phase of the generated signal to jump back to zero. Frequency controls the frequency of the signal, in Hertz (Hz, cycles per second). The Oscillator Kind input controls the shape of the waveform generated - if it is set to zero, a sine wave is generated; to one, a square wave is generated; and to two, a sawtooth wave is generated. The default waveform is a square wave.

Sources/White Noise Generator
This plugin generates a stream of pseudo-random numbers between -1.0 and 1.0, using the C library call random(). (Note that completely random samples taken together are white noise - useful for many different kinds of sound effect.)

Sources/Sampled Voice
This plugin is intended to replay a sample that is stored on disk. Use the Properties option from the component menu to load in a sample file. You will need to use the rart or polyrart plugins if you wish to trigger and stream the sample.

Sources/Variable Oscillator
This plugin is almost identical to the Simple Oscillator, but receives its frequency-control information from a signal connector rather than an event connector. This allows for much more efficient rapid changes of frequency, ideal for use in an FM synthesis module, for instance. The event input connectors do the same job as in the Simple Oscillator (with the obvious exception being the lack of a "frequency" event connector in the Variable Oscillator).

Sources/OSS Input
This plugin (audio_in), currently available on Linux only, reads samples from the currently selected input device on the soundcard and streams them out its signal connector. It can be used to implement an effects chain in conjunction with other plugins - watch the latency though! You can set the size of the buffers via the Edit/Preferences dialog, for both oss_input and oss_output plugins. (Note that the smaller the fragment, the lower the latency, but the greater the chance of buffer underruns (on output) or clicks and pops (on input). YMMV - the default is a buffer size of 12 (ie 2¹² = 4096 bytes).)

Sources/OGG Input RA
This plugin (ogg_ra) is the core of an ogg player. It reads BufferLength seconds from an ogg stream set with the streamname event for every fill buffer event. This Buffer is then accessible through the randomaccess out connectors on the right hand side of the component. The skip event tells the component to skip to n seconds from the beginning of the stream. So the next time fill buffer is received it reads from this position. The streamname event can be emitted by a strcombo component or by a filerequester component. The AtEnd connector emits an event when the stream is at the end. You could wire this to the skip connector for loop playing.

Outputs/OSS Output
Outputs/ESound Output
Outputs/Win32 Output
These three plugins all create a component of class audio_out - use the Preferences dialog box to choose which plugin you want to deal with components of this class by default. When choosing from the New menu, you can choose whichever you want, but when loading from a file, gAlan will use the plugin you specify in the preferences. The two inputs are the left and right channels - all three plugins output in stereo.

Outputs/WAV Recorder (PCM, Stereo)
This plugin allows you to dump an audio signal out to a WAV file, courtesy of Michael Pruetts audiofile sound-file-format library. The two signal inputs are stereo left and right, respectively, and the lone event input is used to tell the plugin to start or stop recording - an event with value 1.0 starts recording, and an event with value 0.0 stops it. (Note that the control available from the "New Control" menu sends just such events internally to this event connector, without your needing to connect to it yourself.) As soon as a 1.0-event is received, the plugin pops up a dialog box asking you to select a file to write the WAV output to (a .wav extension is highly recommended). As soon as "OK" is clicked, with a valid filename chosen, recording starts. As soon as an 0.0-event is received, recording stops, and a dialog box pops up with some statistics about the data recorded.

Outputs/Emu10k1 Output
This plugin is only an OSS Output which outputs to /dev/dsp and /dev/dsp1 at once. So you can use the front and rear outputs of an SB/Live. I dont know how drivers of other soundcards behave so it could be useful for these as well.

Misc/Randomaccess to Realtime Converter
This plugin, when triggered by the reception of an event on its lone event input connector, begins streaming the randomaccess content connected to its signal input out its realtime signal output. After the randomaccess content runs out, this plugin generates silence until retriggered, at which point it begins again.

Misc/Clock
The clock is an essential part of working with sequencers with gAlan. It has a single parameter, frequency (the left of the two event inputs), which controls how often an event is sent out the connector on the bottom. The right-hand of the two top connectors is the "trigger" connector - it is used internally, and you should not need to connect to it under normal circumstances. Read the code (plugins/clock.c) to find out more.

Misc/Signal-to-event Converter
Each time an event is received (for instance, from a clock plugin) on the input event connector, a single sample is taken from the signal input connector, and sent on out the output event connector. With a suitably high frequency of triggering, this can provide an excellent control source from a time-varying signal input such as a sine-wave oscillator.

Misc/Polyphonic Randomaccess Streamer
This plugin is very similar to the regular (monophonic) randomaccess-to-realtime-converter, except that it is, in a sense, polyphonic (with the degree of polyphony controllable at compile time by editing a #define in plugins/polyrart.c). It works well so long as the input stays the same - such as playing a sample without changing the speed/pitch of the sample. If the pitch of the source were changed, all the currently active "voices" would pick up the change, so it's not true polyphony. You can't play several different-pitch notes at once (they have to all be the same). I'm still thinking of a good way of implementing proper polyphony. Can anyone help out here?

Misc/Scope
This plugin is a simple osciloscope which can display the audio signal it is connected to. It samples xsize seconds and displays them. When it receives a trigger event it drops its data and samples again. So if you connect a clock running at 10Hz to the trigger and xsize is set to a value larger than 0.1s it will not display anything because it drops its data before it has sampled xsize seconds.

Misc/Settings
This plugin can save 8 values in each of its 16 Memlines. If it receives an event on an input line it saves the value into the current memline and passes the value to the output line. If it then receives an event on the MemLine connector it will emit the saved values for the selected MemLine.

Misc/Sampler
This plugin samples XSize seconds when it receives a trigger event. You can then mark a region in the sampledisplay control and press the loop button. This loop region will be accessible on the randomaccess connector.

Controls/Control
The generic control plugin plays an important role in many different circumstances. It can be used either as a control for providing a number within a set range, or as a button which generates an event each time it is pressed. It can also act as a toggle-button - this can be useful when the control is connected to a gain component, as a mute button, or when connected to a pcm_out component, as a record/stop control. The event connector on the top is used internally and you should not need to connect to it under normal circumstances. The Properties option from the component-menu allows you to set the upper and lower bounds for the knob and slider controls. For the knob and slider controls, each time the value changes an event is sent out the bottom connector. For the button control, an event of value 1.0 is sent each time the button is pressed. For the toggle-button control, an event is sent each time the button is pressed - the event has value 1.0 if the button is toggled on (depressed) or 0.0 if the button is toggled off (raised).

Controls/Signal Control
This plugin is in a sense the inverse of a sig2evt plugin, discussed above - it accepts an event on its event input connector, and continuously streams out the value it received on its signal output connector. It is also akin to the Control plugin immediately above: it provides a knob, a slider and a toggle-button of its own, and they do the expected thing with regard to the level of the signal sent out the signal connector. The only real point of difference between the controls a Signal Control and a Control make available is the lack of a normal button control from the Signal Control - it's a bit pointless as a button only has one state: what would it change in the output signal?

Controls/Joyport
This plugin makes the joyport visible to galan. It has connectors for 6 Axes and 2 for the buttons. When a button is pressed the number of the button is emitted on the ButtonDown connector. When the button is released its number is emitted on the ButtonUp connector. You can use the Events/Gate2 or Events/Compare plugins to filter the events.

Levels/Gain
There are two main uses for this plugin - scaling an audio signal by a fixed amount, and collecting (multiplexing) many inputs into a single output. The single event connector on top receives the amount of gain to be applied by this plugin - this value can usefully range between 0.0 and infinity. Use the value 1.0 to pass the signal(s) through unscaled.

Levels/Envelope Gain
This plugin reads both its inputs, multiplies them together, and sends the result out its output connector. This can be used to implement several useful structures - for instance, a ring modulator or a volume envelope (in conjunction with an adsr plugin and a rart plugin).

Levels/DC Bias
This plugin is useful for shifting a waveform up or down by a constant amount (it does not alter the amplitude of the wave, just the median line), for instance for use as a control source in association with a sig2evt plugin. The top input accepts a numeric event, the value of which is then used to shift the waveform coming in from the left as it passes through and out the right hand side.

Levels/Cross-fader
This plugin mixes two audio streams into one, mixing a controllable percentage of each into the final output. Events received on the input event connector may be usefully set between -1.0 and 1.0, with -1.0 meaning the output signal is entirely composed of signal from the Left input, and 1.0 meaning the output entirely composed from the Right input. A setting of 0.0 sends both inputs through inaltered. The gain on each input varies linearly from 1.0 to 0.0 as the setting moves further away from the centre.

Levels/atan() Saturation
This plugin simply takes its input signal and passes it through the mathematical arctangent function, dividing by pi/2 to map its output onto the range -1.0 to 1.0. This has the effect of compressing the signal slightly, sharply reducing steep spikes in the input signal.

Levels/ADSR (lin-exp-const-lin) Envelope
This plugin implements a standard attack-decay-sustain-release envelope, with a linear attack and release and an exponential decay to a set sustain level. The five inputs are attack time (in seconds), decay half-time (the time in seconds taken to halve the distance between the current signal-level and the set sustain level), sustain and release times (in seconds), and the sustain level (between 0.0 and 1.0). The plugin outputs a random-access signal corresponding to the envelope shaped by the parameters.

The compound control brings you all five controls in a row, which saves you some space.

Delay/Delay with feedback
This plugin would probably more accurately named an echo effect - it repeats its input signal, delayed by a set number of milliseconds, with optional feedback of a set amount. The delay connector (on the left) accepts a numeric event, whose value is the amount of time to delay the signal by, in seconds, and the feedback connector accepts a number specifying the amount of feedback present in the signal - this number can usefully range between 0.0 and 1.0 (although negative numbers should work too, and will produce a phase inversion on each echo). Numbers 1.0 and greater will cause complete feedback. Using an atan plugin to compress the signal before it is output is often a good idea. The third event connector, on the right, sets the level at which the output from the delay plugin is clipped - the "limit". It is usually set at 1.0, the maximum level that output plugins can accept.

Delay/Variable Delay
This component behaves like the delay. But the delay time is a signal connector.

Events/Sum
This plugin is useful for adding a fixed constant to an event as it passed downward through the component. When an event is received through the leftmost connector, the value of the event is incremented by the value of the last event that was received on the rightmost connector. This plugin might be put to use in shifting the control signal from an LFO (in conjuncation with an evtmul, a sig2evt and a vco).

Events/Multiply
This plugin is useful for multiplying an input event by a fixed constant as it passed downward through the component. When an event is received through the leftmost connector, the value of the event is multiplied by the value of the last event that was received on the rightmost connector. This plugin might be put to use in scaling the control signal from an LFO (in conjuncation with an evtadd, a sig2evt and a vco).

Pattern/Pattern Sequencer
This plugin is used to program loops of patterns. The patterns themselves are generated by other (trigseq, seqnum, seqnote) plugins - this one just instructs the other plugins which pattern to play next. You can string an unlimited number of patterns together using this plugin. There are five event inputs - length-input, edit-pattern, play-pattern, clock, and resync - and three outputs - length-output, play-pattern-output, and step. Signals coming in the length-input connector tell the plugin that each pattern is to last for however many steps are specified by the number carried by the event. After this many steps have elapsed, the pattern will begin to play again from the beginning. The edit-pattern and play-pattern inputs are used to select which pattern of patterns this plugin is to be editing or playing back, respectively. The clock input is to be connected to a time-source, such as a clock plugin, and the resync input is to force the sequencer to reset its internal counters to zero, starting playback from the first step in the first sequenced pattern.

The length-output connector on the bottom is for future use - to let another plugin know that the pattern-length has changed. Currently no other plugin cares about the length of the pattern. The play-pattern-output connector is used to tell a downstream sequencer which pattern should be played out of the 16 slots that each sequencer remembers. Finally, the step event output (the rightmost output event connector) is used to tell downstream sequencers which step is active - each time the clock ticks, an event is sent out this rightmost connector, with its value set to the index of the step that is to be played.

Timebase/Resample
This plugin resamples its input in generating its output. It's useful mostly as a crude pitch-shifter. There are two event inputs - one for specifying a resampling factor directly (where 1.0 is a one-to-one mapping, 2.0 gives an octave increase and 0.5 gives an octave decrease) and one for specifying a MIDI note to use. Note that this plugin assumes that its input is always tuned to MIDI note 48 (C4, middle C) - so any number input on this second connector is interpreted as a MIDI note number, and gets converted into a resampling factor relative to note 48.

Timebase/Reverse
This plugin generates exactly the same signal as is read from its input, only backwards (time-reversed).

Pattern/Pattern Selector
This is simply a fancy control component. When one of the buttons A through P on the control are clicked, an event in the range 0 through 15 is sent out the event output. It's useful for attaching to the edit-pattern and/or play-pattern input event connectors of sequencer plugins such as patloop, trigseq, seqnum or seqnote.

Pattern/Note Sequence
Pattern/Numeric Sequence
Pattern/Trigger Sequence
These three sequencers generate events (with differing values) every step. The three inputs to each plugin are edit-pattern, play-pattern and step. Edit- and play-pattern are used to select which pattern out of the 16 slots numbered 0-15 is currently active for editing or playback, respectively. Each time an event is received on the step connector, the pattern memory is consulted, and an event is sent out the output connector on the bottom (for Note Sequencers an event is sent on both of the two output connectors - the leftmost one emits a frequency, and the rightmost one emits a MIDI note number). For numeric sequencers, a simple number between 0.0 and 1.0 is sent; for trigger sequencers, an event is only sent if the corresponding toggle button on the currently playing pattern is activated (depressed); and for note sequencers, the frequency of the current note is sent if the toggle-button beneath the current note's slider is activated. Note that these plugins rely on a patloop (pattern sequencer) plugin instance to control the pattern playback!

Filter/2-pole Low-pass resonant
This is a standard IIR low-pass resonant filter. The two input events/controls control the resonance at the cutoff frequency (which may be usefully set anywhere between just above zero and, say, ten, depending on the effect you want) and the cutoff frequency itself, respectively.

Next Section