libsmf
smf.h
Go to the documentation of this file.
1 /*-
2  * Copyright (c) 2007, 2008 Edward Tomasz NapieraƂa <trasz@FreeBSD.org>
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  *
14  * ALTHOUGH THIS SOFTWARE IS MADE OF WIN AND SCIENCE, IT IS PROVIDED BY THE
15  * AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
16  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
17  * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
18  * THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
19  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
20  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
21  * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
22  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
23  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
24  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25  *
26  */
27 
213 #ifndef SMF_H
214 #define SMF_H
215 
216 #ifdef __cplusplus
217 extern "C" {
218 #endif
219 
220 #include <stdio.h>
221 #include <glib.h>
222 
223 #if defined(__GNUC__) && __GNUC__ >= 4
224 #define WARN_UNUSED_RESULT __attribute__ ((warn_unused_result))
225 #else
226 #define WARN_UNUSED_RESULT
227 #endif
228 
230 struct smf_struct {
231  int format;
232 
234  int ppqn;
238 
240  FILE *stream;
241  void *file_buffer;
245 
247  GPtrArray *tracks_array;
249 
252  GPtrArray *tempo_array;
253 };
254 
255 typedef struct smf_struct smf_t;
256 
260  double time_seconds;
266 };
267 
269 
273 
276 
278  void *file_buffer;
280  int last_status; /* Used for "running status". */
281 
286 
289  GPtrArray *events_array;
290 
296 };
297 
299 
304 
307 
311 
314 
316  double time_seconds;
317 
320 
322  unsigned char *midi_buffer;
323 
326 
332 };
333 
335 
336 /* Routines for manipulating smf_t. */
337 smf_t *smf_new(void) WARN_UNUSED_RESULT;
338 void smf_delete(smf_t *smf);
339 
340 int smf_set_format(smf_t *smf, int format) WARN_UNUSED_RESULT;
341 int smf_set_ppqn(smf_t *smf, int format) WARN_UNUSED_RESULT;
342 
343 char *smf_decode(const smf_t *smf) WARN_UNUSED_RESULT;
344 
345 smf_track_t *smf_get_track_by_number(const smf_t *smf, int track_number) WARN_UNUSED_RESULT;
346 
347 smf_event_t *smf_peek_next_event(smf_t *smf) WARN_UNUSED_RESULT;
348 smf_event_t *smf_get_next_event(smf_t *smf) WARN_UNUSED_RESULT;
349 void smf_skip_next_event(smf_t *smf);
350 
351 void smf_rewind(smf_t *smf);
352 int smf_seek_to_seconds(smf_t *smf, double seconds) WARN_UNUSED_RESULT;
353 int smf_seek_to_pulses(smf_t *smf, int pulses) WARN_UNUSED_RESULT;
354 int smf_seek_to_event(smf_t *smf, const smf_event_t *event) WARN_UNUSED_RESULT;
355 
356 int smf_get_length_pulses(const smf_t *smf) WARN_UNUSED_RESULT;
357 double smf_get_length_seconds(const smf_t *smf) WARN_UNUSED_RESULT;
358 int smf_event_is_last(const smf_event_t *event) WARN_UNUSED_RESULT;
359 
360 void smf_add_track(smf_t *smf, smf_track_t *track);
362 
363 /* Routines for manipulating smf_track_t. */
364 smf_track_t *smf_track_new(void) WARN_UNUSED_RESULT;
365 void smf_track_delete(smf_track_t *track);
366 
367 smf_event_t *smf_track_get_next_event(smf_track_t *track) WARN_UNUSED_RESULT;
368 smf_event_t *smf_track_get_event_by_number(const smf_track_t *track, int event_number) WARN_UNUSED_RESULT;
369 smf_event_t *smf_track_get_last_event(const smf_track_t *track) WARN_UNUSED_RESULT;
370 
371 void smf_track_add_event_delta_pulses(smf_track_t *track, smf_event_t *event, int pulses);
372 void smf_track_add_event_pulses(smf_track_t *track, smf_event_t *event, int pulses);
373 void smf_track_add_event_seconds(smf_track_t *track, smf_event_t *event, double seconds);
374 int smf_track_add_eot_delta_pulses(smf_track_t *track, int delta) WARN_UNUSED_RESULT;
375 int smf_track_add_eot_pulses(smf_track_t *track, int pulses) WARN_UNUSED_RESULT;
376 int smf_track_add_eot_seconds(smf_track_t *track, double seconds) WARN_UNUSED_RESULT;
378 
379 /* Routines for manipulating smf_event_t. */
380 smf_event_t *smf_event_new(void) WARN_UNUSED_RESULT;
381 smf_event_t *smf_event_new_from_pointer(void *midi_data, int len) WARN_UNUSED_RESULT;
382 smf_event_t *smf_event_new_from_bytes(int first_byte, int second_byte, int third_byte) WARN_UNUSED_RESULT;
383 smf_event_t *smf_event_new_textual(int type, const char *text);
384 void smf_event_delete(smf_event_t *event);
385 
386 int smf_event_is_valid(const smf_event_t *event) WARN_UNUSED_RESULT;
387 int smf_event_is_metadata(const smf_event_t *event) WARN_UNUSED_RESULT;
388 int smf_event_is_system_realtime(const smf_event_t *event) WARN_UNUSED_RESULT;
389 int smf_event_is_system_common(const smf_event_t *event) WARN_UNUSED_RESULT;
390 int smf_event_is_sysex(const smf_event_t *event) WARN_UNUSED_RESULT;
391 int smf_event_is_eot(const smf_event_t *event) WARN_UNUSED_RESULT;
392 int smf_event_is_textual(const smf_event_t *event) WARN_UNUSED_RESULT;
393 char *smf_event_decode(const smf_event_t *event) WARN_UNUSED_RESULT;
394 char *smf_event_extract_text(const smf_event_t *event) WARN_UNUSED_RESULT;
395 
396 /* Routines for loading SMF files. */
397 smf_t *smf_load(const char *file_name) WARN_UNUSED_RESULT;
398 smf_t *smf_load_from_memory(const void *buffer, const int buffer_length) WARN_UNUSED_RESULT;
399 
400 /* Routine for writing SMF files. */
401 int smf_save(smf_t *smf, const char *file_name) WARN_UNUSED_RESULT;
402 
403 /* Routines for manipulating smf_tempo_t. */
404 smf_tempo_t *smf_get_tempo_by_pulses(const smf_t *smf, int pulses) WARN_UNUSED_RESULT;
405 smf_tempo_t *smf_get_tempo_by_seconds(const smf_t *smf, double seconds) WARN_UNUSED_RESULT;
406 smf_tempo_t *smf_get_tempo_by_number(const smf_t *smf, int number) WARN_UNUSED_RESULT;
407 smf_tempo_t *smf_get_last_tempo(const smf_t *smf) WARN_UNUSED_RESULT;
408 
409 const char *smf_get_version(void) WARN_UNUSED_RESULT;
410 
411 #ifdef __cplusplus
412 }
413 #endif
414 
415 #endif /* SMF_H */
416 
void smf_event_delete(smf_event_t *event)
Detaches event from its track and frees it.
Definition: smf.c:363
void smf_track_remove_from_smf(smf_track_t *track)
Detaches track from the smf.
Definition: smf.c:178
int next_event_number
Definition: smf.h:285
int smf_seek_to_seconds(smf_t *smf, double seconds) WARN_UNUSED_RESULT
Seeks the SMF to the given position.
Definition: smf.c:966
int clocks_per_click
Definition: smf.h:264
int smf_set_ppqn(smf_t *smf, int format) WARN_UNUSED_RESULT
Sets the PPQN ("Division") field of MThd header.
Definition: smf.c:674
void smf_add_track(smf_t *smf, smf_track_t *track)
Appends smf_track_t to smf.
Definition: smf.c:156
double time_seconds
Definition: smf.h:260
int next_chunk_offset
Definition: smf.h:243
int smf_event_is_valid(const smf_event_t *event) WARN_UNUSED_RESULT
Definition: smf_load.c:745
int last_status
Definition: smf.h:280
int format
Definition: smf.h:231
GPtrArray * events_array
Definition: smf.h:289
int numerator
Definition: smf.h:262
int smf_track_add_eot_pulses(smf_track_t *track, int pulses) WARN_UNUSED_RESULT
Definition: smf.c:538
int smf_save(smf_t *smf, const char *file_name) WARN_UNUSED_RESULT
Writes the contents of SMF to the file given.
Definition: smf_save.c:620
void * file_buffer
Definition: smf.h:241
void smf_track_add_event_delta_pulses(smf_track_t *track, smf_event_t *event, int pulses)
Adds event to the track at the time "pulses" clocks from the previous event in this track...
Definition: smf_tempo.c:403
GPtrArray * tempo_array
Private, used by smf_tempo.c.
Definition: smf.h:252
smf_t * smf_load_from_memory(const void *buffer, const int buffer_length) WARN_UNUSED_RESULT
Creates new SMF and fills it with data loaded from the given buffer.
Definition: smf_load.c:860
unsigned char * midi_buffer
Pointer to the buffer containing MIDI message.
Definition: smf.h:322
Represents a "song", that is, collection of one or more tracks.
Definition: smf.h:230
smf_event_t * smf_get_next_event(smf_t *smf) WARN_UNUSED_RESULT
Definition: smf.c:835
smf_t * smf_load(const char *file_name) WARN_UNUSED_RESULT
Loads SMF file.
Definition: smf_load.c:912
const char * smf_get_version(void) WARN_UNUSED_RESULT
Definition: smf.c:1112
smf_track_t * smf_get_track_by_number(const smf_t *smf, int track_number) WARN_UNUSED_RESULT
Definition: smf.c:748
Represents a single track.
Definition: smf.h:271
void * user_pointer
API consumer is free to use this for whatever purpose.
Definition: smf.h:295
GPtrArray * tracks_array
Private, used by smf.c.
Definition: smf.h:247
int ppqn
These fields are extracted from "division" field of MThd header.
Definition: smf.h:234
Describes a single tempo or time signature change.
Definition: smf.h:258
int smf_event_is_metadata(const smf_event_t *event) WARN_UNUSED_RESULT
Definition: smf_decode.c:57
int denominator
Definition: smf.h:263
smf_tempo_t * smf_get_tempo_by_number(const smf_t *smf, int number) WARN_UNUSED_RESULT
Definition: smf_tempo.c:257
int track_number
Definition: smf.h:274
int notes_per_note
Definition: smf.h:265
smf_tempo_t * smf_get_tempo_by_seconds(const smf_t *smf, double seconds) WARN_UNUSED_RESULT
Return last tempo (i.e.
Definition: smf_tempo.c:298
void smf_track_delete(smf_track_t *track)
Detaches track from its smf and frees it.
Definition: smf.c:131
smf_t * smf_new(void) WARN_UNUSED_RESULT
Allocates new smf_t structure.
Definition: smf.c:55
char * smf_event_decode(const smf_event_t *event) WARN_UNUSED_RESULT
Definition: smf_decode.c:514
int event_number
Number of this event in the track.
Definition: smf.h:306
int smf_event_is_system_common(const smf_event_t *event) WARN_UNUSED_RESULT
Definition: smf_decode.c:90
smf_t * smf
Definition: smf.h:272
int smf_get_length_pulses(const smf_t *smf) WARN_UNUSED_RESULT
Definition: smf.c:1044
int time_of_next_event
Absolute time of next event on events_queue.
Definition: smf.h:288
int smf_event_is_last(const smf_event_t *event) WARN_UNUSED_RESULT
Definition: smf.c:1100
int expected_number_of_tracks
Definition: smf.h:244
smf_track_t * smf_track_new(void) WARN_UNUSED_RESULT
Allocates new smf_track_t structure.
Definition: smf.c:110
int smf_event_is_eot(const smf_event_t *event) WARN_UNUSED_RESULT
Definition: smf_save.c:475
int time_pulses
Time, in pulses, since the start of the song.
Definition: smf.h:313
double smf_get_length_seconds(const smf_t *smf) WARN_UNUSED_RESULT
Definition: smf.c:1071
void smf_event_remove_from_track(smf_event_t *event)
Detaches event from its track.
Definition: smf.c:581
int smf_event_is_sysex(const smf_event_t *event) WARN_UNUSED_RESULT
Definition: smf_decode.c:104
void * user_pointer
API consumer is free to use this for whatever purpose.
Definition: smf.h:331
void smf_skip_next_event(smf_t *smf)
Advance the "next event counter".
Definition: smf.c:862
int midi_buffer_length
Length of the MIDI message in the buffer, in bytes.
Definition: smf.h:325
int frames_per_second
Definition: smf.h:235
smf_event_t * smf_peek_next_event(smf_t *smf) WARN_UNUSED_RESULT
Definition: smf.c:874
int number_of_tracks
Definition: smf.h:237
int smf_track_add_eot_seconds(smf_track_t *track, double seconds) WARN_UNUSED_RESULT
Definition: smf.c:558
int next_event_offset
Private, used by smf.c.
Definition: smf.h:284
void smf_track_add_event_pulses(smf_track_t *track, smf_event_t *event, int pulses)
Adds event to the track at the time "pulses" clocks from the start of song.
Definition: smf_tempo.c:419
int smf_event_is_system_realtime(const smf_event_t *event) WARN_UNUSED_RESULT
Definition: smf_decode.c:72
int number_of_events
Definition: smf.h:275
double last_seek_position
Definition: smf.h:248
int smf_track_add_eot_delta_pulses(smf_track_t *track, int delta) WARN_UNUSED_RESULT
Add End Of Track metaevent.
Definition: smf.c:524
void smf_rewind(smf_t *smf)
Rewinds the SMF.
Definition: smf.c:899
FILE * stream
These are private fields using only by loading and saving routines.
Definition: smf.h:240
smf_event_t * smf_track_get_event_by_number(const smf_track_t *track, int event_number) WARN_UNUSED_RESULT
Definition: smf.c:769
smf_event_t * smf_track_get_last_event(const smf_track_t *track) WARN_UNUSED_RESULT
Definition: smf.c:789
smf_event_t * smf_event_new_from_pointer(void *midi_data, int len) WARN_UNUSED_RESULT
Allocates an smf_event_t structure and fills it with "len" bytes copied from "midi_data".
Definition: smf.c:243
int resolution
Definition: smf.h:236
int file_buffer_length
Definition: smf.h:242
void smf_delete(smf_t *smf)
Frees smf and all it's descendant structures.
Definition: smf.c:88
char * smf_event_extract_text(const smf_event_t *event) WARN_UNUSED_RESULT
Extracts text from "textual metaevents", such as Text or Lyric.
Definition: smf_load.c:647
double time_seconds
Time, in seconds, since the start of the song.
Definition: smf.h:316
int microseconds_per_quarter_note
Definition: smf.h:261
char * smf_decode(const smf_t *smf) WARN_UNUSED_RESULT
Definition: smf_decode.c:598
int file_buffer_length
Definition: smf.h:279
smf_event_t * smf_event_new_textual(int type, const char *text)
Definition: smf_save.c:193
Represents a single MIDI event or metaevent.
Definition: smf.h:301
int smf_seek_to_event(smf_t *smf, const smf_event_t *event) WARN_UNUSED_RESULT
Seeks the SMF to the given event.
Definition: smf.c:934
int smf_seek_to_pulses(smf_t *smf, int pulses) WARN_UNUSED_RESULT
Seeks the SMF to the given position.
Definition: smf.c:1009
smf_event_t * smf_track_get_next_event(smf_track_t *track) WARN_UNUSED_RESULT
Returns next event from the track given and advances next event counter.
Definition: smf.c:692
void smf_track_add_event_seconds(smf_track_t *track, smf_event_t *event, double seconds)
Adds event to the track at the time "seconds" seconds from the start of song.
Definition: smf_tempo.c:437
int smf_set_format(smf_t *smf, int format) WARN_UNUSED_RESULT
Sets "Format" field of MThd header to the specified value.
Definition: smf.c:652
void * file_buffer
These are private fields using only by loading and saving routines.
Definition: smf.h:278
smf_event_t * smf_event_new(void) WARN_UNUSED_RESULT
Allocates new smf_event_t structure.
Definition: smf.c:217
smf_tempo_t * smf_get_last_tempo(const smf_t *smf) WARN_UNUSED_RESULT
Return last tempo.
Definition: smf_tempo.c:326
int track_number
Tracks are numbered consecutively, starting from 1.
Definition: smf.h:319
int smf_event_is_textual(const smf_event_t *event) WARN_UNUSED_RESULT
Definition: smf_load.c:627
smf_tempo_t * smf_get_tempo_by_pulses(const smf_t *smf, int pulses) WARN_UNUSED_RESULT
Return last tempo (i.e.
Definition: smf_tempo.c:271
int delta_time_pulses
Note that the time fields are invalid, if event is not attached to a track.
Definition: smf.h:310
int time_pulses
Definition: smf.h:259
smf_track_t * track
Pointer to the track, or NULL if event is not attached.
Definition: smf.h:303
smf_event_t * smf_event_new_from_bytes(int first_byte, int second_byte, int third_byte) WARN_UNUSED_RESULT
Allocates an smf_event_t structure and fills it with at most three bytes of data. ...
Definition: smf.c:282
smf_t * smf
Definition: smfsh.c:56