Copyright (c) 1998-2001 SpeechWorks International, Inc. All Rights Reserved.
(struct VXIapInterface* pThis,
Triggers playing an audio stream to the caller, non-blocking
This routine is asynchronous, in that it does not block - it only triggers the begin of a play operation. This interface only supports one play operation at a time, however for streaming playback this function will be called multiple times by the client in order to provide the streaming audio as it becomes available from the streaming source. If another play operation is initiated via TriggerPlay( ) before this operation completes, a VXIap_RESULT_BUSY error is returned.
The first call to TriggerStreamingPlay( ) (while the Audio Player is in an IDLE state) initiates a streaming play operation. For streaming plays, every play node will always contain in-memory audio, never a pointer to a file. The MIME content type and number of bytes of audio within each play node will not vary within a single streaming play operation.
The client merely delivers streaming audio as fast as possible, making no attempt to recover from network delays (jitter) during play operations, so the Audio Player should pre-buffer an implementation defined quantity of audio before actually starting playback to avoid underruns. The AP_EVENT_STARTING event must only be delivered once the actual audio starts getting heard by the caller (playback actually starts). If an underflow does occur, the Audio Player must deliver an AP_EVENT_WARNING event with a VXIap_RESULT_STREAM_UNDERFLOW status code to notify the client, then re-build the pre-buffer before resuming playback again.
For flow control, the Audio Player should maintain high and low watermark thresholds. Whenever the amount of buffered audio is less then the implementation defined high watermark, accept audio from TriggerStreamingPlay( ) calls. When that is exceeded, however return a VXIap_RESULT_STREAM_OVERFLOW error to instruct the client to suppress additional audio until the Audio Player delivers an AP_EVENT_RESUME_STREAM event. The Audio Player should only do so when the amount of buffered audio falls below the low watermark. This mechanism, where there is some distance between the low and high watermarks, ensures the flow control is done efficiently by minimizing the amount of times the audio stream is paused and resumed, as those operations are relatively expensive.
When this function returns successfully, ownership of the play node is passed to the Audio Player, which may then modify the previous and next pointers as desired to support the immplementation. The Audio Player is then responsible for calling the Destroy( ) method of each play node as each node is no longer needed. If this function returns an error, however, this function must not have made any changes to the play node (particularly the previous and next pointers), and ownership is returned to the client.
Alphabetic index Hierarchy of classes
This page was generated with the help of DOC++.