IVSPlayer

Objective-C


@interface IVSPlayer : NSObject

Swift

class IVSPlayer : NSObject

An object to control and observe audio video content.

  • An optional delegate object to receive state changes and other events.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<IVSPlayerDelegate> delegate;

    Swift

    weak var delegate: IVSPlayerDelegate? { get set }

  • Indicates whether adaptive bitrate (ABR) streaming is allowed. Default: true.

    Declaration

    Objective-C

    @property (nonatomic) BOOL autoQualityMode;

    Swift

    var autoQualityMode: Bool { get set }

  • Indicates whether the player loops the content when possible. Default: false.

    Declaration

    Objective-C

    @property (nonatomic) BOOL looping;

    Swift

    var looping: Bool { get set }

  • Logging level for the player. Default is IVSLogLevelError.

    Declaration

    Objective-C

    @property (nonatomic) IVSLogLevel logLevel;

    Swift

    var logLevel: IVSPlayer.LogLevel { get set }

  • For a live stream, the latency from the server to the player. Note: For non-live streams, this value is not meaningful.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CMTime liveLatency;

    Swift

    var liveLatency: CMTime { get }

  • The audio-muting state of the player. Default: false.

    Declaration

    Objective-C

    @property (nonatomic) BOOL muted;

    Swift

    var muted: Bool { get set }

  • The video-playback rate. Supported range: 0.5 to 2.0. Default: 1.0 (normal).

    Declaration

    Objective-C

    @property (nonatomic) float playbackRate;

    Swift

    var playbackRate: Float { get set }

  • Volume of the audio track, if any. Supported range: 0.0 to 1.0. Default: 1.0 (max).

    Declaration

    Objective-C

    @property (nonatomic) float volume;

    Swift

    var volume: Float { get set }

  • Average source media bitrate of the stream in bits per second (bps).

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSInteger averageBitrate;

    Swift

    var averageBitrate: Int { get }

  • Current approximate bandwidth estimate in bits per second (bps).

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSInteger bandwidthEstimate;

    Swift

    var bandwidthEstimate: Int { get }

  • Remaining duration of buffered content.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CMTime buffered;

    Swift

    var buffered: CMTime { get }

  • Total duration of the loaded media stream.

    This property is key-value observable.

    See

    -[IVSPlayerDelegate player:didChangeDuration]

    Declaration

    Objective-C

    @property (nonatomic, readonly) CMTime duration;

    Swift

    var duration: CMTime { get }

  • Playback position.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CMTime position;

    Swift

    var position: CMTime { get }

  • Synchronized time.

    The synchronized time is a UTC time that represents a specific time during playback, at a granularity of 1 second. It can be used to sync external events and state to a specific moment during playback.

    Note that there’s an event dispatched when this value changes:

    See

    -[IVSPlayerDelegate player:didChangeSyncTime:]

    Declaration

    Objective-C

    @property (nonatomic, readonly) CMTime syncTime;

    Swift

    var syncTime: CMTime { get }

  • URL of the loaded media, if any.

    This property is key-value observable.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSURL *path;

    Swift

    var path: URL? { get }

  • Current quality being played, if any.

    This property returns nil before an initial quality has been determined.

    Setting this to a nonnull value implicitly disables autoQualityMode and switches to the new value immediately. Setting the property to nil implicitly enables autoQualityMode, and a new quality will be selected asynchronously.

    This property is key-value observable.

    See

    -[IVSPlayerDelegate player:didChangeQuality:]

    Declaration

    Objective-C

    @property (nonatomic, nullable) IVSQuality *quality;

    Swift

    var quality: IVSQuality? { get set }

  • Quality objects from the loaded source or empty if none are currently available. The qualities will be available after the IVSPlayerStateReady state has been entered. This contains the qualities that can be assigned to quality. Note that this set will contain only qualities capable of being played on the current device and not all those present in the source stream.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSArray<IVSQuality *> *_Nonnull qualities;

    Swift

    var qualities: [IVSQuality] { get }

  • The player’s version, in the format of MAJOR.MINOR.PATCH-HASH.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSString *_Nonnull version;

    Swift

    var version: String { get }

  • Bitrate of the media stream.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSInteger videoBitrate;

    Swift

    var videoBitrate: Int { get }

  • Number of video frames that were decoded.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSInteger videoFramesDecoded;

    Swift

    var videoFramesDecoded: Int { get }

  • Number of video frames that were dropped.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSInteger videoFramesDropped;

    Swift

    var videoFramesDropped: Int { get }

  • Native size of the current video source, in pixels. Default: CGSizeZero until the first frame is rendered.

    This property is key-value observable.

    See

    -[IVSPlayerDelegate player:didChangeVideoSize:]

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGSize videoSize;

    Swift

    var videoSize: CGSize { get }

  • The state of the player.

    This property is key-value observable.

    See

    -[IVSPlayerDelegate player:didChangeState:]

    Declaration

    Objective-C

    @property (nonatomic, readonly) IVSPlayerState state;

    Swift

    var state: IVSPlayer.State { get }

  • Fatal error encountered during playback.

    This property is key-value observable.

    See

    -[IVSPlayerDelegate player:didFailWithError:]

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSError *error;

    Swift

    var error: Error? { get }

  • Indicates whether live low-latency streaming is enabled for the current stream.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isLiveLowLatency) BOOL liveLowLatency;

    Swift

    var isLiveLowLatency: Bool { get }

  • Loads the stream at the specified URL and prepares the player for playback.

    Declaration

    Objective-C

    - (void)load:(nullable NSURL *)path;

    Swift

    func load(_ path: URL?)

    Parameters

    path

    Location of the streaming manifest, clip, or file.

  • A unique identifier for the current playback session. This session identifier can be shared with support or displayed in an user interface to help troubleshoot or diagnose playback issues with the currently playing stream.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSString *_Nonnull sessionId;

    Swift

    var sessionId: String { get }

  • Pauses playback. state transitions to IVSPlayerStateIdle.

    Declaration

    Objective-C

    - (void)pause;

    Swift

    func pause()

  • Starts or resumes playback of the current stream, if no stream is loaded indicates intent to play and the player will automatically play on a subsequent load call. On success depending on the type of stream the player state will change to IVSPlayerStateBuffering and then IVSPlayerStatePlaying or just IVSPlayerStatePlaying. On failure invokes the error delegate.

    Declaration

    Objective-C

    - (void)play;

    Swift

    func play()

  • Seeks to the given time in the stream and begins playing at that position if play() has been called. If no stream is loaded the seek will be be deferred until load is called. On success depending on the type of stream the player state will change to IVSPlayerStateBuffering and then State::Playing or remain in IVSPlayerStatePlaying. The position will update to the seeked time. On failure invokes the error delegate.

    Declaration

    Objective-C

    - (void)seekTo:(CMTime)position;

    Swift

    func seek(to position: CMTime)

    Parameters

    position

    Seek position.

  • Sets the playback time to the specified value and invokes a completion handler when done.

    Declaration

    Objective-C

    - (void)seekTo:(CMTime)position
    completionHandler:(nonnull void (^)(BOOL))completionHandler;

    Swift

    func seek(to position: CMTime) async -> Bool

    Parameters

    position

    Seek position.
    completionHandler

    A block to invoke on the main queue when done. This takes one parameter, indicating whether seeking was successful.

  • Enable low-latency mode when encountering a compatible live stream. Default: true.

    See

    liveLowLatency property, which is true when this mode is enabled for the stream.

    Declaration

    Objective-C

    - (void)setLiveLowLatencyEnabled:(BOOL)enable;

    Swift

    func setLiveLowLatencyEnabled(_ enable: Bool)

    Parameters

    enable

    Whether to enable this mode when available.

  • Set the initial starting bitrate when using auto quality mode. This determines the initial quality for an adaptive stream, when no bandwidth estimate value has been determined. Applied on the next call to the -[IVSPlayer load:] method.

    Declaration

    Objective-C

    - (void)setAutoInitialBitrate:(NSInteger)bitrate;

    Swift

    func setAutoInitialBitrate(_ bitrate: Int)

    Parameters

    bitrate

    Initial bitrate to use.

  • Set the maximum bitrate when using auto quality mode. This can be used to control resource usage. The bitrate you provide here is applied to the current stream as well as future streams loaded by the player.

    Declaration

    Objective-C

    - (void)setAutoMaxBitrate:(NSInteger)bitrate;

    Swift

    func setAutoMaxBitrate(_ bitrate: Int)

    Parameters

    bitrate

    Maximum bitrate to use.

  • Sets the maximum quality the player is allowed to auto-switch up to (if ABR is enabled) using the input quality’s bitrate value. This allows you to control resource usage. The IVSQuality you provide here is applied to the current stream. If you load a new stream, call this again after IVSPlayerStateReady.

    Declaration

    Objective-C

    - (void)setAutoMaxQuality:(nullable IVSQuality *)quality;

    Swift

    func setAutoMaxQuality(_ quality: IVSQuality?)

    Parameters

    quality

    Maximum quality to use.

  • Enable skipping to the live edge on a rebuffer. Note this can cause video content and content associated with it such as timed metadata to be skipped. Defaults to false.

    Declaration

    Objective-C

    - (void)setRebufferToLive:(BOOL)enable;

    Swift

    func setRebufferToLive(_ enable: Bool)

  • Sets the initial (minimum) buffer duration required to start playback. If a value outside the allowable range is used, the current value is maintained. The allowable range is 0.1 to 5.0 seconds. Defaults to 1s in low latency mode, 2s otherwise. Lowering this value may increase rebuffering.

    Declaration

    Objective-C

    - (void)setInitialBufferDuration:(CMTime)duration;

    Swift

    func setInitialBufferDuration(_ duration: CMTime)

    Parameters

    duration

    Duration of the initial buffer.

  • Sets the max video display size of the player. This prevents switching to qualities above the specified resolution when autoQualityMode is true.

    Declaration

    Objective-C

    - (void)setMaxVideoSize:(CGSize)size;

    Swift

    func setMaxVideoSize(_ size: CGSize)

    Parameters

    size

    Maximum video display size

  • When quality is nil or adaptive is false, this method behaves exactly like setQuality:, the setter for the quality property. Otherwise, with adaptive and a nonnull quality, the player will attempt a seamless quality switch asynchronously. This avoids playback interruption, and the new quality will be reported via the delegate method -[IVSPlayerDelegate player:didChangeQuality:].

    Setting the property to nil implicitly enables autoQualityMode, and a new quality will be selected asynchronously. In this case the adaptive parameter is ignored, as this is always an adaptive change.

    See

    quality property

    See

    -[IVSPlayerDelegate player:didChangeQuality:]

    Declaration

    Objective-C

    - (void)setQuality:(nonnull IVSQuality *)quality adaptive:(BOOL)adaptive;

    Swift

    func setQuality(_ quality: IVSQuality, adaptive: Bool)

  • Sets the HTTP ‘Origin’ header on all outgoing requests.

    Declaration

    Objective-C

    - (void)setOrigin:(nullable NSURL *)origin;

    Swift

    func setOrigin(_ origin: URL?)

    Parameters

    origin

    The HTTP ‘Origin’ header value.

  • Sets the network recovery mode for handling network interruptions. Applied on the next call to the -[IVSPlayer load:] method.

    Declaration

    Objective-C

    - (void)setNetworkRecoveryMode:
    (IVSPlayerNetworkRecoveryMode)networkRecoveryMode;

    Swift

    func setNetworkRecoveryMode(_ networkRecoveryMode: IVSPlayer.NetworkRecoveryMode)

    Parameters

    networkRecoveryMode

    The network recovery mode.

IVSPlayerTimeObservation

  • Requests to invoke block on queue at repeating interval.

    See

    -[AVPlayer addPeriodicTimeObserverForInterval:queue:usingBlock:]

    Declaration

    Objective-C

    - (nonnull id)
    addPeriodicTimeObserverForInterval:(CMTime)interval
                                 queue:(nullable dispatch_queue_t)queue
                            usingBlock:(nonnull void (^)(CMTime))block;

    Swift

    func addPeriodicTimeObserver(forInterval interval: CMTime, queue: dispatch_queue_t?, using block: @escaping (CMTime) -> Void) -> Any

    Parameters

    interval

    Duration between block invocations, in terms of playback time.
    queue

    The queue where the block should be enqueued. If nil, the main queue is used.
    block

    The block to be invoked after each interval.

    Return Value

    An object which must be retained for as long as this observer is active. Pass this object to -removeTimeObserver: to end observation.

  • Requests to invoke block at designated playback times.

    See

    -[AVPlayer addBoundaryTimeObserverForTimes:queue:usingBlock:]

    Declaration

    Objective-C

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

    Swift

    func addBoundaryTimeObserver(forTimes times: [NSValue], queue: dispatch_queue_t?, using block: @escaping () -> Void) -> Any

    Parameters

    times

    An array of timestamps to invoke the block. In Objective-C, use [NSValue valueWithCMTime:] to wrap each value. In Swift, an array of CMTime values can be passed directly using as [NSValue].
    queue

    The queue where the block should be enqueued. If nil, the main queue is used.
    block

    The block to be invoked when any of the times is passed during playback.

    Return Value

    An object which must be retained for as long as this observer is active. Pass this object to -removeTimeObserver: to end observation.

  • Removes a registered observer and cancels all future invocations.

    See

    -[AVPlayer removeTimeObserver:]

    Declaration

    Objective-C

    - (void)removeTimeObserver:(nonnull id)observer;

    Swift

    func removeTimeObserver(_ observer: Any)