Instance Method

addBoundaryTimeObserverForTimes:queue:usingBlock:

Requests the invocation of a block when specified times are traversed during normal playback.

Declaration

- (id)addBoundaryTimeObserverForTimes:(NSArray<NSValue *> *)times queue:(dispatch_queue_t)queue usingBlock:(void (^)(void))block;

Parameters

times

An array of NSValue objects containing CMTime values representing the times at which to invoke block.

queue

A serial queue onto which block should be enqueued. Passing a concurrent queue is not supported and will result in undefined behavior.

If you pass nil, the main queue is used.

block

The block to be invoked when any of the times in times is crossed during normal playback.

Return Value

An opaque object that you pass as the argument to removeTimeObserver: to stop observation.

Discussion

Boundary times are arbitrary points of interest you define within the media timeline. As these times are traversed during normal playback, the block you provide to this method will be invoked. You must maintain a strong reference to the returned value as long as you want the time observer to be invoked by the player. Each invocation of this method should be paired with a corresponding call to removeTimeObserver:.

The player does not guarantee the callback block will always be invoked for each boundary time. If your times are very close together along the timeline (close enough that the execution of the block for one takes longer than the difference between them) or if a seek causes time to jump over one or more boundary times, time observation for any specific boundary time may not occur. The best practice is therefore to implement the callback block so it always performs its necessary calculations based solely on the player's currentTime.

The following example shows how you could define boundary times for each quarter of playback.

- (void)addBoundaryTimeObserver {
    NSMutableArray *times = [NSMutableArray array];
 
    // Set initial time to zero
    CMTime currentTime = kCMTimeZero;
    // Get asset duration
    CMTime assetDuration = self.asset.duration;
    // Divide the asset duration into quarters
    CMTime interval = CMTimeMultiplyByFloat64(assetDuration, 0.25);
 
    // Build boundary times at 25%, 50%, 75%, 100%
    while (CMTIME_COMPARE_INLINE(currentTime, <, assetDuration)) {
        currentTime = CMTimeAdd(currentTime, interval);
        [times addObject:[NSValue valueWithCMTime:currentTime]];
    }
    // Add time observer
    self.timeObserverToken =
        [self.player addBoundaryTimeObserverForTimes:times
                                               queue:dispatch_get_main_queue()
                                          usingBlock:^{
            // Use weak reference to self
            // Update user interface state
        }];
}

See Also

Observing Time

- addPeriodicTimeObserverForInterval:queue:usingBlock:

Requests the periodic invocation of a given block during playback to report changing time.

- removeTimeObserver:

Cancels a previously registered periodic or boundary time observer.