libcm is a C development framework with an emphasis on audio signal processing applications.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

cmScore.h 11KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302
  1. #ifndef cmScore_h
  2. #define cmScore_h
  3. #ifdef __cplusplus
  4. extern "C" {
  5. #endif
  6. //( { file_desc:"Object for managing musical score data." kw:[score]}
  7. enum
  8. {
  9. kOkScRC = cmOkRC,
  10. kCsvFailScRC,
  11. kSyntaxErrScRC,
  12. kInvalidIdxScRC,
  13. kTimeLineFailScRC,
  14. kInvalidDynRefCntScRC,
  15. kMidiFileFailScRC,
  16. kPedalInvalidScRC,
  17. kFileFailScRC
  18. };
  19. enum
  20. {
  21. kInvalidEvtScId = 0,
  22. kTimeSigEvtScId,
  23. kKeySigEvtScId,
  24. kTempoEvtScId,
  25. kTrackEvtScId,
  26. kTextEvtScId,
  27. kNameEvtScId,
  28. kEOTrackEvtScId,
  29. kCopyEvtScId,
  30. kBlankEvtScId,
  31. kBarEvtScId,
  32. kPgmEvtScId,
  33. kCtlEvtScId,
  34. kNonEvtScId,
  35. kPedalEvtScId
  36. };
  37. // Flags used by cmScoreEvt_t.flags
  38. enum
  39. {
  40. kEvenScFl = 0x001, // This note is marked for evenness measurement
  41. kDynScFl = 0x002, // This note is marked for dynamics measurement
  42. kTempoScFl = 0x004, // This note is marked for tempo measurement
  43. kSkipScFl = 0x008, // This isn't a real event (e.g. tied note) skip over it
  44. kGraceScFl = 0x010, // This is a grace note
  45. kInvalidScFl = 0x020, // This note has a calculated time
  46. kPedalDnScFl = 0x040, // This is a pedal down event (pitch holds the pedal id and durSecs holds the time the pedal will remain down.)
  47. kPedalUpScFl = 0x080 // This is a pedal up event (pitch holds the pedal id)
  48. };
  49. // Id's used by cmScoreSet_t.varId and as indexes into
  50. // cmScoreSection_t.vars[].
  51. enum
  52. {
  53. kInvalidVarScId,
  54. kEvenVarScId,
  55. kDynVarScId,
  56. kTempoVarScId,
  57. kScVarCnt
  58. };
  59. struct cmScoreLoc_str;
  60. struct cmScoreSet_str;
  61. // The score can be divided into arbitrary non-overlapping sections.
  62. typedef struct
  63. {
  64. const cmChar_t* label; // section label
  65. unsigned index; // index of this record in the internal section array
  66. struct cmScoreLoc_str* locPtr; // location where this section starts
  67. unsigned begEvtIndex; // score element index where this section starts
  68. unsigned setCnt; // Count of elements in setArray[]
  69. struct cmScoreSet_str** setArray; // Ptrs to sets which are applied to this section.
  70. double vars[ kScVarCnt ]; // Set to DBL_MAX by default.
  71. } cmScoreSection_t;
  72. typedef struct
  73. {
  74. unsigned type; // Event type
  75. double secs; // Time location in seconds
  76. double durSecs; // Duration in seconds
  77. unsigned index; // Index of this event in the event array.
  78. unsigned locIdx; // Index of the location containing this event
  79. cmMidiByte_t pitch; // MIDI pitch of this note or the MIDI pedal id of pedal down/up msg (64=sustain 65=sostenuto 66=soft)
  80. unsigned flags; // Attribute flags for this event
  81. unsigned dynVal; // Dynamcis value pppp to ffff (1 to 11) for this note.
  82. double frac; // Note's time value for tempo and non-grace evenness notes.
  83. unsigned barNumb; // Bar id of the measure containing this event.
  84. unsigned barNoteIdx; // Index of this note in this bar
  85. unsigned csvRowNumb; // File row number (not index) from which this record originated
  86. unsigned perfSmpIdx; // Time this event was performed or cmInvalidIdx if the event was not performed.
  87. unsigned perfVel; // Velocity of the performed note or 0 if the note was not performed.
  88. unsigned perfDynLvl; // Index into dynamic level ref. array assoc'd with perfVel
  89. unsigned line; // Line number of this event in the score file.
  90. unsigned csvEventId; // EventId from CSV 'evt' column.
  91. } cmScoreEvt_t;
  92. // A 'set' is a collection of events that are grouped in time and all marked with a given attribute.
  93. // (e.g. eveness, tempo, dynamcs ... )
  94. typedef struct cmScoreSet_str
  95. {
  96. unsigned varId; // See kXXXVarScId flags above
  97. cmScoreEvt_t** eleArray; // Events that make up this set in time order
  98. unsigned eleCnt; //
  99. cmScoreSection_t** sectArray; // Sections this set will be applied to
  100. unsigned sectCnt; //
  101. unsigned* symArray; // symArray[sectCnt] - symbol name of all variables represented by this set (e.g '1a-e', '1b-e', '2-t', etc)
  102. unsigned* costSymArray; // costSymArray[sectCnt] - same as symbols in symArray[] with 'c' prepended to front
  103. bool doneFl;
  104. double value;
  105. struct cmScoreSet_str* llink; // cmScoreLoc_t setList link
  106. } cmScoreSet_t;
  107. typedef enum
  108. {
  109. kInvalidScMId,
  110. kRecdBegScMId,
  111. kRecdEndScMId,
  112. kFadeScMId,
  113. kPlayBegScMId,
  114. kPlayEndScMId
  115. } cmMarkScMId_t;
  116. // score markers
  117. typedef struct cmScoreMarker_str
  118. {
  119. cmMarkScMId_t markTypeId; // marker type
  120. unsigned labelSymId; // marker label
  121. struct cmScoreLoc_str* scoreLocPtr; // score location of the marker
  122. unsigned csvRowIdx; // score CSV file line assoc'd w/ this marker
  123. struct cmScoreMarker_str* link; // cmScoreLoc_t.markList links
  124. } cmScoreMarker_t;
  125. // All events which are simultaneous are collected into a single
  126. // cmScoreLoc_t record.
  127. typedef struct cmScoreLoc_str
  128. {
  129. unsigned index; // index of this location record
  130. double secs; // Time of this location
  131. unsigned evtCnt; // Count of events in evtArray[].
  132. cmScoreEvt_t** evtArray; // Events which occur at this time.
  133. unsigned barNumb; // Bar number this event is contained by.
  134. cmScoreSet_t* setList; // Set's which end on this time location (linked through cmScoreSet_t.llink)
  135. cmScoreSection_t* begSectPtr; // NULL if this location does not start a section
  136. cmScoreMarker_t* markList; // List of markers assigned to this location
  137. } cmScoreLoc_t;
  138. typedef void (*cmScCb_t)( void* arg, const void* data, unsigned byteCnt );
  139. typedef cmRC_t cmScRC_t;
  140. typedef cmHandle_t cmScH_t;
  141. extern cmScH_t cmScNullHandle;
  142. const cmChar_t* cmScEvtTypeIdToLabel( unsigned id );
  143. const cmChar_t* cmScDynIdToLabel( unsigned id );
  144. const cmChar_t* cmScStatusToOpString( unsigned id );
  145. // Initialize a score object from a CSV File generated from a score spreadsheet.
  146. // The dynRefArray[dynRefCnt] and cbFunc(cbArg) are optional if these
  147. // features are not used.
  148. // If provided the dynRefArray[] is copied into an internal array.
  149. // The physical array passed here therefore does not need to remain valid.
  150. // Set 'srate' to zero if the score will not be used to perform measurement calculations.
  151. // The symbol table is only necessary if valid symbols are to be assigned to the cmScoreSet_t.symArray[].
  152. cmScRC_t cmScoreInitialize( cmCtx_t* ctx, cmScH_t* hp, const cmChar_t* fn, double srate, const unsigned* dynRefArray, unsigned dynRefCnt, cmScCb_t cbFunc, void* cbArg, cmSymTblH_t stH );
  153. cmScRC_t cmScoreFinalize( cmScH_t* hp );
  154. // Filename of last successfuly loaded score file.
  155. const cmChar_t* cmScoreFileName( cmScH_t h );
  156. // Sample rate as set in cmScoreInitialize()
  157. double cmScoreSampleRate( cmScH_t h );
  158. // Validate the score handle
  159. bool cmScoreIsValid( cmScH_t h );
  160. // Access the score data.
  161. unsigned cmScoreEvtCount( cmScH_t h );
  162. cmScoreEvt_t* cmScoreEvt( cmScH_t h, unsigned idx );
  163. // Given a bar number return the associated 'bar' event record.
  164. cmScoreEvt_t* cmScoreBarEvt( cmScH_t h, unsigned barNumb );
  165. // Access section records
  166. unsigned cmScoreSectionCount( cmScH_t h );
  167. cmScoreSection_t* cmScoreSection( cmScH_t h, unsigned idx );
  168. // Access the score location data
  169. unsigned cmScoreLocCount( cmScH_t h );
  170. cmScoreLoc_t* cmScoreLoc( cmScH_t h, unsigned idx );
  171. void cmScorePrintLoc( cmScH_t h );
  172. // Return the location associated with a given score event.
  173. cmScoreLoc_t* cmScoreEvtLoc( cmScH_t h, const cmScoreEvt_t* evt );
  174. // Return the count of sets.
  175. unsigned cmScoreSetCount( cmScH_t h );
  176. unsigned cmScoreMarkerLabelCount( cmScH_t h );
  177. unsigned cmScoreMarkerLabelSymbolId( cmScH_t h, unsigned idx );
  178. const cmScoreMarker_t* cmScoreMarker( cmScH_t h, cmMarkScMId_t markMId, unsigned labelSymId );
  179. // Make callbacks for all events in the score. The callbacks
  180. // contain cmScMsg_t records serialized as a byte stream.
  181. // Use cmScoreDecode() to convert the byte string to a
  182. // cmScMsg_t record.
  183. cmScRC_t cmScoreSeqNotify( cmScH_t h );
  184. cmScRC_t cmScoreSeqNotifyCb( cmScH_t h, cmScCb_t cbFunc, void* cbArg );
  185. void cmScoreClearPerfInfo( cmScH_t h );
  186. // Assign 'smpIdx' and 'vel' to the event matching 'pitch' at 'locIdx'
  187. // but do not trigger any variable calculations. Return true if as a
  188. // result of this call all events assigned to 'locIdx' have been received
  189. // otherwise return false.
  190. bool cmScoreSetPerfEvent( cmScH_t h, unsigned locIdx, unsigned smpIdx, unsigned pitch, unsigned vel );
  191. // Assign 'smpIdx' and 'vel' to the event matching 'pitch' at 'locIdx'
  192. // but and trigger any variable calculations which may happen on, or before, 'locIdx'.
  193. void cmScoreExecPerfEvent( cmScH_t h, unsigned locIdx, unsigned smpIdx, unsigned pitch, unsigned vel );
  194. // Assign 'value' to the section at, or before, 'locIdx'.
  195. void cmScoreSetPerfValue( cmScH_t h, unsigned locIdx, unsigned varId, double value );
  196. // Set the performed dynamic level of a score event.
  197. void cmScoreSetPerfDynLevel( cmScH_t h, unsigned evtIdx, unsigned dynLvl );
  198. typedef enum
  199. {
  200. kInvalidMsgScId,
  201. kBeginMsgScId,
  202. kEventMsgScId,
  203. kSectionMsgScId,
  204. kEndMsgScId,
  205. kVarMsgScId,
  206. kDynMsgScId
  207. } cmScMsgTypeId_t;
  208. typedef struct
  209. {
  210. unsigned varId; // see kXXXVarScId from cmScoreSet_t.varId
  211. double value; // value of a variable
  212. } cmScMeas_t;
  213. typedef struct
  214. {
  215. unsigned evtIdx;
  216. unsigned dynLvl;
  217. } cmScDyn_t;
  218. typedef struct
  219. {
  220. cmScMsgTypeId_t typeId;
  221. union
  222. {
  223. cmScoreEvt_t evt; // only used when typeId == kEventMsgScId
  224. cmScMeas_t meas; // only used when typeId == kVarMsgScId
  225. cmScoreSection_t sect; // only used when typeId == kSectionMsgScId
  226. cmScDyn_t dyn; // only used when typeId == kDynLvlMsgScId
  227. } u;
  228. } cmScMsg_t;
  229. // Decode a serialized cmScMsg_t from a byte stream as passed to the
  230. // cmScCb_t function.
  231. cmScRC_t cmScoreDecode( const void* msg, unsigned msgByteCnt, cmScMsg_t* );
  232. void cmScorePrint( cmScH_t h, cmRpt_t* rpt );
  233. typedef struct
  234. {
  235. unsigned type;
  236. unsigned scEvtIdx;
  237. unsigned left;
  238. unsigned top;
  239. unsigned width;
  240. unsigned height;
  241. const cmChar_t* text;
  242. } cmScGraphic_t;
  243. cmScRC_t cmScoreGraphicAlloc( cmScH_t h, cmScGraphic_t** vRef, unsigned* nRef );
  244. cmScRC_t cmScoreGraphicRelease( cmScH_t h, cmScGraphic_t** vRef, unsigned* nRef );
  245. cmScRC_t cmScoreGraphicWriteF( cmScH_t h, const cmChar_t* fn, cmScGraphic_t* v, unsigned n );
  246. cmScRC_t cmScoreGraphicWrite( cmScH_t h, cmFileH_t fH, cmScGraphic_t* v, unsigned n );
  247. // Generate a new score file from a MIDI file.
  248. cmScRC_t cmScoreFileFromMidi( cmCtx_t* ctx, const cmChar_t* midiFn, const cmChar_t* scoreFn );
  249. void cmScoreTest( cmCtx_t* ctx, const cmChar_t* fn );
  250. //)
  251. #ifdef __cplusplus
  252. }
  253. #endif
  254. #endif