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
10 obscure 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
103 retrieve the module name and type. Use xmp_load_module() to load the
104 module to memory. These two calls return 0 on success or <0 in case of
105 error. 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 char **xmp_get_format_list()
203 Query the list of supported module formats.
204 Returns:
206 a NULL-terminated array of strings containing the names of
207 all supported module formats.
208 Context creation
210 xmp_context xmp_create_context()
211 Create a new player context and return an opaque handle to be used
212 in subsequent accesses to this context.
213 Returns:
215 the player context handle.
216 void xmp_free_context(xmp_context c)
218 Destroy a player context previously created using
219 xmp_create_context().
220 Parameters:
222 c the player context handle.
224 Module loading
226 int xmp_test_module(char *path, struct xmp_test_info *test_info)
227 Test if a file is a valid module. Testing a file does not affect the
228 current player context or any currently loaded module.
229 Parameters:
231 path pathname of the module to test.
233 test_info
235 NULL, or a pointer to a structure used to retrieve the
236 module title and format if the file is a valid module.
237 struct xmp_test_info is defined as:
238 struct xmp_test_info {
240 char name[XMP_NAME_SIZE]; /* Module title */
241 char type[XMP_NAME_SIZE]; /* Module format */
242 };
243 Returns:
245 0 if the file is a valid module, or a negative error code in
246 case of error. Error codes can be -XMP_ERROR_FORMAT in case
247 of an unrecognized file format, -XMP_ERROR_DEPACK if the file
248 is compressed and uncompression failed, or -XMP_ERROR_SYSTEM
249 in case of system error (the system error code is set in
250 errno).
251 int xmp_load_module(xmp_context c, char *path)
253 Load a module into the specified player context. (Certain player
254 flags, such as XMP_PLAYER_SMPCTL and XMP_PLAYER_DEFPAN, must be set
255 before loading the module, see xmp_set_player() for more informa‐
256 tion.)
257 Parameters:
259 c the player context handle.
261 path pathname of the module to load.
263 Returns:
265 0 if sucessful, or a negative error code in case of error.
266 Error codes can be -XMP_ERROR_FORMAT in case of an unrecog‐
267 nized file format, -XMP_ERROR_DEPACK if the file is com‐
268 pressed and uncompression failed, -XMP_ERROR_LOAD if the file
269 format was recognized but the file loading failed, or
270 -XMP_ERROR_SYSTEM in case of system error (the system error
271 code is set in errno).
272 int xmp_load_module_from_memory(xmp_context c, void *mem, long size)
274 [Added in libxmp 4.2] Load a module from memory into the specified
275 player context.
276 Parameters:
278 c the player context handle.
280 mem a pointer to the module file image in memory.
282 Multi-file modules or compressed modules can't be
283 loaded from memory.
284 size the size of the module, or 0 if the size is unknown or
286 not specified. If size is set to 0 certain module for‐
287 mats won't be recognized, the MD5 digest will not be
288 set, and module-specific quirks won't be applied.
289 Returns:
291 0 if sucessful, or a negative error code in case of error.
292 Error codes can be -XMP_ERROR_FORMAT in case of an unrecog‐
293 nized file format, -XMP_ERROR_LOAD if the file format was
294 recognized but the file loading failed, or -XMP_ERROR_SYSTEM
295 in case of system error (the system error code is set in
296 errno).
297 int xmp_load_module_from_file(xmp_context c, FILE *f, long size)
299 [Added in libxmp 4.3] Load a module from a stream into the specified
300 player context.
301 Parameters:
303 c the player context handle.
305 f the file stream. On return, the stream position is
307 undefined.
308 size the size of the module, or 0 if the size is unknown or
310 not specified. If size is set to 0 certain module for‐
311 mats won't be recognized, the MD5 digest will not be
312 set, and module-specific quirks won't be applied.
313 Returns:
315 0 if sucessful, or a negative error code in case of error.
316 Error codes can be -XMP_ERROR_FORMAT in case of an unrecog‐
317 nized file format, -XMP_ERROR_LOAD if the file format was
318 recognized but the file loading failed, or -XMP_ERROR_SYSTEM
319 in case of system error (the system error code is set in
320 errno).
321 void xmp_release_module(xmp_context c)
323 Release memory allocated by a module from the specified player con‐
324 text.
325 Parameters:
327 c the player context handle.
329 void xmp_scan_module(xmp_context c)
331 Scan the loaded module for sequences and timing. Scanning is auto‐
332 matically performed by xmp_load_module() and this function should be
333 called only if xmp_set_player() is used to change player timing
334 (with parameter XMP_PLAYER_VBLANK) in libxmp 4.0.2 or older.
335 Parameters:
337 c the player context handle.
339 void xmp_get_module_info(xmp_context c, struct xmp_module_info *info)
341 Retrieve current module data.
342 Parameters:
344 c the player context handle.
346 info pointer to structure containing the module data.
348 struct xmp_module_info is defined as follows:
349 struct xmp_module_info {
351 unsigned char md5[16]; /* MD5 message digest */
352 int vol_base; /* Volume scale */
353 struct xmp_module *mod; /* Pointer to module data */
354 char *comment; /* Comment text, if any */
355 int num_sequences; /* Number of valid sequences */
356 struct xmp_sequence *seq_data; /* Pointer to sequence data */
357 };
358 Detailed module data is exposed in the mod field:
360 struct xmp_module {
362 char name[XMP_NAME_SIZE]; /* Module title */
363 char type[XMP_NAME_SIZE]; /* Module format */
364 int pat; /* Number of patterns */
365 int trk; /* Number of tracks */
366 int chn; /* Tracks per pattern */
367 int ins; /* Number of instruments */
368 int smp; /* Number of samples */
369 int spd; /* Initial speed */
370 int bpm; /* Initial BPM */
371 int len; /* Module length in patterns */
372 int rst; /* Restart position */
373 int gvl; /* Global volume */
374 struct xmp_pattern **xxp; /* Patterns */
376 struct xmp_track **xxt; /* Tracks */
377 struct xmp_instrument *xxi; /* Instruments */
378 struct xmp_sample *xxs; /* Samples */
379 struct xmp_channel xxc[64]; /* Channel info */
380 unsigned char xxo[XMP_MAX_MOD_LENGTH]; /* Orders */
381 };
382 See the header file for more information about pattern
384 and instrument data.
385 Module playing
387 int xmp_start_player(xmp_context c, int rate, int format)
388 Start playing the currently loaded module.
389 Parameters:
391 c the player context handle.
393 rate the sampling rate to use, in Hz (typically 44100).
395 Valid values range from 8kHz to 48kHz.
396 flags bitmapped configurable player flags, one or more of
398 the following:
399 XMP_FORMAT_8BIT /* Mix to 8-bit instead of 16 */
401 XMP_FORMAT_UNSIGNED /* Mix to unsigned samples */
402 XMP_FORMAT_MONO /* Mix to mono instead of stereo */
403 Returns:
405 0 if sucessful, or a negative error code in case of error.
406 Error codes can be -XMP_ERROR_INTERNAL in case of a internal
407 player error, -XMP_ERROR_INVALID if the sampling rate is
408 invalid, or -XMP_ERROR_SYSTEM in case of system error (the
409 system error code is set in errno).
410 int xmp_play_frame(xmp_context c)
412 Play one frame of the module. Modules usually play at 50 frames per
413 second. Use xmp_get_frame_info() to retrieve the buffer containing
414 audio data.
415 Parameters:
417 c the player context handle.
419 Returns:
421 0 if sucessful, -XMP_END if the module ended or was stopped,
422 or -XMP_ERROR_STATE if the player is not in playing state.
423 int xmp_play_buffer(xmp_context c, void *buffer, int size, int loop)
425 [Added in libxmp 4.1] Fill the buffer with PCM data up to the speci‐
426 fied size. This is a convenience function that calls
427 xmp_play_frame() internally to fill the user-supplied buffer. Don't
428 call both xmp_play_frame() and xmp_play_buffer() in the same replay
429 loop. If you don't need equally sized data chunks, xmp_play_frame()
430 may result in better performance. Also note that silence is added at
431 the end of a buffer if the module ends and no loop is to be per‐
432 formed.
433 Parameters:
435 c the player context handle.
437 buffer the buffer to fill with PCM data, or NULL to reset the
439 internal state.
440 size the buffer size in bytes.
442 loop stop replay when the loop counter reaches the speci‐
444 fied value, or 0 to disable loop checking.
445 Returns:
447 0 if sucessful, -XMP_END if module was stopped or the loop
448 counter was reached, or -XMP_ERROR_STATE if the player is not
449 in playing state.
450 void xmp_get_frame_info(xmp_context c, struct xmp_frame_info *info)
452 Retrieve the current frame data.
453 Parameters:
455 c the player context handle.
457 info pointer to structure containing current frame data.
459 struct xmp_frame_info is defined as follows:
460 struct xmp_frame_info { /* Current frame information */
462 int pos; /* Current position */
463 int pattern; /* Current pattern */
464 int row; /* Current row in pattern */
465 int num_rows; /* Number of rows in current pattern */
466 int frame; /* Current frame */
467 int speed; /* Current replay speed */
468 int bpm; /* Current bpm */
469 int time; /* Current module time in ms */
470 int total_time; /* Estimated replay time in ms*/
471 int frame_time; /* Frame replay time in us */
472 void *buffer; /* Pointer to sound buffer */
473 int buffer_size; /* Used buffer size */
474 int total_size; /* Total buffer size */
475 int volume; /* Current master volume */
476 int loop_count; /* Loop counter */
477 int virt_channels; /* Number of virtual channels */
478 int virt_used; /* Used virtual channels */
479 int sequence; /* Current sequence */
480 struct xmp_channel_info { /* Current channel information */
482 unsigned int period; /* Sample period */
483 unsigned int position; /* Sample position */
484 short pitchbend; /* Linear bend from base note*/
485 unsigned char note; /* Current base note number */
486 unsigned char instrument; /* Current instrument number */
487 unsigned char sample; /* Current sample number */
488 unsigned char volume; /* Current volume */
489 unsigned char pan; /* Current stereo pan */
490 unsigned char reserved; /* Reserved */
491 struct xmp_event event; /* Current track event */
492 } channel_info[XMP_MAX_CHANNELS];
493 };
494 This function should be used to retrieve sound buffer
496 data after xmp_play_frame() is called. Fields buffer
497 and buffer_size contain the pointer to the sound buf‐
498 fer PCM data and its size. The buffer size will be no
499 larger than XMP_MAX_FRAMESIZE.
500 void xmp_end_player(xmp_context c)
502 End module replay and release player memory.
503 Parameters:
505 c the player context handle.
507 Player control
509 int xmp_next_position(xmp_context c)
510 Skip replay to the start of the next position.
511 Parameters:
513 c the player context handle.
515 Returns:
517 The new position index, or -XMP_ERROR_STATE if the player is
518 not in playing state.
519 int xmp_prev_position(xmp_context c)
521 Skip replay to the start of the previous position.
522 Parameters:
524 c the player context handle.
526 Returns:
528 The new position index, or -XMP_ERROR_STATE if the player is
529 not in playing state.
530 int xmp_set_position(xmp_context c, int pos)
532 Skip replay to the start of the given position.
533 Parameters:
535 c the player context handle.
537 pos the position index to set.
539 Returns:
541 The new position index, -XMP_ERROR_INVALID of the new posi‐
542 tion is invalid or -XMP_ERROR_STATE if the player is not in
543 playing state.
544 void xmp_stop_module(xmp_context c)
546 Stop the currently playing module.
547 Parameters:
549 c the player context handle.
551 void xmp_restart_module(xmp_context c)
553 Restart the currently playing module.
554 Parameters:
556 c the player context handle.
558 int xmp_seek_time(xmp_context c, int time)
560 Skip replay to the specified time.
561 Parameters:
563 c the player context handle.
565 time time to seek in milliseconds.
567 Returns:
569 The new position index, or -XMP_ERROR_STATE if the player is
570 not in playing state.
571 int xmp_channel_mute(xmp_context c, int chn, int status)
573 Mute or unmute the specified channel.
574 Parameters:
576 c the player context handle.
578 chn the channel to mute or unmute.
580 status 0 to mute channel, 1 to unmute or -1 to query the cur‐
582 rent channel status.
583 Returns:
585 The previous channel status, or -XMP_ERROR_STATE if the
586 player is not in playing state.
587 int xmp_channel_vol(xmp_context c, int chn, int vol)
589 Set or retrieve the volume of the specified channel.
590 Parameters:
592 c the player context handle.
594 chn the channel to set or get volume.
596 vol a value from 0-100 to set the channel volume, or -1 to
598 retrieve the current volume.
599 Returns:
601 The previous channel volume, or -XMP_ERROR_STATE if the
602 player is not in playing state.
603 void xmp_inject_event(xmp_context c, int chn, struct xmp_event *event)
605 Dynamically insert a new event into a playing module.
606 Parameters:
608 c the player context handle.
610 chn the channel to insert the new event.
612 event the event to insert. struct xmp_event is defined as:
614 struct xmp_event {
616 unsigned char note; /* Note number (0 means no note) */
617 unsigned char ins; /* Patch number */
618 unsigned char vol; /* Volume (0 to basevol) */
619 unsigned char fxt; /* Effect type */
620 unsigned char fxp; /* Effect parameter */
621 unsigned char f2t; /* Secondary effect type */
622 unsigned char f2p; /* Secondary effect parameter */
623 unsigned char _flag; /* Internal (reserved) flags */
624 };
625 Player parameter setting
627 int xmp_set_instrument_path(xmp_context c, char *path)
628 Set the path to retrieve external instruments or samples. Used by
629 some formats (such as MED2) to read sample files from a different
630 directory in the filesystem.
631 Parameters:
633 c the player context handle.
635 path the path to retrieve instrument files.
637 Returns:
639 0 if the instrument path was correctly set, or
640 -XMP_ERROR_SYSTEM in case of error (the system error code is
641 set in errno).
642 int xmp_get_player(xmp_context c, int param)
644 Retrieve current value of the specified player parameter.
645 Parameters:
647 c the player context handle.
649 param player parameter to get. Valid parameters are:
651 XMP_PLAYER_AMP /* Amplification factor */
653 XMP_PLAYER_MIX /* Stereo mixing */
654 XMP_PLAYER_INTERP /* Interpolation type */
655 XMP_PLAYER_DSP /* DSP effect flags */
656 XMP_PLAYER_FLAGS /* Player flags */
657 XMP_PLAYER_CFLAGS /* Player flags for current module*/
658 XMP_PLAYER_SMPCTL /* Control sample loading */
659 XMP_PLAYER_VOLUME /* Player master volume */
660 XMP_PLAYER_STATE /* Current player state (read only) */
661 XMP_PLAYER_SMIX_VOLUME /* SMIX Volume */
662 XMP_PLAYER_DEFPAN /* Default pan separation */
663 XMP_PLAYER_MODE /* Player personality */
664 XMP_PLAYER_MIXER_TYPE /* Current mixer (read only) */
665 XMP_PLAYER_VOICES /* Maximum number of mixer voices */
666 Valid states are:
668 XMP_STATE_UNLOADED /* Context created */
670 XMP_STATE_LOADED /* Module loaded */
671 XMP_STATE_PLAYING /* Module playing */
672 Valid mixer types are:
674 XMP_MIXER_STANDARD /* Standard mixer */
676 XMP_MIXER_A500 /* Amiga 500 */
677 XMP_MIXER_A500F /* Amiga 500 with led filter */
678 See xmp_set_player for the rest of valid values for
680 each parameter.
681 Returns:
683 The parameter value, or -XMP_ERROR_STATE if the parameter is
684 not XMP_PLAYER_STATE and the player is not in playing state.
685 int xmp_set_player(xmp_context c, int param, int val)
687 Set player parameter with the specified value.
688 Parameters:
690 param player parameter to set. Valid parameters are:
692 XMP_PLAYER_AMP /* Amplification factor */
694 XMP_PLAYER_MIX /* Stereo mixing */
695 XMP_PLAYER_INTERP /* Interpolation type */
696 XMP_PLAYER_DSP /* DSP effect flags */
697 XMP_PLAYER_FLAGS /* Player flags */
698 XMP_PLAYER_CFLAGS /* Player flags for current module*/
699 XMP_PLAYER_SMPCTL /* Control sample loading */
700 XMP_PLAYER_VOLUME /* Player master volume */
701 XMP_PLAYER_SMIX_VOLUME /* SMIX Volume */
702 XMP_PLAYER_DEFPAN /* Default pan separation */
703 XMP_PLAYER_MODE /* Player personality */
704 XMP_PLAYER_VOICES /* Maximum number of mixer voices */
705 val the value to set. Valid values depend on the parameter
707 being set.
708 Valid values:
710 · Amplification factor: ranges from 0 to 3. Default value is
712 1.
713 · Stereo mixing: percentual left/right channel separation.
715 Default is 70.
716 · Interpolation type: can be one of the following values:
718 XMP_INTERP_NEAREST /* Nearest neighbor */
720 XMP_INTERP_LINEAR /* Linear (default) */
721 XMP_INTERP_SPLINE /* Cubic spline */
722 · DSP effects flags: enable or disable DSP effects. Valid
724 effects are:
725 XMP_DSP_LOWPASS /* Lowpass filter effect */
727 XMP_DSP_ALL /* All effects */
728 · Player flags: tweakable player parameters. Valid flags are:
730 XMP_FLAGS_VBLANK /* Use vblank timing */
732 XMP_FLAGS_FX9BUG /* Emulate Protracker 2.x FX9 bug */
733 XMP_FLAGS_FIXLOOP /* Make sample loop value / 2 */
734 XMP_FLAGS_A500 /* Use Paula mixer in Amiga modules */
735 · [Added in libxmp 4.1] Player flags for current module: same
737 flags as above but after applying module-specific quirks
738 (if any).
739 · [Added in libxmp 4.1] Sample control: Valid values are:
741 XMP_SMPCTL_SKIP /* Don't load samples */
743 · Disabling sample loading when loading a module allows
745 allows computation of module duration without decompressing
746 and loading large sample data, and is useful when duration
747 information is needed for a module that won't be played
748 immediately.
749 · [Added in libxmp 4.2] Player volumes: Set the player master
751 volume or the external sample mixer master volume. Valid
752 values are 0 to 100.
753 · [Added in libxmp 4.3] Default pan separation: percentual
755 left/right pan separation in formats with only left and
756 right channels. Default is 100%.
757 · [Added in libxmp 4.4] Player personality: The player can be
759 forced to emulate a specific tracker in cases where the module
760 relies on a format quirk and tracker detection fails. Valid
761 modes are:
762 XMP_MODE_AUTO /* Autodetect mode (default) */
764 XMP_MODE_MOD /* Play as a generic MOD player */
765 XMP_MODE_NOISETRACKER /* Play using Noisetracker quirks */
766 XMP_MODE_PROTRACKER /* Play using Protracker 1/2 quirks */
767 XMP_MODE_S3M /* Play as a generic S3M player */
768 XMP_MODE_ST3 /* Play using ST3 bug emulation */
769 XMP_MODE_ST3GUS /* Play using ST3+GUS quirks */
770 XMP_MODE_XM /* Play as a generic XM player */
771 XMP_MODE_FT2 /* Play using FT2 bug emulation */
772 XMP_MODE_IT /* Play using IT quirks */
773 XMP_MODE_ITSMP /* Play using IT sample mode quirks */
774 By default, formats similar to S3M such as PTM or IMF will use
776 S3M replayer (without Scream Tracker 3 quirks/bug emulation),
777 and formats similar to XM such as RTM and MDL will use the XM
778 replayer (without FT2 quirks/bug emulation).
779 Multichannel MOD files will use the XM replayer, and Scream
781 Tracker 3 MOD files will use S3M replayer with ST3 quirks. S3M
782 files will use the most appropriate replayer according to the
783 tracker used to create the file, and enable Scream Tracker 3
784 quirks and bugs only if created using ST3. XM files will be
785 played with FT2 bugs and quirks only if created using Fast
786 Tracker II.
787 Modules created with OpenMPT will be played with all bugs and
789 quirks of the original trackers.
790 · [Added in libxmp 4.4] Maximum number of mixer voices: the max‐
792 imum number of virtual channels that can be used to play the
793 module. If set too high, modules with voice leaks can cause
794 excessive CPU usage. Default is 128.
795 Returns:
797 0 if parameter was correctly set, -XMP_ERROR_INVALID if
798 parameter or values are out of the valid ranges, or
799 -XMP_ERROR_STATE if the player is not in playing state.
800
802 Libxmp 4.2 includes a mini-API that can be used to add sound effects to
803 games and similar applications, provided that you have a low latency
804 sound system. It allows module instruments or external sample files in
805 WAV format to be played in response to arbitrary events.
806 Example
808 This example using SDL loads a module and a sound sample, plays the
809 module as background music, and plays the sample when a key is pressed:
810 #include <SDL/SDL.h>
812 #include <xmp.h>
813 static void fill_audio(void *udata, unsigned char *stream, int len)
815 {
816 xmp_play_buffer(udata, stream, len, 0);
817 }
818 int sound_init(xmp_context ctx, int sampling_rate, int channels)
820 {
821 SDL_AudioSpec a;
822 a.freq = sampling_rate;
824 a.format = (AUDIO_S16);
825 a.channels = channels;
826 a.samples = 2048;
827 a.callback = fill_audio;
828 a.userdata = ctx;
829 if (SDL_OpenAudio(&a, NULL) < 0) {
831 fprintf(stderr, "%s\n", SDL_GetError());
832 return -1;
833 }
834 }
835 int video_init()
837 {
838 if (SDL_Init(SDL_INIT_VIDEO) < 0) {
839 fprintf(stderr, "%s\n", SDL_GetError());
840 return -1;
841 }
842 if (SDL_SetVideoMode(640, 480, 8, 0) == NULL) {
843 fprintf(stderr, "%s\n", SDL_GetError());
844 return -1;
845 }
846 atexit(SDL_Quit);
847 }
848 int main(int argc, char **argv)
850 {
851 SDL_Event event;
852 xmp_context ctx;
853 if ((ctx = xmp_create_context()) == NULL)
855 return 1;
856 video_init();
858 sound_init(ctx, 44100, 2);
859 xmp_start_smix(ctx, 1, 1);
861 xmp_smix_load_sample(ctx, 0, "blip.wav");
862 xmp_load_module(ctx, "music.mod");
864 xmp_start_player(ctx, 44100, 0);
865 xmp_set_player(ctx, XMP_PLAYER_VOLUME, 40);
866 SDL_PauseAudio(0);
868 while (1) {
870 if (SDL_WaitEvent(&event)) {
871 if (event.type == SDL_KEYDOWN) {
872 if (event.key.keysym.sym == SDLK_ESCAPE)
873 break;
874 xmp_smix_play_sample(ctx, 0, 60, 64, 0);
875 }
876 }
877 }
878 SDL_PauseAudio(1);
880 xmp_end_player(ctx);
882 xmp_release_module(ctx);
883 xmp_free_context(ctx);
884 xmp_end_smix(ctx);
885 SDL_CloseAudio();
887 return 0;
888 }
889 SMIX API reference
891 int xmp_start_smix(xmp_context c, int nch, int nsmp)
892 Initialize the external sample mixer subsystem with the given number
893 of reserved channels and samples.
894 Parameters:
896 c the player context handle.
898 nch number of reserved sound mixer channels (1 to 64).
900 nsmp number of external samples.
902 Returns:
904 0 if the external sample mixer system was correctly initial‐
905 ized, -XMP_ERROR_INVALID in case of invalid parameters,
906 -XMP_ERROR_STATE if the player is already in playing state,
907 or -XMP_ERROR_SYSTEM in case of system error (the system
908 error code is set in errno).
909 int xmp_smix_play_instrument(xmp_context c, int ins, int note, int vol, int
911 chn)
912 Play a note using an instrument from the currently loaded module in
913 one of the reserved sound mixer channels.
914 Parameters:
916 c the player context handle.
918 ins the instrument to play.
920 note the note number to play (60 = middle C).
922 vol the volume to use (range: 0 to the maximum volume
924 value used by the current module).
925 chn the reserved channel to use to play the instrument.
927 Returns:
929 0 if the instrument was correctly played, -XMP_ERROR_INVALID
930 in case of invalid parameters, or -XMP_ERROR_STATE if the
931 player is not in playing state.
932 int xmp_smix_play_sample(xmp_context c, int ins, int vol, int chn)
934 Play an external sample file in one of the reserved sound channels.
935 The sample must have been previously loaded using
936 xmp_smix_load_sample().
937 Parameters:
939 c the player context handle.
941 ins the sample to play.
943 vol the volume to use (0 to the maximum volume value used
945 by the current module.
946 chn the reserved channel to use to play the sample.
948 Returns:
950 0 if the sample was correctly played, -XMP_ERROR_INVALID in
951 case of invalid parameters, or -XMP_ERROR_STATE if the player
952 is not in playing state.
953 int xmp_smix_channel_pan(xmp_context c, int chn, int pan)
955 Set the reserved channel pan value.
956 Parameters:
958 c the player context handle.
960 chn the reserved channel number.
962 pan the pan value to set (0 to 255).
964 Returns:
966 0 if the pan value was set, or -XMP_ERROR_INVALID if parame‐
967 ters are invalid.
968 int xmp_smix_load_sample(xmp_context c, int num, char *path)
970 Load a sound sample from a file. Samples should be in mono WAV
971 (RIFF) format.
972 Parameters:
974 c the player context handle.
976 num the slot number of the external sample to load.
978 path pathname of the file to load.
980 Returns:
982 0 if the sample was correctly loaded, -XMP_ERROR_INVALID if
983 the sample slot number is invalid (not reserved using
984 xmp_start_smix()), -XMP_ERROR_FORMAT if the file format is
985 unsupported, or -XMP_ERROR_SYSTEM in case of system error
986 (the system error code is set in errno).
987 int xmp_smix_release_sample(xmp_context c, int num)
989 Release memory allocated by an external sample in the specified
990 player context.
991 Parameters:
993 c the player context handle.
995 num the sample slot number to release.
997 Returns:
999 0 if memory was correctly released, or -XMP_ERROR_INVALID if
1000 the sample slot number is invalid.
1001 void xmp_end_smix(xmp_context c)
1003 Deinitialize and resease memory used by the external sample mixer
1004 subsystem.
1005 Parameters:
1007 c the player context handle.
1009
1011 Claudio Matsuoka and Hipolito Carraro Jr.
10124.2 Nov 2013 LIBXMP(3)