doc/mad/rob_leslie.txt

   1 From - Mon Nov  5 09:19:09 2001
   2 Return-Path: <mad-dev-admin@lists.mars.org>
   3 Received: from smtp01.wxs.nl ([195.121.5.15]) by po05.wxs.nl
   4           (Netscape Messaging Server 4.15) with ESMTP id GLLMFJ00.3DF for
   5           <jpsaman@wxs.nl>; Mon, 22 Oct 2001 10:33:19 +0200
   6 Received: from surveyor.mars.org ([216.98.134.66]) by
   7           smtp01.wxs.nl (Netscape Messaging Server 4.15) with ESMTP id
   8           GLLMFZ00.C2Z for <jpsaman@wxs.nl>; Mon, 22 Oct 2001 10:33:35 +0200
   9 Received: from surveyor.mars.org (localhost [127.0.0.1])
  10         by surveyor.mars.org (8.9.3/8.9.3/Debian 8.9.3-21) with ESMTP id BAA07654;
  11         Mon, 22 Oct 2001 01:32:07 -0700
  12 Received: from mars.org (localhost [127.0.0.1])
  13         by surveyor.mars.org (8.9.3/8.9.3/Debian 8.9.3-21) with ESMTP id BAA07629
  14         for <mad-dev@lists.mars.org>; Mon, 22 Oct 2001 01:31:30 -0700
  15 Message-Id: <200110220831.BAA07629@surveyor.mars.org>
  16 X-Authentication-Warning: surveyor.mars.org: Host localhost [127.0.0.1] claimed to be mars.org
  17 From: Rob Leslie <rob@mars.org>
  18 To: mad-dev@lists.mars.org
  19 Subject: Re: [mad-dev] Some information about programming with MAD (in synchronous mode)
  20 In-reply-to: Your message of "21 Oct 2001 16:13:19 EDT."
  21         <1003695199.24019.56.camel@pisces>
  22 Mime-Version: 1.0 (generated by tm-edit 7.106)
  23 Content-Type: text/plain; charset=US-ASCII
  24 Sender: mad-dev-admin@lists.mars.org
  25 Errors-To: mad-dev-admin@lists.mars.org
  26 X-BeenThere: mad-dev@lists.mars.org
  27 X-Mailman-Version: 2.0.1
  28 Precedence: bulk
  29 List-Help: <mailto:mad-dev-request@lists.mars.org?subject=help>
  30 List-Post: <mailto:mad-dev@lists.mars.org>
  31 List-Subscribe: <http://www.mars.org/bin/mailman/listinfo/mad-dev>,
  32         <mailto:mad-dev-request@lists.mars.org?subject=subscribe>
  33 List-Id: MAD developer's mailing list <mad-dev.lists.mars.org>
  34 List-Unsubscribe: <http://www.mars.org/bin/mailman/listinfo/mad-dev>,
  35         <mailto:mad-dev-request@lists.mars.org?subject=unsubscribe>
  36 List-Archive: <http://www.mars.org/mailman/public/mad-dev/>
  37 Date: Mon, 22 Oct 2001 01:31:30 -0700
  38 X-Mozilla-Status: 8011
  39 X-Mozilla-Status2: 00000000
  40 X-UIDL: 1879-1001307689
  41
  42 Joe Drew wrote some good info on the MAD high-level API that I hope will be
  43 helpful to others.
  44
  45 By way of clarification, MAD also has a low-level API which does not use
  46 callbacks. You can control the entire decoding process yourself more or less
  47 as follows:
  48
  49   /* load buffer with your MPEG audio data */
  50
  51   mad_stream_buffer(&stream, buffer, buflen);
  52
  53   while (1) {
  54     mad_frame_decode(&frame, &stream);
  55     mad_synth_frame(&synth, &frame);
  56
  57     /* output PCM samples in synth.pcm */
  58   }
  59
  60 This is vastly simplified, but it shows the general idea. mad_frame_decode()
  61 decodes the next frame's header and subband samples. mad_synth_frame() takes
  62 those subband samples and synthesizes PCM samples.
  63
  64 It is also possible to call mad_header_decode() before mad_frame_decode().
  65 This just gives you the frame's header info, in case that's all you want, or
  66 perhaps to help you decide whether you want to decode the rest of the frame.
  67
  68 As Joe mentions, each of the stream, frame, and synth structs needs to be
  69 initialized and "finished" before and after use:
  70
  71   struct mad_stream stream;
  72   struct mad_frame frame;
  73   struct mad_synth synth;
  74
  75   mad_stream_init(&stream);
  76   mad_frame_init(&frame);
  77   mad_synth_init(&synth);
  78
  79   /* ... */
  80
  81   mad_synth_finish(&synth);
  82   mad_frame_finish(&frame);
  83   mad_stream_finish(&stream);
  84
  85 You can work with just a struct mad_header instead of a struct mad_frame if
  86 you only want to decode frame headers.
  87
  88 Joe writes:
  89 > MAD always outputs 32-bit (well, mad_fixed_t) little-endian data. Take
  90 > this into account when outputting samples to the sound card.
  91
  92 This isn't quite right: the mad_fixed_t type is not necessarily little-endian.
  93 It's the same endianness as the native integer types. Also, it's only
  94 guaranteed to be *at least* 32 bits wide.
  95
  96 The fixed-point sample format is important to understand, and I recommend
  97 reading the comments in libmad/fixed.h. The thing to remember when converting
  98 MAD's fixed-point integer samples to 16-bit PCM (or whatever) is that MAD
  99 encodes samples as numbers in the full-scale range [-1.0, +1.0) where the
 100 binary point is placed 28 (MAD_F_FRACBITS) bits to the left of the integer.
 101 However, you need to be prepared to handle clipping as some numbers may be
 102 less than -1.0 (-MAD_F_ONE) or greater than or equal to +1.0 (MAD_F_ONE, aka
 103 1 << MAD_F_FRACBITS).
 104
 105 > Information on the other (error, filter, message) functions would be
 106 > appreciated, though I think in knowing this information anyone should be
 107 > able to puzzle it out.
 108
 109 In the high-level API, the error callback function is called whenever a
 110 decoding error occurs. The error number is in stream->error.
 111
 112 The filter callback function is called after decoding a frame, but before
 113 synthesis. Here it is possible to modify the frame's subband samples, for
 114 example to perform a uniform attenuation/amplification, or to do other special
 115 processing in the frequency domain.
 116
 117 The message callback function is only used with MAD_DECODER_MODE_ASYNC, and is
 118 called whenever the parent process sends a message via mad_decoder_message().
 119 This callback can generate a reply by overwriting the message buffer that is
 120 passed to it. (The size of the reply must be the same or smaller than the
 121 message.)
 122
 123 Cheers,
 124   -rob