sscore_synth.h

Introduction

The C interface to SeeScoreLib sound synthesizer

C Pseudoclasses

sscore_synth

the abstract sound synthesizer

Functions

sscore_sy_addsampledinstrument

create a sampled instrument for the synth to use from a set of file sound samples, 1 for each midi note

sscore_sy_addsynthesizedinstrument

create a synthesized instrument (metronome tick) for the synth to use

sscore_sy_createsynth

create a new synth and return it

sscore_sy_disposesynth

dispose the synth

sscore_sy_isplaying

detect if the synth is playing

sscore_sy_pause

pause playing

sscore_sy_playingbar

sscore_sy_removeinstrument

remove an instrument previously added with sscore_sy_addsampledinstrument or sscore_sy_addsynthesizedinstrument

sscore_sy_reset

stop playing and reset to the start of the score

sscore_sy_setmetronomevolume

change the volume of the metronome

sscore_sy_setnextplaybar

set the next play bar while playing (eg when the user taps a bar in the score)

sscore_sy_setpartvolume

change the volume of a part

sscore_sy_setup

sscore_sy_startat

start playing the notes in playdata after the given delay

sscore_sy_updatetempo

notification that the user has changed the tempo (viz. sscore_pd_usertempo)

sscore_sy_addsampledinstrument

create a sampled instrument for the synth to use from a set of file sound samples, 1 for each midi note

EXPORT sscore_sy_instrumentid sscore_sy_addsampledinstrument(
    sscore_synth *synth, 
    const sscore_sy_sampledinstrumentinfo *info, 
    enum sscore_error *err);  

Parameters

Return Value

a unique identifier for the instrument

sscore_sy_addsynthesizedinstrument

create a synthesized instrument (metronome tick) for the synth to use

EXPORT sscore_sy_instrumentid sscore_sy_addsynthesizedinstrument(
    sscore_synth *synth, 
    const sscore_sy_synthesizedinstrumentinfo *info, 
    enum sscore_error *err);  

Parameters

Return Value

a unique identifier for the instrument

sscore_sy_createsynth

create a new synth and return it

EXPORT sscore_synth *sscore_sy_createsynth(
    const sscore_sy_controls *controls,
    const sscore_libkeytype *key);  

Parameters

Return Value

the synth

sscore_sy_disposesynth

dispose the synth

EXPORT void sscore_sy_disposesynth(
    sscore_synth *synth);  

Parameters

sscore_sy_isplaying

detect if the synth is playing

EXPORT bool sscore_sy_isplaying(
    sscore_synth *synth);  

Parameters

Return Value

true if playing

sscore_sy_pause

pause playing

EXPORT void sscore_sy_pause(
    sscore_synth *synth);  

Parameters

sscore_sy_playingbar

EXPORT int sscore_sy_playingbar(
    sscore_synth *synth);  

Parameters

Return Value

the index of the bar playing

sscore_sy_removeinstrument

remove an instrument previously added with sscore_sy_addsampledinstrument or sscore_sy_addsynthesizedinstrument

EXPORT void sscore_sy_removeinstrument(
    sscore_synth *synth,
    sscore_sy_instrumentid iid);  

Parameters

sscore_sy_reset

stop playing and reset to the start of the score

EXPORT void sscore_sy_reset(
    sscore_synth *synth);  

Parameters

sscore_sy_setmetronomevolume

change the volume of the metronome

EXPORT void sscore_sy_setmetronomevolume(
    sscore_synth *synth,
    float volume);  

Parameters

sscore_sy_setnextplaybar

set the next play bar while playing (eg when the user taps a bar in the score)

EXPORT void sscore_sy_setnextplaybar(
    sscore_synth *synth,
    int barindex,
    unsigned long long restart_time);  

Parameters

sscore_sy_setpartvolume

change the volume of a part

EXPORT void sscore_sy_setpartvolume(
    sscore_synth *synth,
    int partindex,
    float volume);  

Parameters

sscore_sy_setup

EXPORT enum sscore_error sscore_sy_setup(
    sscore_synth *synth,
    sscore_playdata *playdata);  

Parameters

Return Value

any error

sscore_sy_startat

start playing the notes in playdata after the given delay

EXPORT enum sscore_error sscore_sy_startat(
    sscore_synth *synth,
    unsigned long long start_time,
    int barindex=0);  

Parameters

Return Value

any error

sscore_sy_updatetempo

notification that the user has changed the tempo (viz. sscore_pd_usertempo)

EXPORT void sscore_sy_updatetempo(
    sscore_synth *synth,
    unsigned long long restart_time);  

Parameters

Typedefs

sscore_sampledinstrumentinfo

info defining a sampled instrument

sscore_sy_sampledinstrumentinfo

info defining a sampled instrument

sscore_sy_synthesizedinstrumentinfo

info defining a synthesized instrument (metronome tick only supported at present)

sscore_sampledinstrumentinfo

info defining a sampled instrument

typedef struct sscore_sy_sampledinstrumentinfo { 
    const char *instrument_name; // the name of the instrument 
    const char *base_filename; // the start of the filename before the .<midipitch> 
    const char *extn; // the filename extension 
    int base_midipitch; // the lowest midi pitch file 
    int numfiles; // the number of sample files with sequential midi values from base_midipitch 
    float volume; // for adjustment of balance with other instruments 
    int attack_time_ms; // time from start of sample play to beat reference point 
    int decay_time_ms; // 90% to 10% sigmoid decay time 
    int overlap_time_ms; // overlap with following note 
    const char *alternativenames; // comma-separated (lower case) alternative names for matching part name, eg "cello,violoncello" 
    int pitch_offset; // the pitch offset for a transposing instrument 
    unsigned dummy[16]; 
} sscore_sy_sampledinstrumentinfo;  

Discussion

a sampled instrument requires a set of files, one for each note, included in the Resources for the app The file naming scheme is defined: sample files have the name <base_filename>.<midipitch>.extn eg "Piano.60.m4a" base_filename and extn are defined below; base_midipitch and numfiles define the range of <midipitch>. Parameters attack_time_ms, decay_time_ms and overlap_time_ms need to be 'tweaked' to make a sequence sound right when played against a metronome tick. alternativenames is used for instrument name matching pitch_offset is used to transpose the instrument, eg it can be used to mimic a clarinet when playing an _untransposed_ score. Note that a score scored for transposing instrument should specify the transposition and in this case pitch_offset should be zero

See Also

sscore_sy_sampledinstrumentinfo

info defining a sampled instrument

typedef struct sscore_sy_sampledinstrumentinfo { 
    const char *instrument_name; // the name of the instrument 
    const char *base_filename; // the start of the filename before the .<midipitch> 
    const char *extn; // the filename extension 
    int base_midipitch; // the lowest midi pitch file 
    int numfiles; // the number of sample files with sequential midi values from base_midipitch 
    float volume; // for adjustment of balance with other instruments 
    int attack_time_ms; // time from start of sample play to beat reference point 
    int decay_time_ms; // 90% to 10% sigmoid decay time 
    int overlap_time_ms; // overlap with following note 
    const char *alternativenames; // comma-separated (lower case) alternative names for matching part name, eg "cello,violoncello" 
    int pitch_offset; // the pitch offset for a transposing instrument 
    unsigned dummy[16]; 
} sscore_sy_sampledinstrumentinfo;  

Discussion

a sampled instrument requires a set of files, one for each note, included in the Resources for the app The file naming scheme is defined: sample files have the name <base_filename>.<midipitch>.extn eg "Piano.60.m4a" base_filename and extn are defined below; base_midipitch and numfiles define the range of <midipitch>. Parameters attack_time_ms, decay_time_ms and overlap_time_ms need to be 'tweaked' to make a sequence sound right when played against a metronome tick. alternativenames is used for instrument name matching pitch_offset is used to transpose the instrument, eg it can be used to mimic a clarinet when playing an _untransposed_ score. Note that a score scored for transposing instrument should specify the transposition and in this case pitch_offset should be zero

See Also

sscore_sy_synthesizedinstrumentinfo

info defining a synthesized instrument (metronome tick only supported at present)

typedef struct sscore_sy_synthesizedinstrumentinfo { 
    const char *instrument_name; // the name of the instrument 
    int tickpitch; // defines metronome tick 
    float volume; // for adjustment of balance with other instruments 
    enum sscore_sy_synthesizedinstrumentvoice voice; unsigned dummy[
            16]; 
} sscore_sy_synthesizedinstrumentinfo;