sscore_playdata.h
IntroductionThe C interface to play information in SeeScoreLib The barindex parameter is zero-based. ie 0 is the first bar in the score. All times are in milliseconds C Pseudoclasses
Groupssscore_pd_barnotes_iteratorGroup members:
sscore_pd_bar_iteratorall functions must be called on a single thread Group members:
sscore_playdataGroup members:
Functions
sscore_pd_abbrevpartnameEXPORT const char *sscore_pd_abbrevpartname( const sscore_playdata *pd, int partindex); Return Valuethe abbreviated name of the part eg "Pno" sscore_pd_actualbeatsforbarget the effective time signature information for a bar EXPORT enum sscore_error sscore_pd_actualbeatsforbar( const sscore *sc, int barindex, sscore_timesig *timesig); ParametersReturn Valueany error DiscussionThis should return the same value as sscore_timesigforbar for a full bar, less for a partial bar sscore_pd_bartypeforbarget information about a partial bar with fewer beats than the time signature (anacrusis or double-barline bar) EXPORT enum sscore_bartype_e sscore_pd_bartypeforbar( const sscore *sc, int barindex); ParametersReturn Valuetype of partial bar Discussionit is important to know if a partial bar contains the first beat or the last beat sscore_pd_beginan iterator to the start bar of the piece (viz STL container) EXPORT sscore_pd_bar_iterator sscore_pd_begin( const sscore_playdata *pd); ParametersReturn Valuean iterator to the start bar of the piece Discussionincrement the iterator to move to the next bar in play order allowing for repeats sscore_pd_bi_bardurationthe duration of the current bar in ms EXPORT int sscore_pd_bi_barduration( const sscore_pd_bar_iterator *bi); ParametersReturn Valueduration of bar in ms sscore_pd_bi_barduration_midithe duration of the current bar in midi ticks (24 per crotchet) EXPORT int sscore_pd_bi_barduration_midi( const sscore_pd_bar_iterator *bi, int crotchet_duration); ParametersReturn Valueduration of bar in midi ticks sscore_pd_bi_barindexget the index of the current bar EXPORT int sscore_pd_bi_barindex( const sscore_pd_bar_iterator *bi); ParametersReturn Valuethe index of the bar which the iterator refers to (0 for first bar) sscore_pd_bi_beginan iterator to notes in the current and next bar EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_begin( const sscore_pd_bar_iterator *bi, int partindex); ParametersReturn Valuethe start barnotes iterator pointing to the first played note in the bar. Discussionincrement the returned iterator (sscore_pd_bni_inc) to move to the next note in time order in the given part 'dereference' the iterator (sscore_pd_bni_getnote) to get the note information NB The iterator never returns the right hand note of a tie, as that only modifies the duration of the first tied note sscore_pd_bi_canchangebartrue if sscore_pd_bi_changebar will succeed with these parameters EXPORT bool sscore_pd_bi_canchangebar( const sscore_pd_bar_iterator *bi, int barindex); Parameterssscore_pd_bi_changebarmove the bar iterator to the given bar index. This will fail if it is outside the range of any defined loop on this iterator EXPORT bool sscore_pd_bi_changebar( sscore_pd_bar_iterator *bi, int barindex); ParametersReturn Valuetrue if successful sscore_pd_bi_converttocountinconvert an iterator to work for a count-in bar ie with a maximum of 4 beats EXPORT sscore_pd_bar_iterator sscore_pd_bi_converttocountin( const sscore_pd_bar_iterator *bi); ParametersReturn Valuean iterator converted to produce a count-in bar sscore_pd_bi_decmove the bar iterator to the previous bar accounting for repeats. Unchanged if at beginning EXPORT void sscore_pd_bi_dec( sscore_pd_bar_iterator *bi); Parameterssscore_pd_bi_endnextan iterator 1 past the last note in next bar so begin->endnext includes all notes in 2 bars so that the bar transition is covered EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_endnext( const sscore_pd_bar_iterator *bi, int partindex); ParametersReturn Valuethe past-end barnotes iterator Discussioncompare a barnotes iterator with this to detect the end of sequence sscore_pd_bi_endthisan iterator 1 past the last note in the bar/part EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_endthis( const sscore_pd_bar_iterator *bi, int partindex); ParametersReturn Valuethe past-end barnotes iterator Discussioncompare a barnotes iterator with this to detect the end of sequence for the bar sscore_pd_bi_equalcompare 2 iterators EXPORT bool sscore_pd_bi_equal( const sscore_pd_bar_iterator *bi1, const sscore_pd_bar_iterator *bi2); ParametersReturn Valuetrue if iterators are equal (point to the same bar, same repeat) sscore_pd_bi_getnotesampleinfoget information about notes required for preloading note samples ahead of time EXPORT enum sscore_error sscore_pd_bi_getnotesampleinfo( const sscore_pd_bar_iterator *bi, int numbars, const sscore_pd_partset *partset, sscore_pd_notesamples *rval); Parameters
Return Valueany error sscore_pd_bi_incmove the bar iterator to the next bar accounting for repeats. Unchanged if at end. If bi is a looping iterator and it is at the last bar in the loop it goes to the first bar in the loop EXPORT void sscore_pd_bi_inc( sscore_pd_bar_iterator *bi); Parameterssscore_pd_bi_incbyindexincrement the bar iterator by index EXPORT void sscore_pd_bi_incbyindex( sscore_pd_bar_iterator *bi, int index); Parameterssscore_pd_bi_iscountincount-in bar? EXPORT bool sscore_pd_bi_iscountin( const sscore_pd_bar_iterator *bi); ParametersReturn Valuetrue for a count-in bar sscore_pd_bi_keythe key signature in the bar EXPORT int sscore_pd_bi_keysig( int partindex, const sscore_pd_bar_iterator *bi); ParametersReturn Valuekey signature - positive indicates number of sharps in key sig, negative indicates number of flats sscore_pd_bi_keysigthe key signature in the bar EXPORT int sscore_pd_bi_keysig( int partindex, const sscore_pd_bar_iterator *bi); ParametersReturn Valuekey signature - positive indicates number of sharps in key sig, negative indicates number of flats sscore_pd_bi_lesscompare 2 iterators EXPORT bool sscore_pd_bi_less( const sscore_pd_bar_iterator *bi1, const sscore_pd_bar_iterator *bi2); ParametersReturn Valuetrue if bi1 is at an earlier bar than bi2 sscore_pd_bi_metronome_beginan iterator to pseudo metronome notes in the current and next bar EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_metronome_begin( const sscore_pd_bar_iterator *bi); ParametersReturn Valuethe barnotes iterator Discussionthe metronome is modelled as a series of notes, 1 per beat in each bar. The correct bar sequence time signature changes are followed sscore_pd_bi_metronome_endnextan iterator 1 past the last note in the metronome sequence for this bar and the next bar EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_metronome_endnext( const sscore_pd_bar_iterator *bi); ParametersReturn Valuethe barnotes iterator sscore_pd_bi_metronome_endthisan iterator 1 past the last note in the metronome sequence for the bar EXPORT sscore_pd_barnotes_iterator sscore_pd_bi_metronome_endthis( const sscore_pd_bar_iterator *bi); ParametersReturn Valuethe barnotes iterator sscore_pd_bi_metronomebeatsinbarthe number of metronome ticks, max 4 if count-in bar EXPORT int sscore_pd_bi_metronomebeatsinbar( const sscore_pd_bar_iterator *bi); ParametersReturn Valuethe number of metronome beats in the bar sscore_pd_bi_nextbarindexindex of next bar EXPORT int sscore_pd_bi_nextbarindex( const sscore_pd_bar_iterator *bi); ParametersReturn Valueindex of the next bar after inc if canadvance, else sscore_pd_kAfterEndBarIndex sscore_pd_bi_seqindexplay index of bar in nondecreasing sequence EXPORT int sscore_pd_bi_seqindex( const sscore_pd_bar_iterator *bi); ParametersReturn Valuesequential play index of the bar accounting for any repeats sscore_pd_bi_tempo_crotchet_bpmreturn the crotchet beats per minute in this bar EXPORT int sscore_pd_bi_tempo_crotchet_bpm( const sscore_pd_bar_iterator *bi); ParametersReturn Valuethe crotchet tempo sscore_pd_bi_timesigthe time signature in the bar EXPORT sscore_timesig sscore_pd_bi_timesig( int partindex, const sscore_pd_bar_iterator *bi); ParametersReturn Valuetime signature sscore_pd_bni_decdecrement the barnotes iterator so sscore_pd_bni_getnote returns the previous note EXPORT void sscore_pd_bni_dec( sscore_pd_barnotes_iterator *bni); Parameterssscore_pd_bni_equalcompare 2 iterators EXPORT bool sscore_pd_bni_equal( const sscore_pd_barnotes_iterator *bni1, const sscore_pd_barnotes_iterator *bni2); ParametersReturn Valuetrue if iterators are equal sscore_pd_bni_getnoteget the note information at the current iterator position EXPORT sscore_pd_note sscore_pd_bni_getnote( const sscore_pd_barnotes_iterator *bni); ParametersReturn Valueplay information about a note sscore_pd_bni_incincrement the barnotes iterator so sscore_pd_bni_getnote returns the next note EXPORT void sscore_pd_bni_inc( sscore_pd_barnotes_iterator *bni); ParametersDiscussionnotes are returned in non-decreasing start time order sscore_pd_bni_incbyindexincrement the barnotes iterator by index EXPORT void sscore_pd_bni_incbyindex( sscore_pd_barnotes_iterator *bni, int index); Parameterssscore_pd_bni_lesscompare 2 iterators EXPORT bool sscore_pd_bni_less( const sscore_pd_barnotes_iterator *bni1, const sscore_pd_barnotes_iterator *bni2); ParametersReturn Valuetrue if bni1 is earlier in the score than bni2 (assuming same playdata and part) sscore_pd_converttempotobpmconvert a tempo with a given beat type to the given time sig beat type EXPORT int sscore_pd_converttempotobpm( const sscore_pd_tempo *tempo, const sscore_timesig *timesig); ParametersReturn Valuebeats per minute Discussionthis is useful for converting sound tempo values, which are always crotchet relative (beat = 4) to the current time signature sscore_pd_create_midifilecreate a MIDI file from the playdata EXPORT enum sscore_error sscore_pd_create_midifile( const sscore_playdata *pd, const char *midifilename); ParametersReturn Valueerror sscore_pd_create_midifile_controlcreate a MIDI file from the playdata EXPORT enum sscore_error sscore_pd_create_midifile_control( const sscore_playdata *pd, const char *midifilename, const sscore_pd_controls *controls, const sscore_pd_midi_params *params); ParametersReturn Valueerror Discussionlicence playloop_capable is required to use the playloop function sscore_pd_disposeplaydatadispose the playdata EXPORT void sscore_pd_disposeplaydata( const sscore_playdata *pd); ParametersDiscussiondispose the memory allocated for this by sscore_pd_newplaydata sscore_pd_endan iterator to 1 past the end bar of the piece EXPORT sscore_pd_bar_iterator sscore_pd_end( const sscore_playdata *pd); ParametersReturn Valuean iterator to 1 past the end bar of the piece Discussionif the iterator is equal to this then the play is finished sscore_pd_firstbaranacrusisdetect partial first bar (anacrusis) EXPORT bool sscore_pd_firstbaranacrusis( const sscore_playdata *pd); ParametersReturn Valuetrue if 1st bar starts after first beat sscore_pd_fullpartnameEXPORT const char *sscore_pd_fullpartname( const sscore_playdata *pd, int partindex); Return Valuethe full name of the part eg "Piano" sscore_pd_getbarbeatsget the beats and divisions in a bar and the duration EXPORT enum sscore_error sscore_pd_getbarbeats( const sscore *sc, int barindex, int bpm, enum sscore_bartype_e bartype, sscore_pd_barbeats *barbeats); Parameters
Return Valueany error sscore_pd_getusertempointernal function sscore_pd_usertempo sscore_pd_getusertempo( const sscore_playdata *pd); ParametersReturn Valuethe sscore_pd_usertempo sscore_pd_hasdataformetronomeEXPORT bool sscore_pd_hasdataformetronome( const sscore_playdata *pd); Return Valuetrue if the metronome is enabled for play sscore_pd_hasdataforpartEXPORT bool sscore_pd_hasdataforpart( const sscore_playdata *pd, int partindex); Return Valuetrue if the part is enabled for play sscore_pd_hasdefinedtempois tempo defined in the score? EXPORT bool sscore_pd_hasdefinedtempo( const sscore *sc); ParametersReturn Valuetrue if the score defines tempo (metronome or sound tempo element). DiscussionIf this returns true then sscore_pd_usertempo.get_user_tempo_scaling will be called, else sscore_pd_usertempo.get_user_bpm will be used sscore_pd_loopbeginget an iterator which goes repeatedly from startBarIndex to loopBarIndex for the given number of repeats EXPORT sscore_pd_bar_iterator sscore_pd_loopbegin( const sscore_playdata *pd, int startBarIndex, int loopBarIndex, int numRepeats); ParametersReturn Valuean iterator which loops between the specified bars Discussionlicence playloop_capable is required to use this function sscore_pd_loopendget an iterator for the end of looping of loopbegin EXPORT sscore_pd_bar_iterator sscore_pd_loopend( const sscore_playdata *pd, const sscore_pd_bar_iterator *begin); ParametersReturn Valuean iterator to the end of the loop sscore_pd_maxdynamicmaximum value of any sound dynamic value in all bars EXPORT float sscore_pd_maxdynamic( const sscore_playdata *pd); ParametersReturn Valuemax sound dynamic value in score or 0 if none defined sscore_pd_metronomeforbarget any metronome defined in or before a bar EXPORT enum sscore_error sscore_pd_metronomeforbar( const sscore *sc, int barindex, sscore_pd_tempo *tempo); ParametersReturn Valuesscore_ItemNotFoundError if no metronome value defined sscore_pd_midiprogramchangeEXPORT int sscore_pd_midiprogramchange( const sscore_playdata *pd, int partindex); Return Valuethe program change value if virtual instrument is correctly defined in the MusicXML, else return 0 Discussionif the <virtual-instrument><virtual-library> element contains "General MIDI" then lookup the string value of the <virtual-instrument><virtual-name> element in Program Change table of standard instrument names in MIDI spec 1.1 http://www.midimusic.org.uk/tech/midispec.html of the sscore_pd_newplaydatacreate playdata which provides iterators for bar and note access EXPORT const sscore_playdata *sscore_pd_newplaydata( const sscore *sc, const sscore_pd_usertempo *usertempo, const sscore_libkeytype *key); Parameters
Return Valuepointer to new playdata sscore_pd_newplaydata_singlebarcreate playdata for single part/single bar only EXPORT const sscore_playdata *sscore_pd_newplaydata_singlebar( const sscore *sc, int partIndex, int barIndex, const sscore_pd_usertempo *usertempo, const sscore_libkeytype *key); ParametersReturn Valuepointer to new playdata sscore_pd_newplaydata_singlechordcreate playdata for single note or chord only EXPORT const sscore_playdata *sscore_pd_newplaydata_singlechord( const sscore *sc, int partIndex, int barIndex, sscore_item_handle noteId, const sscore_libkeytype *key); ParametersReturn Valuepointer to new playdata sscore_pd_newplaydata_singlepartcreate playdata for single part/single bar only EXPORT const sscore_playdata *sscore_pd_newplaydata_singlepart( const sscore *sc, int partIndex, int barIndex, const sscore_pd_usertempo *usertempo, const sscore_libkeytype *key); ParametersReturn Valuepointer to new playdata sscore_pd_newplaydata_withtimingcreate playdata which is synchronised to the timing array EXPORT const sscore_playdata *sscore_pd_newplaydata_withtiming( const sscore *sc, const sscore_pd_usertempo *usertempo, const sscore_pd_timinginfo *timing, const sscore_libkeytype *key, enum sscore_error *error); Parameters
Return Valuepointer to new playdata sscore_pd_numpartsEXPORT int sscore_pd_numparts( const sscore_playdata *pd); Return Valuenumber of parts in score sscore_pd_numstavesforpartEXPORT int sscore_pd_numstavesforpart( const sscore_playdata *pd, int partindex); Return Valuenumber of staves in part sscore_pd_scalemidifiletempopoke a new tickrate value into the midi file to scale the tempo EXPORT void sscore_pd_scalemidifiletempo( const char *midifilename, float temposcaling); ParametersReturn Valueerror sscore_pd_tempoatbarget any tempo applying at the start of the given bar EXPORT enum sscore_error sscore_pd_tempoatbar( const sscore *sc, int barindex, sscore_pd_tempo *tempo); ParametersReturn Valuesscore_ItemNotFoundError if no tempo value defined Discussionthis returns in tempo a) any metronome value or b) any sound tempo value defined at the start of the given bar sscore_pd_tempoatstartget any tempo applying at the start of the score EXPORT enum sscore_error sscore_pd_tempoatstart( const sscore *sc, sscore_pd_tempo *tempo); ParametersReturn Valuesscore_ItemNotFoundError if no tempo value defined Discussionthis returns in tempo a) any metronome value or b) any sound tempo value defined at the start of the score sscore_pd_timesigforbarget information about the notated time signature which applies to a bar EXPORT enum sscore_error sscore_pd_timesigforbar( const sscore *sc, int barindex, sscore_timesig *timesig); ParametersReturn Valueany error sscore_pd_titleEXPORT const char *sscore_pd_title( const sscore_playdata *pd); ParametersReturn Valuea suitable title string if available sscore_pd_virtualinstrumentlibraryEXPORT const char *sscore_pd_virtualinstrumentlibrary( const sscore_playdata *pd, int partindex); Return Valuethe string value of the <virtual-instrument><virtual-library> element for the part - empty if non-existent sscore_pd_virtualinstrumentnameEXPORT const char *sscore_pd_virtualinstrumentname( const sscore_playdata *pd, int partindex); Return Valuethe string value of the <virtual-instrument><virtual-name> element for the part - empty if non-existent Typedefs
sscore_barbeatsnumber and duration of beats in a bar typedef struct sscore_pd_barbeats { int beatsinbar; int beattime; // ms } sscore_pd_barbeats; See Also sscore_pd_bar_iteratorprivate bar iterator for accessing bars in correct sequence when playing typedef struct sscore_pd_bar_iterator { // private fields const sscore_playdata *pd; int idx; int ci; unsigned loop; int loopc; unsigned dummy[5]; } sscore_pd_bar_iterator; Discussionthis is not multi-thread safe. ie all functions using this must be called on a single thread sscore_pd_barbeatsnumber and duration of beats in a bar typedef struct sscore_pd_barbeats { int beatsinbar; int beattime; // ms } sscore_pd_barbeats; See Also sscore_pd_barnotes_iteratorprivate bar notes iterator for playing typedef struct sscore_pd_barnotes_iterator { // private fields sscore_pd_bar_iterator bi; int pidx; int nidx; unsigned dummy[8]; } sscore_pd_barnotes_iterator; Discussionthis provides notes sequentially with non-decreasing start time from the start of the bar to the end of the _following_ bar, ie notes in 2 bars, so that there is not an inter-bar discontinuity when using non-bar-aligned buffers NB This must be used with the supplied functions. The private fields should not be tampered with sscore_pd_controlslink to UI which defines playing parameters typedef struct sscore_pd_controls { void *context; sscore_pd_bool_intfn partEnabled; // return true to output notes in this part into MIDI file sscore_pd_int_intfn midiProgramForPart; // define MIDI program change value for part if > 0 sscore_pd_bool_intintfn partStaffEnabled; // return true to output notes in unsigned dummy[64]; // for future enhancement } sscore_pd_controls; sscore_pd_midi_paramsdefine various midi parameters typedef struct sscore_pd_midi_params { int loopStartBarIndex; // define loop start bar index int loopEndBarIndex; // define end loop bar index int loopNumRepeats; // 0 for no play loop unsigned dummy[128];// future expansion } sscore_pd_midi_params; sscore_pd_noteinformation about a note for playing typedef struct sscore_pd_note { int midipitch; // 60 = C4. 0 = unpitched (eg rest or percussion) (also used as beat index for metronome) int startbarindex; // index of bar in which this note starts (may be tied) int start; // start time from start of bar (milliseconds) int duration; // (ms) may be longer than a bar if tied int dynamic; // [0..100] value of the last dynamic enum sscore_pd_grace_e grace; // set for grace note sscore_item_handle item_h; // item handle used in sscore_contents int midi_start; // midi start time (24 ticks per crotchet/quarter note) int midi_duration; // midi duration (24 ticks per crotchet/quarter note) int staffindex; // index of the staff containing this note. 0 is top (or only) staff unsigned articulation_flags; // bit flags sscore_pd_articulation_flags_e. A rest has pitch = 0 and .._rest_flag set unsigned dummy[4]; // future } sscore_pd_note; DiscussionNB The right-hand note of a tie is included in the duration of the left hand note and omitted from the list sscore_pd_notesampleinformation required for pre-loading a note sample typedef struct sscore_pd_notesample { int midipitch; // 60 = C4. 0 = unpitched (eg percussion) int duration; // (ms) may be longer than a bar if tied unsigned articulation_flags; // bit flags sscore_pd_articulation_flags_e unsigned dummy[1]; } sscore_pd_notesample; sscore_pd_notesamplesinformation required for pre-loading note samples typedef struct sscore_pd_notesamples { int num; sscore_pd_notesample samples[sscore_pd_MaxNoteSamples]; unsigned dummy[8]; } sscore_pd_notesamples; sscore_pd_partsetdefine playing parts typedef struct sscore_pd_partset { int num; // the number of parts bool parts[sscore_kMaxParts]; // play value per part } sscore_pd_partset; sscore_pd_tempotempo information typedef struct sscore_pd_tempo { int bpm; int beattype; bool dot; bool usebeattype; // set if this is a beat type from a metronome mark and should be displayed, else it is a standard 4 for a sound tempo and is irrelevant to the beat unsigned dummy[8]; } sscore_pd_tempo; sscore_pd_timinginfospecification of beat timing for media synchronisation typedef struct sscore_pd_timinginfo { int mediaStart_ms; // if non-zero specifies a delay before starting synchronised media int numbars; struct { int barIndex; // the 0-based index of this bar int duration_ms; // duration of bar in ms int numSubsequentBeats; // = 3 for a 4-beat bar struct { int time_ms; // time of subsequent beat from start (first beat) of bar unsigned dummy[4]; } beat[sscore_pd_kMaxBeatsInBar]; unsigned dummy[4]; } bar[sscore_kMaxBars]; unsigned dummy[64]; } sscore_pd_timinginfo; sscore_pd_usertempodefine realtime user tempo specification typedef struct sscore_pd_usertempo { sscore_pd_int_fn get_user_bpm; sscore_pd_float_fn get_user_tempo_scaling; void *context; unsigned dummy[8]; } sscore_pd_usertempo; Fields
Enumerated Types
sscore_bartype_ecategorise partial bars enum sscore_bartype_e { sscore_bartype_full_bar, // normal full bar sscore_bartype_partial_first_bar, // partial bar is first bar in score (ie anacrusis) sscore_bartype_partial_bar_start, // partial bar including beat 1 (ie before repeat mark) sscore_bartype_partial_bar_end, // partial bar missing beat 1 (ie after repeat mark) sscore_bartype_default // for default argument }; Macro Definitions
sscore_pd_kAfterEndBarIndexspecial value to indicate beyond the last bar in the piece #define sscore_pd_kAfterEndBarIndex Value 0xfffffffffffffffe (-2) sscore_pd_kInvalidBarIndexan invalid bar index #define sscore_pd_kInvalidBarIndex Value 0xffffffffffffffff (-1) |