Content-type: text/html

# decoder.so

Section: User Commands (1)
Index Return to Main Contents

## NAME

libmpgedit_decoder.so, libdecoder_popen.so, libdecoder_mpg123.so - MPEG 1/2/2.5 audio player plugin

## SYNOPSIS

libmpgedit_decoder.so
libdecoder_popen.so
libdecoder_mpg123.so

## DESCRIPTION

libmpgedit_decoder.so, libdecoder_popen.so, and libdecoder_mpg123.so are MPEG audio player plugins for mpgedit. The plugin named libmpgedit_decoder.so is loaded by mpgedit. By default, this is configured as a symbolic link pointing to the player plugin libdecoder_mpg123.so.

The libdecoder_mpg123.so plugin makes calls to the MPGLIB decoding engine to decode MPEG audio frames, then writes the decoded PCM data to the audio device /dev/dsp for playback.

The libdecoder_popen.so plugin is implemented to call the popen(3) system call, which executes the decoder shell script mp3decoder.sh.

The mechanism implemented in libdecoder_popen.so is the default audio playback mechanism for UNIX platforms when the libmpgedit_decoder.so plugin cannot be loaded. The Win32 implementation has no such fail over, and merely calls stub functions. The purpose of the audio player plugin mechanism is to provide a more portable audio playback mechanism for mpgedit. The use of the popen(3) function introduces a strong UNIX dependency, which cannot be ported to operating systems that do not support popen(3) (e.g., Windows).

## DECODER PLUGIN API

void *mpgdecoder_alloc(void);

void mpgdecoder_free(void *ctx);

void mpgdecoder_init(void *ctx);

FILE *mpgdecoder_open(void *ctx, int sample_rate, int stereo);

void mpgdecoder_close(void *ctx);

void mpgdecoder_play_frame(void *ctx, FILE **playfp, unsigned char *buf, int len, int sample_rate, int stereo);

The mpgdecoder_alloc function allocates a new MPEG decoder context, which is passed to all of the functions in the plugin API. This context is released by mpgdecoder_free when mpgedit is shut down. The decoder context ctx is used by the decoder plugin to store the state of the MPEG decoder, and is treated as opaque data by the caller of this plugin API.

The mpgdecoder_init function is called once every time audio play back is initiated. This provides the opportunity to initialize the MPEG audio decoder to a known state before starting playback of a new audio segment.

The mpgdecoder_open function is called once every time audio playback is initiated. The audio segment sample rate, in hertz, is passed via the sample_rate parameter. Typical values for this parameter are 22050 and 44100. The stereo parameter is a boolean value, with a value of 1 when the playback audio segment is stereo, and 0 when mono.

Warning: The return value from mpgdecoder_open should only be tested in a boolean expresssion for the success or failure of mpgdecoder_open, where non-zero is success and zero (NULL) is failure. You cannot treat the return as a file pointer, as the function type would indicate. This is a change from mpgedit 0.5, and was necessary for support of the Win32 port of mpgedit. Generally it is a "bad thing" to change function semantics like this, since this consititues an API change. However, as the return value from mpgdecoder_open was treated as an opaque value by the caller, this change should not break any code.

The mpgdecoder_close function is called once every time audio playback has completed. This function must be called before calling mpgdecoder_open again.

The mpgdecoder_play_frame function is called to playback one frame of MPEG audio from the audio segment. The playback parameter is the return value from a previous call to mpgdecoder_open. The MPEG audio data to be decoded is contained in buf, with a length of len. The sample_rate and stereo parameters are the sample rate and stereo/mono value for the current frame of data being decoded. These values can be different than what was passed to mpgdecoder_open, and may be different for each MPEG audio frame being decoded, although typically this is not the case.

## IMPLEMENTATION LIMITATIONS AND ANOMALIES

Different platform's decoder plugin end with a different extension. Most UNIX and UNIX-like platforms are .so, HP-UX is .sl, Mac OSX is .dylib, and Windows is .dll. Not all error messages involving the decoder plugin display the correct extension, invariably .so will be displayed over other extensions.

## ACKNOWLEDGEMENTS

The libdecoder_popen.so plugin calls mp3libdecoder.sh, which by default depends on the MPEG audio player mpg123, written by Michael Hipp (www.mpg123.de), and released under the GPL. The libdecoder_mpg123.so plugin depends on the MPGLIB decoding engine, which comes from the MPG123 package, written by Michael Hipp (www.mpg123.de). MPGLIB is released under the GPL.

## SEE ALSO

mpgedit(1), xmpgedit(1), mp3decoder.sh(1)

## Index

NAME
SYNOPSIS
DESCRIPTION
DECODER PLUGIN API
IMPLEMENTATION LIMITATIONS AND ANOMALIES
ACKNOWLEDGEMENTS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 06:35:59 GMT, April 17, 2006