Overview

The goal of the setPosition() API is to abort the current data being streamed, flush the AV data pipeline and begin streaming from the specified target position as quickly as possible. Note that Rialto's client may call setPosition() whilst a previous seek is in progress and must handle this gracefully, flushing the pipelines and rendering AV from the most recently requested position as soon as possible.

Note that setPosition() may be called by a client before the call to play() to set the start position of playback (default is 0) but this should be processed in the same way.

Seek

@startuml

autonumber

box "Container" #LightGreen
participant Cobalt
participant Starboard
participant GStreamer_client
participant rialtoClient
end box

box "Platform" #LightBlue
participant rialtoServer
participant GStreamer_server
end box

note over Cobalt, GStreamer_client
The Rialto's client should abort any pending needData() requests before calling setPosition and ignore any
needData() requests received before the SEEK_DONE event as they will be stale.
** TODO - document this in the API header file **
end note

Cobalt             ->  Starboard:         SbPlayerSeek2(player, position)
Starboard          ->  GStreamer_client:  gst_element_seek(pipeline, position, GST_SEEK_FLAG_FLUSH)
GStreamer_client   --> Starboard:
Starboard          --> Cobalt:
GStreamer_client   ->  rialtoClient:      setPosition(pipeline_session, position)
rialtoClient       ->  rialtoClient:      clear local cache of any active data requests for pipeline session
rialtoClient       ->  rialtoServer:      setPosition(pipeline_session, position)
rialtoServer       -/  rialtoClient:      notifyPlaybackState(pipeline_session, PLAYBACK_STATE_SEEKING)
rialtoClient       -/  GStreamer_client:  notifyPlaybackState(pipeline_session, PLAYBACK_STATE_SEEKING)
rialtoServer       ->  rialtoServer:      store position as "target position" for sample fulfilment algorithm
rialtoServer       ->  rialtoServer:      stop sending new need data requests
rialtoServer       ->  rialtoServer:      clear local cache of any active data requests for pipeline session
rialtoServer       ->  rialtoServer:      clear buffered samples for pipeline session
rialtoServer       ->  GStreamer_server:  gst_element_seek(pipeline, position, GST_SEEK_FLAG_FLUSH)

note left
Use of the FLUSH flag ensures the
pipeline is flushed when call returns
**TODO - is this correct or do we need**
**to wait for ASYNC_DONE**
end note

GStreamer_server   --> rialtoServer:
rialtoServer       --> rialtoClient:
rialtoClient       --> GStreamer_client:

opt Seek initiated successfully
rialtoServer       -/  rialtoClient:      notifyPlaybackState(pipeline_session, PLAYBACK_STATE_SEEK_DONE)
rialtoClient       -/  GStreamer_client:  notifyPlaybackState(pipeline_session, PLAYBACK_STATE_SEEK_DONE)
else Error initiating seek
rialtoServer       -/  rialtoClient:      notifyPlaybackState(pipeline_session, PLAYBACK_STATE_FAILURE)
rialtoClient       -/  GStreamer_client:  notifyPlaybackState(pipeline_session, PLAYBACK_STATE_FAILURE)
end

rialtoServer       ->  rialtoServer:      trigger need data for all attached sources

ref over GStreamer_client, rialtoServer
Start requesting samples as for regular playback
end ref

@enduml