Un naufragio personal

Ángel Ortega

Ann Hell Ex Machina API

This document references version 1.0.13 of the C API.

By Source

song.c

ss_core.c

ss_eff.c

ss_gen.c

ss_input.c

ss_ins.c

ss_output.c

support.c

Alphabetical

add_event

Name

add_event - Adds an event to an event list.

Synopsis

 struct song_ev *add_event(struct song_ev **song, int *count);

Arguments

song
A pointer to an event list (dynamically allocated)
count
A pointer to an integer (number of elements)

Description

Increments the song event list to fit count number of elements, probably reallocating its memory.

Returns a pointer to the new element.

copy_event

Name

copy_event - Appends an event to an event list.

Synopsis

 struct song_ev *copy_event(struct song_ev **song, int *count,
                           const struct song_ev *e);

Arguments

song
the event list
count
a pointer to the number of elements
e
the event to be copied

Description

Appends the e event to the song event list.

libpath_add

Name

libpath_add - Adds a directory path to the search path

Synopsis

 void libpath_add(const char *path, int strip);

Arguments

path
the directory path
strip
flag to strip the upper level

Description

Adds path to the list of searchable paths for libpath_fopen(), optionally stripping the upper level if strip is set. The last part of the path is stripped before being stored, and duplication is avoided.

libpath_fopen

Name

libpath_fopen - Opens a file, optionally searching in a path list

Synopsis

 FILE *libpath_fopen(const char *filename, const char *mode);

Arguments

filename
the file name
mode
the file mode

Description

Opens a file. If the file is found as is, it's opened; otherwise, the full list of directory paths maintained by libpath_add() is searched until it's found or the end of the list is reached. Whenever a file is successfully opened, its path is also stored.

libpath_locate

Name

libpath_locate - Locates a file inside the path

Synopsis

 char *libpath_locate(const char *filename);

Arguments

filename
the file to be located

Description

Locates a file inside the library path maintained by libpath_fopen() and add_library_path(). If the file is found, a pointer to a static buffer containing the real path of the file is returned, or NULL otherwise.

libpath_print

Name

libpath_print - Prints the library path

Synopsis

 void libpath_print(void);

Description

Prints the library path.

mute_tracks

Name

mute_tracks - Converts track events to NOPs.

Synopsis

 void mute_tracks(int trk_id);

Arguments

trk_id
Track to be muted. If negative, all buts this will be muted

Description

Converts events to NOP. If trk_id is positive, all events for that track id will be converted to NOP; if it's negative, all events BUT for the ones in that track will be muted.

song_clear

Name

song_clear - Clears the song stream

Synopsis

 void song_clear(void);

Description

Clears the song stream.

song_sort

Name

song_sort - Sorts the song stream

Synopsis

 void song_sort(void);

Description

Sorts the song stream.

song_test_measure_boundary

Name

song_test_measure_boundary - Does a measure boundary check

Synopsis

 int song_test_measure_boundary(double ev_time, int num, int den, int line);

Arguments

ev_time
event time
num
meter numerator
den
meter denominator

Description

Does a measure boundary check. Returns 0 if the event time falls exactly between two measures, or nonzero otherwise.

ss_alloc_wave

Name

ss_alloc_wave - Allocates a wave structure.

Synopsis

 struct ss_wave *ss_alloc_wave(int size, int n_channels, int s_rate,
                              int p_size);

Arguments

size
size in frames
n_channels
number of channels
s_rate
sampling rate
p_size
size of the sound page

Description

Allocates a wave structure. If p_size is -1, it's assumed to be the same as size (so the sound will live entirely in memory).

ss_eff_allpass

Name

ss_eff_allpass - Adds an allpass filter.

Synopsis

 void ss_eff_allpass(struct ss_eff **ec, double size, sample_t gain);

Arguments

ec
the effect chain
size
delay in milliseconds
gain
filter gain

Description

Adds an allpass filter, being size the number of samples to delay and gain the feedback output. Allpass filters are used in reverbs.

ss_eff_atan

Name

ss_eff_atan - Adds an 'atan' distortion effect.

Synopsis

 void ss_eff_atan(struct ss_eff **ec, sample_t gain);

Arguments

ec
the effect chain
gain
amount of effect

Description

Adds an 'atan' distortion effect.

ss_eff_delay

Name

ss_eff_delay - Adds a delay effect.

Synopsis

 void ss_eff_delay(struct ss_eff **ec, double size);

Arguments

ec
the effect chain
size
delay in milliseconds

Description

Adds a delay effect. On output, this effect will simply delay the output of the samples fed to it in size frames. No further filtering is done.

ss_eff_distort

Name

ss_eff_distort - Adds a 'distort' distortion effect.

Synopsis

 void ss_eff_distort(struct ss_eff **ec, sample_t gain);

Arguments

ec
the effect chain
gain
amount of effect

Description

Adds a 'distort' distortion effect.

ss_eff_echo

Name

ss_eff_echo - Adds an echo effect.

Synopsis

 void ss_eff_echo(struct ss_eff **ec, double size, sample_t gain);

Arguments

ec
the effect chain
size
delay in milliseconds
gain
echo gain

Description

Adds an echo effect. Outputs the current sample mixed with the product of the sample sent size frames ago multiplied by the specified gain.

ss_eff_fader

Name

ss_eff_fader - Adds a fader effect.

Synopsis

 void ss_eff_fader(struct ss_eff **ec, double size, sample_t initial,
                  sample_t final);

Arguments

ec
the effect chain
size
number of milliseconds the fader will last
initial
initial volume
final
final volume

Description

Adds a fader effect. The effect will fade in or out the input volume from initial to final during size samples.

ss_eff_flanger

Name

ss_eff_flanger - Adds a flanger effect.

Synopsis

 void ss_eff_flanger(struct ss_eff **ec, double size, sample_t gain,
                    double depth, double freq, double phase);

Arguments

ec
the effect chain
size
delay in milliseconds
gain
output gain
depth
flanger depth in milliseconds
freq
LFO frequency [0..1]
phase
initial phase [0..1]

Description

Adds a flanger effect, being size the number of samples to delay, gain the output gain, depth the number of samples the output will be 'flanged' (bigger values mean bigger fluctuations in the final frequency), freq the frequency of the LFO in Hz and phase the initial LFO value as a fractional part of a period, being 0 the start of the period, 0.5 half a period and so on. The LFO is sinusoidal.

ss_eff_foldback

Name

ss_eff_foldback - Adds a foldback distortion effect.

Synopsis

 void ss_eff_foldback(struct ss_eff **ec, sample_t threshold);

Arguments

ec
the effect chain
threshold
threshold to apply the folding

Description

Adds a foldback distortion effect. All aplitudes above the threshold are folded back.

ss_eff_half_wobble

Name

ss_eff_half_wobble - Adds a half wave wobble effect.

Synopsis

 void ss_eff_half_wobble(struct ss_eff **ec, double freq, double phase);

Arguments

ec
the effect chain
freq
frequency [0..1]
phase
initial phase [0..1]

Description

Adds an effect like the wobble one (see documentation for effect_wobble()), but returning only the first half of the full period as a wobble and the second as silence.

ss_eff_off

Name

ss_eff_off - Destroys a chain of digital effects

Synopsis

 void ss_eff_off(struct ss_eff **ec);

Arguments

ec
the effect chain

Description

Destroys a chain of digital effects.

ss_eff_overdrive

Name

ss_eff_overdrive - Adds an 'overdrive' distortion effect.

Synopsis

 void ss_eff_overdrive(struct ss_eff **ec, sample_t gain);

Arguments

ec
the effect chain
gain
amount of effect

Description

Adds an 'overdrive' distortion effect.

ss_eff_process

Name

ss_eff_process - Processes a chain of digital effects

Synopsis

 sample_t ss_eff_process(struct ss_eff * e, sample_t s);

Arguments

e
the effect chain
s
input sample

Description

Processes a chain of digital effects, taking each one as input the output of the previous one.

ss_eff_reverb

Name

ss_eff_reverb - Adds a simple reverb effect.

Synopsis

 void ss_eff_reverb(struct ss_eff **ec);

Arguments

ec
the effect chain

Description

Adds a simple reverb effect, using a chain of allpass filters.

ss_eff_square_wobble

Name

ss_eff_square_wobble - Adds a square wave wobble effect.

Synopsis

 void ss_eff_square_wobble(struct ss_eff **ec, double freq, double phase);

Arguments

ec
the effect chain
freq
frequency [0..1]
phase
initial phase [0..1]

Description

Adds an effect like the wobble one (see documentation for effect_wobble()), but using a square wave, meaning that input goes unfiltered (full amplitude) for half the period and complete silence the other half.

ss_effect_comb

Name

ss_effect_comb - Adds a comb filter.

Synopsis

 void ss_eff_comb(struct ss_eff **ec, double size, sample_t gain);

Arguments

ec
the effect chain
size
delay in milliseconds
gain
filter gain

Description

Adds a comb filter, being size the number of samples to delay and gain the feedback output. Comb filters are used in reverbs.

ss_effect_wobble

Name

ss_effect_wobble - Adds a wobble effect.

Synopsis

 void ss_eff_wobble(struct ss_eff **ec, double freq, double phase,
                   sample_t gain);

Arguments

ec
the effect chain
freq
frequency [0..1]
phase
initial phase [0..1]
gain
ammount of effect [0..1]

Description

Adds a wobble effect, where the sample amplitudes are multiplied by an LFO, so sound volume wobbles from full volume to silence twice a period. freq is the LFO frequency in Hz and phase the initial LFO value as a fractional part of a period, being 0 the start of the period, 0.5 half a period and so on. The LFO is sinusoidal.

ss_free_wave

Name

ss_free_wave - Frees a wave structure.

Synopsis

 void ss_free_wave(struct ss_wave *w);

Arguments

w
the wave structure

Description

Frees a struct ss_wave allocated by ss_alloc_wave().

ss_gen_alloc

Name

ss_gen_alloc - Allocs and enqueues a generator

Synopsis

 struct ss_gen *ss_gen_alloc(struct ss_gen **q);

Arguments

q
queue where the generator will be enqueued

Description

Allocs and enqueues a generator into the q queue.

The new generator is returned, or NULL if the generator pool is empty.

ss_gen_attack

Name

ss_gen_attack - Sets attack for a generator

Synopsis

 void ss_gen_attack(struct ss_gen *g, double attack);

Arguments

g
the generator
attack
attack time in msecs

Description

Sets attack for a generator, where attack is expressed in milliseconds.

ss_gen_frame

Name

ss_gen_frame - Generates a frame of samples.

Synopsis

 int ss_gen_frame(struct ss_gen *g, int n_channels, sample_t frame[]);

Arguments

g
the generator
n_channels
the desired number of channels
frame
array where the output samples will be stored

Description

Generates a frame of samples from the g generator, that will be stored in the frame array. If n_channels is greater than the number of channels the generator has, they are sequentially spread.

Returns non-zero if the generator is stopped and should be freed.

ss_gen_free

Name

ss_gen_free - Dequeues a generator and frees it

Synopsis

 void ss_gen_free(struct ss_gen **q, struct ss_gen *g);

Arguments

q
the queue holding the generator
g
the generator

Description

Dequeues a generator and sends it back to the generator pool.

ss_gen_play

Name

ss_gen_play - Activates a generator.

Synopsis

 void ss_gen_play(struct ss_gen *g, double freq, sample_t vol, int note_id,
                 struct ss_wave *w);

Arguments

g
generator
freq
frequency of the sound to be generated
vol
volume
note_id
note id
w
the wave

Description

Activates a generator, usually as a response for a 'note on' message from an upper level. The wave w holds all the sample data (PCM data, base frequency, etc.), freq is the desired frequency, vol the volume and note_id a positive, unique identifier for the note.

ss_gen_portamento

Name

ss_gen_portamento - Sets portamento for a generator

Synopsis

 void ss_gen_portamento(struct ss_gen *g, double portamento);

Arguments

g
the generator
portamento
portamento value

Description

Sets portamento for a generator, where portamento is an increment to the internal cursor of the wave. This value must be very small. Negative values will make the frequency slide down and positive slide up.

ss_gen_release

Name

ss_gen_release - Releases a generator.

Synopsis

 void ss_gen_release(struct ss_gen *g);

Arguments

g
the generator

Description

Releases a generator, usually as a response for a 'note off' message from an upper level. The generator enters SS_GEN_RELEASED mode, which starts generating sustain data until it's over.

ss_gen_sustain

Name

ss_gen_sustain - Sets sustain for a generator

Synopsis

 void ss_gen_sustain(struct ss_gen *g, double sustain);

Arguments

g
the generator
sustain
sustain time in msecs

Description

Sets sustain for a generator, where sustain is expressed in milliseconds.

ss_gen_vibrato

Name

ss_gen_vibrato - Sets vibrato for a generator

Synopsis

 void ss_gen_vibrato(struct ss_gen *g, double depth, double freq);

Arguments

g
the generator
depth
vibrato depth in msecs
freq
vibrato frequency

Description

Sets vibrato for a generator, with a depth expressed in milliseconds and a frequency freq expressed in hzs.

ss_get_sample

Name

ss_get_sample - Reads a sample from a wave.

Synopsis

 sample_t ss_get_sample(struct ss_wave * w, int channel, double offset);

Arguments

wave
the wave
channel
the channel
offset
sample number to be returned

Description

Returns the sample number offset from the channel of the wave. Offset can be a non-integer value.

ss_ins_add_layer

Name

ss_ins_add_layer - Adds a layer to an instrument.

Synopsis

 void ss_ins_add_layer(struct ss_ins *i, struct ss_wave *w);

Arguments

i
the instrument
w
wave describing the layer

Description

Adds a layer to an instrument.

Returns 0 if the layer was added successfully.

ss_ins_disable

Name

ss_ins_disable - Disables an instrument.

Synopsis

 void ss_ins_disable(struct ss_ins *i);

Arguments

i
the instrument

Description

Disables an instrument. From now on, no more notes can be played on this instrument. If no note are left sounding, ss_ins_frame() will return immediately.

ss_ins_find_layer

Name

ss_ins_find_layer - Finds a layer inside an instrument

Synopsis

 struct ss_wave *ss_ins_find_layer(const struct ss_ins *i, double freq,
                                  int *off);

Arguments

i
the instrument
freq
the desired frequency
off
pointer to element offset to start searching

Description

Finds a layer inside the i instrument with a matching freq, starting from the layer number pointed by off. If a matching layer is found, its struct ss_wave is returned and off is left pointing to the next layer (allowing it to be used as an enumerator). If no layer is found, NULL is returned.

ss_ins_frame

Name

ss_ins_frame - Generates a frame of samples.

Synopsis

 int ss_ins_frame(struct ss_ins *i, sample_t frame[]);

Arguments

i
the instrument
frame
array where the output samples will be stored

Description

Generates a frame of samples mixing all the active generators of a track.

Returns 0 if the instrument is disabled and is no longer emitting sound, or 1 otherwise.

ss_ins_init

Name

ss_ins_init - Initializes an instrument.

Synopsis

 void ss_ins_init(struct ss_ins *i);

Arguments

i
the instrument

Description

Initializes an instrument structure.

ss_ins_note_off

Name

ss_ins_note_off - Releases a note.

Synopsis

 void ss_ins_note_off(struct ss_ins *i, int note_id);

Arguments

i
the instrument
note_id
the id of the note to be released

Description

Releases a note. The generators associated to it will enter release mode.

ss_ins_note_on

Name

ss_ins_note_on - Plays a note.

Synopsis

 int ss_ins_note_on(struct ss_ins *i, int note, sample_t vol, int note_id);

Arguments

i
the instrument
note
MIDI note to be played
vol
note volume
note_id
note id

Description

Locates a layer to play a note, and starts generators to play it. The note is expressed as a MIDI note and the desired volume (from 0 to 1) stored in vol. The note id should be a positive, unique identifier for this note; no two simultaneously playing notes should share this id.

Returns the number of generators that were activated.

ss_ins_play

Name

ss_ins_play - Plays a note given the desired wave.

Synopsis

 int ss_ins_play(struct ss_ins *i, double freq, sample_t vol, int note_id,
                struct ss_wave *w);

Arguments

i
the instrument
freq
frequency
vol
volume
note_id
note id
w
the wave

Description

Orders the instrument to start playing a note, given a specific wave. The wave is usually one of the instrument's layers, but it doesn't have to.

Returns -1 if the instrument is disabled, -2 if no free generators were found, or 0 if everything went ok.

ss_ins_set_attack

Name

ss_ins_set_attack - Sets the attack for an instrument.

Synopsis

 void ss_ins_set_attack(struct ss_ins *i, double attack);

Arguments

i
the instrument
attack
the attack time in milliseconds

Description

Sets the attack for an instrument. attack is expressed in milliseconds.

ss_ins_set_channel

Name

ss_ins_set_channel - Sets the volume for an instrument's channel.

Synopsis

 void ss_ins_set_channel(struct ss_ins *i, int channel, sample_t vol);

Arguments

i
the instrument
channel
channel number
vol
volume

Description

Sets the volume for an instrument's channel. If the channel does not exist, it's created and space allocated for it in the volume and effect dynamic arrays.

ss_ins_set_portamento

Name

ss_ins_set_portamento - Sets portamento for an instrument.

Synopsis

 void ss_ins_set_portamento(struct ss_ins *i, double portamento);

Arguments

i
the instrument
portamento
portamento value

Description

Sets portamento for an instrument.

ss_ins_set_sustain

Name

ss_ins_set_sustain - Sets the sustain for an instrument.

Synopsis

 void ss_ins_set_sustain(struct ss_ins *i, double sustain);

Arguments

i
the instrument
sustain
the sustain time in milliseconds

Description

Sets the sustain for an instrument. sustain is expressed in milliseconds.

ss_ins_set_vibrato

Name

ss_ins_set_vibrato - Sets the vibrato for an instrument.

Synopsis

 void ss_ins_set_vibrato(struct ss_ins *i, double depth, double freq);

Arguments

i
the instrument
depth
vibrato depth in msecs
freq
vibrato frequency in Hzs

Description

Sets the vibrato for an instrument. depth is expressed in milliseconds and freq in Hzs.

ss_load_pat_file

Name

ss_load_pat_file - Loads an instrument in .PAT format.

Synopsis

 int ss_load_pat_file(struct ss_ins *i, const char *file);

Arguments

i
The instrument
filename
filename holding the instrument

Description

Loads data from a Gravis Ultrasound patch (.PAT) format and stores it as layers for an instrument.

Returns -100 if the file could not be read, -101 or -102 if the file is not recognized as a .PAT file, or 0 if everything went OK.

ss_load_wav_file

Name

ss_load_wav_file - Loads a file in .WAV format.

Synopsis

 struct ss_wave *ss_load_wav_file(const char *file,
                                 double base_freq, double min_freq,
                                 double max_freq, double loop_start,
                                 double loop_end, int first_channel,
                                 int skip_channels);

Arguments

file
name of the file
base_freq
base frequency
min_freq
minimum frequency
max_freq
maximum frequency
loop_start
frame number of loop start (-1, no loop)
loop_end
frame number of loop end (-1, end of wave)
first_channel
first channel to start spreading
skip_channels
channels to skip when spreading

Description

Loads a file in .WAV format.

ss_note_frequency

Name

ss_note_frequency - MIDI note to frequency converter

Synopsis

 double ss_note_frequency(int note);

Arguments

note
the MIDI note

Description

Accepts a MIDI note number (range 0 to 127) and returns its frequency in Hz.

ss_output_close

Name

ss_output_close - Closes the output device.

Synopsis

 void ss_output_close(void);

Description

Closes the output driver.

ss_output_init_frame

Name

ss_output_init_frame - Inits a frame

Synopsis

 void ss_output_init_frame(sample_t frame[]);

Arguments

frame
the frame

Description

Inits a frame, setting all samples to zero.

ss_output_open

Name

ss_output_open - Opens an output device.

Synopsis

 int ss_output_open(const char *drvname, const char *filename);

Arguments

name
name of the driver
filename
name of the file or device

Description

Opens an output device. name contains the name of the driver (i.e. "oss" or "wav"), filename contains the (optional) name of the output file or device (i.e. a filename "wav" or "/dev/dsp" for a direct audio device like "oss"). Name can be the special pseudo-driver "default" to select the most appropriate (usually a platform-specific direct output device, or "wav" if no one exists). filename can also be NULL; in that case, a driver dependent, default value is used.

Returns zero if the output device was correctly open, or nonzero otherwise.

ss_output_write

Name

ss_output_write - Outputs a frame of samples.

Synopsis

 int ss_output_write(sample_t frame[]);

Arguments

frame
the frame of samples

Description

Outputs a frame of samples. Applies master volume, tests for maximum amplitudes and clips all saturating ones.

Returns a negative value in case of error, or 0 otherwise.

ss_pitch_from_tempo

Name

ss_pitch_from_tempo - Calculates a pitch from a tempo

Synopsis

 double ss_pitch_from_tempo(const struct ss_wave *w, double tempo,
                           double len);

Arguments

w
the wave
tempo
current tempo
len
desired length in whole notes

Description

Calculates the optimal frequency (pitch) for the w wave, at tempo, to last len whole notes.

ss_tempo_from_wave

Name

ss_tempo_from_wave - Calculates a tempo from a wave

Synopsis

 double ss_tempo_from_wave(const struct ss_wave *w, int note, double len);

Arguments

w
the wave
note
note to calculate the tempo from
len
whole notes the tempo should match

Description

Calculates the optimal tempo for the w wave, playing the note, to last len whole notes.

Angel Ortega - angel@triptico.com - Built with mp_doccer 1.2.2