Commit 63e5cfb0 authored by Christophe Massiot's avatar Christophe Massiot

libmad plug-in, courtesy of Jean-Paul Saman <jpsaman@wxs.nl>.

parent 8fec59e1
......@@ -209,6 +209,11 @@ N: Olivier Pomel
E: pomel@via.ecp.fr
C: pomel
N: Jean-Paul Saman
E: jpsaman@wxs.nl
D: libmad plug-in
D: iPAQ port
N: Steven M. Schultz
E: sms@TO.GD-ES.COM
D: BSD/OS port
......
......@@ -4,6 +4,8 @@
HEAD
* New libmad plug-in, courtesy of Jean-Paul Saman. We now have sound on
iPAQ Familiar Linux.
* Borrowed MPlayer's fast memcpy() routines. Best is autodetected, choose
"--memcpy <whatever>" to choose one from c, mmx, mmxext or 3dn.
* Added versioned build-dep to libasound2-dev (Closes Debian bug #121057).
......
......@@ -34,6 +34,7 @@ PLUGINS_DIR := ac3_adec \
kde \
lpcm_adec \
macosx \
mad_adec \
memcpy \
mga \
motion \
......@@ -79,6 +80,7 @@ PLUGINS_TARGETS := ac3_adec/ac3_adec \
kde/kde \
lpcm_adec/lpcm_adec \
macosx/macosx \
mad_adec/mad_adec \
memcpy/memcpy \
memcpy/memcpymmx \
memcpy/memcpymmxext \
......
......@@ -83,6 +83,7 @@ LIB_GTK = @LIB_GTK@
LIB_KDE = @LIB_KDE@
LIB_LIBDVDCSS = @LIB_LIBDVDCSS@
LIB_MACOSX = @LIB_MACOSX@
LIB_MAD_ADEC = @LIB_MAD_ADEC@
LIB_NCURSES = @LIB_NCURSES@
LIB_QNX = @LIB_QNX@
LIB_QT = @LIB_QT@
......@@ -104,6 +105,7 @@ CFLAGS_ESD = @CFLAGS_ESD@
CFLAGS_LIBDVDCSS = @CFLAGS_LIBDVDCSS@
CFLAGS_ESD = @CFLAGS_ESD@
CFLAGS_GTK = @CFLAGS_GTK@
CFLAGS_MAD_ADEC = @CFLAGS_MAD_ADEC@
CFLAGS_SDL = @CFLAGS_SDL@
CFLAGS_X11 = @CFLAGS_X11@
......
This diff is collapsed.
......@@ -747,12 +747,40 @@ dnl rc plugin
dnl
AC_ARG_ENABLE(rc,
[ --disable-rc rc module (default enabled)])
if test x$enable_rc != xno
then
BUILTINS="${BUILTINS} rc"
fi
dnl
dnl libmad plugin
dnl
AC_ARG_WITH(libmad,
[ --with-libmad[=PATH] libmad module (default disabled)],
[ if test "x$with_val" != "xno"; then
if test -n $with_val; then
CFLAGS_MAD_ADEC="-I$with_val/include"
LIB_MAD_ADEC="-L$with_val/lib -lmad"
else
LIB_MAD_ADEC="-lmad"
fi
save_CFLAGS=$CFLAGS
save_LDFLAGS=$LDFLAGS
CFLAGS="$CFLAGS $CFLAGS_MAD_ADEC"
LDFLAGS="$LDFLAGS $LIB_MAD_ADEC"
AC_CHECK_HEADERS(mad.h, ,
[ echo "Cannot find development headers for libmad..."
exit 1
])
AC_CHECK_LIB(mad, mad_bit_init, ,
[ echo "Cannot find libmad library..."
exit 1
])
CFLAGS=$save_CFLAGS
LDFLAGS=$save_LDFLAGS
PLUGINS="${PLUGINS} mad_adec"
fi ])
dnl special case for BeOS
if test x$SYS = xbeos
then
......@@ -1203,6 +1231,7 @@ AC_SUBST(LIB_GTK)
AC_SUBST(LIB_KDE)
AC_SUBST(LIB_LIBDVDCSS)
AC_SUBST(LIB_MACOSX)
AC_SUBST(LIB_MAD_ADEC)
AC_SUBST(LIB_NCURSES)
AC_SUBST(LIB_QNX)
AC_SUBST(LIB_QT)
......@@ -1221,6 +1250,7 @@ AC_SUBST(CFLAGS_LIBDVDCSS)
AC_SUBST(CFLAGS_ARTS)
AC_SUBST(CFLAGS_ESD)
AC_SUBST(CFLAGS_GTK)
AC_SUBST(CFLAGS_MAD_ADEC)
AC_SUBST(CFLAGS_SDL)
AC_SUBST(CFLAGS_X11)
......
......@@ -175,22 +175,23 @@
#define INPUT_NETWORK_PROTOCOL_VAR "vlc_network_protocol"
#define INPUT_NETWORK_PROTOCOL_DEFAULT "ts"
/* Default remote server */
#define INPUT_SERVER_VAR "vlc_server"
#define INPUT_SERVER_DEFAULT "138.195.143.220"
/* Default input port */
#define INPUT_PORT_VAR "vlc_server_port"
#define INPUT_PORT_DEFAULT 1234
/* Default broadcast address */
#define INPUT_BCAST_ADDR_VAR "vlc_broadcast_addr"
#define INPUT_BCAST_ADDR_DEFAULT "138.195.143.255"
/* FIXME : Delete those ! */
/* Default remote server */
#define INPUT_SERVER_VAR "vlc_server"
#define INPUT_SERVER_DEFAULT "138.195.143.220"
/* Broadcast mode */
#define INPUT_BROADCAST_VAR "vlc_broadcast"
#define INPUT_BROADCAST_DEFAULT 0
/* Default broadcast address */
#define INPUT_BCAST_ADDR_VAR "vlc_broadcast_addr"
#define INPUT_BCAST_ADDR_DEFAULT "138.195.143.255"
/* Channels mode */
#define INPUT_NETWORK_CHANNEL_VAR "vlc_channel"
#define INPUT_NETWORK_CHANNEL_DEFAULT 0
......@@ -299,6 +300,9 @@
* - long, in order to perform the buffer calculations as few as possible */
#define AOUT_BUFFER_DURATION 100000
/* Environment variable for MPEG audio decoder */
#define ADEC_MPEG_VAR "vlc_mpeg_adec"
/*****************************************************************************
* Video configuration
*****************************************************************************/
......@@ -334,8 +338,6 @@
#define VOUT_HEIGHT_DEFAULT 576
#define VOUT_DEPTH_VAR "vlc_depth"
#define VOUT_DEPTH_DEFAULT 15
#define VOUT_FULLSCREEN_DEPTH_VAR "vlc_fullscreen_depth"
#define VOUT_FULLSCREEN_DEPTH_DEFAULT 32
/* Maximum width of a scaled source picture - this should be relatively high,
* since higher stream values will result in no display at all. */
......
......@@ -2,7 +2,7 @@
* tests.h: several test functions needed by the plugins
*****************************************************************************
* Copyright (C) 1996, 1997, 1998, 1999, 2000 VideoLAN
* $Id: tests.h,v 1.11 2001/05/30 17:03:11 sam Exp $
* $Id: tests.h,v 1.12 2001/12/04 13:47:46 massiot Exp $
*
* Authors: Samuel Hocevar <sam@zoy.org>
*
......@@ -30,6 +30,7 @@
#define CPU_CAPABILITY_MMXEXT 1<<5
#define CPU_CAPABILITY_SSE 1<<6
#define CPU_CAPABILITY_ALTIVEC 1<<16
#define CPU_CAPABILITY_FPU 1<<31
/*****************************************************************************
* TestVersion: tests if the given string equals the current version
......
--- plugins/sdl/vout_sdl.c 2001/12/03 16:18:37 1.66
+++ plugins/sdl/vout_sdl.c 2001/12/04 13:29:29
@@ -329,12 +329,16 @@
break;
case SDL_MOUSEBUTTONUP:
+#if 0
switch( event.button.button )
{
case SDL_BUTTON_RIGHT:
p_main->p_intf->b_menu_change = 1;
break;
}
+#else
+ intf_ProcessKey( p_main->p_intf, SDLK_q );
+#endif
break;
case SDL_MOUSEBUTTONDOWN:
......@@ -7,7 +7,7 @@
export CC=arm-linux-gcc
export LD=arm-linux-ld
export STRIP=arm-linux-strip
export CONFIG_FLAGS="--enable-release --prefix=/usr --disable-gtk --enable-fb --enable-sdl --disable-xvideo --disable-plugins --with-tuning=strongarm1100 --x-includes=/skiff/local/arm-linux/include --x-libraries=/skiff/local/arm-linux/lib/X11 --with-sdl-config-path=/skiff/local/bin"
export CONFIG_FLAGS="--enable-release --prefix=/usr --disable-gtk --enable-fb --enable-sdl --disable-xvideo --disable-plugins --with-tuning=strongarm1100 --x-includes=/skiff/local/arm-linux/include --x-libraries=/skiff/local/arm-linux/lib/X11 --with-sdl-config-path=/skiff/local/bin --with-libmad=/skiff/local/arm-linux"
export LIBDVDCSS_FLAGS="--with-dvdcss=local-static"
export VIDDIR="usr/share/videolan"
export PIXDIR="usr/share/pixmaps"
......@@ -19,6 +19,9 @@ build-stamp:
--infodir=$${prefix}/share/info \
$(shell echo $(CONFIG_FLAGS)) $(shell echo $(LIBDVDCSS_FLAGS))
# This is ugly -- I know
patch -p 0 < ipkg/patch
$(MAKE)
touch build-stamp
......
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.)
bug #09/11/2001-1: (FIXED 20/11/2001, by JP Saman)
Makefile.opts.in and Makefile.opts static libmad.a library is not filled in automatically by configure.
It should say in Makefile.opts LIB_MAD_ADEC=lib/libmad.a
bug #09/11/2001-2:
libmad/mad.h is not created automatically. Fix compile step and dependencies for mad_adec to automatically
configure and or build libmad when not build yet. This means integration of configure.in scripts.
bug #12/11/2001-1 (WORKING, by JP Saman)
smoothen out audio in libmad_output callback function, by optimizing conversion routines. After investigation
and experimenting I found out that my input routine and output routine were not balanced correctly with
respect to buffer sizes. A lot of data got lost. I fixed that, but still need a bater scaling/smoothing routine
for the audio.
bug #20/11/2001-1 (FIXED 25/11/2001, by JP Saman)
synchronization between audio and video output is lost. In libmad_output a timestamp is set on the audio data, but
it points to a later video frame, then when the audio data was read. How can I set the correct timestamp on the
audio fifo at the time it was read from the bitstream, so that it matches the video frame it belongs to?
Solution: Do it in two steps, in the input function save i_pts of fifo and in output function pass saved i_pts to
aout_fifo.
\ No newline at end of file
File: Plugin mad for vlc is based upon libmad from the mad distribution.
Author: Jean-Paul Saman <jpsaman@wxs.nl>
Directories:
============
vlc/ : adapted config.in and Makefile
: added libtool, ltmain.sh and ltconfig
vlc/extras/libmad : libmad from the original mad distribution
vlc/plugins/mad_adec : mad audio decoder plugin for vlc
Interface functions to implement in mad plugin are:
=========
adec_mad_Probe
adec_mad_Run
adec_mad_Init
adec_mad_ErrorThread
adec_mad_EndThread
libmad_input
libmad_output
libmad_header
libmad_messages
Design: (ASCII art)
=======
It represents the function call flow viewed from the vlc main program. The main program is in charge of allocating decoders,
initializing, starting and stopping them.
---------------
| <library> |
| libmad |
---------------
^
|
---------------
| <plugin> |
| mad_adec |
_______________
^
|
________________________
| <decoder interface> |
| vlc plugin interface |
________________________
Interface view:
===============
[mad_adec decoder plugin]
----------------------
vlc decoder interface -> | mad_adec mad_libmad | -> libmad
-----------------------
Rationel:
Keeping libmad as a separate library, either dynamic or statically linked in, makes maintenance so much simpeler.
Merging with a new libmad version should be straight forward as long as the interface stays stable.
There is another benefit: Disk (actually flash ROM) resources and memory are very limited on a iPaq.
Other programs or utilities like madplay and BBplay can make use of the same libmad version we do. In this way
limiting the needed storage place on disk (flash ROM). Also this is only possible when the interface stays the same.
###############################################################################
# vlc (VideoLAN Client) MAD audio decoder module makefile
# (c)2001 VideoLAN
###############################################################################
#
# Objects
#
PLUGIN_MAD = mad_adec.o mad_libmad.o
BUILTIN_MAD = $(PLUGIN_MAD:%.o=BUILTIN_%.o)
ALL_OBJ = $(PLUGIN_MAD) $(BUILTIN_MAD)
#
# Virtual targets
#
include ../../Makefile.modules
$(PLUGIN_MAD): %.o: .dep/%.d
$(PLUGIN_MAD): %.o: %.c
$(CC) $(CFLAGS) $(PCFLAGS) $(CFLAGS_MAD_ADEC) -DPLUGIN -c -o $@ $<
$(BUILTIN_MAD): BUILTIN_%.o: .dep/%.d
$(BUILTIN_MAD): BUILTIN_%.o: %.c
$(CC) $(CFLAGS) $(CFLAGS_MAD_ADEC) -DBUILTIN -c -o $@ $<
#
# Real targets
#
../mad_adec.so: $(PLUGIN_MAD)
$(CC) $(PCFLAGS) -o $@ $^ $(PLCFLAGS) $(LIB_MAD_ADEC)
../mad_adec.a: $(BUILTIN_MAD)
ar r $@ $^
$(RANLIB) $@
TODO: (Jean-Paul Saman <jpsaman@wxs.nl>)
[1 - 30 October 2001, done]
introduce libmad in vlc-dev code tree, this includes:
configure from top level of source tree
compilable from top level of source tree
[2 - 25 November 2001, done]
creating basic mad plugin in vlc-dev code tree, this include:
writing most simple vlc-plugin (no fancy stuf)
configurable from top level of source tree
compilable from top level of source tree
[3 - 25 November 2001, done]
test basic mad plugin
native Intel
native iPaq
[4 - 26 November 2001, working]
commit to current vlc-dev tree in CVS at VideoLan
fix broken things and conflicts
run tests again (see [3])
[5 - all ready done by Christophe Massiot]
make cross-compile possible for vlc without interface. With interface it is to damn difficult to do cross-compilation.
[6 - ]
extending mad plugin with more features
do fancy stuff (enable MP3 decoding)
[7 - ]
test extended plugin
native Intel
native iPaq
cross-compile iPaq
[8 - ]
commit to current vlc-dev tree in CVS at Videolan
fix broken things and conflicts
run tests again (see [7])
[9 - ]
incorporate new libmad version if possible
see 1
see 7
see 8
Subject: [mad-dev] Some information about programming with MAD (in synchronous mode)
As the author of mpg321, I too faced the problem of MAD not being
documented. However, in looking at minimad.c, and re-writing mpg321 to
use MAD, I came to understand it better. Here's some information which
will help anybody start out with MAD:
First, some basic information.
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.)