PM123 Decoder Plugins: commands

This section is a detailed description of the function decoder_command of the level 3 decoder interface.

The operation sequence is in general:

DECODER_SETUP
DECODER_FFWD (optional)
DECODER_SAVEDATA (optional)
DECODER_PLAY
1. DECODER_JUMPTO (optional)
2. DECODER_FFWD (optional)
3. DECODER_SAVEDATA (optional)
DECODER_STOP

The decoder will always be stopped before it is reused. Both, the outer and the inner enumeration could be repeated in a loop.

`DECODER_PARAMS2`

This structure is used to pass parameters to decoder_command.

typedef struct _DECODER_PARAMS2
{
  /* --- DECODER_PLAY */
  xstring      URL;         /**< URL to play */
  const INFO_BUNDLE_CV* Info;/**< Info about the URL to play */

  /* --- DECODER_PLAY DECODER_REW, FFWD and JUMPTO */
  PM123_TIME   JumpTo;      /**< absolute positioning in seconds */
  DECFASTMODE  Fast;        /**< fast forward/rewind */

  /* --- DECODER_SETUP */
  /** specify a function which the decoder should use for output */
  int   DLLENTRYP(OutRequestBuffer)(void* a, const FORMAT_INFO2* format, float** buf);
  void  DLLENTRYP(OutCommitBuffer )(void* a, int len, PM123_TIME posmarker);
  /** decoder events */
  void  DLLENTRYP(DecEvent        )(void* a, DECEVENTTYPE event, void* param);
  void* A;                  /**< only to be used with the precedent functions */

  /* --- DECODER_SAVEDATA */
  xstring      SaveFilename;/**< File where to save the raw stream. */

} DECODER_PARAMS2;

`DECODER_SETUP`

The DECODER_SETUP command is used to pass callback pointers to the decoder engine. But the decoder could use it to do other initializations as well.

Parameters

The following fields of the DECODER_PARAMS2 structure are guaranteed to be valid at this call:

OutRequestBuffer
OutCommitBuffer
DecEvent
A

All other fields should not be accessed during the processing of DECODER_SETUP as their content is undefined.

Return value

PLUGIN_OK: Every thing is fine.
PLUGIN_GO_ALREADY: The decoder in in an invalid state (already playing).
PLUGIN_ERROR: Internal error in the plugin => cancel processing.

`DECODER_PLAY`

This command kicks off the decoder thread to start decoding of an URL. The command implicitly implies the DECODER_JUMPTO command if the JumpTo field in DECODER_PARAMS2 is grater than zero.

Parameters

The following fields of the DECODER_PARAMS2 structure are guaranteed to be valid at this call:

URL
Info
JumpTo (see DECODER_JUMPTO)
Fast

DECODER_PLAY should not wait for data to become available. It should also not wait for the desired URL to open, because this could lead to time-outs.

When a decoder starts playing it might start at a certain location of the target rather than the beginning of the song. In this case JumpTo is set to the starting position. Otherwise it is 0.
If a start position makes no sense e.g. because the source is an internet radio stream, the decoder should ignore this and just start decoding. It is not an error that JumpTo is greater than zero in this case.

Return value

PLUGIN_OK: Every thing is fine decoding starts in background. The OutRequestBuffer/OutCommitBuffer callbacks are called asynchronously when decoded data is available.
PLUGIN_GO_ALREADY: The decoder in in an invalid state (already playing).
PLUGIN_GO_FAILED: The decoder could not start decoding of the requested URL.
In general this error should be used rarely, because it is synchronously and you cannot pass a descriptive error text to PM123. You should call the DecEvent and message_display callbacks from the decoder thread instead.

`DECODER_STOP`

The stop command resets the decoder into it's initial state. It could take a while for this command to complete, i.e. until no more callbacks to OutRequestBuffer/OutCommitBuffer are on the way. DECODER_STOP must not wait for that condition or deadlocks may occur. PM123 considers DECODER_STOP to have completed as soon as decoder_status returns DECODER_STOPPED.

Parameters

DECODER_STOP does not have parameters.

Return value

PLUGIN_OK: Every thing is fine decoding will stop shortly.
PLUGIN_GO_ALREADY: The decoder in in an invalid state (e.g. already stopped).

The return value of the DECODER_STOP is currently ignored by PM123.

`DECODER_JUMPTO`

Interrupt decoding immediately and continue at a certain position of the source. The command should not wait for the seek operation to complete.

Parameters

The JumpTo field points to a location from the start of the current object in seconds where the decoding should continue.
The position should be rounded to the closest sample.

Return value

PLUGIN_OK: Every thing is fine decoding will continue at the given location shortly.
PLUGIN_UNSUPPORTED: The decoder cannot seek within the current URL.

`DECODER_FFWD`

Change fast forward/rewind mode. This could happen before DECODER_PLAY if playback should immediately start in scan mode. In case decoding should start in rewind mode the following DECODER_PLAY command will always set the JumpTo filed to a location close to the end of the current URL.

A DECODER_FFWD command is usually preceded by DECODER_JUMPTO to reset the decoding position to the current playing position.

Parameters

The field Fast will contain the new mode.

Return value

PLUGIN_OK: Every thing is fine.
PLUGIN_UNSUPPORTED: The decoder cannot fast forward/rewind within the current URL. It is valid that DECODER_FORWARD is supported for a certain stream while DECODER_REWIND is not.

`DECODER_SAVEDATA`

Save the raw stream to a file. The decoder should append an existing file.

Parameters

SaveFilename contains the name/URL of the file where to save the stream data. If SaveFilename is NULL then stream saving should be turned off.

Return value

PLUGIN_OK: Every thing is fine.
PLUGIN_NO_SAVE: SaveFilename cannot be used.
PLUGIN_UNSUPPORTED: The decoder does not support saving the stream.