This document references version 1.0.13 of the C API.
add_event - Adds an event to an event list.
struct song_ev *add_event(struct song_ev **song, int *count);
Increments the song event list to fit count number of elements, probably reallocating its memory.
Returns a pointer to the new element.
copy_event - Appends an event to an event list.
struct song_ev *copy_event(struct song_ev **song, int *count,
const struct song_ev *e);
Appends the e event to the song event list.
libpath_add - Adds a directory path to the search path
void libpath_add(const char *path, int strip);
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 - Opens a file, optionally searching in a path list
FILE *libpath_fopen(const char *filename, const char *mode);
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 - Locates a file inside the path
char *libpath_locate(const char *filename);
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 - Prints the library path
void libpath_print(void);
Prints the library path.
mute_tracks - Converts track events to NOPs.
void mute_tracks(int trk_id);
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 - Clears the song stream
void song_clear(void);
Clears the song stream.
song_sort - Sorts the song stream
void song_sort(void);
Sorts the song stream.
song_test_measure_boundary - Does a measure boundary check
int song_test_measure_boundary(double ev_time, int num, int den, int line);
Does a measure boundary check. Returns 0 if the event time falls exactly between two measures, or nonzero otherwise.
ss_alloc_wave - Allocates a wave structure.
struct ss_wave *ss_alloc_wave(int size, int n_channels, int s_rate,
int p_size);
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 - Adds an allpass filter.
void ss_eff_allpass(struct ss_eff **ec, double size, sample_t gain);
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 - Adds an 'atan' distortion effect.
void ss_eff_atan(struct ss_eff **ec, sample_t gain);
Adds an 'atan' distortion effect.
ss_eff_delay - Adds a delay effect.
void ss_eff_delay(struct ss_eff **ec, double size);
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 - Adds a 'distort' distortion effect.
void ss_eff_distort(struct ss_eff **ec, sample_t gain);
Adds a 'distort' distortion effect.
ss_eff_echo - Adds an echo effect.
void ss_eff_echo(struct ss_eff **ec, double size, sample_t gain);
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 - Adds a fader effect.
void ss_eff_fader(struct ss_eff **ec, double size, sample_t initial,
sample_t final);
Adds a fader effect. The effect will fade in or out the input volume from initial to final during size samples.
ss_eff_flanger - Adds a flanger effect.
void ss_eff_flanger(struct ss_eff **ec, double size, sample_t gain,
double depth, double freq, double phase);
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 - Adds a foldback distortion effect.
void ss_eff_foldback(struct ss_eff **ec, sample_t threshold);
Adds a foldback distortion effect. All aplitudes above the threshold are folded back.
ss_eff_half_wobble - Adds a half wave wobble effect.
void ss_eff_half_wobble(struct ss_eff **ec, double freq, double phase);
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 - Destroys a chain of digital effects
void ss_eff_off(struct ss_eff **ec);
Destroys a chain of digital effects.
ss_eff_overdrive - Adds an 'overdrive' distortion effect.
void ss_eff_overdrive(struct ss_eff **ec, sample_t gain);
Adds an 'overdrive' distortion effect.
ss_eff_process - Processes a chain of digital effects
sample_t ss_eff_process(struct ss_eff * e, sample_t s);
Processes a chain of digital effects, taking each one as input the output of the previous one.
ss_eff_reverb - Adds a simple reverb effect.
void ss_eff_reverb(struct ss_eff **ec);
Adds a simple reverb effect, using a chain of allpass filters.
ss_eff_square_wobble - Adds a square wave wobble effect.
void ss_eff_square_wobble(struct ss_eff **ec, double freq, double phase);
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 - Adds a comb filter.
void ss_eff_comb(struct ss_eff **ec, double size, sample_t gain);
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 - Adds a wobble effect.
void ss_eff_wobble(struct ss_eff **ec, double freq, double phase,
sample_t gain);
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 - Frees a wave structure.
void ss_free_wave(struct ss_wave *w);
Frees a struct ss_wave allocated by ss_alloc_wave().
ss_gen_alloc - Allocs and enqueues a generator
struct ss_gen *ss_gen_alloc(struct ss_gen **q);
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 - Sets attack for a generator
void ss_gen_attack(struct ss_gen *g, double attack);
Sets attack for a generator, where attack is expressed in milliseconds.
ss_gen_frame - Generates a frame of samples.
int ss_gen_frame(struct ss_gen *g, int n_channels, sample_t frame[]);
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 - Dequeues a generator and frees it
void ss_gen_free(struct ss_gen **q, struct ss_gen *g);
Dequeues a generator and sends it back to the generator pool.
ss_gen_play - Activates a generator.
void ss_gen_play(struct ss_gen *g, double freq, sample_t vol, int note_id,
struct ss_wave *w);
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 - Sets portamento for a generator
void ss_gen_portamento(struct ss_gen *g, double portamento);
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 - Releases a generator.
void ss_gen_release(struct ss_gen *g);
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 - Sets sustain for a generator
void ss_gen_sustain(struct ss_gen *g, double sustain);
Sets sustain for a generator, where sustain is expressed in milliseconds.
ss_gen_vibrato - Sets vibrato for a generator
void ss_gen_vibrato(struct ss_gen *g, double depth, double freq);
Sets vibrato for a generator, with a depth expressed in milliseconds and a frequency freq expressed in hzs.
ss_get_sample - Reads a sample from a wave.
sample_t ss_get_sample(struct ss_wave * w, int channel, double offset);
Returns the sample number offset from the channel of the wave. Offset can be a non-integer value.
ss_ins_add_layer - Adds a layer to an instrument.
void ss_ins_add_layer(struct ss_ins *i, struct ss_wave *w);
Adds a layer to an instrument.
Returns 0 if the layer was added successfully.
ss_ins_disable - Disables an instrument.
void ss_ins_disable(struct ss_ins *i);
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 - Finds a layer inside an instrument
struct ss_wave *ss_ins_find_layer(const struct ss_ins *i, double freq,
int *off);
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 - Generates a frame of samples.
int ss_ins_frame(struct ss_ins *i, sample_t frame[]);
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 - Initializes an instrument.
void ss_ins_init(struct ss_ins *i);
Initializes an instrument structure.
ss_ins_note_off - Releases a note.
void ss_ins_note_off(struct ss_ins *i, int note_id);
Releases a note. The generators associated to it will enter release mode.
ss_ins_note_on - Plays a note.
int ss_ins_note_on(struct ss_ins *i, int note, sample_t vol, int note_id);
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 - Plays a note given the desired wave.
int ss_ins_play(struct ss_ins *i, double freq, sample_t vol, int note_id,
struct ss_wave *w);
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 - Sets the attack for an instrument.
void ss_ins_set_attack(struct ss_ins *i, double attack);
Sets the attack for an instrument. attack is expressed in milliseconds.
ss_ins_set_channel - Sets the volume for an instrument's channel.
void ss_ins_set_channel(struct ss_ins *i, int channel, sample_t vol);
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 - Sets portamento for an instrument.
void ss_ins_set_portamento(struct ss_ins *i, double portamento);
Sets portamento for an instrument.
ss_ins_set_sustain - Sets the sustain for an instrument.
void ss_ins_set_sustain(struct ss_ins *i, double sustain);
Sets the sustain for an instrument. sustain is expressed in milliseconds.
ss_ins_set_vibrato - Sets the vibrato for an instrument.
void ss_ins_set_vibrato(struct ss_ins *i, double depth, double freq);
Sets the vibrato for an instrument. depth is expressed in milliseconds and freq in Hzs.
ss_load_pat_file - Loads an instrument in .PAT format.
int ss_load_pat_file(struct ss_ins *i, const char *file);
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 - Loads a file in .WAV format.
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);
Loads a file in .WAV format.
ss_note_frequency - MIDI note to frequency converter
double ss_note_frequency(int note);
Accepts a MIDI note number (range 0 to 127) and returns its frequency in Hz.
ss_output_close - Closes the output device.
void ss_output_close(void);
Closes the output driver.
ss_output_init_frame - Inits a frame
void ss_output_init_frame(sample_t frame[]);
Inits a frame, setting all samples to zero.
ss_output_open - Opens an output device.
int ss_output_open(const char *drvname, const char *filename);
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 - Outputs a frame of samples.
int ss_output_write(sample_t frame[]);
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 - Calculates a pitch from a tempo
double ss_pitch_from_tempo(const struct ss_wave *w, double tempo,
double len);
Calculates the optimal frequency (pitch) for the w wave, at tempo, to last len whole notes.
ss_tempo_from_wave - Calculates a tempo from a wave
double ss_tempo_from_wave(const struct ss_wave *w, int note, double len);
Calculates the optimal tempo for the w wave, playing the note, to last len whole notes.