PM123 Output Plug-ins

Output plug-ins must implement and export the functions defined in output_plug.h. There are different interface versions. It is recommended to use level 3.

Interface revision level 3 (recommended)

Initialization interface

The initialization interface does not need to be thread safe.

     ULONG DLLENTRY output_init  (void** a)
     ULONG DLLENTRY output_uninit(void*  a)

• a - Allocate any chunk of memory necessary for the output's function. This pointer will be passed to the other functions.
• return value - PLUGIN_OK (0) means the output was initialized successfully.

The output_init function is called when the user requests the use of your output plug-in. So only one output plug-in is active at any given time. It should initialize the control variables for an eventual call to output_command with OUTPUT_OPEN.
output_uninit is called when another output plug-in is request by the user and should free the allocated memory for a.

Control interface

The control interface does not need to be thread safe itself, but it is called from a different thread than the data interface.

ULONG DLLENTRY output_command(void* a, ULONG msg, OUTPUT_PARAMS2* info)

• msg - one of the following:
  
  • OUTPUT_OPEN opens the device or file needed for output.
    This may happen while the device is already open, if the playback moves to the next file in playlist mode. As long as you do not care about the new filename you should ignore this message in this case.
  • OUTPUT_CLOSE immediately stop playback and close the audio device.
  • OUTPUT_VOLUME changes the volume of an output device.
  • OUTPUT_PAUSE pauses the playback (ie.: block in output_request_buffer()).
  • OUTPUT_SETUP setup the format that output_request_buffer() will most likely receive, event callback.
  • OUTPUT_TRASH_BUFFERS trash any buffers currently awaiting to be played.
• info - structure that contains the parameters needed by the preceding commands
• return value -
  PLUGIN_OK (0) -> O.K.
  others -> MMOS/2 errors or anything else.

There is a lot of commands to implement for this function. Parameters needed for each of them are described in the definition of the OUTPUT_PARAMS2 structure in the output_plug.h file.

The status graph is as follows:

1. OUTPUT_VOLUME
2. OUTPUT_SETUP
3. OUTPUT_OPEN - now we are active. The data interface may be used.
   Optionally repeat this step.
4. OUTPUT_CLOSE - now we are no longer active.

The function codes (OUTPUT_PAUSE and OUTPUT_TRASH_BUFFERS) are allowed only in active mode. OUTPUT_VOLUME is always allowed.

Notes

1. The output plug-in MUST call the event handler output_event with the parameter OUTEVENT_PLAY_ERROR when a playback error occurs. This will stop the playback, but it is not guaranteed that this ist done immediately.
2. The output plug-in must call output_event with OUTEVENT_END_OF_DATA when the last sample is really processed. This must not be done unless the function output_play_samples has been called with a buffer pointer of NULL (flush signal).
3. The output plug-in may raise the events OUTEVENT_LOW_WATER and OUTEVENT_HIGH_WATER to signal that the buffers are running low or the buffers are getting full respectively. This is used by PM123 to control the scheduling priority.
4. The event handler may be called from any thread in any context.
5. The URI parameter at the OUTPUT_OPEN call uses the following syntax:
   file:///D:/Music/my favorite song.mp3
   file://server/share/favorite song.mp3 (UNC path)
   http://... (as you would expect)
   cdda:///H:/track02
   The URI may change during playback. This is signaled with a new OUTPUT_OPEN call. You may ignore this.

Data interface

The data interface is only used when the control interface is in activated state.

The data interface does not need to be thread safe itself, but it is called from a different thread than the control interface.

The level 3 interface allocates the sample buffers by the plug-in rather than the data source. This is known to cause less double buffering. The buffer size is no longer fixed. The functions output_request_buffer and output_commit_buffer have to be called alternatingly. Anything else is an error.

All samples are passed as 16 bit signed integers regardless what type the input has been.

     int DLLENTRY output_request_buffer(void* a, FORMAT_INFO2* format, float** buf)

• format - format of buf.
  This may change during playback but not within a buffer.
• buf [out] - pointer to a storage area where the samples should be placed. A value of NULL indicates that there are no more samples to come (flush signal).
• return value - the number of samples that fit in the returned buffer. The buffer size in bytes is this value multiplied by the number of channels and sizeof(float). Return values ≤ 0 signals a fatal error, except for the flush signal which always returns zero.

This function is called by the decoder or last in chain filter plug-in to store samples for playing. The function call may block until enough buffer space is available.

After a flush request (buf == NULL) there is no need to call output_commit_buffer. The flush signal should be used to play any internal buffers regardless if they are completely full or not.
Note that the flush signal is an implicit request for an OUTEVENT_END_OF_DATA event. The output_request_buffer call must not block until all buffers are played.

     void DLLENTRY output_commit_buffer(void* a, int len, PM123_TIME pos)

• len - used length of buffer in samples.
  The length might be less than the length returned at output_request_buffer. This does not mean that it is a good advise to play a buffer smaller than usual unless you receive a flush signal. A length of 0 is not an error but an undo request to the previous output_request_buffer call.
• pos = position marker to return with output_playing_pos. This is a time index of the starting point of this buffer in seconds. The time position marker may have a large offset far beyond the length of the current file.

This function is called by the decoder or last in chain filter plug-in to play the stored samples.

Status interface

The status interface must be thread safe and reentrant.

     PM123_TIME DLLENTRY output_playing_pos(void* a)

     BOOL  DLLENTRY output_playing_data(void* a)

     ULONG DLLENTRY output_playing_samples(void* a, FORMAT_INFO2* info, float* buf, int len)

• info - return the format of buf.
• buf - return data currently being played.
• len - requested number of data points to be placed in buf. Note that the resulting number of samples depends on the number of channels.

This function is used by visual plug-ins so the user can visualize what is currently being played. len is usually in the order of 2048 samples or less. So check that amount usually required by your visual plug-ins before making complicated buffering functions in your output plug-in.

Interface revision level 0 and 1 (deprecated)

This interface revisions should not be used for development because the impementations tends to modify the current thread's priority to boost the speed of the data source. This implies that the current thread while calling output_play_samples is the bottleneck and that it is always the same thread. Both is not true in general (e.g. remote data sources).

Initialization interface

See level 3 interface. This part of the interface has not been changed.

Control interface

The control interface does not need to be thread safe itself, but it is called from a different thread than the data interface.

ULONG DLLENTRY output_command(void *a, ULONG msg, OUTPUT_PARAMS *info)

• msg - one of the following:
  
  • OUTPUT_OPEN opens the device or file needed for output.
  • OUTPUT_CLOSE closes it.
  • OUTPUT_VOLUME changes the volume of an output device.
  • OUTPUT_PAUSE pauses the playback (ie.: block in output_playsamples()).
  • OUTPUT_SETUP setup the format that output_playsamples() will most likely receive, boost priority values, error_display functions and hwnd.
  • OUTPUT_TRASH_BUFFERS trash any buffers currently awating to be played.
  • OUTPUT_NOBUFFERMODE forces the plug-in to not accumulate buffers for the time being.
    Note: this command is no longer used since PM123 1.40.
• info - structure that contains the parameters needed by the preceding commands
• return value:
  0 -> O.K.
  others -> MMOS/2 errors or anything else

There is a lot of commands to implement for this function. Parameters needed for each of them are described in the definition of the structure in the .h file.

The status graph is as follows:

1. OUTPUT_VOLUME
2. OUTPUT_SETUP
3. OUTPUT_OPEN - now we are active. The data interface may be used.
4. OUTPUT_OPEN - next song
   ...
5. OUTPUT_CLOSE - now we are no longer active.

The other function codes (OUTPUT_PAUSE and OUTPUT_TRASH_BUFFERS) are allowed only in active mode. OUTPUT_VOLUME is always allowed.

The output plug-in MUST WinPostMsg() the following messages to hwnd:

• WM_PLAYERROR when a playback error occures.
• WM_OUTPUT_OUTOFDATA when the output plug-in has finished playing all. its buffers. Not needed when always_hungry flag is enabled.

Data interface

The data interface is only used when the control interface is in activated state.

The data interface does not need to be thread safe itself, but it is called from a different thread than the control interface.

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

• format - format of buf. The format type is always WAVE_FORMAT_PCM and from PM123 version 1.40 the number of bits per sample is always 16. The number of channels may change during playback but not within a buffer.
• buf - data to play.
• len - length of buf.
• posmarker = position marker to return with output_playing_pos.
• return value - the number of bytes from len processed. ie.: < len = error.

This function is called by the decoder or last in chain filter plug-in to play samples.

Status interface

The status interface must be thread safe and reentrant.

     int DLLENTRY output_playing_pos(void* a)

     BOOL  DLLENTRY output_playing_data(void* a)

     ULONG DLLENTRY output_playing_samples(void* a, FORMAT_INFO* info, char* buf, int len)

• info - return the format of buf.
• buf - return len amount of data currently being played.
• len - requested amount of data to be placed in buf.
• return value
  PLUGIN_OK (0) = O.K.
  other = error
  

This function is used by visual plug-ins so the user can visualize what is currently being played. len is usually in the order of 2048 samples or less. So check that amount usually required by your visual plug-ins before making complicated buffering functions in your output plug-in.