git.sesse.net Git - vlc/blob - doc/mad/API

   1 MAD API documentation collected from e-mails of Joe Drew and Rob Leslie.
   2 The original e-mails can be found in the docs directory. They contain the
   3 same information as is presented below.
   4
   5 INDEX
   6 ======
   7 1. I/O Synchronous Mode
   8 2. Low-level API
   9
  10
  11
  12 1. I/O SYNCHRONOUS MODE (extract from Joe Drew)
  13 ===============================================
  14 MAD operates with callbacks for functions. Each of these functions is
  15 expected to return type enum mad_flow; this allows you to control the
  16 decoding process.
  17
  18 MAD always outputs 32-bit (well, mad_fixed_t) little-endian data. Take
  19 this into account when outputting samples to the sound card.
  20 Related to the above, since MAD outputs type mad_fixed_t, unless you can
  21 output with 32-bit accuracy (most sound cards can't), you will have to
  22 quantize, round, dither, etc these samples to 16-bit (or whatever you
  23 need.) While there is a sample routine in minimad.c, if you want good
  24 quality you'll either want to roll your own or take a look in madplay's
  25 sources.
  26
  27 Integral to understanding MAD: MAD is a decoding library only. You
  28 handle input and output; you're responsible for fast-forwarding and
  29 rewinding, if you want that type of functionality. All that MAD will do
  30 is take input from you, decode the MPEG frames, give you some
  31 information about them, and give you the decoded PCM data.
  32
  33 Now, the nitty-gritty information.
  34
  35 First, you need a mad_decoder struct. This holds all information about
  36 how you want your stream decoded, such as input/output functions, error
  37 handling functions, etc.
  38
  39 mad_decoder_init() sets this structure up for you.
  40
  41 struct mad_decoder decoder;
  42 struct my_playbuf playbuf;
  43
  44 mad_decoder_init(&decoder, &playbuf, input_func, header_func, /*filter*/
  45 0, output_func, /*error*/ 0, /* message */ 0);
  46
  47 In this example, the function called to get more data is set to
  48 input_func, the function called after MPEG headers have been decoded is
  49 header_func, the function called after all sound data has been decoded
  50 to PCM (for output) is output_func, and the filter, error, and message
  51 functions are unset.
  52
  53 Now, MAD runs in a constant decoding loop. It runs something along the
  54 following lines:
  55
  56 if I'm out of data
  57         call input_func
  58 if input_func says there's no more data,
  59         quit
  60 decode the header and call header_func
  61 decode the mpeg audio data
  62 call the filter function
  63 call the output function
  64 loop
  65
  66 Now, this is an oversimplification obviously. The important thing to
  67 realise is that at every step of the process you can tell MAD what to
  68 do.
  69
  70 Since all of these functions return enum mad_flow, you can tell MAD to
  71 do any of the following:
  72
  73 enum mad_flow {
  74   MAD_FLOW_CONTINUE = 0x0000, /* Keep decoding this stream */
  75   MAD_FLOW_STOP     = 0x0010, /* Stop decoding this stream, but exit
  76                                  normally */
  77   MAD_FLOW_BREAK    = 0x0011, /* Stop decoding this stream, and exit
  78                                  with an error */
  79   MAD_FLOW_IGNORE   = 0x0020  /* Don't decode this frame,
  80                                  but continue afterwards */
  81 };
  82
  83 Most of the time you'll probably want to return MAD_FLOW_CONTINUE. In
  84 every case, you'll have to return one of these values from the functions
  85 you define.
  86
  87 This is the definition of each of the functions:
  88
  89 enum mad_flow (*input_func)(void *, struct mad_stream *);
  90 enum mad_flow (*header_func)(void *, struct mad_header const *);
  91 enum mad_flow (*filter_func)(void *, struct mad_stream const *, struct
  92 mad_frame *);
  93 enum mad_flow (*output_func)(void *, struct mad_header const *, struct
  94 mad_pcm *);
  95 enum mad_flow (*error_func)(void *, struct mad_stream *, struct
  96 mad_frame *);
  97 enum mad_flow (*message_func)(void *, void *, unsigned int *);
  98
  99 In each of these functions the void* pointer passed to the function is
 100 your "playbuf" structure. This can hold whatever you want - for example,
 101 song title, length, number of frames - just remember to re-cast it to
 102 the type you've defined.
 103
 104 input_func takes a mad_stream pointer. Most of the time what you'll want
 105 to do is something along the lines of the following:
 106
 107 if (more_data_available)
 108   buffer = refill_buffer();
 109   mad_stream_buffer(stream, buffer, length_of_buffer);
 110   return MAD_FLOW_CONTINUE;
 111 else
 112   return MAD_FLOW_STOP;
 113
 114 (On many systems you'll want to use mmap() for this.)
 115
 116 header_func takes a mad_header pointer. This contains most of the
 117 important information about a given frame; in constant bitrate files, it
 118 can contain most of the important information about the stream. It will
 119 give you the length of that frame, using mad_timer_t; the audio layer;
 120 extension; bitrate... the list is long. Read frame.h or mad.h in the
 121 frame.h area for more information.
 122 Again, return MAD_FLOW_{CONTINUE,STOP,BREAK} depending on outside
 123 conditions.
 124
 125 The only other function I have firsthand information on is output_func;
 126 in this case, you are given a pointer to struct mad_pcm. This gives you
 127 the sampling rate, number of channels, and number of samples per
 128 channel; doing something like the following should work:
 129
 130 mad_fixed_t *left_channel = pcm->samples[0], *right_channel =
 131 pcm->samples[1];
 132 int nsamples = pcm->length;
 133 signed int sample;
 134 unsigned char * buffer = some_buffer;
 135 unsigned char * ptr = buffer;
 136
 137 while (nsamples--)
 138 {
 139             sample = (signed int) do_downsample(*left_ch++)
 140
 141             *ptr++ = (unsigned char) (sample >> 0);
 142             *ptr++ = (unsigned char) (sample >> 8);
 143
 144             sample = (signed int) do_downsample(*right_ch++)
 145
 146             *ptr++ = (unsigned char) (sample >> 0);
 147             *ptr++ = (unsigned char) (sample >> 8);
 148 }
 149
 150 output buffer to device.
 151
 152 Be sure to handle the big-endian case (autoconf can test for this), and
 153 also the mono (1 channel) case. See mad.c in mpg321, at the end of the
 154 file, for an example.
 155
 156 Information on the other (error, filter, message) functions would be
 157 appreciated, though I think in knowing this information anyone should be
 158 able to puzzle it out.
 159
 160 Now that the decoder is set up with all these callback functions, you
 161 call
 162
 163 mad_decoder_run(&decoder, MAD_DECODER_MODE_SYNC);
 164
 165 and then
 166
 167 mad_decoder_finish(&decoder);
 168
 169 Once you've called mad_decoder_finish, you can re-use the decoder
 170 struct, if you're, for example, within a playlist. Incidentally, all MAD
 171 structures have similar mad_(whatever)_init and mad_(whatever)_finish
 172 functions.
 173
 174 I hope this helps people get their feet wet with MAD. Read the source,
 175 and particularly mad.h - there are a lot of things there you might not
 176 expect. Rob has done a good job in making MAD a complete solution. :)
 177
 178
 179 2. LOW-LEVEL API (extract from Rob Leslie)
 180 ==========================================
 181
 182 By way of clarification, MAD also has a low-level API which does not use
 183 callbacks. You can control the entire decoding process yourself more or less
 184 as follows:
 185
 186   /* load buffer with your MPEG audio data */
 187
 188   mad_stream_buffer(&stream, buffer, buflen);
 189
 190   while (1) {
 191     mad_frame_decode(&frame, &stream);
 192     mad_synth_frame(&synth, &frame);
 193
 194     /* output PCM samples in synth.pcm */
 195   }
 196
 197 This is vastly simplified, but it shows the general idea. mad_frame_decode()
 198 decodes the next frame's header and subband samples. mad_synth_frame() takes
 199 those subband samples and synthesizes PCM samples.
 200
 201 It is also possible to call mad_header_decode() before mad_frame_decode().
 202 This just gives you the frame's header info, in case that's all you want, or
 203 perhaps to help you decide whether you want to decode the rest of the frame.
 204
 205 As Joe mentions, each of the stream, frame, and synth structs needs to be
 206 initialized and "finished" before and after use:
 207
 208   struct mad_stream stream;
 209   struct mad_frame frame;
 210   struct mad_synth synth;
 211
 212   mad_stream_init(&stream);
 213   mad_frame_init(&frame);
 214   mad_synth_init(&synth);
 215
 216   /* ... */
 217
 218   mad_synth_finish(&synth);
 219   mad_frame_finish(&frame);
 220   mad_stream_finish(&stream);
 221
 222 You can work with just a struct mad_header instead of a struct mad_frame if
 223 you only want to decode frame headers.
 224
 225 Joe writes:
 226 > MAD always outputs 32-bit (well, mad_fixed_t) little-endian data. Take
 227 > this into account when outputting samples to the sound card.
 228
 229 This isn't quite right: the mad_fixed_t type is not necessarily little-endian.
 230 It's the same endianness as the native integer types. Also, it's only
 231 guaranteed to be *at least* 32 bits wide.
 232
 233 The fixed-point sample format is important to understand, and I recommend
 234 reading the comments in libmad/fixed.h. The thing to remember when converting
 235 MAD's fixed-point integer samples to 16-bit PCM (or whatever) is that MAD
 236 encodes samples as numbers in the full-scale range [-1.0, +1.0) where the
 237 binary point is placed 28 (MAD_F_FRACBITS) bits to the left of the integer.
 238 However, you need to be prepared to handle clipping as some numbers may be
 239 less than -1.0 (-MAD_F_ONE) or greater than or equal to +1.0 (MAD_F_ONE, aka
 240 1 << MAD_F_FRACBITS).
 241
 242 > Information on the other (error, filter, message) functions would be
 243 > appreciated, though I think in knowing this information anyone should be
 244 > able to puzzle it out.
 245
 246 In the high-level API, the error callback function is called whenever a
 247 decoding error occurs. The error number is in stream->error.
 248
 249 The filter callback function is called after decoding a frame, but before
 250 synthesis. Here it is possible to modify the frame's subband samples, for
 251 example to perform a uniform attenuation/amplification, or to do other special
 252 processing in the frequency domain.
 253
 254 The message callback function is only used with MAD_DECODER_MODE_ASYNC, and is
 255 called whenever the parent process sends a message via mad_decoder_message().
 256 This callback can generate a reply by overwriting the message buffer that is
 257 passed to it. (The size of the reply must be the same or smaller than the
 258 message.)
 259
 260
 261
 262