sscore_synth.h
IntroductionThe C interface to SeeScoreLib sound synthesizer C Pseudoclasses
Functions
sscore_sy_addsampledinstrumentcreate 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); ParametersReturn Valuea unique identifier for the instrument sscore_sy_addsynthesizedinstrumentcreate 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); ParametersReturn Valuea unique identifier for the instrument sscore_sy_changedcontrolsnotification that the controls have changed so the sscore_sy_controls needs to be reread EXPORT void sscore_sy_changedcontrols( sscore_synth *synth); Parameterssscore_sy_createsynthcreate a new synth and return it EXPORT sscore_synth *sscore_sy_createsynth( const sscore_sy_controls *controls, const sscore_libkeytype *key); ParametersReturn Valuethe synth sscore_sy_createsynth_pluscreate 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); ParametersReturn Valuethe synth sscore_sy_disposesynthdispose the synth EXPORT void sscore_sy_disposesynth( sscore_synth *synth); Parameterssscore_sy_ispausedEXPORT bool sscore_sy_ispaused( sscore_synth *synth); ParametersReturn Valuetrue if synth is paused sscore_sy_isplayingdetect if the synth is playing EXPORT bool sscore_sy_isplaying( sscore_synth *synth); ParametersReturn Valuetrue if playing sscore_sy_pausepause playing EXPORT bool sscore_sy_pause( sscore_synth *synth); ParametersReturn Valuetrue if success sscore_sy_playingbarEXPORT int sscore_sy_playingbar( sscore_synth *synth); ParametersReturn Valuethe index of the bar playing sscore_sy_removeinstrumentremove an instrument previously added with sscore_sy_addsampledinstrument or sscore_sy_addsynthesizedinstrument EXPORT void sscore_sy_removeinstrument( sscore_synth *synth, sscore_sy_instrumentid iid); Parameterssscore_sy_resetstop playing and reset to the start of the score EXPORT void sscore_sy_reset( sscore_synth *synth); Parameterssscore_sy_resumeresume playing after pause EXPORT bool sscore_sy_resume( sscore_synth *synth); ParametersReturn Valuetrue if success sscore_sy_setmetronomevolumechange the volume of the metronome EXPORT void sscore_sy_setmetronomevolume( sscore_synth *synth, float volume); Parameterssscore_sy_setnextplaybarset 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); ParametersReturn Valuetrue if success sscore_sy_setpartvolumechange the volume of a part EXPORT void sscore_sy_setpartvolume( sscore_synth *synth, int partindex, float volume); Parameterssscore_sy_setupsetup the synth with playdata. EXPORT enum sscore_error sscore_sy_setup( sscore_synth *synth, const sscore_playdata *playdata); ParametersReturn Valueany error DiscussionYou must add instruments before calling setup sscore_sy_startatstart 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); ParametersReturn Valueany error sscore_sy_updatetemponotification that the user has changed the tempo (viz. sscore_pd_usertempo) EXPORT void sscore_sy_updatetempo( sscore_synth *synth, unsigned long long restart_time); ParametersTypedefs
sscore_sampledinstrumentinfoinfo 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; Discussiona 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_controlslink 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_pluslink 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_sampledinstrumentinfoinfo 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; Discussiona 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_synthesizedinstrumentinfoinfo 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_flagsbit flags for specifying set of samples for instrument articulation enum sscore_sy_sampledinstrument_samples_flags { sscore_sy_normalsamples_flag = 1, sscore_sy_shortsamples_flag = 1<<1, sscore_sy_pizzicatosamples_flag = 1<<2, }; Constants
sscore_sy_synthesizedinstrumentvoicedefine voices for synthesized instrument (metronome ticks) enum sscore_sy_synthesizedinstrumentvoice { sscore_sy_tick1, sscore_sy_tick2, sscore_sy_tick3 }; |