AudioSyncController

@interface AudioSyncController : NSObject

@brief A class to synchronise the playback of an audio player (AudioPlayer or AudioPlayerViewController) to a timeline representing the desired playback progress of the media object.

@discussion It needs a reference to an audio player (AudioPlayer or AudioPlayerViewController instance) and a CorrelatedClock representing the expected timeline of the audio object. This controller reads the actual and expected timeline positions of the audio 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 audio 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
audioPlayer
An audio player to synchronise.
Declaration
Objective-C

@property (nonatomic, weak) AudioPlayer *audioPlayer


                    
                    
                    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) AudioSyncControllerState state;

Swift

var state: AudioSyncControllerState { 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.
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 AudioSyncController : NSObject


                    
                    
                    -initWithAudioPlayer:Timeline:CorrelationTimestamp:

Initialises an AudioSyncController with a audioplayer and a timeline to synchronise to.

Declaration

Objective-C

- (instancetype)initWithAudioPlayer:(id)audioplayer
                           Timeline:(id)sync_timeline
               CorrelationTimestamp:(id)correlation;

Swift

init!(audioPlayer audioplayer: Any!, timeline sync_timeline: Any!, correlationTimestamp correlation: Any!)

Parameters

`audioplayer`	an AudioPlayer instance
`timeline`	a CorrelatedClock instance modelling a particular timeline

Return Value

initialised AudioSyncController instance


                    
                    
                    -initWithAudioPlayer:Timeline:CorrelationTimestamp:ReSyncInterval:

Initialises an AudioSyncController with a audioplayer and a timeline to synchronise to.

Declaration

Objective-C

- (instancetype)initWithAudioPlayer:(id)audioplayer
                           Timeline:(id)sync_timeline
               CorrelationTimestamp:(id)correlation
                     ReSyncInterval:(NSTimeInterval)interval_secs;

Swift

init!(audioPlayer audioplayer: Any!, timeline sync_timeline: Any!, correlationTimestamp correlation: Any!, reSyncInterval interval_secs: TimeInterval)

Parameters

`audioplayer`	an AudioPlayer instance
`timeline`	a CorrelatedClock instance modelling a particular timeline
`interval_secs`	resynchronisation interval in seconds (as a double value)

Return Value

initialised AudioSyncController instance


                    
                    
                    -initWithAudioPlayer:Timeline:CorrelationTimestamp:ReSyncInterval:Delegate:

Initialises an AudioSyncController with a audioplayer and a timeline to synchronise to.

Declaration

Objective-C

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

Swift

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

Parameters

`audioplayer`	an AudioPlayer 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 AudioSyncControllerDelegate protocol) to receive callbacks

Return Value

initialised AudioSyncController instance

Class Factory Methods


                    
                    
                    +syncControllerWithAudioPlayer:SyncTimeline:CorrelationTimestamp:

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

Declaration

Objective-C

+ (instancetype)syncControllerWithAudioPlayer:(id)audioplayer
                                 SyncTimeline:(id)sync_timeline
                         CorrelationTimestamp:(id)correlation;

Swift

convenience init!(audioPlayer audioplayer: Any!, syncTimeline sync_timeline: Any!, correlationTimestamp correlation: Any!)

Parameters

`audioplayer`	a AudioPlayer object
`sync_timeline`	a CorrelatedClock object representing a synchronisation timeline
`correlation`	a pair of timestamps mapping the synchronisation timeline to the audio object timeline

Return Value

initialised AudioSyncController instance


                    
                    
                    +syncControllerWithAudioPlayer:SyncTimeline:CorrelationTimestamp:AndDelegate:

Creates an instance of AudioSyncController initialised with an audio player and
a synchronisation timelime (the timeline to synchronise to) and a delegate to
receive callbacks. *
- parameter: audioplayer a AudioPlayer object
- parameter: sync_timeline a CorrelatedClock object representing a synchronisation timeline
- parameter: correlation a pair of timestamps mapping the synchronisation timeline to the audio object timeline
- parameter: delegate an object conforming to the AudioSyncControllerDelegate protocol *
- returns: initialised AudioSyncController instance

Declaration

Objective-C

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

Swift

convenience init!(audioPlayer audioplayer: Any!, syncTimeline sync_timeline: Any!, correlationTimestamp correlation: Any!, andDelegate delegate: SyncControllerDelegate!)

Parameters

`audioplayer`	a AudioPlayer object
`sync_timeline`	a CorrelatedClock object representing a synchronisation timeline
`correlation`	a pair of timestamps mapping the synchronisation timeline to the audio object timeline
`delegate`	an object conforming to the AudioSyncControllerDelegate protocol

Return Value

initialised AudioSyncController instance


                    
                    
                    +syncControllerWithAudioPlayer:SyncTimeline:CorrelationTimestamp:AndSyncInterval:

Creates an instance of AudioSyncController initialised with an audio player and
a synchronisation timelime (the timeline to synchronise to). Resynchronisation of the
player occurs every ‘resync_interval’ seconds. *
- parameter: audioplayer a AudioPlayer object
- parameter: sync_timeline a CorrelatedClock object representing a synchronisation timeline
- parameter: correlation a pair of timestamps mapping the synchronisation timeline to the audio object timeline
- parameter: resync_interval resynchronisation interval in seconds *
- returns: initialised AudioSyncController instance

Declaration

Objective-C

+ (instancetype)syncControllerWithAudioPlayer:(id)audioplayer
                                 SyncTimeline:(id)sync_timeline
                         CorrelationTimestamp:(id)correlation
                              AndSyncInterval:(NSTimeInterval)resync_interval;

Swift

convenience init!(audioPlayer audioplayer: Any!, syncTimeline sync_timeline: Any!, correlationTimestamp correlation: Any!, andSyncInterval resync_interval: TimeInterval)

Parameters

`audioplayer`	a AudioPlayer object
`sync_timeline`	a CorrelatedClock object representing a synchronisation timeline
`correlation`	a pair of timestamps mapping the synchronisation timeline to the audio object timeline
`resync_interval`	resynchronisation interval in seconds

Return Value

initialised AudioSyncController instance


                    
                    
                    +syncControllerWithAudioPlayer:SyncTimeline:CorrelationTimestamp:SyncInterval:AndDelegate:

Creates an instance of AudioSyncController initialised with an audio player and
a synchronisation timelime (the timeline to synchronise to). Resynchronisation of the
player occurs every ‘resync_interval’ seconds. *
- parameter: audioplayer a AudioPlayer object
- parameter: sync_timeline a CorrelatedClock object representing a synchronisation timeline
- parameter: correlation a pair of timestamps mapping the synchronisation timeline to the audio object timeline
- parameter: resync_interval resynchronisation interval in seconds
- parameter: delegate an object conforming to the AudioSyncControllerDelegate protocol *
- returns: initialised AudioSyncController instance

Declaration

Objective-C

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

Swift

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

Parameters

`audioplayer`	a AudioPlayer object
`sync_timeline`	a CorrelatedClock object representing a synchronisation timeline
`correlation`	a pair of timestamps mapping the synchronisation timeline to the audio object timeline
`resync_interval`	resynchronisation interval in seconds
`delegate`	an object conforming to the AudioSyncControllerDelegate protocol

Return Value

initialised AudioSyncController 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()