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).
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.