MAD API documentation collected from e-mails of Joe Drew and Rob Leslie. The original e-mails can be found in the docs directory. They contain the same information as is presented below. INDEX ====== 1. I/O Synchronous Mode 2. Low-level API 1. I/O SYNCHRONOUS MODE (extract from Joe Drew) =============================================== MAD operates with callbacks for functions. Each of these functions is expected to return type enum mad_flow; this allows you to control the decoding process. MAD always outputs 32-bit (well, mad_fixed_t) little-endian data. Take this into account when outputting samples to the sound card. Related to the above, since MAD outputs type mad_fixed_t, unless you can output with 32-bit accuracy (most sound cards can't), you will have to quantize, round, dither, etc these samples to 16-bit (or whatever you need.) While there is a sample routine in minimad.c, if you want good quality you'll either want to roll your own or take a look in madplay's sources. Integral to understanding MAD: MAD is a decoding library only. You handle input and output; you're responsible for fast-forwarding and rewinding, if you want that type of functionality. All that MAD will do is take input from you, decode the MPEG frames, give you some information about them, and give you the decoded PCM data. Now, the nitty-gritty information. First, you need a mad_decoder struct. This holds all information about how you want your stream decoded, such as input/output functions, error handling functions, etc. mad_decoder_init() sets this structure up for you. struct mad_decoder decoder; struct my_playbuf playbuf; mad_decoder_init(&decoder, &playbuf, input_func, header_func, /*filter*/ 0, output_func, /*error*/ 0, /* message */ 0); In this example, the function called to get more data is set to input_func, the function called after MPEG headers have been decoded is header_func, the function called after all sound data has been decoded to PCM (for output) is output_func, and the filter, error, and message functions are unset. Now, MAD runs in a constant decoding loop. It runs something along the following lines: if I'm out of data call input_func if input_func says there's no more data, quit decode the header and call header_func decode the mpeg audio data call the filter function call the output function loop Now, this is an oversimplification obviously. The important thing to realise is that at every step of the process you can tell MAD what to do. Since all of these functions return enum mad_flow, you can tell MAD to do any of the following: enum mad_flow { MAD_FLOW_CONTINUE = 0x0000, /* Keep decoding this stream */ MAD_FLOW_STOP = 0x0010, /* Stop decoding this stream, but exit normally */ MAD_FLOW_BREAK = 0x0011, /* Stop decoding this stream, and exit with an error */ MAD_FLOW_IGNORE = 0x0020 /* Don't decode this frame, but continue afterwards */ }; Most of the time you'll probably want to return MAD_FLOW_CONTINUE. In every case, you'll have to return one of these values from the functions you define. This is the definition of each of the functions: enum mad_flow (*input_func)(void *, struct mad_stream *); enum mad_flow (*header_func)(void *, struct mad_header const *); enum mad_flow (*filter_func)(void *, struct mad_stream const *, struct mad_frame *); enum mad_flow (*output_func)(void *, struct mad_header const *, struct mad_pcm *); enum mad_flow (*error_func)(void *, struct mad_stream *, struct mad_frame *); enum mad_flow (*message_func)(void *, void *, unsigned int *); In each of these functions the void* pointer passed to the function is your "playbuf" structure. This can hold whatever you want - for example, song title, length, number of frames - just remember to re-cast it to the type you've defined. input_func takes a mad_stream pointer. Most of the time what you'll want to do is something along the lines of the following: if (more_data_available) buffer = refill_buffer(); mad_stream_buffer(stream, buffer, length_of_buffer); return MAD_FLOW_CONTINUE; else return MAD_FLOW_STOP; (On many systems you'll want to use mmap() for this.) header_func takes a mad_header pointer. This contains most of the important information about a given frame; in constant bitrate files, it can contain most of the important information about the stream. It will give you the length of that frame, using mad_timer_t; the audio layer; extension; bitrate... the list is long. Read frame.h or mad.h in the frame.h area for more information. Again, return MAD_FLOW_{CONTINUE,STOP,BREAK} depending on outside conditions. The only other function I have firsthand information on is output_func; in this case, you are given a pointer to struct mad_pcm. This gives you the sampling rate, number of channels, and number of samples per channel; doing something like the following should work: mad_fixed_t *left_channel = pcm->samples[0], *right_channel = pcm->samples[1]; int nsamples = pcm->length; signed int sample; unsigned char * buffer = some_buffer; unsigned char * ptr = buffer; while (nsamples--) { sample = (signed int) do_downsample(*left_ch++) *ptr++ = (unsigned char) (sample >> 0); *ptr++ = (unsigned char) (sample >> 8); sample = (signed int) do_downsample(*right_ch++) *ptr++ = (unsigned char) (sample >> 0); *ptr++ = (unsigned char) (sample >> 8); } output buffer to device. Be sure to handle the big-endian case (autoconf can test for this), and also the mono (1 channel) case. See mad.c in mpg321, at the end of the file, for an example. Information on the other (error, filter, message) functions would be appreciated, though I think in knowing this information anyone should be able to puzzle it out. Now that the decoder is set up with all these callback functions, you call mad_decoder_run(&decoder, MAD_DECODER_MODE_SYNC); and then mad_decoder_finish(&decoder); Once you've called mad_decoder_finish, you can re-use the decoder struct, if you're, for example, within a playlist. Incidentally, all MAD structures have similar mad_(whatever)_init and mad_(whatever)_finish functions. I hope this helps people get their feet wet with MAD. Read the source, and particularly mad.h - there are a lot of things there you might not expect. Rob has done a good job in making MAD a complete solution. :) 2. LOW-LEVEL API (extract from Rob Leslie) ========================================== By way of clarification, MAD also has a low-level API which does not use callbacks. You can control the entire decoding process yourself more or less as follows: /* load buffer with your MPEG audio data */ mad_stream_buffer(&stream, buffer, buflen); while (1) { mad_frame_decode(&frame, &stream); mad_synth_frame(&synth, &frame); /* output PCM samples in synth.pcm */ } This is vastly simplified, but it shows the general idea. mad_frame_decode() decodes the next frame's header and subband samples. mad_synth_frame() takes those subband samples and synthesizes PCM samples. It is also possible to call mad_header_decode() before mad_frame_decode(). This just gives you the frame's header info, in case that's all you want, or perhaps to help you decide whether you want to decode the rest of the frame. As Joe mentions, each of the stream, frame, and synth structs needs to be initialized and "finished" before and after use: struct mad_stream stream; struct mad_frame frame; struct mad_synth synth; mad_stream_init(&stream); mad_frame_init(&frame); mad_synth_init(&synth); /* ... */ mad_synth_finish(&synth); mad_frame_finish(&frame); mad_stream_finish(&stream); You can work with just a struct mad_header instead of a struct mad_frame if you only want to decode frame headers. Joe writes: > MAD always outputs 32-bit (well, mad_fixed_t) little-endian data. Take > this into account when outputting samples to the sound card. This isn't quite right: the mad_fixed_t type is not necessarily little-endian. It's the same endianness as the native integer types. Also, it's only guaranteed to be *at least* 32 bits wide. The fixed-point sample format is important to understand, and I recommend reading the comments in libmad/fixed.h. The thing to remember when converting MAD's fixed-point integer samples to 16-bit PCM (or whatever) is that MAD encodes samples as numbers in the full-scale range [-1.0, +1.0) where the binary point is placed 28 (MAD_F_FRACBITS) bits to the left of the integer. However, you need to be prepared to handle clipping as some numbers may be less than -1.0 (-MAD_F_ONE) or greater than or equal to +1.0 (MAD_F_ONE, aka 1 << MAD_F_FRACBITS). > Information on the other (error, filter, message) functions would be > appreciated, though I think in knowing this information anyone should be > able to puzzle it out. In the high-level API, the error callback function is called whenever a decoding error occurs. The error number is in stream->error. The filter callback function is called after decoding a frame, but before synthesis. Here it is possible to modify the frame's subband samples, for example to perform a uniform attenuation/amplification, or to do other special processing in the frequency domain. The message callback function is only used with MAD_DECODER_MODE_ASYNC, and is called whenever the parent process sends a message via mad_decoder_message(). This callback can generate a reply by overwriting the message buffer that is passed to it. (The size of the reply must be the same or smaller than the message.)