VideoPlayerSyncController

@interface VideoPlayerSyncController : NSObject

@brief A class to synchronise the playback of a video player (VideoPlayerViewController) to a timeline representing the desired playback progress of the media object.

@discussion It needs a reference to a video player (VideoPlayerViewController instance) and a CorrelatedClock representing the expected timeline of the video object. This controller reads the actual and expected timeline positions of the video item and determines the discrepancy between both readings. Based on the size of the discrepancy, it applies a simple strategy to adapt the playback of the video player to achieve the expected playback position.

The resync process happens every ‘syncInterval’ seconds or when changes to the expectedTimeline are observed.

Ideas for future iterations of this component: 1. Allow for different playback adaptation algorithms e.g. QoE-aware algo to be plugged in at configuration time 2. Generalise component to synchronise media player timelines instead of actual players. Players will respond to changes in their timelines.

Properties

syncTimeline
A media timeline to synchronise to.
Declaration
Objective-C

@property (nonatomic, weak) CorrelatedClock *syncTimeline
mediaObjectTimeline
The expected timeline of the media object. Set using correlation timestamp supplied at initialisation time.
Declaration
Objective-C

@property (readonly, nonatomic) int *mediaObjectTimeline;
Swift

var mediaObjectTimeline: UnsafeMutablePointer


                    
                    
                    videoPlayer

A video player to synchronise.

Declaration

Objective-C

@property (nonatomic, weak) VideoPlayerViewController *videoPlayer


                    
                    
                    syncInterval

Synchronisation interval

Declaration

Objective-C

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

Swift

var syncInterval: TimeInterval { get set }


                    
                    
                    state

This sync controller’s state

Declaration

Objective-C

@property (readonly, nonatomic) VideoSyncControllerState state;

Swift

var state: VideoSyncControllerState { get }


                    
                    
                    delegate

A delegate to report resynchronisation status.

Declaration

Objective-C

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

Swift

weak var delegate: SyncControllerDelegate! { get set }


                    
                    
                    syncJitter

The jitter in media playback when resynchronising

Declaration

Objective-C

@property (readonly, nonatomic) NSTimeInterval syncJitter;

Swift

var syncJitter: TimeInterval { get }

reSyncJitterThreshold
The threshold on the difference between expected and actual playback position, for which to trigger a resynchronisation. E.g. for values lower than a video frame duration, no resync needs to be done.
Declaration
Objective-C

@property (readonly, nonatomic) NSTimeInterval reSyncJitterThreshold;
Swift

var reSyncJitterThreshold: TimeInterval { get }
rateAdaptationJitterThreshold
A threshold for doing playback rate adaptation (increase/decrease speed) to allow the player to catchup/slow down. For a jitter value less than this threshold, a rate increase of 0.5 is applied to enable the player to be in sync. For a jitter value greater than this threshold, it is assumed that the discrepancy is too large for catchup by playback rate adjustment. A seek operation is performed on the player.
Declaration
Objective-C

@property (assign, readwrite, nonatomic) NSTimeInterval rateAdaptationJitterThreshold;
Swift

var rateAdaptationJitterThreshold: TimeInterval { get set }

Initialisers


                    
                    
                    -init

Undocumented

Declaration

Objective-C

@interface VideoPlayerSyncController : NSObject


                    
                    
                    -initWithVideoPlayer:Timeline:CorrelationTimestamp:

Initialises a VideoPlayerSyncController with a videoplayer and a timeline to synchronise to.

Declaration

Objective-C

- (instancetype)initWithVideoPlayer:(id)videoplayer
                           Timeline:(id)sync_timeline
               CorrelationTimestamp:(id)correlation;

Swift

init!(videoPlayer videoplayer: Any!, timeline sync_timeline: Any!, correlationTimestamp correlation: Any!)

Parameters

`videoplayer`	a VideoPlayerViewController instance
`timeline`	a CorrelatedClock instance modelling a particular timeline

Return Value

initialised VideoPlayerSyncController instance


                    
                    
                    -initWithVideoPlayer:Timeline:CorrelationTimestamp:ReSyncInterval:

Initialises a VideoPlayerSyncController with a videoplayer and a timeline to synchronise to.

Declaration

Objective-C

- (instancetype)initWithVideoPlayer:(id)videoplayer
                           Timeline:(id)sync_timeline
               CorrelationTimestamp:(id)correlation
                     ReSyncInterval:(NSTimeInterval)interval_secs;

Swift

init!(videoPlayer videoplayer: Any!, timeline sync_timeline: Any!, correlationTimestamp correlation: Any!, reSyncInterval interval_secs: TimeInterval)

Parameters

`videoplayer`	a VideoPlayerViewController instance
`timeline`	a CorrelatedClock instance modelling a particular timeline
`interval_secs`	resynchronisation interval in seconds (as a double value)

Return Value

initialised VideoPlayerSyncController instance


                    
                    
                    -initWithVideoPlayer:Timeline:CorrelationTimestamp:ReSyncInterval:Delegate:

Initialises a VideoPlayerSyncController with a videoplayer and a timeline to synchronise to.

Declaration

Objective-C

- (instancetype)initWithVideoPlayer:(id)videoplayer
                           Timeline:(id)sync_timeline
               CorrelationTimestamp:(id)correlation
                     ReSyncInterval:(NSTimeInterval)interval_secs
                           Delegate:(id<SyncControllerDelegate>)delegate;

Swift

init!(videoPlayer videoplayer: Any!, timeline sync_timeline: Any!, correlationTimestamp correlation: Any!, reSyncInterval interval_secs: TimeInterval, delegate: SyncControllerDelegate!)

Parameters

`videoplayer`	a VideoPlayerViewController instance
`timeline`	a CorrelatedClock instance modelling a particular timeline
`interval_secs`	resynchronisation interval in seconds (as a double value)
`delegate`	a delegate object (conforming to VideoSyncControllerDelegate protocol) to receive callbacks

Return Value

initialised VideoPlayerSyncController instance

Class Factory Methods


                    
                    
                    +syncControllerWithVideoPlayer:SyncTimeline:CorrelationTimestamp:

Creates an instance of VideoPlayerSyncController initialised with a video player and a synchronisation timelime (the timeline to synchronise to).

Declaration

Objective-C

+ (instancetype)syncControllerWithVideoPlayer:(id)videoplayer
                                 SyncTimeline:(id)sync_timeline
                         CorrelationTimestamp:(id)correlation;

Swift

convenience init!(videoPlayer videoplayer: Any!, syncTimeline sync_timeline: Any!, correlationTimestamp correlation: Any!)

Parameters

`videoplayer`	a VideoPlayerViewController object
`sync_timeline`	a CorrelatedClock object representing a synchronisation timeline

Return Value

initialised VideoPlayerSyncController instance


                    
                    
                    +syncControllerWithVideoPlayer:SyncTimeline:CorrelationTimestamp:AndDelegate:

Creates an instance of VideoPlayerSyncController initialised with a video player, a synchronisation timelime (the timeline to synchronise to) and a delegate to receive callbacks.

Declaration

Objective-C

+ (instancetype)syncControllerWithVideoPlayer:(id)videoplayer
                                 SyncTimeline:(id)sync_timeline
                         CorrelationTimestamp:(id)correlation
                                  AndDelegate:
                                      (id<SyncControllerDelegate>)delegate;

Swift

convenience init!(videoPlayer videoplayer: Any!, syncTimeline sync_timeline: Any!, correlationTimestamp correlation: Any!, andDelegate delegate: SyncControllerDelegate!)

Parameters

`videoplayer`	a VideoPlayerViewController object
`sync_timeline`	a CorrelatedClock object representing a synchronisation timeline
`delegate`	an object conforming to the VideoSyncControllerDelegate protocol

Return Value

initialised VideoPlayerSyncController instance


                    
                    
                    +syncControllerWithVideoPlayer:SyncTimeline:CorrelationTimestamp:AndSyncInterval:

Creates an instance of VideoPlayerSyncController initialised with a video player and a synchronisation timelime (the timeline to synchronise to). Resynchronisation of the player occurs every ‘resync_interval’ seconds.

Declaration

Objective-C

+ (instancetype)syncControllerWithVideoPlayer:(id)videoplayer
                                 SyncTimeline:(id)sync_timeline
                         CorrelationTimestamp:(id)correlation
                              AndSyncInterval:(NSTimeInterval)resync_interval;

Swift

convenience init!(videoPlayer videoplayer: Any!, syncTimeline sync_timeline: Any!, correlationTimestamp correlation: Any!, andSyncInterval resync_interval: TimeInterval)

Parameters

`videoplayer`	a VideoPlayerViewController object
`sync_timeline`	a CorrelatedClock object representing a synchronisation timeline
`resync_interval`	resynchronisation interval in seconds

Return Value

initialised VideoPlayerSyncController instance


                    
                    
                    +syncControllerWithVideoPlayer:SyncTimeline:CorrelationTimestamp:SyncInterval:AndDelegate:

Creates an instance of VideoPlayerSyncController initialised with a video player, a synchronisation timelime (the timeline to synchronise to) and a delegate to receive callbacks. Resynchronisation of the player occurs every ‘resync_interval’ seconds.

Declaration

Objective-C

+ (instancetype)syncControllerWithVideoPlayer:(id)videoplayer
                                 SyncTimeline:(id)sync_timeline
                         CorrelationTimestamp:(id)correlation
                                 SyncInterval:(NSTimeInterval)resync_interval
                                  AndDelegate:
                                      (id<SyncControllerDelegate>)delegate;

Swift

convenience init!(videoPlayer videoplayer: Any!, syncTimeline sync_timeline: Any!, correlationTimestamp correlation: Any!, syncInterval resync_interval: TimeInterval, andDelegate delegate: SyncControllerDelegate!)

Parameters

`videoplayer`	a VideoPlayerViewController object
`sync_timeline`	a CorrelatedClock object representing a synchronisation timeline
`resync_interval`	resynchronisation interval in seconds
`delegate`	an object conforming to the VideoSyncControllerDelegate protocol

Return Value

initialised VideoPlayerSyncController instance

Actions

-start
Start the synchronisation process.
Declaration
Objective-C

- (void)start;
Swift

func start()
-stop
Stop the synchronisation process.
Declaration
Objective-C

- (void)stop;
Swift

func stop()