sscore_synth.h

Includes:

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_changedcontrols

notification that the controls have changed so the sscore_sy_controls needs to be reread

sscore_sy_createsynth

create a new synth and return it

sscore_sy_createsynth_plus

create a new synth and return it

sscore_sy_disposesynth

dispose the synth

sscore_sy_ispaused
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_resume

resume playing after pause

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

setup the synth with playdata.

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
synth

the synth returned from sscore_sy_createsynth

info

a struct defining the sample file naming, and various instrument parameters

err

returns any error

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
synth

the synth returned from sscore_sy_createsynth

info

a struct defining the synthesized sound (only tick available)

err

returns any error

Return Value

a unique identifier for the instrument


sscore_sy_changedcontrols


notification that the controls have changed so the sscore_sy_controls needs to be reread

EXPORT void sscore_sy_changedcontrols(
    sscore_synth *synth);  
Parameters
synth

the synth from sscore_sy_createsynth


sscore_sy_createsynth


create a new synth and return it

Parameters
controls

synth ui controls defined above

key

the key defining licenses owned by the user. If this key does not include a synth licence then the synth will operate for a limited time only after the app is started

Return Value

the synth


sscore_sy_createsynth_plus


create a new synth and return it

EXPORT sscore_synth *sscore_sy_createsynth_plus(
    const sscore_sy_controls_plus *controls,
    const sscore_synth_options *options,
    const sscore_libkeytype *key);  
Parameters
controls

synth ui controls with extra functions defined above

options

unused at present - can be null

key

the key defining licenses owned by the user. If this key does not include a synth licence then the synth will operate for a limited time only after the app is started

Return Value

the synth


sscore_sy_disposesynth


dispose the synth

EXPORT void sscore_sy_disposesynth(
    sscore_synth *synth);  
Parameters
synth

the synth returned from sscore_sy_createsynth


sscore_sy_ispaused


EXPORT bool sscore_sy_ispaused(
    sscore_synth *synth);  
Parameters
synth

the synth from sscore_sy_createsynth

Return Value

true if synth is paused


sscore_sy_isplaying


detect if the synth is playing

EXPORT bool sscore_sy_isplaying(
    sscore_synth *synth);  
Parameters
synth

the synth from sscore_sy_createsynth

Return Value

true if playing


sscore_sy_pause


pause playing

EXPORT bool sscore_sy_pause(
    sscore_synth *synth);  
Parameters
synth

the synth from sscore_sy_createsynth

Return Value

true if success


sscore_sy_playingbar


EXPORT int sscore_sy_playingbar(
    sscore_synth *synth);  
Parameters
synth

the synth from sscore_sy_createsynth

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
synth

the synth returned from sscore_sy_createsynth

iid

the identifier returned from sscore_sy_addXXXinstrument


sscore_sy_reset


stop playing and reset to the start of the score

EXPORT void sscore_sy_reset(
    sscore_synth *synth);  
Parameters
synth

the synth from sscore_sy_createsynth


sscore_sy_resume


resume playing after pause

EXPORT bool sscore_sy_resume(
    sscore_synth *synth);  
Parameters
synth

the synth from sscore_sy_createsynth

Return Value

true if success


sscore_sy_setmetronomevolume


change the volume of the metronome

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

the synth from sscore_sy_createsynth

volume

the volume [0..1]


sscore_sy_setnextplaybar


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

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

the synth from sscore_sy_createsynth

barindex

the index of the bar to restart playing from

restart_time

the (system-dependent) time to restart playing

Return Value

true if success


sscore_sy_setpartvolume


change the volume of a part

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

the synth from sscore_sy_createsynth

partindex

the index of the part

volume

the volume [0..1]


sscore_sy_setup


setup the synth with playdata.

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

the synth from sscore_sy_createsynth

playdata

returned from sscore_pd_newplaydata

Return Value

any error

Discussion

You must add instruments before calling setup


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,
    bool delayStartForCountIn);  
Parameters
synth

the synth from sscore_sy_createsynth

start_time

the (system-dependent) time to start playing NB This should be at least 1 or 2 seconds in the future to allow time for the setup to complete

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
synth

the synth from sscore_sy_createsynth

restart_time

the (system-dependent) time to restart playing the current bar with the new tempo


Typedefs

sscore_sampledinstrumentinfo

info defining a sampled instrument

sscore_sy_controls

link to UI which defines playing parameters

sscore_sy_controls_plus

link to UI which defines playing parameters with extra function partStaffEnabled which permits playing of a single staff in a part

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 
    enum sscore_sy_instrumentfamily family; // type of instrument 
    unsigned flags; // bit set of sscore_sy_sampledinstrument_flags 
    unsigned samplesflags; // bit set of sscore_sy_sampledinstrument_samples_flags 
    unsigned dummy[13]; 
} 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_controls


link to UI which defines playing parameters

typedef struct sscore_sy_controls { 
    sscore_sy_bool_intfn partEnabled; 
    sscore_sy_uint_intfn partInstrument; 
    sscore_sy_float_intfn partVolume; // [0.0..1.0] 
    sscore_sy_boolfn metronomeEnabled; 
    sscore_sy_uintfn metronomeInstrument; 
    sscore_sy_floatfn metronomeVolume; // [0.0..1.0] 
    void *context; 
} sscore_sy_controls;  

sscore_sy_controls_plus


link to UI which defines playing parameters with extra function partStaffEnabled which permits playing of a single staff in a part

typedef struct sscore_sy_controls_plus { 
    sscore_sy_bool_intfn partEnabled; 
    sscore_sy_uint_intfn partInstrument; 
    sscore_sy_float_intfn partVolume; // [0.0..1.0] 
    sscore_sy_boolfn metronomeEnabled; 
    sscore_sy_uintfn metronomeInstrument; 
    sscore_sy_floatfn metronomeVolume; // [0.0..1.0] 
    void *context; 
    // version >= 2.17.. 
    sscore_sy_bool_intintfn partStaffEnabled; 
    sscore_sy_int_fn loopstart; 
    sscore_sy_int_fn loopend; 
    sscore_sy_int_fn looprepeats; // set to 0 to disable looping 
    sscore_sy_int_fn dummyfn[64]; // future 
    unsigned dummy[64]; // for future 
} sscore_sy_controls_plus;  

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 
    enum sscore_sy_instrumentfamily family; // type of instrument 
    unsigned flags; // bit set of sscore_sy_sampledinstrument_flags 
    unsigned samplesflags; // bit set of sscore_sy_sampledinstrument_samples_flags 
    unsigned dummy[13]; 
} 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;  

Enumerated Types

sscore_sy_sampledinstrument_samples_flags

bit flags for specifying set of samples for instrument articulation

sscore_sy_synthesizedinstrumentvoice

define voices for synthesized instrument (metronome ticks)


sscore_sy_sampledinstrument_samples_flags


bit flags for specifying set of samples for instrument articulation

Constants
sscore_sy_normalsamples_flag

(required) normal note sample files must be named (base_filename).(midipitch).extn

sscore_sy_shortsamples_flag

(optional) short note sample files must be named (base_filename).short.(midipitch).extn

sscore_sy_pizzicatosamples_flag

(optional) pizz sample files must be named (base_filename).pizz.(midipitch).extn


sscore_sy_synthesizedinstrumentvoice


define voices for synthesized instrument (metronome ticks)

enum sscore_sy_synthesizedinstrumentvoice { 
    sscore_sy_tick1, 
    sscore_sy_tick2, 
    sscore_sy_tick3 
};