PM123 Decoder Plugins (1)

This is the description for the decoder interface before revision 2. This interface is deprecated. For new developments you should have a look at the recent level 3 interface.

Interface revision level 0 and 1

Decoder plugins must implement and export the functions defined in decoder_plug.h.

Playback interface

int DLLENTRY decoder_init ( struct DECODER_STRUCT **w )
BOOL DLLENTRY decoder_uninit( struct DECODER_STRUCT *w )

• w - Allocate any chunk of memory necessary for the decoder's function. This pointer will be passed to the other functions.
  The type struct DECODER_STRUCT is incomplete. You may fill it with life or simply cast to your own type. Before PM123 1.41 this have been void*. The change breaks source compatibility, but the interface is still binary compatible.
• return value - PLUGIN_FAILED (-1) means the decoder was not initialized successfully.

Init function is called when PM123 needs the specified decoder to play the stream demanded by the user. So only one decoder plugin is active at any given time. It should initialize the necessary semaphores and threads. decoder_uninit is called when another decoder than yours is needed, and should destroy the decoder's thread, semaphores, other opened handles and free allocated memory for w.

ULONG DLLENTRY decoder_command( struct DECODER_STRUCT *w, ULONG msg, DECODER_PARAMS *params )

• msg: one of the following:
  • DECODER_PLAY start playing the given filename, URL or others.
  • DECODER_STOP stop playing.
  • DECODER_FFWD engage in ffwd mode (ie.: play faster or skip when playing).
  • DECODER_REW engage rewind mode.
  • DECODER_JUMPTO jump and start decoding at the given time position.
  • DECODER_SETUP setup various parameters such as the output plugin functions, hwnd where to send messages and an optional play semaphore.
  • DECODER_EQ usually only useful for MPEG decoding where frequency equalization is cheap.
  • DECODER_BUFFER reports the reader buffer status.
  • DECODER_SAVEDATA tells the decoder to start saving the stream to HD.
• params: structure that contains the parameters needed by the preceding commands.
• return value:
  PLUGIN_OK (0) -> OK.
  PLUGIN_UNSUPPORTED (1) -> command unsupported.
  DECODER_PLAY and DECODER_STOP can return also PLUGIN_GO_ALREADY (101) and PLUGIN_GO_FAILED (102).

There is a lot of commands to implement for this function. Parameters needed for each of the are described in the definition of the structure in the decoder_plug.h file. The decoder necessarily should support following commands: DECODER_SETUP, DECODER_PLAY and DECODER_STOP.

The decoder plugin must WinPostMsg() the following messages to hwnd:

• WM_PLAYSTOP - when the stream has finished decoding.
• WM_PLAYERROR - when a playback error occurred so that PM123 should know to stop immediately.
• WM_SEEKSTOP - when a DECODER_JUMPTO operation is completed (ie.: when no buffers from before the seek is sent to the output plugin anymore).
• WM_CHANGEBR - is sent whenever you want PM123 to change the display of the current bit rate. mp1 = current bit rate in kbit/s.
• WM_METADATA - is sent whenever streaming meta data is updated and contains the pointer to the streaming meta data in mp1. This pointer should be the same one that is passed with DECODER_SETUP because it is guaranteed to be available to PM123 without memory leaking.

Streaming meta data currently is for SHOUTcast (and icecast is using the same method), so it is a string with the following format:

StreamingTitle='blah blah';StreamingURL='more useless information';

Status interface

The status interface has to be thread safe.

ULONG DLLENTRY decoder_status( struct DECODER_STRUCT *w )

• return value - One of the following:
  DECODER_STOPPED
  DECODER_PLAYING
  DECODER_STARTING
  DECODER_PAUSED

ULONG DLLENTRY decoder_length( struct DECODER_STRUCT *w )

• return value - number of milliseconds the stream lasts (you can report (ULONG)-1 if unknown).

The call to this function must be valid even if DECODER_STARTING or DECODER_STOPPED is reported (when the stream plays too fast for example).

Output interface

The decoder must use this interface to pass the decoded samples to the output stage. Strictly speaking this is part of the playback interface, but the interface functions have to be called by the decoder in a separate thread. The function entry points for these callbacks are passed in DECODER_PARAMS at the DECODER_SETUP call.

int (DLLENTRYPP output_play_samples)( void* a, const FORMAT_INFO* format,
 const char* buf, int len, int posmarker )

• a - pointer from DECODER_PARAMS.
• format - format of the passed samples.
  See FORMAT_INFO in format.h for more details. The data at *format need not to be valid after this call returned.
• buf - data buffer.
• len - length of the buffer in bytes.
  Whatever happens the decoder must not pass incomplete samples.
• return value - number of samples processed. Anything ≠ len is an error.

The decoder should pass the decoded samples to this function. The decoder should pass a bunch of samples at once unless the end of the data is reached to keep the performance reasonable.

Info interface

The info interface functions must be independent of the current decoder status. They should always be functional and give consistent results in any conditions. The functions must be thread-safe.

ULONG DLLENTRY decoder_fileinfo( const char *url, DECODER_INFO *info )

• url - full path or URL to the desired stream.
• info - this structure must be filled with the required information.
• return value -
  0 = everything's perfect, structure is set.
  100 = error reading file. This error should only be set if there is no chance that any other plugin may read this URL. E.g. if the file does not exist or if it is a http URL and the domain does not exist or the server does not respond on the port.
  200 = this decoder can't play that. PM123 will try other decoders if available.

ULONG DLLENTRY decoder_saveinfo( char* url, const DECODER_INFO* info )

• url - full path or URL to the desired stream.
• info - new meta information to write. Only the fields title, artist, album, year, comment, genre, track and copyright of the structure are significant. And only the fields with the corresponding bits in haveinfo set must be modified. The others should be left unchanged.
• return value:
  PLUGIN_OK (0) = everything's perfect, meta info is saved to url.
  other values = errno.

It is called if it is necessary to change the meta information for the specified file and the decoder supports this feature. Exporting this function is optional. See decoder_support.

ULONG DLLENTRY decoder_trackinfo( const char *drive, int track, DECODER_INFO *info )

• drive - ie.: "X:"
• track - CD tracks start from 1.
• info - this structure must be filled with the required information.
• return value -
  PLUGIN_OK (0) = everything's perfect, structure is set.
  PLUGIN_NO_READ (100) = error reading file (too small?).
  PLUGIN_NO_PLAY (200) = decoder can't play that.
  other values = errno.

ULONG DLLENTRY decoder_cdinfo( char *drive, DECODER_CDINFO *info )

• drive: ...
• info - required info on the number of tracks available from the decoder.
• return value:
  PLUGIN_OK (0) = everything's perfect, structure is set.
  PLUGIN_NO_READ (100) = error reading required info.
  other values = errno.

This function is unused by PM123 since version 1.40 but it might still be invoked by visual plugins. You need not to export the CD related functions unless decoder_support returns the DECODER_TRACK flag.

ULONG DLLENTRY decoder_support( char *fileext[], int *size )

• fileext - fill this array with all the wildcard expression matching filenames this decoder can play (each element is a 8 bytes char array).
• size - number of wildcard expressions returned (if this value is not big enough, ie.: 0, return the appropriate size without filling fileext).
• return value - return what kind of stream can the decoder play:
  DECODER_FILENAME (1) - decoder can play files (including UNC names)
  DECODER_URL (2) - decoder can play URLs (http, ftp, etc.)
  DECODER_TRACK (4) - decoder can play CD tracks
  DECODER_OTHER (8) - decoder can play other URLs
  DECODER_METAINFO (0x8000) - decoder supports decoder_saveinfo.
  The values may be ored.

This is used by PM123 to suggest to the user what he can play with the decoder and what features are supported. Extensions can be for example "*.MOD".

GUI enhancement interface

See level 3 GUI enhancement interface. This part of the interface is new with PM123 1.40, but since all of the functions are optional it is compatible anyway.