APIs for media synchronization
Support in HbbTV
Available since: HbbTV 2.0.1 (ETSI TS 102 796 V1.4.1)
Introduction (informative)
This clause defines the API for multi-stream synchronization as defined in clause 10.2.8 and the API for the inter-device synchronization with a media presentation on companion screens.
As the architecture for multi-stream and inter-device synchronization is basically the same, the MediaSynchroniser embedded object defined in clause 8.2.3.2 is the main object for both synchronization features. The sequence diagrams in clause 13.8 provide further indication how the API interacts with the architecture entities.
Example usage for multi-stream synchronization:
Example usage for inter-device synchronization:
JavaScript snippets on HbbTV® terminal:
The MediaSynchroniser embedded object
General
The terminal shall support a non-visual embedded object of type “application/hbbtvMediaSynchroniser” with the following JavaScript API. The terminal shall support one operable MediaSynchroniser embedded object. If an application creates multiple instances only the last one created needs to be operable. A MediaSynchroniser can be used for multi-stream synchronization and for inter-device synchronization.
Properties
readonly Boolean interDeviceSyncEnabled | |
Description | Shall be true if and only if the terminal is currently a master terminal for inter-device synchronization. |
Methods
DOM2 events
When an error occurs for the MediaSynchroniser object then the intrinsic event onError shall be generated and a corresponding DOM level 2 event shall be generated in the following manner:
Intrinsic event | Corresponding DOM 2 event | DOM 2 Event properties |
onError | Error | Bubbles: No Cancelable: No Context Info: lastError, lastErrorSource |
For the intrinsic event onSyncNowAchievable , a corresponding DOM level 2 event shall be generated, in the following manner:
Intrinsic event | Corresponding DOM 2 event | DOM 2 Event properties |
onSyncNowAchievable | SyncNowAchievable | Bubbles: No Cancelable: No Context Info: mediaObject |
For the intrinsic event onSynchroniserInitialised, a corresponding DOM level 2 event shall be generated, in the following manner:
Intrinsic event | Corresponding DOM 2 event | DOM 2 Event properties |
onSynchroniserInitialised | SynchroniserInitialised | Bubbles: No Cancelable: No Context Info: None |
For the intrinsic event on onMediaObjectAdded, a corresponding DOM level 2 event shall be generated, in the following manner:
Intrinsic event | Corresponding DOM 2 event | DOM 2 Event properties |
onMediaObjectAdded | MediaObjectAdded | Bubbles: No Cancelable: No Context Info: mediaObject |
NOTE: These DOM 2 events are directly dispatched to the event target, and will not bubble nor capture. Applications SHOULD NOT rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM 2 event handlers have to call the addEventListener() method on the MediaSynchroniser embedded object. The third parameter of addEventListener(), i.e. “useCapture”, will be ignored.
Error codes
The values of the error property are defined in this clause.
Value | Description | Permanent or Transient |
1 | Synchronization is unachievable because the terminal could not delay presentation of content (represented by a media object added using the addMediaObject() method) sufficiently to synchronize it with the master media. For example: the buffer size for media synchronization is not sufficient. | Transient |
2 | The presentation of media object(that was added using the addMediaObject() method) failed. The specific reason is given by the error handler of that media object. | Transient |
3 | The media or the selected timeline for the media could not be found or the media timeline is no longer present (for media represented by a media object that was added using the addMediaObject() method). | Transient |
4 | Media object is already associated with the MediaSynchroniser. | Transient |
5 | The correlation timestamp set for a media object is null or has an invalid format. | Transient |
6 | Not used. | |
7 | The call failed because the MediaSynchroniser is not yet initialized. | Transient |
8 | The media object has not been added to the MediaSynchroniser using the addMediaObject() method. | Transient |
9 | The media object (that was passed using the addMediaObject() method) is not in a suitable state to participate in synchronization. See clause 9.7.1. | Transient |
10 | Not used. | |
11 | Synchronization is unachievable because the terminal could not present the content (represented by a media object added using the addMediaObject() method) sufficiently early to synchronize it with the master media. | Transient |
13 | The method call failed because the MediaSynchroniser is in a permanent error state or because it has been replaced by a newer initialized MediaSynchroniser. | Transient (see note) |
14 | The presentation of the master media (that was specified as an argument when the initMediaSynchroniser() method was called) failed. The specific reason is given by the error handler of that media object. | Permanent |
15 | Either the master media object or the selected timeline for the master media object (that were specified as arguments when the initMediaSynchroniser() method was called) could not be found or the media timeline is no longer present. | Permanent |
16 | The master media object is not in a suitable state to participate in synchronization. See clause 9.7.1. | Permanent |
17 | The method call failed because the MediaSynchroniser is already initialized. | Transient |
18 | This MediaSynchroniser has been replaced by a new MediaSynchroniser being initialized. | Permanent |
19 | Not used. | |
20 | The combination of streams requested for multi-stream synchronization (by a call to the addMediaObject() method) is unsupported. | Transient |
NOTE: The MediaSynchroniser will already be in a permanent error state. If this error occurs, the MediaSynchroniser remains in the permanent error state. |
Behaviour of the MediaSynchroniser object depending on whether the error is transient or permanent is defined in clauses 13.3.7 and 13.3.8.
The CorrelationTimestamp class
General
Applications shall construct objects that conform to this class definition to deliver correlation timestamps to the terminal. Any object conforms to this class definition if it includes the named properties described in this class definition.
Properties
Number tlvMaster | |
Description | A value on the timeline used by the MediaSynchroniser API. |
Number tlvOther | |
Description | A value on the timeline of a media object that correlates to the value on the timeline used by the MediaSynchroniser API. |
The significance of the properties of this class for both multi-stream and inter-device synchronization are discussed in more detail in clause 13.4.