PM123 Decoder Plugins

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

There are two interface revision levels. For developing new plugins the level 3 interface is strongly recommended. But level 0/1 plugins are still supported. The level 2 of PM123 1.40 is discontinued.

Decoder plugins are used to decode audio data as well as to examine playlists. Each item is identified by an URI.
You should not take the term 'playlist' too literally. It only means that an URI has logically a sequence of sub URIs, i.e. the URI has to be enumerable. This applies to a playlist as well as to a file system folder or a compact disc containing tracks.
In theory an item could be enumerable as well as directly playable. E.g. index tracks of a CD or a CUE sheet. But this has not been well tested in the PM123 core so far.

Interface revision level 3 (recommended)

The level 3 interface has the following components:

1. Playback interface, status interface and output interface
   This interfaces are used to play audio data. Plugins that only support playlists do not need to export these interfaces.
2. Info interface, save interface
   This interface is used to obtain or change information of a song or a playlist and to identify whether an item is supported by the plugin.
3. GUI enhancement interface

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.

decoder_support

ULONG DLLENTRY decoder_support(const DECODER_FILETYPE** types, int* count)

• types (out) - Pointer to the first element of an array of supported file types.
• count (out) - Number of entries in the above array.
• 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 internet URIs (http, ftp, etc.).
  DECODER_TRACK (4) - Decoder can play CD tracks, i.e. cdda URIs.
  DECODER_OTHER (8) - Decoder can play something else.
  DECODER_SONG (0x0100) - Decoder can play songs.
  DECODER_PLAYLIST (0x0200) - Decoder can read playlists.
  DECODER_WRITABLE (0x1000) - Decoder can save items.
  DECODER_METAINFO (0x2000) - Decoder can save meta info.
  The values should be ored as required.

This is used by PM123 to suggest to the user what he can play with the decoder. Furthermore, by default PM123 will not query the decoder about files or other objects that are not listed in the above filter list to keep performance up.

The function is called again after a successful call to plugin_configure. This allows to modify the supported file types through the configuration.

decoder_fileinfo

ULONG DLLENTRY decoder_fileinfo(const char *url, XFILE* handle, int* what, const INFO_BUNDLE* info,
                                DECODER_INFO_ENUMERATION_CB cb, void* param)

• url - URL to the desired stream. See URL samples.
• handle - optional XIO object handle. If the core engine can open the object via XIO then it passes the handle to the decoder to avoid that every decoder opens the object anew only to find out that it does not support it. The handle is opened in binary read only mode with deny none and with synchronous buffering enabled. Even if the source stream does not support seeking, you may seek within one buffer size. The buffer size depends on the protocol. It it at least 4kiB, so you should not read more than the first 4kiB.
  Decoders should use this handle unless they have a good reason not to do so. Decoders must not close the handle. Only decoders that returned DECODER_OTHER at decoder_support may be called with handle == NULL.
• what (in/out) - Bit vector of INFOTYPE. The requested fields in INFO_BUNDLE.
  The decoder may return more information than requested if it is cheap to do so. In this case it should set the additional bits in *what to notify PM123 that the desired information is valid too.
  The decoder must not return less information than requested. However, some information may not have any content for the desired object. In this case there is no need to modify the appropriate fields in *info.
  If *what is 0 on input, the information in INFO_BUNDLE is not required at all. Only the return value of decoder_fileinfo is used. However, the decoder may return more even in this case.
• info (out) - this structure must be filled at least with the information required by *what. See INFO_BUNDLE for further details. All entries of INFO_BUNDLE point to the appropriate structures when decoder_fileinfo is called.
  If some information is not available, the requested fields in INFO_BUNDLE should be left unchanged. Normally all fields have their initial value. But the TECH_INFO sub structure could contain some format information from a playlist plugin or an earlier call. This could be used to read raw PCM files.
  If the handle parameter is not NULL, the PHYS_INFO structure is already filled with the appropriate values.
  Note, that leaving fields initial is different from unrequested informations where the corresponding bits in *what are not set. In the latter case the information might become available later on request. It is just not yet known.
  In case of an error (non-zero return value) the decoder should return an error text in the tech->info field, if available.
• cb - Callback function.
  If INFO_OTHER is requested, the decoder has to call this function once for each item in the playlist (or collection) before decoder_fileinfo returns. Of course, this does not apply to songs.
• param - This parameter is to be passed as first argument to each call to *cb.
• return value -
  PLUGIN_OK (0) = everything's perfect, structure is set.
  PLUGIN_NO_READ (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 it is a file URI and the file does not exist or if it is a http URI and the domain does not exist or the server does not respond on the port. In fact decoders normally shall not return PLUGIN_NO_READ if they are called with a valid handle.
  PLUGIN_NO_PLAY (200) = this decoder can't play that. PM123 will try other decoders if available.

If a decoder knows that some information, that is not explicitly requested, is not available for the current URI or it knows it's content during processing of the request, it should always set the corresponding bit in *what and return the information if applicable. This avoids redundant calls to decoder_fileinfo.

PM123 does not need all informations for all kind of objects. The aggregate type recursive playlist information is never requested explicitly by PM123. PM123 will also never request INFO_PHYS if a handle is not NULL. However, a plugin may supply aggregate information if it is available. E.g. playlists may store cached information about their children to improve performance. If you are in doubt, do not supply this kind of information.

Legend:
X = required if requested by the PM123
Q = may be requested by the PM123
C = my be cached and returned by the decoder
O = may be overridden by a playlist item

DECODER_INFO_ENUMERATION_CB

void (DLLENTRY* cb)(void* param, const char* url, const INFO_BUNDLE* info, int cached, int reliable)

• param - Arbitrary parameter from decoder_fileinfo.
• url - URI of the sub item. The URI may be absolute or relative. In case of relative URIs the context of the enclosing playlist is used for URI resolution.
• info - Known information about the sub item. If you already know some information about an item, you should place it in *info. This can make PM123 significantly faster. If you do not have any information, you can pass NULL as info.
• cached, reliable - Two bit vectors of INFOTYPE corresponding to fields in *info.
  

  cached	reliable	Corresponding field in *info contains
  0	0	- ignored -, may be NULL
  1	0	The field contain cached information that might no longer be valid.
  0	1	The field contains reliable information that just had been verified.
  1	1	The field contains information that is overridden by this reference only.

  You may use overridden information e.g. to give meaningful meta information to a slice of an object. For example a cue sheet may reference slices of a long file, but the slices have different meta information although the underlying object is the same. You cannot override all kind of information. See the above matrix for details.

Playback interface

decoder_init, decoder_uninit

int DLLENTRY decoder_init (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.
• return value:
  PLUGIN_OK (0) means success.
  PLUGIN_FAILED (-1) means the decoder was not initialized successfully.

BOOL DLLENTRY decoder_uninit(struct DECODER_STRUCT *w)

• w - The pointer received by decoder_init.
• return value: TRUE = success

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. The decoder must not execute any callback function like OutRequestBuffer from another thread when decoder_uninit has returned.

decoder_command

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

• msg - one of the following:
  • DECODER_SETUP - setup various parameters such as the output plugin functions.
  • DECODER_PLAY - start playing the given filename, URL or others.
  • DECODER_FFWD - engage in ffwd mode (i.e.: play faster or skip forward or backward when playing).
  • DECODER_JUMPTO - jump and start decoding at the given time position.
  • DECODER_SAVEDATA - tells the decoder to start saving the stream to HD.
  • DECODER_STOP - stop playing.
• 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 are a lot of commands to implement for this function. Parameters needed for each of them are passed in the DECODER_PARAMS2 structure and described in detail here and in the decoder_plug.h include. The decoder necessarily should support following commands: DECODER_SETUP, DECODER_PLAY and DECODER_STOP.

In the level 3 interface the data source always passed as an URL. The URL parameter uses the following syntax:

file:///D:/Music/my favorite song.mp3
file://server/share/path/song.mp3 (UNC path)
http://... (as you would expect)
cdda:///H:/track02 (CD track)
cdda:///H:/ (CD TOC)

DECODER_SETUP

The DECODER_SETUP call is intended to capture the callback entries for the output interface. They do not change during decoding.

DECODER_PLAY

This command tell the decoder which song to decode. This should spawn a new thread that decodes the song and feeds the result to the output interface.

DECODER_JUMPTO

Tells the decoder to continue decoding at a certain location of the song. The structure member JumpTo is the location in seconds from the song's start.

DECODER_FFWD

Change the fast forward or rewind mode. The structure member SkipSpeed tell the decoder which playback speed is intended. The value i a delta to the normal playback speed, i.e. speed = SkipSpeed + 1. Examples:

• 0.0 => normal playback
• 1.0 => play twice as fast
• 3.0 => play 4 times faster
• -2.0 => play reverse
• -3.0 => play reverse twice as fast
• -5.0 => play revers 4 time faster
• -0.5 => play at half speed (currently unused)

There is no need to hit this value exactly. It is better to skip parts of the song instead of transforming the sample rate. Common values are marked bold. If a decoder can't support different speeds, it could simply use SkipSpeed > 0 for fast forward, and SkipSpeed < 0 for fest rewind.

Implementation hint: If you implement fast scan mode by seeking every 100 ms forward or reverse, then you need to seek SkipSpeed * 100 ms every time to get the desired average speed.

DECODER_STOP

Stop decoding of the current song. This should terminate the decoder thread. After DECODER_STOP the decoder should ignore all errors and simply terminate.

Status interface

The status interface has to be thread safe.

decoder_status

ULONG DLLENTRY decoder_status(struct DECODER_STRUCT *w)

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

decoder_length

PM123_TIME DLLENTRY decoder_length(struct DECODER_STRUCT *w)

• return value - number of seconds the stream lasts (you can report -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). The function is used to follow increasing length of files that are written on the fly while playing.

Output interface

The decoder must use this interface to pass the decoded samples to the output stage. The samples must be passed as 32 bit floating point values.

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_PARAMS2 at the DECODER_SETUP call.

The level 3 interface allocates the buffers by the consumer. This causes less double buffering and allows dynamic buffer sizes. In the optimal case the samples can be placed immediately in the output buffers of the audio device.

You must call OutRequestBuffer and OutCommitBuffer alternately to pass the samples to the next plugin. Anything else is an error. Note that any of the two functions might block.

OutRequestBuffer

int (DLLENTRYP OutRequestBuffer)(void* a, const FORMAT_INFO2* format, float** buf)

• a - pointer from DECODER_PARAMS2.
• format - format of the passed samples. The data at *format need not to be valid after this call returned.
• buf [out] - pointer to receive a memory location where to store the decoded samples.
• return value - the number of samples that fit in the returned buffer. A return value of ≤ 0 indicates a permanent error. PM123 stops the playback in this case.

If you get a smaller buffer as you need to pass your data you should call OutRequestBuffer and OutCommitBuffer again until all your data is consumed. There is no guaranteed minimum size of the buffer, but you should not expect to get very small buffers quite often.

OutCommitBuffer

void (DLLENTRY* OutCommitBuffer)(void* a, int len, PM123_TIME posmarker)

• a - pointer from DECODER_PARAMS2.
• len - used number of samples placed in the buffer.
• posmarker - stream position in seconds of the first sample that will be stored in this buffer relative to the beginning of the stream.

The length must not be higher than the the return value from the previous OutRequestBuffer call. But it might be less than the requested length. This causes no significant performance impact as long as you do not always pass very few samples.

DecEvent

void (DLLENTRY* DecEvent)(void* a, DECEVENTTYPE event, void* param)

• a - pointer from DECODER_PARAMS2.
• event - type of the event to send.
• param - event specific parameter. See below.

The decoder plugin MUST call the above function on the following conditions:

• DECEVENT_PLAYSTOP when the stream has finished decoding and the last sample has been passed to output_commit_buffer or when the decoder received a DECODER_STOP command.
• DECEVENT_PLAYERROR when a playback error occurred so that PM123 should know to stop immediately.
  param could optionally point to an error text or should be NULL otherwise. Passing a buffer to a temporary storage is valid. The information is copied by the PM123 core before the function returns.
• DECEVENT_SEEKSTOP when a DECODER_JUMPTO operation is completed (i.e. when no buffers from before the seek is sent to the output plugin anymore). The message must also be sent, when playback starts in the middle of a song.
• DECEVENT_CHANGETECH is sent whenever you want PM123 to change the display of the current technical information of the stream (like samplerate). param must point to a TECH_INFO structure.
• DECEVENT_CHANGEOBJ is sent whenever you want PM123 to change the display of the current object information of the stream (like song length). param must point to a OBJ_INFO structure. Note that you should not sent the bitrate of individual MPEG frames this way like the level 1 interface supported by WM_CHANGEBR. The object information keeps the bitrate of the entire stream.
• DECEVENT_METADATA is sent whenever streaming metadata is updated. param must point to a META_INFO structure.

decoder_event

void DLLENTRY decoder_event(void* w, OUTEVENTTYPE event)

• w - pointer from decoder_init
• event - one of the following values
  OUTEVENT_LOW_WATER - the output plugin detected that it will run out of data soon.
  OUTEVENT_HIGH_WATER - the output plugin detected a clear condition.

The events may be used to speed up the data source. If you get OUTEVENT_HIGH_WATER you should return to normal behavior. There is one task that the core engine does for you: PM123 automatically changes the priority of the decoder thread. So if there is nothing more the decoder can do (e.g. QoS settings) it could safely ignore the events.

The event handler may be called from any thread in any context. It might be called when the decoder is in stopped state if the end of the stream has been reached recently. This should be ignored. You will usually get a OUTEVENT_LOW_WATER call immediately after the decoding started or after a seek command because the buffers are not yet filled.

The export of decoder_event is optional.

Save interface

decoder_saveinfo

ULONG DLLENTRY decoder_saveinfo(char* url, const META_INFO* info, int haveinfo, xstring* errortext)

• url - URI to the desired object.
• info - new meta information to write.
  Only the fields with the corresponding bits in haveinfo set must be modified. The others should be left unchanged.
• haveinfo - Components of info to modify.
• errortext - place a descriptive error text here if the function fails.
• return value
  PLUGIN_OK (0) = everything is perfect, meta info is saved to url.
  PLIGIN_ERROR (500) = failed.

The function modifies the meta information of a certain song. Calling the function should succeed even if the file is currently playing.

decoder_savefile

ULONG DLLENTRY decoder_savefile(const char* url, const char* format, int* what, const INFO_BUNDLE* info,
                                DECODER_SAVE_ENUMERATION_CB cb, void* param, xstring* errortext)

• url - URI to the desired object.
  It is valid to pass a URI of a currently playing song. The decoder should be able to handle that appropriately.
• format - optional format parameter if the decoder supports different file formats.
  
• what (in/out) - Bit vector of INFOTYPE flags with the information to save. Any information that corresponds to bits that are not set in *what should be preserved by this call. And if INFO_META is specified, any meta information that does not have the corresponding bit in info->meta->haveinfo set, should be left unchanged too.
  On return the decoder resets the the bits in *what that could not be saved because they are not supported in the requested format.
  Furthermore the decoder may set the INFO_PHYS bit to indicate that *info->phys has been updated with recent informations after the update. (Of course, PM123 will never request this on input.)
• info - Information of the playlist object itself. Usually playlists do not contain additional object information other than their content. So the info may be mostly ignored. However, it could speed up PM123 if decoder_fileinfo can restore some infos in a cheap way.
• cb - Enumeration callback. The decoder should call this function to retrieve the information about the playlist content from PM123, but only if *what contains INFO_CHILD.
• param - Parameter to be passed as first argument to *cb.
• errortext - place a descriptive error text here if the function fails.
• return value
  PLUGIN_OK (0) = everything is perfect, meta info is saved to url.
  PLIGIN_ERROR (500) = failed.

The function is used to modify a file (or other object) in place. It is currently only used to save playlists.

DECODER_SAVE_ENUMERATION_CB

int (DLLENTRY* cb)(void* param, xstring* url, const INFO_BUNDLE** info, int* cached, int* reliable)

• param - Arbitrary parameter from decoder_savelist.
• url (out) - Return URI of the sub item. The URI may be absolute or relative. In case of relative URIs the context of the enclosing playlist is used for URI resolution. Note that the xstring structure must be initialized when the function is called.
• info (out) - Return known information about the sub item. The decoder can store this information in the playlist and return it when the list is read with decoder_fileinfo to speed up large playlists.
  The storage where *info points to is only valid until the next call to cb or until decoder_savefile returned.
• cached, reliable (out) - Return INFOTYPE bit vectors. See DECODER_INFO_ENUMERATION_CB for details.
  The decoder should not store information that is not at least cached. When both bits are set the specified type of information in **info is overridden by this reference only. The decoder should store this information together with the URI reference when possible.
• return value - PLUGIN_OK (0) = everything is fine, anything else = error, e.g. no more items.

DECODER_FILETYPE

typedef struct
{ const char* category;
  const char* eatype;
  const char* extension;
  int         flags;
} DECODER_FILETYPE;

TODO

GUI enhancement interface

The following functions are used to improve the GUI of PM123 with plugin specific content.
All functions in this section are optional.

decoder_editmeta

ULONG DLLENTRY decoder_editmeta(HWND owner, const char* url)

• owner - Parent window handle.
• url - URL to the desired stream. See URI samples. Keep in mind that this URL may be the same as the one currently played. The plugin must handle this concurrent write access.
• return value -
  PLUGIN_OK      (0) = everything is perfect, information has been changed. PM123 will invalidate the Meta information of this URL and likely call decoder_fileinfo to update its internal cache.
  PLUGIN_NO_READ (200) = decoder can't handle that. (PM123 raises an error dialog)
  PLUGIN_NO_OP   (300) = no change, e.g. user abort. This return value should also be used when the plugin already raised a meaningful message using plugin_api->error_display.
  PLUGIN_NO_SAVE (400) = can't edit tag of this stream. (PM123 raises an error dialog)
  PLUGIN_ERROR   (500) = error writing tag. (PM123 raises an error dialog)

If decoder_editmeta is not implemented, the edit tag entry is always disabled.

decoder_getwizard

const DECODER_WIZARD* DLLENTRY decoder_getwizard(void)

• return value - Zero or more DECODER_WIZARD structures (linked list).
  Each structure represents an entry in the context menu to load something into the player or a playlist. To terminate the list of DECODER_WIZARD objects set the link pointer to NULL. The returned storage must be valid until the next call to decoder_getwizard or the plugin gets unloaded.

If the function is not implemented or returns NULL the context menu is not extended with entries specific to this plugin.

The field prompt is the menu text. It should not contain information about the accelerator key, because this is generated automatically.

The fields accel_key[2] and accel_opt[2] can be used to extend the accelerator table of PM123. They correspond to the fields key and fs of the ACCEL structure. The first set of entries is used for the PM123 main window and the playlist windows. The second set is for the Playlist Manager to append to the currently selected playlist.
You should set accel_key to 0 if you do not want an accelerator key for your plugin's wizard dialog. Be careful with the choice of the accelerator keys because there may be clashes. Using Alt for the first entry and Shift-Alt for the second entry as meta keys is recommended.

When the menu entry is selected the corresponding wizard function is called by PM123.

ULONG (DLLENTRY* wizard)(HWND owner, const char* title,
                         DECODER_INFO_ENUMERATION_CB callback, void* param)

• owner - Parent window handle.
• title - Window title.
  The title may contain "%s" for the object type. E.g. "Add%s to playlist." may evaluate to "Add track(s) to playlist.".
• callback - Function that will be called for each selected item.
• param - Parameter to pass to the callback function as the first argument.
• return value -
  PLUGIN_OK    (0)   = OK, callback has been called at least once.
  PLUGIN_NO_OP (300) = Cancel. Do not add/play anything.
  PLUGIN_ERROR (500) = Internal error.