doc/mad/joe_drew.txt

   1 Subject: [mad-dev] Some information about programming with MAD (in synchronous mode)
   2
   3 As the author of mpg321, I too faced the problem of MAD not being
   4 documented. However, in looking at minimad.c, and re-writing mpg321 to
   5 use MAD, I came to understand it better. Here's some information which
   6 will help anybody start out with MAD:
   7
   8 First, some basic information.
   9 MAD operates with callbacks for functions. Each of these functions is
  10 expected to return type enum mad_flow; this allows you to control the
  11 decoding process.
  12 MAD always outputs 32-bit (well, mad_fixed_t) little-endian data. Take
  13 this into account when outputting samples to the sound card.
  14 Related to the above, since MAD outputs type mad_fixed_t, unless you can
  15 output with 32-bit accuracy (most sound cards can't), you will have to
  16 quantize, round, dither, etc these samples to 16-bit (or whatever you
  17 need.) While there is a sample routine in minimad.c, if you want good
  18 quality you'll either want to roll your own or take a look in madplay's
  19 sources.
  20 Integral to understanding MAD: MAD is a decoding library only. You
  21 handle input and output; you're responsible for fast-forwarding and
  22 rewinding, if you want that type of functionality. All that MAD will do
  23 is take input from you, decode the MPEG frames, give you some
  24 information about them, and give you the decoded PCM data.
  25
  26 Now, the nitty-gritty information.
  27
  28 First, you need a mad_decoder struct. This holds all information about
  29 how you want your stream decoded, such as input/output functions, error
  30 handling functions, etc.
  31
  32 mad_decoder_init() sets this structure up for you.
  33
  34 struct mad_decoder decoder;
  35 struct my_playbuf playbuf;
  36
  37 mad_decoder_init(&decoder, &playbuf, input_func, header_func, /*filter*/
  38 0, output_func, /*error*/ 0, /* message */ 0);
  39
  40 In this example, the function called to get more data is set to
  41 input_func, the function called after MPEG headers have been decoded is
  42 header_func, the function called after all sound data has been decoded
  43 to PCM (for output) is output_func, and the filter, error, and message
  44 functions are unset.
  45
  46 Now, MAD runs in a constant decoding loop. It runs something along the
  47 following lines:
  48
  49 if I'm out of data
  50         call input_func
  51 if input_func says there's no more data,
  52         quit
  53 decode the header and call header_func
  54 decode the mpeg audio data
  55 call the filter function
  56 call the output function
  57 loop
  58
  59 Now, this is an oversimplification obviously. The important thing to
  60 realise is that at every step of the process you can tell MAD what to
  61 do.
  62
  63 Since all of these functions return enum mad_flow, you can tell MAD to
  64 do any of the following:
  65
  66 enum mad_flow {
  67   MAD_FLOW_CONTINUE = 0x0000, /* Keep decoding this stream */
  68   MAD_FLOW_STOP     = 0x0010, /* Stop decoding this stream, but exit
  69                                  normally */
  70   MAD_FLOW_BREAK    = 0x0011, /* Stop decoding this stream, and exit
  71                                  with an error */
  72   MAD_FLOW_IGNORE   = 0x0020  /* Don't decode this frame,
  73                                  but continue afterwards */
  74 };
  75
  76 Most of the time you'll probably want to return MAD_FLOW_CONTINUE. In
  77 every case, you'll have to return one of these values from the functions
  78 you define.
  79
  80 This is the definition of each of the functions:
  81
  82 enum mad_flow (*input_func)(void *, struct mad_stream *);
  83 enum mad_flow (*header_func)(void *, struct mad_header const *);
  84 enum mad_flow (*filter_func)(void *, struct mad_stream const *, struct
  85 mad_frame *);
  86 enum mad_flow (*output_func)(void *, struct mad_header const *, struct
  87 mad_pcm *);
  88 enum mad_flow (*error_func)(void *, struct mad_stream *, struct
  89 mad_frame *);
  90 enum mad_flow (*message_func)(void *, void *, unsigned int *);
  91
  92 In each of these functions the void* pointer passed to the function is
  93 your "playbuf" structure. This can hold whatever you want - for example,
  94 song title, length, number of frames - just remember to re-cast it to
  95 the type you've defined.
  96
  97 input_func takes a mad_stream pointer. Most of the time what you'll want
  98 to do is something along the lines of the following:
  99
 100 if (more_data_available)
 101   buffer = refill_buffer();
 102   mad_stream_buffer(stream, buffer, length_of_buffer);
 103   return MAD_FLOW_CONTINUE;
 104 else
 105   return MAD_FLOW_STOP;
 106
 107 (On many systems you'll want to use mmap() for this.)
 108
 109 header_func takes a mad_header pointer. This contains most of the
 110 important information about a given frame; in constant bitrate files, it
 111 can contain most of the important information about the stream. It will
 112 give you the length of that frame, using mad_timer_t; the audio layer;
 113 extension; bitrate... the list is long. Read frame.h or mad.h in the
 114 frame.h area for more information.
 115 Again, return MAD_FLOW_{CONTINUE,STOP,BREAK} depending on outside
 116 conditions.
 117
 118 The only other function I have firsthand information on is output_func;
 119 in this case, you are given a pointer to struct mad_pcm. This gives you
 120 the sampling rate, number of channels, and number of samples per
 121 channel; doing something like the following should work:
 122
 123 mad_fixed_t *left_channel = pcm->samples[0], *right_channel =
 124 pcm->samples[1];
 125 int nsamples = pcm->length;
 126 signed int sample;
 127 unsigned char * buffer = some_buffer;
 128 unsigned char * ptr = buffer;
 129
 130 while (nsamples--)
 131 {
 132             sample = (signed int) do_downsample(*left_ch++)
 133
 134             *ptr++ = (unsigned char) (sample >> 0);
 135             *ptr++ = (unsigned char) (sample >> 8);
 136
 137             sample = (signed int) do_downsample(*right_ch++)
 138
 139             *ptr++ = (unsigned char) (sample >> 0);
 140             *ptr++ = (unsigned char) (sample >> 8);
 141 }
 142
 143 output buffer to device.
 144
 145 Be sure to handle the big-endian case (autoconf can test for this), and
 146 also the mono (1 channel) case. See mad.c in mpg321, at the end of the
 147 file, for an example.
 148
 149 Information on the other (error, filter, message) functions would be
 150 appreciated, though I think in knowing this information anyone should be
 151 able to puzzle it out.
 152
 153 Now that the decoder is set up with all these callback functions, you
 154 call
 155
 156 mad_decoder_run(&decoder, MAD_DECODER_MODE_SYNC);
 157
 158 and then
 159
 160 mad_decoder_finish(&decoder);
 161
 162 Once you've called mad_decoder_finish, you can re-use the decoder
 163 struct, if you're, for example, within a playlist. Incidentally, all MAD
 164 structures have similar mad_(whatever)_init and mad_(whatever)_finish
 165 functions.
 166
 167 I hope this helps people get their feet wet with MAD. Read the source,
 168 and particularly mad.h - there are a lot of things there you might not
 169 expect. Rob has done a good job in making MAD a complete solution. :)
 170
 171 --
 172 Joe Drew <hoserhead@woot.net> <drew@debian.org>
 173
 174 Please encrypt email sent to me.