Synchroniser

@interface Synchroniser : NSObject

A convenience DVB-CSS media synchroniser for Companion Screen Applications. A Synchroniser object is a singleton that will accept media players (each playing a media object) or web views to synchronise against a discovered TV running DVB-CSS set of Companion Synchronisation protocols.

See README.md for usage explanation.

Properties

  • The contentId reported by the TV via CSS-CII protocol. This property is updated before a kSynchroniserStateNotification with

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSString *contentId;

    Swift

    var contentId: String! { get }

  • The status of the ContentId as defined in DVB-CSS specifications

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSString *contentIdStatus;

    Swift

    var contentIdStatus: String! { get }

  • TV content’s presentation status e.g. final, or transitioning to another programme

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSString *presentationStatus;

    Swift

    var presentationStatus: String! { get }

  • Media timelines supported by the TV for synchronisation.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSArray *availableTimelines;

    Swift

    var availableTimelines: [Any]! { get }

  • Material Resolution Service URL

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSString *MRS_URL;

    Swift

    var mrs_URL: String! { get }

  • The selected master device’s CSS-WC server endpoint

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSString *WC_URL;

    Swift

    var wc_URL: String! { get }

  • The selected master device’s CSS-TS server endpoint

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSString *TS_URL;

    Swift

    var ts_URL: String! { get }

  • A local WallClock that is kept synchronised with the TV’s wallclock

    Declaration

    Objective-C

    @property (readonly, nonatomic) int *wallclock;

    Swift

    var wallclock: UnsafeMutablePointer

  • The companion’s copy of the Synchronisation Timeline (for example, the TV’s timeline signalled in the broadcast) For a PTS timeline, selector = urn:dvb:css:timeline:pts, tickrate =90000

    Declaration

    Objective-C

    @property (readonly, nonatomic) int *syncTimeline;

    Swift

    var syncTimeline: UnsafeMutablePointer

  • An offset to add to the time on the synchronisation timeline

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSTimeInterval syncTimelineOffset;

    Swift

    var syncTimelineOffset: TimeInterval { get set }

  • The current synchronisation error on the timeline synchronisation

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSTimeInterval error;

    Swift

    var error: TimeInterval { get }

  • Media synchroniser delegate

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) id<SynchroniserDelegate> delegate;

    Swift

    var delegate: SynchroniserDelegate! { get set }

  • Current media synchroniser state

    Declaration

    Objective-C

    @property (readonly, nonatomic) SynchroniserState state;

    Swift

    var state: SynchroniserState { get }

  • Set YES to enable Status reports via NSNotifications

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL sendNotifications;

    Swift

    var sendNotifications: Bool { get set }

  • Synchronisation accuracy threshold

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSTimeInterval syncThreshold;

    Swift

    var syncThreshold: TimeInterval { get set }

Factory methods

  • Create a singleton instance of a Synchroniser

    Declaration

    Objective-C

    + (instancetype)getInstance;

    Swift

    class func getInstance() -> Self!

    Return Value

    Synchroniser instance

Initialisers

  • Initialiser. On initialisation, the Synchroniser connects to the CSS-CII endpoint cii_service_url to receive CII messages containing contentId, CSS-WC URL, CSS-TS-URL, available-timeine information.

    Declaration

    Objective-C

    - (instancetype)initWithInterDeviceSyncURL:(NSString *)cii_service_url
                                App2AppURL:(NSString *)app2app_url
                          TimelineSelector:(id)timeline_properties;

    Swift

    init!(interDeviceSyncURL cii_service_url: String!, app2AppURL app2app_url: String!, timelineSelector timeline_properties: Any!)

    Parameters

    cii_service_url

    interdevice synchronisation URL
    app2app_url

    app2app server URL
    timeline_properties

    properties of the timeline to select for synchronisation

    Return Value

    initialised Synchroniser instance

  • Initialiser. On initialisation, the Synchroniser connects to the CSS-CII endpoint cii_service_url to receive CII messages containing contentId, CSS-WC URL, CSS-TS-URL, available-timeine information.

    Declaration

    Objective-C

    - (instancetype)initWithInterDeviceSyncURL:(NSString *)cii_service_url
                                App2AppURL:(NSString *)app2app_url
                          TimelineSelector:(id)timeline_properties
                                  Delegate:(id<SynchroniserDelegate>)delegate;

    Swift

    init!(interDeviceSyncURL cii_service_url: String!, app2AppURL app2app_url: String!, timelineSelector timeline_properties: Any!, delegate: SynchroniserDelegate!)

    Parameters

    cii_service_url

    interdevice synchronisation URL
    app2app_url

    app2app server URL
    timeline_properties

    properties of the timeline to select for synchronisation
    delegate

    a SynchroniserDelegate delegate object

    Return Value

    initialised Synchroniser instance

  • Initialiser

    Declaration

    Objective-C

    - (instancetype)initWithInterDeviceSyncURL:(NSString *)cii_service_url
                                App2AppURL:(NSString *)app2app_url
                              MediaObjects:(NSArray *)media_object_list
                          TimelineSelector:(id)timeline_properties;

    Swift

    init!(interDeviceSyncURL cii_service_url: String!, app2AppURL app2app_url: String!, mediaObjects media_object_list: [Any]!, timelineSelector timeline_properties: Any!)

    Parameters

    cii_service_url

    interdevice synchronisation URL
    app2app_url

    app2app server URL
    media_object_list

    list of media players/webviews with loaded media objects and their correlations mapping timestamps from synchronisation timeline to media object’s timeline
    timeline_properties

    properties of the timeline to select for synchronisation

    Return Value

    initialised Synchroniser instance

    • Initialiser. On initialisation, the Synchroniser connects to the CSS-CII endpoint cii_service_url to
    • receive CII messages containing contentId, CSS-WC URL, CSS-TS-URL, available-timeine information.

    * * - parameter: cii_service_url interdevice synchronisation URL * - parameter: media_object_list list of media players/webviews with loaded media objects and their correlations mapping timestamps from synchronisation timeline to media object’s timeline * - parameter: timeline_properties properties of the timeline to select for synchronisation * - parameter: delegate a delegate to receive callback notifications during synchronisation * * - returns: initialised Synchroniser instance

    Declaration

    Objective-C

    - (instancetype)initWithInterDeviceSyncURL:(NSString *)cii_service_url
                              MediaObjects:(NSArray *)media_object_list
                          TimelineSelector:(id)timeline_properties
                                  Delegate:(id<SynchroniserDelegate>)delegate;

    Swift

    init!(interDeviceSyncURL cii_service_url: String!, mediaObjects media_object_list: [Any]!, timelineSelector timeline_properties: Any!, delegate: SynchroniserDelegate!)

    Parameters

    cii_service_url

    interdevice synchronisation URL
    media_object_list

    list of media players/webviews with loaded media objects and their correlations mapping timestamps from synchronisation timeline to media object’s timeline
    timeline_properties

    properties of the timeline to select for synchronisation
    delegate

    a delegate to receive callback notifications during synchronisation

    Return Value

    initialised Synchroniser instance

    • Initialiser. On initialisation, the Synchroniser connects to the CSS-CII endpoint cii_service_url to
    • receive CII messages containing contentId, CSS-WC URL, CSS-TS-URL, available-timeine information.

    * * - parameter: cii_service_url interdevice synchronisation URL * - parameter: App2App_URL the HbbTV 2.0 app2app URL * - parameter: media_object_list list of media players/webviews with loaded media objects and their correlations mapping timestamps from synchronisation timeline to media object’s timeline * - parameter: timeline_properties properties of the timeline to select for synchronisation * - parameter: delegate a delegate to receive callback notifications during synchronisation * * - returns: initialised Synchroniser instance

    Declaration

    Objective-C

    - (instancetype)initWithInterDeviceSyncURL:(NSString *)cii_service_url
                                App2AppURL:(NSString *)app2app_url
                              MediaObjects:(NSArray *)media_object_list
                          TimelineSelector:(id)timeline_properties
                                  Delegate:(id<SynchroniserDelegate>)delegate;

    Swift

    init!(interDeviceSyncURL cii_service_url: String!, app2AppURL app2app_url: String!, mediaObjects media_object_list: [Any]!, timelineSelector timeline_properties: Any!, delegate: SynchroniserDelegate!)

    Parameters

    cii_service_url

    interdevice synchronisation URL
    App2App_URL

    the HbbTV 2.0 app2app URL
    media_object_list

    list of media players/webviews with loaded media objects and their correlations mapping timestamps from synchronisation timeline to media object’s timeline
    timeline_properties

    properties of the timeline to select for synchronisation
    delegate

    a delegate to receive callback notifications during synchronisation

    Return Value

    initialised Synchroniser instance

Actions

  • Add a media object to be synchronised. It creates a SyncController for the media object

    Declaration

    Objective-C

    - (BOOL)addMediaObject:(MediaPlayerObject *)media_obj;

    Swift

    func addMediaObject(_ media_obj: MediaPlayerObject!) -> Bool

    Parameters

    media_obj

    a media player, media item and its correlation

    Return Value

    true if the sync controller for this media object was created and started.

  • Remove media object from synchroniser. The SyncController for the media object is stopped and destroyed.

    Declaration

    Objective-C

    - (BOOL)removeMediaObject:(MediaPlayerObject *)media_obj;

    Swift

    func removeMediaObject(_ media_obj: MediaPlayerObject!) -> Bool

    Parameters

    media_obj

    a MediaPlayerObject instance

    Return Value

    true if the sync controller for this media object was stopped.

  • Enable synchronisation by instantiating DVB-CSS protocol endpoints and protocol handlers.

    @description The Synchroniser first initiates WallClock synchronisation. When the WallClock is sync'ed it performs timeline synchronisation to build an estimate of the TV timeline. Once a TV timeline is available locally, the Synchroniser creates SyncController for every media player registered with it. The SyncController uses a Correlation Timestamp to estimate the expected media timeline and makes the media player adhere to this timeline.

    Declaration

    Objective-C

    - (void)enableSynchronisation:(float)syncThreshold Error:(NSError **)error;

    Swift

    func enableSynchronisation(_ syncThreshold: Float, error: NSErrorPointer)

    Parameters

    syncThreshold

    a target sync accuracy. If this threshold is exceeded, a kSynchroniserSyncAccuracyNotification notification is emitted by the Synchroniser
    error

    an error object if something went wrong; else nil is returned

  • Stops the synchronisation process. For every media object registered with the Synchroniser, this operation stops and destroys the SyncController. It then stops the Timeline Synchronisation by destroying the TimelineSynchroniser and the SynchronisationTimeline clock (also called TVTimeline).

    Declaration

    Objective-C

    - (void)disableSynchronisation:(NSError **)error;

    Swift

    func disableSynchronisation(_ error: NSErrorPointer)