                               Elara
                               -----

Introduction
------------
Elara is a real-time software synthesizer for PC compatible machines
running Linux.  Elara is designed to replicate an analogue synthesizer,
and has a very comprehensive voice architecture.

The main features include:

i)   Two independent audio oscillators per voice - with cross
     modulation and sync.
ii)  Two independent envelope generators - with keyboard tracking.
iii) A low frequency oscillator - with variable delay.
iv)  A resonant low pass filter - with switchable -12 dB/octave
     or -24 dB/octave cutoff slope and variable keyboard tracking.
v)   A variable high pass filter - with a -6 dB/octave cutoff slope.

Requirements
------------
The synthesizer requires a 16 bit sound-card, X (with at least a 16 bits per
pixel display), and a working sound driver (the synth has only been tested
with the OSS driver).  The synthesizer works best on fast machines, and is
probably not usable on anything less than a Pentium class machine.
The number of playable notes is a function of the machine speed and the sample
rate selected in the configuration file.  For example, the development
machine, a Cyrix 6x86 P200+, manages one note with an output sample rate of
44,100 Hz.
Elara may be played via an external MIDI keyboard, or MIDI events may be sent
to the synth via a named pipe.

Installation
------------
The executable (elara) may be put anywhere in the user's path.  The small
script install.sh should be run as the synth user (not as root).  This script
places a configuration file .elararc and a directory .elara (which is used
for patch storage) in the user's home directory.  Forty sample patches
are placed in the .elara directory.  Elara will look in the home directory of
the current user on startup to find this configuration file and patch
directory.  If Elara cannot find the patch directory then patch saving will
not be possible.

To optionally improve the audio performance, real-time scheduling for Elara
may be enabled.  The elara executable should be modified as follows (this must
be done as root):

   chown root elara

   chmod u+s elara

Configuration
-------------
The configuration file (.elararc) contains values of the five parameters that
may be set by the user.  If this file cannot be found by the synthesizer then
default values are used.  The parameters are set, one per line, by equating the
parameter with a value, eg:

   user_parameter = value

Whitespace is ignored, as is all text between a # and the end of a line, eg:

   # this is a legal comment

   user_parameter = value # this parameter will be set

   # the following parameter will not be set
   # user_parameter = value

The five user parameters are:

midi_device - This is used to set the MIDI input to the synthesizer.  This
              should be a path and device/fifo name.  The default is /dev/midi.

dsp_device - This is used to set the audio output for the synthesizer.
             The default is /dev/dsp.

midi_channel - This is used to set the MIDI receive channel.  Valid values
               are numbers 1 to 16 or the word all to receive on all channels.
               The default is all.

polyphony - The maximum allowed number of simultaneous notes is set using this
            parameter.  The number allowed includes the notes that are
            releasing.  Notes played after the maximum has been reached will
            cutoff the oldest releasing note or, if no notes are in their
            release phase, the oldest held note.  The polyphony value should,
            if possible, be set to at least twice the expected number
            of held notes - so that notes may have some chance of decaying
            naturally.  The default is 1.

sample_rate - The number of sound samples per second produced by the synth is
              set by this parameter.  A high value gives good sound quality
              and low latency, but is more demanding in terms of processing
              power required.  For low end Pentium machines a compromise
              between polyphony and sample_rate will be required.
              The default is 44100.

If polyphony or sample_rate is set to a value that is too high the machine
will not be able to keep up with the required rate of sound sample production.
When this happens a "buffer underrun" occurs.  If a buffer underrun is detected
by the synthesizer then notes are killed until no further underrun occurs.
A buffer underrun might be audible, so care should be taken in selecting the
sample_rate and polyphony values.  One approach to setting these values is to
set the sample rate to a value that gives acceptable sound quality, then use
a CPU monitor such as top to show the amount of CPU time used by the
synthesizer.  Notes should be progressively held until the total CPU load is
somewhere between 50% and 75%.  The number of held notes is then the maximum
polyphony value for the machine at the selected sample rate.

Using Elara
-----------
Elara may be started by typing elara at the command prompt.  Elara should
ALWAYS be closed by using the POWER switch located at the bottom left of the
control panel.  Failure to shutdown Elara correctly may leave stray processes
running on the system.  It will then be impossible to restart Elara without
manually killing these processes.  If it is suspected that this has happened
then all processes named elara should be killed manually before restarting.

Using Elara should be easy for anyone that is familiar with analogue synthesis,
and a tutorial on subtractive synthesis will not be given here.  The control
panel is split into three main regions, the top two of which control the basic
sound made by the synthesizer.  On the third panel are the controls for BEND
and additional LFO MODulation, as well as the patch memory controls, the MASTER
TUNE and VOLUME controls, and the POWER switch.

Elara receives and responds to MIDI pitch bend and modulation information
according to the settings on the BEND and LFO MOD controls.  MIDI pitch bend
may be used to modulate the pitch of the oscillators and the cutoff frequency
of the low pass filter.  The sliders in the BEND section control the amount
of bend applied (0 to +/- 1 octave for the oscillators), and the switches
allow the bend to be applied to any combination of oscillators and filter.
The MIDI modulation parameter is used to trigger the additional LFO
modulation for trill effects.  Any value of the MIDI modulation parameter
greater than zero will trigger LFO modulation.  The LFO modulation will rise
to the maximum level set by the corresponding sliders at a rate determined by
the LFO MOD RISE TIME control.  The VCO MOD and VCF MOD switches allow LFO
modulation to be applied to either the pitch or the filter cutoff frequency.

Patches are loaded by pressing three of the numbered buttons below the patch
number display.  To load patch 1 the buttons 0, 0, and 1 should be pressed; to
load patch 123 the buttons 1, 2, and 3 should be pressed.  To write a patch the
WRITE button should be pressed, followed by three numbers corresponding to the
new patch location.  Patches may also be copied in this way.  For example, to
copy patch 11 to patch 123 the sequence would be:

i)   Load patch 11 (by pressing 0, 1, and 1).
ii)  Press the WRITE button.
iii) Press buttons 1, 2, and 3.

Patch 11 will now be copied to patch 123.

To cancel writing the WRITE button should be pressed again before three number
buttons are pressed.  Valid patch numbers are in the range 0 to 127.  Patches
are also selectable via MIDI.

Problems
--------
Distorted sound when playing many notes or with the filter resonance control
at a high position.

 - Clipping of the output signal, try reducing the VOLUME or VCA LEVEL.

Periodic distortion or distortion present in the sound when using the panel
or other windows.

 - Try switching on the real-time scheduling, ie (as root):

   chown root elara

   chmod u+s elara

Comments and Suggestions
------------------------
Email to elara_synth@yahoo.co.uk

Warranty
--------
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
