smflite
view src/smf.h @ 0:4264abea8b06
smf-lite initial commit
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Thu, 26 Jan 2012 11:25:11 +0200 |
| parents | |
| children |
line source
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 */
28 /**
29 * \file
30 *
31 * Public interface declaration for libsmf, Standard MIDI File format library.
32 */
34 /**
35 *
36 * \mainpage libsmf - general usage instructions
37 *
38 * An smf_t structure represents a "song". Every valid smf contains one or more tracks.
39 * Tracks contain zero or more events. Libsmf doesn't care about actual MIDI data, as long
40 * as it is valid from the MIDI specification point of view - it may be realtime message,
41 * SysEx, whatever.
42 *
43 * The only field in smf_t, smf_track_t, smf_event_t and smf_tempo_t structures your
44 * code may modify is event->midi_buffer and event->midi_buffer_length. Do not modify
45 * other fields, _ever_. You may read them, though. Do not declare static instances
46 * of these types, i.e. never do something like this: "smf_t smf;". Always use
47 * "smf_t *smf = smf_new();". The same applies to smf_track_t and smf_event_t.
48 *
49 * Say you want to load a Standard MIDI File (.mid) file and play it back somehow. This is (roughly)
50 * how you do this:
51 *
52 * \code
53 * smf_t *smf;
54 * smf_event_t *event;
55 *
56 * smf = smf_load(file_name);
57 * if (smf == NULL) {
58 * Whoops, something went wrong.
59 * return;
60 * }
61 *
62 * while ((event = smf_get_next_event(smf)) != NULL) {
63 * if (smf_event_is_metadata(event))
64 * continue;
65 *
66 * wait until event->time_seconds.
67 * feed_to_midi_output(event->midi_buffer, event->midi_buffer_length);
68 * }
69 *
70 * smf_delete(smf);
71 *
72 * \endcode
73 *
74 * Saving works like this:
75 *
76 * \code
77 *
78 * smf_t *smf;
79 * smf_track_t *track;
80 * smf_event_t *event;
81 *
82 * smf = smf_new();
83 * if (smf == NULL) {
84 * Whoops.
85 * return;
86 * }
87 *
88 * for (int i = 1; i <= number of tracks; i++) {
89 * track = smf_track_new();
90 * if (track == NULL) {
91 * Whoops.
92 * return;
93 * }
94 *
95 * smf_add_track(smf, track);
96 *
97 * for (int j = 1; j <= number of events you want to put into this track; j++) {
98 * event = smf_event_new_from_pointer(your MIDI message, message length);
99 * if (event == NULL) {
100 * Whoops.
101 * return;
102 * }
103 *
104 * smf_track_add_event_seconds(track, event, seconds since start of the song);
105 * }
106 * }
107 *
108 * ret = smf_save(smf, file_name);
109 * if (ret) {
110 * Whoops, saving failed for some reason.
111 * return;
112 * }
113 *
114 * smf_delete(smf);
115 *
116 * \endcode
117 *
118 * There are two basic ways of getting MIDI data out of smf - sequential or by track/event number. You may
119 * mix them if you need to. First one is used in the example above - seek to the point from which you want
120 * the playback to start (using smf_seek_to_seconds(), smf_seek_to_pulses() or smf_seek_to_event()) and then
121 * do smf_get_next_event() in loop, until it returns NULL. Calling smf_load() causes the smf to be rewound
122 * to the start of the song.
123 *
124 * Getting events by number works like this:
125 *
126 * \code
127 *
128 * smf_track_t *track = smf_get_track_by_number(smf, track_number);
129 * smf_event_t *event = smf_track_get_event_by_number(track, event_number);
130 *
131 * \endcode
132 *
133 * To create new event, use smf_event_new(), smf_event_new_from_pointer() or smf_event_new_from_bytes().
134 * First one creates an empty event - you need to manually allocate (using malloc(3)) buffer for
135 * MIDI data, write MIDI data into it, put the address of that buffer into event->midi_buffer,
136 * and the length of MIDI data into event->midi_buffer_length. Note that deleting the event
137 * (using smf_event_delete()) will free the buffer.
138 *
139 * Second form does most of this for you: it takes an address of the buffer containing MIDI data,
140 * allocates storage and copies MIDI data into it.
141 *
142 * Third form is useful for manually creating short events, up to three bytes in length, for
143 * example Note On or Note Off events. It simply takes three bytes and creates MIDI event containing
144 * them. If you need to create MIDI message that takes only two bytes, pass -1 as the third byte.
145 * For one byte message (System Realtime), pass -1 as second and third byte.
146 *
147 * To free an event, use smf_event_delete().
148 *
149 * To add event to the track, use smf_track_add_event_delta_pulses(), smf_track_add_event_pulses(),
150 * or smf_track_add_event_seconds(). The difference between them is in the way you specify the time of
151 * the event - with the first one, you specify it as an interval, in pulses, from the previous event
152 * in this track; with the second one, you specify it as pulses from the start of the song, and with the
153 * last one, you specify it as seconds from the start of the song. Obviously, the first version can
154 * only append events at the end of the track.
155 *
156 * To remove an event from the track it's attached to, use smf_event_remove_from_track(). You may
157 * want to free the event (using smf_event_delete()) afterwards.
158 *
159 * To create new track, use smf_track_new(). To add track to the smf, use smf_add_track().
160 * To remove track from its smf, use smf_track_remove_from_smf(). To free the track structure,
161 * use smf_track_delete().
162 *
163 * Note that libsmf keeps things consistent. If you free (using smf_track_delete()) a track that
164 * is attached to an smf and contains events, libsmf will detach the events, free them, detach
165 * the track, free it etc.
166 *
167 * Tracks and events are numbered consecutively, starting from one. If you remove a track or event,
168 * the rest of tracks/events will get renumbered. To get the number of a given event in its track, use event->event_number.
169 * To get the number of track in its smf, use track->track_number. To get the number of events in the track,
170 * use track->number_of_events. To get the number of tracks in the smf, use smf->number_of_tracks.
171 *
172 * In SMF File Format, each track has to end with End Of Track metaevent. If you load SMF file using smf_load(),
173 * that will be the case. If you want to create or edit an SMF, you don't need to worry about EOT events;
174 * libsmf automatically takes care of them for you. If you try to save an SMF with tracks that do not end
175 * with EOTs, smf_save() will append them. If you try to add event that happens after EOT metaevent, libsmf
176 * will remove the EOT. If you want to add EOT manually, you can, of course, using smf_track_add_eot_seconds()
177 * or smf_track_add_eot_pulses().
178 *
179 * Each event carries three time values - event->time_seconds, which is seconds since the start of the song,
180 * event->time_pulses, which is PPQN clocks since the start of the song, and event->delta_pulses, which is PPQN clocks
181 * since the previous event in that track. These values are invalid if the event is not attached to the track.
182 * If event is attached, all three values are valid. Time of the event is specified when adding the event
183 * (using smf_track_add_event_seconds(), smf_track_add_event_pulses() or smf_track_add_event_delta_pulses()); the remaining
184 * two values are computed from that.
185 *
186 * Tempo related stuff happens automatically - when you add a metaevent that
187 * is Tempo Change or Time Signature, libsmf adds that event to the tempo map. If you remove
188 * Tempo Change event that is in the middle of the song, the rest of the events will have their
189 * event->time_seconds recomputed from event->time_pulses before smf_event_remove_from_track() function returns.
190 * Adding Tempo Change in the middle of the song works in a similar way.
191 *
192 * MIDI data (event->midi_buffer) is always kept in normalized form - it always begins with status byte
193 * (no running status), there are no System Realtime events embedded in them etc. Events like SysExes
194 * are in "on the wire" form, without embedded length that is used in SMF file format. Obviously
195 * libsmf "normalizes" MIDI data during loading and "denormalizes" (adding length to SysExes, escaping
196 * System Common and System Realtime messages etc) during writing.
197 *
198 * Note that you always have to first add the track to smf, and then add events to the track.
199 * Doing it the other way around will trip asserts. Also, try to add events at the end of the track and remove
200 * them from the end of the track, that's much more efficient.
201 *
202 * All the libsmf functions have prefix "smf_". First argument for routines whose names start with
203 * "smf_event_" is "smf_event_t *", for routines whose names start with "smf_track_" - "smf_track_t *",
204 * and for plain "smf_" - "smf_t *". The only exception are smf_whatever_new routines.
205 * Library does not use any global variables and is thread-safe,
206 * as long as you don't try to work on the same SMF (smf_t and its descendant tracks and events) from several
207 * threads at once without protecting it with mutex. Library depends on glib and nothing else. License is
208 * BSD, two clause, which basically means you can use it freely in your software, both Open Source (including
209 * GPL) and closed source.
210 *
211 */
213 #ifndef SMF_H
214 #define SMF_H
216 #ifdef __cplusplus
217 extern "C" {
218 #endif
220 #include <stdio.h>
222 #if defined(__GNUC__) && __GNUC__ >= 4
223 #define WARN_UNUSED_RESULT __attribute__ ((warn_unused_result))
224 #else
225 #define WARN_UNUSED_RESULT
226 #endif
228 struct FakeGPtrArray;
230 /** Represents a "song", that is, collection of one or more tracks. */
231 struct smf_struct {
232 int format;
234 /** These fields are extracted from "division" field of MThd header. Valid is _either_ ppqn or frames_per_second/resolution. */
235 int ppqn;
236 int frames_per_second;
237 int resolution;
238 int number_of_tracks;
240 /** These are private fields using only by loading and saving routines. */
241 FILE *stream;
242 void *file_buffer;
243 int file_buffer_length;
244 int next_chunk_offset;
245 int expected_number_of_tracks;
247 /** Private, used by smf.c. */
248 struct FakeGPtrArray *tracks_array;
249 double last_seek_position;
251 /** Private, used by smf_tempo.c. */
252 /** Array of pointers to smf_tempo_struct. */
253 struct FakeGPtrArray *tempo_array;
254 };
256 typedef struct smf_struct smf_t;
258 /** Describes a single tempo or time signature change. */
259 struct smf_tempo_struct {
260 int time_pulses;
261 double time_seconds;
262 int microseconds_per_quarter_note;
263 int numerator;
264 int denominator;
265 int clocks_per_click;
266 int notes_per_note;
267 };
269 typedef struct smf_tempo_struct smf_tempo_t;
271 /** Represents a single track. */
272 struct smf_track_struct {
273 smf_t *smf;
275 int track_number;
276 int number_of_events;
278 /** These are private fields using only by loading and saving routines. */
279 void *file_buffer;
280 int file_buffer_length;
281 int last_status; /* Used for "running status". */
283 /** Private, used by smf.c. */
284 /** Offset into buffer, used in parse_next_event(). */
285 int next_event_offset;
286 int next_event_number;
288 /** Absolute time of next event on events_queue. */
289 int time_of_next_event;
290 struct FakeGPtrArray *events_array;
292 /** API consumer is free to use this for whatever purpose. NULL in freshly allocated track.
293 Note that tracks might be deallocated not only explicitly, by calling smf_track_delete(),
294 but also implicitly, e.g. when calling smf_delete() with tracks still added to
295 the smf; there is no mechanism for libsmf to notify you about removal of the track. */
296 void *user_pointer;
297 };
299 typedef struct smf_track_struct smf_track_t;
301 /** Represents a single MIDI event or metaevent. */
302 struct smf_event_struct {
303 /** Pointer to the track, or NULL if event is not attached. */
304 smf_track_t *track;
306 /** Number of this event in the track. Events are numbered consecutively, starting from one. */
307 int event_number;
309 /** Note that the time fields are invalid, if event is not attached to a track. */
310 /** Time, in pulses, since the previous event on this track. */
311 int delta_time_pulses;
313 /** Time, in pulses, since the start of the song. */
314 int time_pulses;
316 /** Time, in seconds, since the start of the song. */
317 double time_seconds;
319 /** Tracks are numbered consecutively, starting from 1. */
320 int track_number;
322 /** Pointer to the buffer containing MIDI message. This is freed by smf_event_delete. */
323 unsigned char *midi_buffer;
325 /** Length of the MIDI message in the buffer, in bytes. */
326 int midi_buffer_length;
328 /** API consumer is free to use this for whatever purpose. NULL in freshly allocated event.
329 Note that events might be deallocated not only explicitly, by calling smf_event_delete(),
330 but also implicitly, e.g. when calling smf_track_delete() with events still added to
331 the track; there is no mechanism for libsmf to notify you about removal of the event. */
332 void *user_pointer;
333 };
335 typedef struct smf_event_struct smf_event_t;
337 /* Routines for manipulating smf_t. */
338 smf_t *smf_new(void) WARN_UNUSED_RESULT;
339 void smf_delete(smf_t *smf);
341 int smf_set_format(smf_t *smf, int format) WARN_UNUSED_RESULT;
342 int smf_set_ppqn(smf_t *smf, int format) WARN_UNUSED_RESULT;
344 char *smf_decode(const smf_t *smf) WARN_UNUSED_RESULT;
346 smf_track_t *smf_get_track_by_number(const smf_t *smf, int track_number) WARN_UNUSED_RESULT;
348 smf_event_t *smf_peek_next_event(smf_t *smf) WARN_UNUSED_RESULT;
349 smf_event_t *smf_get_next_event(smf_t *smf) WARN_UNUSED_RESULT;
350 void smf_skip_next_event(smf_t *smf);
352 void smf_rewind(smf_t *smf);
353 int smf_seek_to_seconds(smf_t *smf, double seconds) WARN_UNUSED_RESULT;
354 int smf_seek_to_pulses(smf_t *smf, int pulses) WARN_UNUSED_RESULT;
355 int smf_seek_to_event(smf_t *smf, const smf_event_t *event) WARN_UNUSED_RESULT;
357 int smf_get_length_pulses(const smf_t *smf) WARN_UNUSED_RESULT;
358 double smf_get_length_seconds(const smf_t *smf) WARN_UNUSED_RESULT;
359 int smf_event_is_last(const smf_event_t *event) WARN_UNUSED_RESULT;
361 void smf_add_track(smf_t *smf, smf_track_t *track);
362 void smf_track_remove_from_smf(smf_track_t *track);
364 /* Routines for manipulating smf_track_t. */
365 smf_track_t *smf_track_new(void) WARN_UNUSED_RESULT;
366 void smf_track_delete(smf_track_t *track);
368 smf_event_t *smf_track_get_next_event(smf_track_t *track) WARN_UNUSED_RESULT;
369 smf_event_t *smf_track_get_event_by_number(const smf_track_t *track, int event_number) WARN_UNUSED_RESULT;
370 smf_event_t *smf_track_get_last_event(const smf_track_t *track) WARN_UNUSED_RESULT;
372 void smf_track_add_event_delta_pulses(smf_track_t *track, smf_event_t *event, int pulses);
373 void smf_track_add_event_pulses(smf_track_t *track, smf_event_t *event, int pulses);
374 void smf_track_add_event_seconds(smf_track_t *track, smf_event_t *event, double seconds);
375 int smf_track_add_eot_delta_pulses(smf_track_t *track, int delta) WARN_UNUSED_RESULT;
376 int smf_track_add_eot_pulses(smf_track_t *track, int pulses) WARN_UNUSED_RESULT;
377 int smf_track_add_eot_seconds(smf_track_t *track, double seconds) WARN_UNUSED_RESULT;
378 void smf_event_remove_from_track(smf_event_t *event);
380 /* Routines for manipulating smf_event_t. */
381 smf_event_t *smf_event_new(void) WARN_UNUSED_RESULT;
382 smf_event_t *smf_event_new_from_pointer(void *midi_data, int len) WARN_UNUSED_RESULT;
383 smf_event_t *smf_event_new_from_bytes(int first_byte, int second_byte, int third_byte) WARN_UNUSED_RESULT;
384 smf_event_t *smf_event_new_textual(int type, const char *text);
385 void smf_event_delete(smf_event_t *event);
387 int smf_event_is_valid(const smf_event_t *event) WARN_UNUSED_RESULT;
388 int smf_event_is_metadata(const smf_event_t *event) WARN_UNUSED_RESULT;
389 int smf_event_is_system_realtime(const smf_event_t *event) WARN_UNUSED_RESULT;
390 int smf_event_is_system_common(const smf_event_t *event) WARN_UNUSED_RESULT;
391 int smf_event_is_sysex(const smf_event_t *event) WARN_UNUSED_RESULT;
392 int smf_event_is_eot(const smf_event_t *event) WARN_UNUSED_RESULT;
393 int smf_event_is_textual(const smf_event_t *event) WARN_UNUSED_RESULT;
394 char *smf_event_decode(const smf_event_t *event) WARN_UNUSED_RESULT;
395 char *smf_event_extract_text(const smf_event_t *event) WARN_UNUSED_RESULT;
397 /* Routines for loading SMF files. */
398 smf_t *smf_load(const char *file_name) WARN_UNUSED_RESULT;
399 smf_t *smf_load_from_memory(const void *buffer, const int buffer_length) WARN_UNUSED_RESULT;
401 /* Routine for writing SMF files. */
402 int smf_save(smf_t *smf, const char *file_name) WARN_UNUSED_RESULT;
404 /* Routines for manipulating smf_tempo_t. */
405 smf_tempo_t *smf_get_tempo_by_pulses(const smf_t *smf, int pulses) WARN_UNUSED_RESULT;
406 smf_tempo_t *smf_get_tempo_by_seconds(const smf_t *smf, double seconds) WARN_UNUSED_RESULT;
407 smf_tempo_t *smf_get_tempo_by_number(const smf_t *smf, int number) WARN_UNUSED_RESULT;
408 smf_tempo_t *smf_get_last_tempo(const smf_t *smf) WARN_UNUSED_RESULT;
410 const char *smf_get_version(void) WARN_UNUSED_RESULT;
412 #ifdef __cplusplus
413 }
414 #endif
416 #endif /* SMF_H */