1LIBXMP(3) Extended Module Player LIBXMP(3)
2
6 libxmp - A tracker module player library
7
9 Libxmp is a module player library supporting many mainstream and ob‐
10 scure module formats including Protracker MOD, Scream Tracker III S3M
11 and Impulse Tracker IT. Libxmp loads the module and renders the sound
12 as linear PCM samples in a buffer at rate and format specified by the
13 user, one frame at a time (standard modules usually play at 50 frames
14 per second).
15 Possible applications for libxmp include stand-alone module players,
17 module player plugins for other players, module information extractors,
18 background music replayers for games and other applications, mod‐
19 ule-to-mp3 renderers, etc.
20 Concepts
22 • Player context: Most libxmp functions require a handle that identi‐
23 fies the module player context. Each context is independent and mul‐
24 tiple contexts can be defined simultaneously.
25 • Sequence: Each group of positions in the order list that loops over
27 itself, also known as "subsong". Most modules have only one sequence,
28 but some modules, especially modules used in games can have multiple
29 sequences. "Hidden patterns" outside the main song are also listed as
30 extra sequences, certain module authors such as Skaven commonly place
31 extra patterns at the end of the module.
32 • State: [Added in libxmp 4.2] The player can be in one of three possi‐
34 ble states: unloaded, loaded, or playing. The player is in unloaded
35 state after context creation, changing to other states when a module
36 is loaded or played.
37 • External sample mixer: [Added in libxmp 4.2] Special sound channels
39 can be reserved using xmp_start_smix() to play module instruments or
40 external samples. This is useful when libxmp is used to provide back‐
41 ground music to games or other applications where sound effects can
42 be played in response to events or user actions
43 • Amiga mixer: [Added in libxmp 4.4] Certain formats may use special
45 mixers modeled after the original hardware used to play the format,
46 providing more realistic sound at the expense of CPU usage. Currently
47 Amiga formats such as Protracker can use a mixer modeled after the
48 Amiga 500, with or without the led filter.
49 A simple example
51 This example loads a module, plays it at 44.1kHz and writes it to a raw
52 sound file:
53 #include <stdio.h>
55 #include <stdlib.h>
56 #include <xmp.h>
57 int main(int argc, char **argv)
59 {
60 xmp_context c;
61 struct xmp_frame_info mi;
62 FILE *f;
63 /* The output raw file */
65 f = fopen("out.raw", "wb");
66 if (f == NULL) {
67 fprintf(stderr, "can't open output file\n");
68 exit(EXIT_FAILURE);
69 }
70 /* Create the player context */
72 c = xmp_create_context();
73 /* Load our module */
75 if (xmp_load_module(c, argv[1]) != 0) {
76 fprintf(stderr, "can't load module\n");
77 exit(EXIT_FAILURE);
78 }
79 /* Play the module */
81 xmp_start_player(c, 44100, 0);
82 while (xmp_play_frame(c) == 0) {
83 xmp_get_frame_info(c, &mi);
84 if (mi.loop_count > 0) /* exit before looping */
86 break;
87 fwrite(mi.buffer, mi.buffer_size, 1, f); /* write audio data */
89 }
90 xmp_end_player(c);
91 xmp_release_module(c); /* unload module */
92 xmp_free_context(c); /* destroy the player context */
93 fclose(f);
95 exit(EXIT_SUCCESS);
97 }
98 A player context can load and play a single module at a time. Multiple
100 contexts can be defined if needed.
101 Use xmp_test_module() to check if the file is a valid module and re‐
103 trieve the module name and type. Use xmp_load_module() to load the mod‐
104 ule to memory. These two calls return 0 on success or <0 in case of er‐
105 ror. Error codes are:
106 -XMP_ERROR_INTERNAL /* Internal error */
108 -XMP_ERROR_FORMAT /* Unsupported module format */
109 -XMP_ERROR_LOAD /* Error loading file */
110 -XMP_ERROR_DEPACK /* Error depacking file */
111 -XMP_ERROR_SYSTEM /* System error */
112 -XMP_ERROR_STATE /* Incorrect player state */
113 If a system error occurs, the specific error is set in errno.
115 Parameters to xmp_start_player() are the sampling rate (up to 48kHz)
117 and a bitmapped integer holding one or more of the following mixer
118 flags:
119 XMP_MIX_8BIT /* Mix to 8-bit instead of 16 */
121 XMP_MIX_UNSIGNED /* Mix to unsigned samples */
122 XMP_MIX_MONO /* Mix to mono instead of stereo */
123 XMP_MIX_NEAREST /* Mix using nearest neighbor interpolation */
124 XMP_MIX_NOFILTER /* Disable lowpass filter */
125 After xmp_start_player() is called, each call to xmp_play_frame() will
127 render an audio frame. Call xmp_get_frame_info() to retrieve the buffer
128 address and size. xmp_play_frame() returns 0 on success or -1 if replay
129 should stop.
130 Use xmp_end_player(), xmp_release_module() and xmp_free_context() to
132 release memory and end replay.
133 SDL example
135 To use libxmp with SDL, just provide a callback function that renders
136 module data. The module will play when SDL_PauseAudio(0) is called:
137 #include <SDL/SDL.h>
139 #include <xmp.h>
140 static void fill_audio(void *udata, unsigned char *stream, int len)
142 {
143 xmp_play_buffer(udata, stream, len, 0);
144 }
145 int sound_init(xmp_context ctx, int sampling_rate, int channels)
147 {
148 SDL_AudioSpec a;
149 a.freq = sampling_rate;
151 a.format = (AUDIO_S16);
152 a.channels = channels;
153 a.samples = 2048;
154 a.callback = fill_audio;
155 a.userdata = ctx;
156 if (SDL_OpenAudio(&a, NULL) < 0) {
158 fprintf(stderr, "%s\n", SDL_GetError());
159 return -1;
160 }
161 }
162 int main(int argc, char **argv)
164 {
165 xmp_context ctx;
166 if ((ctx = xmp_create_context()) == NULL)
168 return 1;
169 sound_init(ctx, 44100, 2);
171 xmp_load_module(ctx, argv[1]);
172 xmp_start_player(ctx, 44100, 0);
173 SDL_PauseAudio(0);
175 sleep(10); /* Do something important here */
177 SDL_PauseAudio(1);
179 xmp_end_player(ctx);
181 xmp_release_module(ctx);
182 xmp_free_context(ctx);
183 SDL_CloseAudio();
185 return 0;
186 }
187 SDL callbacks run in a separate thread, so don't forget to protect sec‐
189 tions that manipulate module data with SDL_LockAudio() and SDL_Unlock‐
190 Audio().
191
193 Version and player information
194 const char *xmp_version
195 A string containing the library version, such as "4.0.0".
196 const unsigned int xmp_vercode
198 The library version encoded in a integer value. Bits 23-16 contain
199 the major version number, bits 15-8 contain the minor version num‐
200 ber, and bits 7-0 contain the release number.
201 int xmp_syserrno()
203 [Added in libxmp 4.5] Use to retrieve errno if you received
204 -XMP_ERROR_SYSTEM from an xmp function call. Useful if either libxmp
205 or its client is statically linked to libc.
206 Returns: System errno.
208 const char *const *xmp_get_format_list()
210 Query the list of supported module formats.
211 Returns:
213 a NULL-terminated read-only array of strings containing the
215 names of all supported module formats.
216 Context creation
218 xmp_context xmp_create_context()
219 Create a new player context and return an opaque handle to be used
220 in subsequent accesses to this context.
221 Returns:
223 the player context handle.
225 void xmp_free_context(xmp_context c)
227 Destroy a player context previously created using
228 xmp_create_context().
229 Parameters:
231 c the player context handle.
233 Module loading
235 int xmp_test_module(char *path, struct xmp_test_info *test_info)
236 Test if a file is a valid module. Testing a file does not affect the
237 current player context or any currently loaded module.
238 Parameters:
240 path pathname of the module to test.
242 test_info
244 NULL, or a pointer to a structure used to retrieve the
245 module title and format if the file is a valid module.
246 struct xmp_test_info is defined as:
247 struct xmp_test_info {
249 char name[XMP_NAME_SIZE]; /* Module title */
250 char type[XMP_NAME_SIZE]; /* Module format */
251 };
252 Returns:
254 0 if the file is a valid module, or a negative error code in
256 case of error. Error codes can be -XMP_ERROR_FORMAT in case
257 of an unrecognized file format, -XMP_ERROR_DEPACK if the file
258 is compressed and uncompression failed, or -XMP_ERROR_SYSTEM
259 in case of system error (the system error code is set in er‐
260 rno).
261 int xmp_test_module_from_memory(const void *mem, long size, struct
263 xmp_test_info *test_info)
264 [Added in libxmp 4.5] Test if a memory buffer is a valid module.
265 Testing memory does not affect the current player context or any
266 currently loaded module.
267 Parameters:
269 mem a pointer to the module file image in memory.
271 Multi-file modules or compressed modules can't be
272 tested in memory.
273 size the size of the module.
275 test_info
277 NULL, or a pointer to a structure used to retrieve the
278 module title and format if the memory buffer is a
279 valid module. struct xmp_test_info is defined as:
280 struct xmp_test_info {
282 char name[XMP_NAME_SIZE]; /* Module title */
283 char type[XMP_NAME_SIZE]; /* Module format */
284 };
285 Returns:
287 0 if the memory buffer is a valid module, or a negative error
289 code in case of error. Error codes can be -XMP_ERROR_FORMAT
290 in case of an unrecognized file format or -XMP_ERROR_SYSTEM
291 in case of system error (the system error code is set in er‐
292 rno).
293 int xmp_test_module_from_file(FILE *f, struct xmp_test_info *test_info)
295 [Added in libxmp 4.5] Test if a module from a stream is a valid mod‐
296 ule. Testing streams does not affect the current player context or
297 any currently loaded module.
298 Parameters:
300 f the file stream. Compressed modules that need an ex‐
302 ternal depacker can't be tested from a file stream. On
303 return, the stream position is undefined. Caller is
304 responsible for closing the file stream.
305 test_info
307 NULL, or a pointer to a structure used to retrieve the
308 module title and format if the memory buffer is a
309 valid module. struct xmp_test_info is defined as:
310 struct xmp_test_info {
312 char name[XMP_NAME_SIZE]; /* Module title */
313 char type[XMP_NAME_SIZE]; /* Module format */
314 };
315 Returns:
317 0 if the stream is a valid module, or a negative error code
319 in case of error. Error codes can be -XMP_ERROR_FORMAT in
320 case of an unrecognized file format, -XMP_ERROR_DEPACK if the
321 stream is compressed and uncompression failed, or -XMP_ER‐
322 ROR_SYSTEM in case of system error (the system error code is
323 set in errno).
324 int xmp_test_module_from_callbacks(void *priv, struct xmp_callbacks call‐
326 backs, struct xmp_test_info *test_info)
327 [Added in libxmp 4.5] Test if a module from a custom stream is a
328 valid module. Testing custom streams does not affect the current
329 player context or any currently loaded module.
330 Parameters:
332 priv pointer to the custom stream. Multi-file modules or
334 compressed modules can't be tested using this func‐
335 tion. This should not be NULL.
336 callbacks
338 struct specifying stream callbacks for the custom
339 stream. These callbacks should behave as close to
340 fread/fseek/ftell/fclose as possible, and seek_func
341 must be capable of seeking to SEEK_END. The
342 close_func is optional, but all other functions must
343 be provided. If a close_func is provided, the stream
344 will be closed once testing has finished or upon re‐
345 turning an error code. struct xmp_callbacks is de‐
346 fined as:
347 struct xmp_callbacks {
349 unsigned long (*read_func)(void *dest, unsigned long len,
350 unsigned long nmemb, void *priv);
351 int (*seek_func)(void *priv, long offset, int whence);
352 long (*tell_func)(void *priv);
353 int (*close_func)(void *priv);
354 };
355 test_info
357 NULL, or a pointer to a structure used to retrieve the
358 module title and format if the memory buffer is a
359 valid module.
360 struct xmp_test_info is defined as:
362 struct xmp_test_info {
364 char name[XMP_NAME_SIZE]; /* Module title */
365 char type[XMP_NAME_SIZE]; /* Module format */
366 };
367 Returns:
369 0 if the custom stream is a valid module, or a negative error
371 code in case of error. Error codes can be -XMP_ERROR_FORMAT
372 in case of an unrecognized file format or -XMP_ERROR_SYSTEM
373 in case of system error (the system error code is set in er‐
374 rno).
375 int xmp_load_module(xmp_context c, char *path)
377 Load a module into the specified player context. (Certain player
378 flags, such as XMP_PLAYER_SMPCTL and XMP_PLAYER_DEFPAN, must be set
379 before loading the module, see xmp_set_player() for more informa‐
380 tion.)
381 Parameters:
383 c the player context handle.
385 path pathname of the module to load.
387 Returns:
389 0 if successful, or a negative error code in case of error.
391 Error codes can be -XMP_ERROR_FORMAT in case of an unrecog‐
392 nized file format, -XMP_ERROR_DEPACK if the file is com‐
393 pressed and uncompression failed, -XMP_ERROR_LOAD if the file
394 format was recognized but the file loading failed, or
395 -XMP_ERROR_SYSTEM in case of system error (the system error
396 code is set in errno).
397 int xmp_load_module_from_memory(xmp_context c, const void *mem, long size)
399 [Added in libxmp 4.2] Load a module from memory into the specified
400 player context.
401 Parameters:
403 c the player context handle.
405 mem a pointer to the module file image in memory.
407 Multi-file modules or compressed modules can't be
408 loaded from memory.
409 size the size of the module.
411 Returns:
413 0 if successful, or a negative error code in case of error.
415 Error codes can be -XMP_ERROR_FORMAT in case of an unrecog‐
416 nized file format, -XMP_ERROR_LOAD if the file format was
417 recognized but the file loading failed, or -XMP_ERROR_SYSTEM
418 in case of system error (the system error code is set in er‐
419 rno).
420 int xmp_load_module_from_file(xmp_context c, FILE *f, long size)
422 [Added in libxmp 4.3] Load a module from a stream into the specified
423 player context.
424 Parameters:
426 c the player context handle.
428 f the file stream. On return, the stream position is un‐
430 defined. Caller is responsible for closing the file
431 stream.
432 size the size of the module (ignored.)
434 Returns:
436 0 if successful, or a negative error code in case of error.
438 Error codes can be -XMP_ERROR_FORMAT in case of an unrecog‐
439 nized file format, -XMP_ERROR_LOAD if the file format was
440 recognized but the file loading failed, or -XMP_ERROR_SYSTEM
441 in case of system error (the system error code is set in er‐
442 rno).
443 int xmp_load_module_from_callbacks(xmp_context c, void *priv, struct
445 xmp_callbacks callbacks)
446 [Added in libxmp 4.5] Load a module from a custom stream into the
447 specified player context.
448 Parameters:
450 c the player context handle.
452 priv pointer to the custom stream. Multi-file modules or
454 compressed modules can't be loaded using this func‐
455 tion. This should not be NULL.
456 callbacks
458 struct specifying stream callbacks for the custom
459 stream. These callbacks should behave as close to
460 fread/fseek/ftell/fclose as possible, and seek_func
461 must be capable of seeking to SEEK_END. The
462 close_func is optional, but all other functions must
463 be provided. If a close_func is provided, the stream
464 will be closed once loading has finished or upon re‐
465 turning an error code. struct xmp_callbacks is de‐
466 fined as:
467 struct xmp_callbacks {
469 unsigned long (*read_func)(void *dest, unsigned long len,
470 unsigned long nmemb, void *priv);
471 int (*seek_func)(void *priv, long offset, int whence);
472 long (*tell_func)(void *priv);
473 int (*close_func)(void *priv);
474 };
475 Returns:
477 0 if successful, or a negative error code in case of error.
479 Error codes can be -XMP_ERROR_FORMAT in case of an unrecog‐
480 nized file format, -XMP_ERROR_LOAD if the file format was
481 recognized but the file loading failed, or -XMP_ERROR_SYSTEM
482 in case of system error (the system error code is set in er‐
483 rno).
484 void xmp_release_module(xmp_context c)
486 Release memory allocated by a module from the specified player con‐
487 text.
488 Parameters:
490 c the player context handle.
492 void xmp_scan_module(xmp_context c)
494 Scan the loaded module for sequences and timing. Scanning is auto‐
495 matically performed by xmp_load_module() and this function should be
496 called only if xmp_set_player() is used to change player timing
497 (with parameter XMP_PLAYER_VBLANK) in libxmp 4.0.2 or older.
498 Parameters:
500 c the player context handle.
502 void xmp_get_module_info(xmp_context c, struct xmp_module_info *info)
504 Retrieve current module data.
505 Parameters:
507 c the player context handle.
509 info pointer to structure containing the module data.
511 struct xmp_module_info is defined as follows:
512 struct xmp_module_info {
514 unsigned char md5[16]; /* MD5 message digest */
515 int vol_base; /* Volume scale */
516 struct xmp_module *mod; /* Pointer to module data */
517 char *comment; /* Comment text, if any */
518 int num_sequences; /* Number of valid sequences */
519 struct xmp_sequence *seq_data; /* Pointer to sequence data */
520 };
521 Detailed module data is exposed in the mod field:
523 struct xmp_module {
525 char name[XMP_NAME_SIZE]; /* Module title */
526 char type[XMP_NAME_SIZE]; /* Module format */
527 int pat; /* Number of patterns */
528 int trk; /* Number of tracks */
529 int chn; /* Tracks per pattern */
530 int ins; /* Number of instruments */
531 int smp; /* Number of samples */
532 int spd; /* Initial speed */
533 int bpm; /* Initial BPM */
534 int len; /* Module length in patterns */
535 int rst; /* Restart position */
536 int gvl; /* Global volume */
537 struct xmp_pattern **xxp; /* Patterns */
539 struct xmp_track **xxt; /* Tracks */
540 struct xmp_instrument *xxi; /* Instruments */
541 struct xmp_sample *xxs; /* Samples */
542 struct xmp_channel xxc[64]; /* Channel info */
543 unsigned char xxo[XMP_MAX_MOD_LENGTH]; /* Orders */
544 };
545 See the header file for more information about pattern
547 and instrument data.
548 Module playing
550 int xmp_start_player(xmp_context c, int rate, int format)
551 Start playing the currently loaded module.
552 Parameters:
554 c the player context handle.
556 rate the sampling rate to use, in Hz (typically 44100).
558 Valid values range from 8kHz to 48kHz.
559 flags bitmapped configurable player flags, one or more of
561 the following:
562 XMP_FORMAT_8BIT /* Mix to 8-bit instead of 16 */
564 XMP_FORMAT_UNSIGNED /* Mix to unsigned samples */
565 XMP_FORMAT_MONO /* Mix to mono instead of stereo */
566 Returns:
568 0 if successful, or a negative error code in case of error.
570 Error codes can be -XMP_ERROR_INTERNAL in case of a internal
571 player error, -XMP_ERROR_INVALID if the sampling rate is in‐
572 valid, or -XMP_ERROR_SYSTEM in case of system error (the sys‐
573 tem error code is set in errno).
574 int xmp_play_frame(xmp_context c)
576 Play one frame of the module. Modules usually play at 50 frames per
577 second. Use xmp_get_frame_info() to retrieve the buffer containing
578 audio data.
579 Parameters:
581 c the player context handle.
583 Returns:
585 0 if successful, -XMP_END if the module ended or was stopped,
587 or -XMP_ERROR_STATE if the player is not in playing state.
588 int xmp_play_buffer(xmp_context c, void *buffer, int size, int loop)
590 [Added in libxmp 4.1] Fill the buffer with PCM data up to the speci‐
591 fied size. This is a convenience function that calls
592 xmp_play_frame() internally to fill the user-supplied buffer. Don't
593 call both xmp_play_frame() and xmp_play_buffer() in the same replay
594 loop. If you don't need equally sized data chunks, xmp_play_frame()
595 may result in better performance. Also note that silence is added at
596 the end of a buffer if the module ends and no loop is to be per‐
597 formed.
598 Parameters:
600 c the player context handle.
602 buffer the buffer to fill with PCM data, or NULL to reset the
604 internal state.
605 size the buffer size in bytes.
607 loop stop replay when the loop counter reaches the speci‐
609 fied value, or 0 to disable loop checking.
610 Returns:
612 0 if successful, -XMP_END if module was stopped or the loop
614 counter was reached, or -XMP_ERROR_STATE if the player is not
615 in playing state.
616 void xmp_get_frame_info(xmp_context c, struct xmp_frame_info *info)
618 Retrieve the current frame data.
619 Parameters:
621 c the player context handle.
623 info pointer to structure containing current frame data.
625 struct xmp_frame_info is defined as follows:
626 struct xmp_frame_info { /* Current frame information */
628 int pos; /* Current position */
629 int pattern; /* Current pattern */
630 int row; /* Current row in pattern */
631 int num_rows; /* Number of rows in current pattern */
632 int frame; /* Current frame */
633 int speed; /* Current replay speed */
634 int bpm; /* Current bpm */
635 int time; /* Current module time in ms */
636 int total_time; /* Estimated replay time in ms*/
637 int frame_time; /* Frame replay time in us */
638 void *buffer; /* Pointer to sound buffer */
639 int buffer_size; /* Used buffer size */
640 int total_size; /* Total buffer size */
641 int volume; /* Current master volume */
642 int loop_count; /* Loop counter */
643 int virt_channels; /* Number of virtual channels */
644 int virt_used; /* Used virtual channels */
645 int sequence; /* Current sequence */
646 struct xmp_channel_info { /* Current channel information */
648 unsigned int period; /* Sample period */
649 unsigned int position; /* Sample position */
650 short pitchbend; /* Linear bend from base note*/
651 unsigned char note; /* Current base note number */
652 unsigned char instrument; /* Current instrument number */
653 unsigned char sample; /* Current sample number */
654 unsigned char volume; /* Current volume */
655 unsigned char pan; /* Current stereo pan */
656 unsigned char reserved; /* Reserved */
657 struct xmp_event event; /* Current track event */
658 } channel_info[XMP_MAX_CHANNELS];
659 };
660 This function should be used to retrieve sound buffer
662 data after xmp_play_frame() is called. Fields buffer
663 and buffer_size contain the pointer to the sound buf‐
664 fer PCM data and its size. The buffer size will be no
665 larger than XMP_MAX_FRAMESIZE.
666 void xmp_end_player(xmp_context c)
668 End module replay and release player memory.
669 Parameters:
671 c the player context handle.
673 Player control
675 int xmp_next_position(xmp_context c)
676 Skip replay to the start of the next position.
677 Parameters:
679 c the player context handle.
681 Returns:
683 The new position index, or -XMP_ERROR_STATE if the player is
685 not in playing state.
686 int xmp_prev_position(xmp_context c)
688 Skip replay to the start of the previous position.
689 Parameters:
691 c the player context handle.
693 Returns:
695 The new position index, or -XMP_ERROR_STATE if the player is
697 not in playing state.
698 int xmp_set_position(xmp_context c, int pos)
700 Skip replay to the start of the given position.
701 Parameters:
703 c the player context handle.
705 pos the position index to set.
707 Returns:
709 The new position index, -XMP_ERROR_INVALID of the new posi‐
711 tion is invalid or -XMP_ERROR_STATE if the player is not in
712 playing state.
713 int xmp_set_row(xmp_context c, int row)
715 [Added in libxmp 4.5] Skip replay to the given row.
716 Parameters:
718 c the player context handle.
720 row the row to set.
722 Returns:
724 The new row, -XMP_ERROR_INVALID if the new row is invalid or
726 -XMP_ERROR_STATE if the player is not in playing state.
727 int xmp_set_tempo_factor(xmp_context c, double val)
729 [Added in libxmp 4.5] Modify the replay tempo multiplier.
730 Parameters:
732 c the player context handle.
734 val the new multiplier.
736 Returns:
738 0 on success, or -1 if value is invalid.
740 void xmp_stop_module(xmp_context c)
742 Stop the currently playing module.
743 Parameters:
745 c the player context handle.
747 void xmp_restart_module(xmp_context c)
749 Restart the currently playing module.
750 Parameters:
752 c the player context handle.
754 int xmp_seek_time(xmp_context c, int time)
756 Skip replay to the specified time.
757 Parameters:
759 c the player context handle.
761 time time to seek in milliseconds.
763 Returns:
765 The new position index, or -XMP_ERROR_STATE if the player is
767 not in playing state.
768 int xmp_channel_mute(xmp_context c, int chn, int status)
770 Mute or unmute the specified channel.
771 Parameters:
773 c the player context handle.
775 chn the channel to mute or unmute.
777 status 0 to mute channel, 1 to unmute or -1 to query the cur‐
779 rent channel status.
780 Returns:
782 The previous channel status, or -XMP_ERROR_STATE if the
784 player is not in playing state.
785 int xmp_channel_vol(xmp_context c, int chn, int vol)
787 Set or retrieve the volume of the specified channel.
788 Parameters:
790 c the player context handle.
792 chn the channel to set or get volume.
794 vol a value from 0-100 to set the channel volume, or -1 to
796 retrieve the current volume.
797 Returns:
799 The previous channel volume, or -XMP_ERROR_STATE if the
801 player is not in playing state.
802 void xmp_inject_event(xmp_context c, int chn, struct xmp_event *event)
804 Dynamically insert a new event into a playing module.
805 Parameters:
807 c the player context handle.
809 chn the channel to insert the new event.
811 event the event to insert. struct xmp_event is defined as:
813 struct xmp_event {
815 unsigned char note; /* Note number (0 means no note) */
816 unsigned char ins; /* Patch number */
817 unsigned char vol; /* Volume (0 to basevol) */
818 unsigned char fxt; /* Effect type */
819 unsigned char fxp; /* Effect parameter */
820 unsigned char f2t; /* Secondary effect type */
821 unsigned char f2p; /* Secondary effect parameter */
822 unsigned char _flag; /* Internal (reserved) flags */
823 };
824 Player parameter setting
826 int xmp_set_instrument_path(xmp_context c, char *path)
827 Set the path to retrieve external instruments or samples. Used by
828 some formats (such as MED2) to read sample files from a different
829 directory in the filesystem.
830 Parameters:
832 c the player context handle.
834 path the path to retrieve instrument files.
836 Returns:
838 0 if the instrument path was correctly set, or -XMP_ER‐
840 ROR_SYSTEM in case of error (the system error code is set in
841 errno).
842 int xmp_get_player(xmp_context c, int param)
844 Retrieve current value of the specified player parameter.
845 Parameters:
847 c the player context handle.
849 param player parameter to get. Valid parameters are:
851 XMP_PLAYER_AMP /* Amplification factor */
853 XMP_PLAYER_MIX /* Stereo mixing */
854 XMP_PLAYER_INTERP /* Interpolation type */
855 XMP_PLAYER_DSP /* DSP effect flags */
856 XMP_PLAYER_FLAGS /* Player flags */
857 XMP_PLAYER_CFLAGS /* Player flags for current module*/
858 XMP_PLAYER_SMPCTL /* Control sample loading */
859 XMP_PLAYER_VOLUME /* Player master volume */
860 XMP_PLAYER_STATE /* Current player state (read only) */
861 XMP_PLAYER_SMIX_VOLUME /* SMIX Volume */
862 XMP_PLAYER_DEFPAN /* Default pan separation */
863 XMP_PLAYER_MODE /* Player personality */
864 XMP_PLAYER_MIXER_TYPE /* Current mixer (read only) */
865 XMP_PLAYER_VOICES /* Maximum number of mixer voices */
866 Valid states are:
868 XMP_STATE_UNLOADED /* Context created */
870 XMP_STATE_LOADED /* Module loaded */
871 XMP_STATE_PLAYING /* Module playing */
872 Valid mixer types are:
874 XMP_MIXER_STANDARD /* Standard mixer */
876 XMP_MIXER_A500 /* Amiga 500 */
877 XMP_MIXER_A500F /* Amiga 500 with led filter */
878 See xmp_set_player for the rest of valid values for
880 each parameter.
881 Returns:
883 The parameter value, or -XMP_ERROR_STATE if the parameter is
885 not XMP_PLAYER_STATE and the player is not in playing state.
886 int xmp_set_player(xmp_context c, int param, int val)
888 Set player parameter with the specified value.
889 Parameters:
891 param player parameter to set. Valid parameters are:
893 XMP_PLAYER_AMP /* Amplification factor */
895 XMP_PLAYER_MIX /* Stereo mixing */
896 XMP_PLAYER_INTERP /* Interpolation type */
897 XMP_PLAYER_DSP /* DSP effect flags */
898 XMP_PLAYER_FLAGS /* Player flags */
899 XMP_PLAYER_CFLAGS /* Player flags for current module*/
900 XMP_PLAYER_SMPCTL /* Control sample loading */
901 XMP_PLAYER_VOLUME /* Player master volume */
902 XMP_PLAYER_SMIX_VOLUME /* SMIX Volume */
903 XMP_PLAYER_DEFPAN /* Default pan separation */
904 XMP_PLAYER_MODE /* Player personality */
905 XMP_PLAYER_VOICES /* Maximum number of mixer voices */
906 val the value to set. Valid values depend on the parameter
908 being set.
909 Valid values:
911 • Amplification factor: ranges from 0 to 3. Default value is
913 1.
914 • Stereo mixing: percentual left/right channel separation.
916 Default is 70.
917 • Interpolation type: can be one of the following values:
919 XMP_INTERP_NEAREST /* Nearest neighbor */
921 XMP_INTERP_LINEAR /* Linear (default) */
922 XMP_INTERP_SPLINE /* Cubic spline */
923 • DSP effects flags: enable or disable DSP effects. Valid ef‐
925 fects are:
926 XMP_DSP_LOWPASS /* Lowpass filter effect */
928 XMP_DSP_ALL /* All effects */
929 • Player flags: tweakable player parameters. Valid flags are:
931 XMP_FLAGS_VBLANK /* Use vblank timing */
933 XMP_FLAGS_FX9BUG /* Emulate Protracker 2.x FX9 bug */
934 XMP_FLAGS_FIXLOOP /* Make sample loop value / 2 */
935 XMP_FLAGS_A500 /* Use Paula mixer in Amiga modules */
936 • [Added in libxmp 4.1] Player flags for current module: same
938 flags as above but after applying module-specific quirks
939 (if any).
940 • [Added in libxmp 4.1] Sample control: Valid values are:
942 XMP_SMPCTL_SKIP /* Don't load samples */
944 • Disabling sample loading when loading a module allows al‐
946 lows computation of module duration without decompressing
947 and loading large sample data, and is useful when duration
948 information is needed for a module that won't be played im‐
949 mediately.
950 • [Added in libxmp 4.2] Player volumes: Set the player master
952 volume or the external sample mixer master volume. Valid
953 values are 0 to 100.
954 • [Added in libxmp 4.3] Default pan separation: percentual
956 left/right pan separation in formats with only left and
957 right channels. Default is 100%.
958 • [Added in libxmp 4.4] Player personality: The player can be
960 forced to emulate a specific tracker in cases where the module
961 relies on a format quirk and tracker detection fails. Valid
962 modes are:
963 XMP_MODE_AUTO /* Autodetect mode (default) */
965 XMP_MODE_MOD /* Play as a generic MOD player */
966 XMP_MODE_NOISETRACKER /* Play using Noisetracker quirks */
967 XMP_MODE_PROTRACKER /* Play using Protracker 1/2 quirks */
968 XMP_MODE_S3M /* Play as a generic S3M player */
969 XMP_MODE_ST3 /* Play using ST3 bug emulation */
970 XMP_MODE_ST3GUS /* Play using ST3+GUS quirks */
971 XMP_MODE_XM /* Play as a generic XM player */
972 XMP_MODE_FT2 /* Play using FT2 bug emulation */
973 XMP_MODE_IT /* Play using IT quirks */
974 XMP_MODE_ITSMP /* Play using IT sample mode quirks */
975 By default, formats similar to S3M such as PTM or IMF will use
977 S3M replayer (without Scream Tracker 3 quirks/bug emulation),
978 and formats similar to XM such as RTM and MDL will use the XM
979 replayer (without FT2 quirks/bug emulation).
980 Multichannel MOD files will use the XM replayer, and Scream
982 Tracker 3 MOD files will use S3M replayer with ST3 quirks. S3M
983 files will use the most appropriate replayer according to the
984 tracker used to create the file, and enable Scream Tracker 3
985 quirks and bugs only if created using ST3. XM files will be
986 played with FT2 bugs and quirks only if created using Fast
987 Tracker II.
988 Modules created with OpenMPT will be played with all bugs and
990 quirks of the original trackers.
991 • [Added in libxmp 4.4] Maximum number of mixer voices: the max‐
993 imum number of virtual channels that can be used to play the
994 module. If set too high, modules with voice leaks can cause
995 excessive CPU usage. Default is 128.
996 Returns:
998 0 if parameter was correctly set, -XMP_ERROR_INVALID if pa‐
1000 rameter or values are out of the valid ranges, or -XMP_ER‐
1001 ROR_STATE if the player is not in playing state.
1002
1004 Libxmp 4.2 includes a mini-API that can be used to add sound effects to
1005 games and similar applications, provided that you have a low latency
1006 sound system. It allows module instruments or external sample files in
1007 WAV format to be played in response to arbitrary events.
1008 Example
1010 This example using SDL loads a module and a sound sample, plays the
1011 module as background music, and plays the sample when a key is pressed:
1012 #include <SDL/SDL.h>
1014 #include <xmp.h>
1015 static void fill_audio(void *udata, unsigned char *stream, int len)
1017 {
1018 xmp_play_buffer(udata, stream, len, 0);
1019 }
1020 int sound_init(xmp_context ctx, int sampling_rate, int channels)
1022 {
1023 SDL_AudioSpec a;
1024 a.freq = sampling_rate;
1026 a.format = (AUDIO_S16);
1027 a.channels = channels;
1028 a.samples = 2048;
1029 a.callback = fill_audio;
1030 a.userdata = ctx;
1031 if (SDL_OpenAudio(&a, NULL) < 0) {
1033 fprintf(stderr, "%s\n", SDL_GetError());
1034 return -1;
1035 }
1036 }
1037 int video_init()
1039 {
1040 if (SDL_Init(SDL_INIT_VIDEO) < 0) {
1041 fprintf(stderr, "%s\n", SDL_GetError());
1042 return -1;
1043 }
1044 if (SDL_SetVideoMode(640, 480, 8, 0) == NULL) {
1045 fprintf(stderr, "%s\n", SDL_GetError());
1046 return -1;
1047 }
1048 atexit(SDL_Quit);
1049 }
1050 int main(int argc, char **argv)
1052 {
1053 SDL_Event event;
1054 xmp_context ctx;
1055 if ((ctx = xmp_create_context()) == NULL)
1057 return 1;
1058 video_init();
1060 sound_init(ctx, 44100, 2);
1061 xmp_start_smix(ctx, 1, 1);
1063 xmp_smix_load_sample(ctx, 0, "blip.wav");
1064 xmp_load_module(ctx, "music.mod");
1066 xmp_start_player(ctx, 44100, 0);
1067 xmp_set_player(ctx, XMP_PLAYER_VOLUME, 40);
1068 SDL_PauseAudio(0);
1070 while (1) {
1072 if (SDL_WaitEvent(&event)) {
1073 if (event.type == SDL_KEYDOWN) {
1074 if (event.key.keysym.sym == SDLK_ESCAPE)
1075 break;
1076 xmp_smix_play_sample(ctx, 0, 60, 64, 0);
1077 }
1078 }
1079 }
1080 SDL_PauseAudio(1);
1082 xmp_end_player(ctx);
1084 xmp_release_module(ctx);
1085 xmp_end_smix(ctx);
1086 xmp_free_context(ctx);
1087 SDL_CloseAudio();
1089 return 0;
1090 }
1091 SMIX API reference
1093 int xmp_start_smix(xmp_context c, int nch, int nsmp)
1094 Initialize the external sample mixer subsystem with the given number
1095 of reserved channels and samples.
1096 Parameters:
1098 c the player context handle.
1100 nch number of reserved sound mixer channels (1 to 64).
1102 nsmp number of external samples.
1104 Returns:
1106 0 if the external sample mixer system was correctly initial‐
1108 ized, -XMP_ERROR_INVALID in case of invalid parameters,
1109 -XMP_ERROR_STATE if the player is already in playing state,
1110 or -XMP_ERROR_SYSTEM in case of system error (the system er‐
1111 ror code is set in errno).
1112 int xmp_smix_play_instrument(xmp_context c, int ins, int note, int vol, int
1114 chn)
1115 Play a note using an instrument from the currently loaded module in
1116 one of the reserved sound mixer channels.
1117 Parameters:
1119 c the player context handle.
1121 ins the instrument to play.
1123 note the note number to play (60 = middle C).
1125 vol the volume to use (range: 0 to the maximum volume
1127 value used by the current module).
1128 chn the reserved channel to use to play the instrument.
1130 Returns:
1132 0 if the instrument was correctly played, -XMP_ERROR_INVALID
1134 in case of invalid parameters, or -XMP_ERROR_STATE if the
1135 player is not in playing state.
1136 int xmp_smix_play_sample(xmp_context c, int ins, int vol, int chn)
1138 Play an external sample file in one of the reserved sound channels.
1139 The sample must have been previously loaded using
1140 xmp_smix_load_sample().
1141 Parameters:
1143 c the player context handle.
1145 ins the sample to play.
1147 vol the volume to use (0 to the maximum volume value used
1149 by the current module.
1150 chn the reserved channel to use to play the sample.
1152 Returns:
1154 0 if the sample was correctly played, -XMP_ERROR_INVALID in
1156 case of invalid parameters, or -XMP_ERROR_STATE if the player
1157 is not in playing state.
1158 int xmp_smix_channel_pan(xmp_context c, int chn, int pan)
1160 Set the reserved channel pan value.
1161 Parameters:
1163 c the player context handle.
1165 chn the reserved channel number.
1167 pan the pan value to set (0 to 255).
1169 Returns:
1171 0 if the pan value was set, or -XMP_ERROR_INVALID if parame‐
1173 ters are invalid.
1174 int xmp_smix_load_sample(xmp_context c, int num, char *path)
1176 Load a sound sample from a file. Samples should be in mono WAV
1177 (RIFF) format.
1178 Parameters:
1180 c the player context handle.
1182 num the slot number of the external sample to load.
1184 path pathname of the file to load.
1186 Returns:
1188 0 if the sample was correctly loaded, -XMP_ERROR_INVALID if
1190 the sample slot number is invalid (not reserved using
1191 xmp_start_smix()), -XMP_ERROR_FORMAT if the file format is
1192 unsupported, or -XMP_ERROR_SYSTEM in case of system error
1193 (the system error code is set in errno).
1194 int xmp_smix_release_sample(xmp_context c, int num)
1196 Release memory allocated by an external sample in the specified
1197 player context.
1198 Parameters:
1200 c the player context handle.
1202 num the sample slot number to release.
1204 Returns:
1206 0 if memory was correctly released, or -XMP_ERROR_INVALID if
1208 the sample slot number is invalid.
1209 void xmp_end_smix(xmp_context c)
1211 Deinitialize and resease memory used by the external sample mixer
1212 subsystem.
1213 Parameters:
1215 c the player context handle.
1217
1219 Claudio Matsuoka and Hipolito Carraro Jr.
12204.5 Nov 2020 LIBXMP(3)