| LIBXMP(3) | Extended Module Player | LIBXMP(3) |
libxmp - A tracker module player library
Libxmp is a module player library supporting many mainstream and obscure module formats including Protracker MOD, Scream Tracker III S3M and Impulse Tracker IT. Libxmp loads the module and renders the sound as linear PCM samples in a buffer at rate and format specified by the user, one frame at a time (standard modules usually play at 50 frames per second).
Possible applications for libxmp include stand-alone module players, module player plugins for other players, module information extractors, background music replayers for games and other applications, module-to-mp3 renderers, etc.
This example loads a module, plays it at 44.1kHz and writes it to a raw sound file:
#include <stdio.h>
#include <stdlib.h>
#include <xmp.h>
int main(int argc, char **argv)
{
xmp_context c;
struct xmp_frame_info mi;
FILE *f;
/* The output raw file */
f = fopen("out.raw", "wb");
if (f == NULL) {
fprintf(stderr, "can't open output file\n");
exit(EXIT_FAILURE);
}
/* Create the player context */
c = xmp_create_context();
/* Load our module */
if (xmp_load_module(c, argv[1]) != 0) {
fprintf(stderr, "can't load module\n");
exit(EXIT_FAILURE);
}
/* Play the module */
xmp_start_player(c, 44100, 0);
while (xmp_play_frame(c) == 0) {
xmp_get_frame_info(c, &mi);
if (mi.loop_count > 0) /* exit before looping */
break;
fwrite(mi.buffer, mi.buffer_size, 1, f); /* write audio data */
}
xmp_end_player(c);
xmp_release_module(c); /* unload module */
xmp_free_context(c); /* destroy the player context */
fclose(f);
exit(EXIT_SUCCESS);
}
A player context can load and play a single module at a time. Multiple contexts can be defined if needed.
Use xmp_test_module() to check if the file is a valid module and retrieve the module name and type. Use xmp_load_module() to load the module to memory. These two calls return 0 on success or <0 in case of error. Error codes are:
-XMP_ERROR_INTERNAL /* Internal error */ -XMP_ERROR_FORMAT /* Unsupported module format */ -XMP_ERROR_LOAD /* Error loading file */ -XMP_ERROR_DEPACK /* Error depacking file */ -XMP_ERROR_SYSTEM /* System error */ -XMP_ERROR_STATE /* Incorrect player state */
If a system error occurs, the specific error is set in errno.
Parameters to xmp_start_player() are the sampling rate (up to 48kHz) and a bitmapped integer holding one or more of the following mixer flags:
XMP_MIX_8BIT /* Mix to 8-bit instead of 16 */ XMP_MIX_UNSIGNED /* Mix to unsigned samples */ XMP_MIX_MONO /* Mix to mono instead of stereo */ XMP_MIX_NEAREST /* Mix using nearest neighbor interpolation */ XMP_MIX_NOFILTER /* Disable lowpass filter */
After xmp_start_player() is called, each call to xmp_play_frame() will render an audio frame. Call xmp_get_frame_info() to retrieve the buffer address and size. xmp_play_frame() returns 0 on success or -1 if replay should stop.
Use xmp_end_player(), xmp_release_module() and xmp_free_context() to release memory and end replay.
To use libxmp with SDL, just provide a callback function that renders module data. The module will play when SDL_PauseAudio(0) is called:
#include <SDL/SDL.h>
#include <xmp.h>
static void fill_audio(void *udata, unsigned char *stream, int len)
{
xmp_play_buffer(udata, stream, len, 0);
}
int sound_init(xmp_context ctx, int sampling_rate, int channels)
{
SDL_AudioSpec a;
a.freq = sampling_rate;
a.format = (AUDIO_S16);
a.channels = channels;
a.samples = 2048;
a.callback = fill_audio;
a.userdata = ctx;
if (SDL_OpenAudio(&a, NULL) < 0) {
fprintf(stderr, "%s\n", SDL_GetError());
return -1;
}
}
int main(int argc, char **argv)
{
xmp_context ctx;
if ((ctx = xmp_create_context()) == NULL)
return 1;
sound_init(ctx, 44100, 2);
xmp_load_module(ctx, argv[1]);
xmp_start_player(ctx, 44100, 0);
SDL_PauseAudio(0);
sleep(10); /* Do something important here */
SDL_PauseAudio(1);
xmp_end_player(ctx);
xmp_release_module(ctx);
xmp_free_context(ctx);
SDL_CloseAudio();
return 0;
}
SDL callbacks run in a separate thread, so don't forget to protect sections that manipulate module data with SDL_LockAudio() and SDL_UnlockAudio().
Returns: System errno.
struct xmp_test_info {
char name[XMP_NAME_SIZE]; /* Module title */
char type[XMP_NAME_SIZE]; /* Module format */
};
struct xmp_test_info {
char name[XMP_NAME_SIZE]; /* Module title */
char type[XMP_NAME_SIZE]; /* Module format */
};
struct xmp_test_info {
char name[XMP_NAME_SIZE]; /* Module title */
char type[XMP_NAME_SIZE]; /* Module format */
};
struct xmp_callbacks {
unsigned long (*read_func)(void *dest, unsigned long len,
unsigned long nmemb, void *priv);
int (*seek_func)(void *priv, long offset, int whence);
long (*tell_func)(void *priv);
int (*close_func)(void *priv);
};
struct xmp_test_info is defined as:
struct xmp_test_info {
char name[XMP_NAME_SIZE]; /* Module title */
char type[XMP_NAME_SIZE]; /* Module format */
};
struct xmp_callbacks {
unsigned long (*read_func)(void *dest, unsigned long len,
unsigned long nmemb, void *priv);
int (*seek_func)(void *priv, long offset, int whence);
long (*tell_func)(void *priv);
int (*close_func)(void *priv);
};
struct xmp_module_info {
unsigned char md5[16]; /* MD5 message digest */
int vol_base; /* Volume scale */
struct xmp_module *mod; /* Pointer to module data */
char *comment; /* Comment text, if any */
int num_sequences; /* Number of valid sequences */
struct xmp_sequence *seq_data; /* Pointer to sequence data */
};
Detailed module data is exposed in the mod field:
struct xmp_module {
char name[XMP_NAME_SIZE]; /* Module title */
char type[XMP_NAME_SIZE]; /* Module format */
int pat; /* Number of patterns */
int trk; /* Number of tracks */
int chn; /* Tracks per pattern */
int ins; /* Number of instruments */
int smp; /* Number of samples */
int spd; /* Initial speed */
int bpm; /* Initial BPM */
int len; /* Module length in patterns */
int rst; /* Restart position */
int gvl; /* Global volume */
struct xmp_pattern **xxp; /* Patterns */
struct xmp_track **xxt; /* Tracks */
struct xmp_instrument *xxi; /* Instruments */
struct xmp_sample *xxs; /* Samples */
struct xmp_channel xxc[64]; /* Channel info */
unsigned char xxo[XMP_MAX_MOD_LENGTH]; /* Orders */
};
See the header file for more information about pattern and instrument data.
XMP_FORMAT_8BIT /* Mix to 8-bit instead of 16 */ XMP_FORMAT_UNSIGNED /* Mix to unsigned samples */ XMP_FORMAT_MONO /* Mix to mono instead of stereo */
struct xmp_frame_info { /* Current frame information */
int pos; /* Current position */
int pattern; /* Current pattern */
int row; /* Current row in pattern */
int num_rows; /* Number of rows in current pattern */
int frame; /* Current frame */
int speed; /* Current replay speed */
int bpm; /* Current bpm */
int time; /* Current module time in ms */
int total_time; /* Estimated replay time in ms*/
int frame_time; /* Frame replay time in us */
void *buffer; /* Pointer to sound buffer */
int buffer_size; /* Used buffer size */
int total_size; /* Total buffer size */
int volume; /* Current master volume */
int loop_count; /* Loop counter */
int virt_channels; /* Number of virtual channels */
int virt_used; /* Used virtual channels */
int sequence; /* Current sequence */
struct xmp_channel_info { /* Current channel information */
unsigned int period; /* Sample period */
unsigned int position; /* Sample position */
short pitchbend; /* Linear bend from base note*/
unsigned char note; /* Current base note number */
unsigned char instrument; /* Current instrument number */
unsigned char sample; /* Current sample number */
unsigned char volume; /* Current volume */
unsigned char pan; /* Current stereo pan */
unsigned char reserved; /* Reserved */
struct xmp_event event; /* Current track event */
} channel_info[XMP_MAX_CHANNELS];
};
This function should be used to retrieve sound buffer data after xmp_play_frame() is called. Fields buffer and buffer_size contain the pointer to the sound buffer PCM data and its size. The buffer size will be no larger than XMP_MAX_FRAMESIZE.
struct xmp_event {
unsigned char note; /* Note number (0 means no note) */
unsigned char ins; /* Patch number */
unsigned char vol; /* Volume (0 to basevol) */
unsigned char fxt; /* Effect type */
unsigned char fxp; /* Effect parameter */
unsigned char f2t; /* Secondary effect type */
unsigned char f2p; /* Secondary effect parameter */
unsigned char _flag; /* Internal (reserved) flags */
};
XMP_PLAYER_AMP /* Amplification factor */ XMP_PLAYER_MIX /* Stereo mixing */ XMP_PLAYER_INTERP /* Interpolation type */ XMP_PLAYER_DSP /* DSP effect flags */ XMP_PLAYER_FLAGS /* Player flags */ XMP_PLAYER_CFLAGS /* Player flags for current module*/ XMP_PLAYER_SMPCTL /* Control sample loading */ XMP_PLAYER_VOLUME /* Player master volume */ XMP_PLAYER_STATE /* Current player state (read only) */ XMP_PLAYER_SMIX_VOLUME /* SMIX Volume */ XMP_PLAYER_DEFPAN /* Default pan separation */ XMP_PLAYER_MODE /* Player personality */ XMP_PLAYER_MIXER_TYPE /* Current mixer (read only) */ XMP_PLAYER_VOICES /* Maximum number of mixer voices */
Valid states are:
XMP_STATE_UNLOADED /* Context created */ XMP_STATE_LOADED /* Module loaded */ XMP_STATE_PLAYING /* Module playing */
Valid mixer types are:
XMP_MIXER_STANDARD /* Standard mixer */ XMP_MIXER_A500 /* Amiga 500 */ XMP_MIXER_A500F /* Amiga 500 with led filter */
See xmp_set_player for the rest of valid values for each parameter.
XMP_PLAYER_AMP /* Amplification factor */ XMP_PLAYER_MIX /* Stereo mixing */ XMP_PLAYER_INTERP /* Interpolation type */ XMP_PLAYER_DSP /* DSP effect flags */ XMP_PLAYER_FLAGS /* Player flags */ XMP_PLAYER_CFLAGS /* Player flags for current module*/ XMP_PLAYER_SMPCTL /* Control sample loading */ XMP_PLAYER_VOLUME /* Player master volume */ XMP_PLAYER_SMIX_VOLUME /* SMIX Volume */ XMP_PLAYER_DEFPAN /* Default pan separation */ XMP_PLAYER_MODE /* Player personality */ XMP_PLAYER_VOICES /* Maximum number of mixer voices */
Valid values:
XMP_INTERP_NEAREST /* Nearest neighbor */ XMP_INTERP_LINEAR /* Linear (default) */ XMP_INTERP_SPLINE /* Cubic spline */
XMP_DSP_LOWPASS /* Lowpass filter effect */ XMP_DSP_ALL /* All effects */
XMP_FLAGS_VBLANK /* Use vblank timing */ XMP_FLAGS_FX9BUG /* Emulate Protracker 2.x FX9 bug */ XMP_FLAGS_FIXLOOP /* Make sample loop value / 2 */ XMP_FLAGS_A500 /* Use Paula mixer in Amiga modules */
XMP_SMPCTL_SKIP /* Don't load samples */
XMP_MODE_AUTO /* Autodetect mode (default) */ XMP_MODE_MOD /* Play as a generic MOD player */ XMP_MODE_NOISETRACKER /* Play using Noisetracker quirks */ XMP_MODE_PROTRACKER /* Play using Protracker 1/2 quirks */ XMP_MODE_S3M /* Play as a generic S3M player */ XMP_MODE_ST3 /* Play using ST3 bug emulation */ XMP_MODE_ST3GUS /* Play using ST3+GUS quirks */ XMP_MODE_XM /* Play as a generic XM player */ XMP_MODE_FT2 /* Play using FT2 bug emulation */ XMP_MODE_IT /* Play using IT quirks */ XMP_MODE_ITSMP /* Play using IT sample mode quirks */
By default, formats similar to S3M such as PTM or IMF will use S3M replayer (without Scream Tracker 3 quirks/bug emulation), and formats similar to XM such as RTM and MDL will use the XM replayer (without FT2 quirks/bug emulation).
Multichannel MOD files will use the XM replayer, and Scream Tracker 3 MOD files will use S3M replayer with ST3 quirks. S3M files will use the most appropriate replayer according to the tracker used to create the file, and enable Scream Tracker 3 quirks and bugs only if created using ST3. XM files will be played with FT2 bugs and quirks only if created using Fast Tracker II.
Modules created with OpenMPT will be played with all bugs and quirks of the original trackers.
Libxmp 4.2 includes a mini-API that can be used to add sound effects to games and similar applications, provided that you have a low latency sound system. It allows module instruments or external sample files in WAV format to be played in response to arbitrary events.
This example using SDL loads a module and a sound sample, plays the module as background music, and plays the sample when a key is pressed:
#include <SDL/SDL.h>
#include <xmp.h>
static void fill_audio(void *udata, unsigned char *stream, int len)
{
xmp_play_buffer(udata, stream, len, 0);
}
int sound_init(xmp_context ctx, int sampling_rate, int channels)
{
SDL_AudioSpec a;
a.freq = sampling_rate;
a.format = (AUDIO_S16);
a.channels = channels;
a.samples = 2048;
a.callback = fill_audio;
a.userdata = ctx;
if (SDL_OpenAudio(&a, NULL) < 0) {
fprintf(stderr, "%s\n", SDL_GetError());
return -1;
}
}
int video_init()
{
if (SDL_Init(SDL_INIT_VIDEO) < 0) {
fprintf(stderr, "%s\n", SDL_GetError());
return -1;
}
if (SDL_SetVideoMode(640, 480, 8, 0) == NULL) {
fprintf(stderr, "%s\n", SDL_GetError());
return -1;
}
atexit(SDL_Quit);
}
int main(int argc, char **argv)
{
SDL_Event event;
xmp_context ctx;
if ((ctx = xmp_create_context()) == NULL)
return 1;
video_init();
sound_init(ctx, 44100, 2);
xmp_start_smix(ctx, 1, 1);
xmp_smix_load_sample(ctx, 0, "blip.wav");
xmp_load_module(ctx, "music.mod");
xmp_start_player(ctx, 44100, 0);
xmp_set_player(ctx, XMP_PLAYER_VOLUME, 40);
SDL_PauseAudio(0);
while (1) {
if (SDL_WaitEvent(&event)) {
if (event.type == SDL_KEYDOWN) {
if (event.key.keysym.sym == SDLK_ESCAPE)
break;
xmp_smix_play_sample(ctx, 0, 60, 64, 0);
}
}
}
SDL_PauseAudio(1);
xmp_end_player(ctx);
xmp_release_module(ctx);
xmp_end_smix(ctx);
xmp_free_context(ctx);
SDL_CloseAudio();
return 0;
}
Claudio Matsuoka and Hipolito Carraro Jr.
| December 2024 | 4.6 |