iOS Player SDK Changelog

The Twilio Player SDK use Semantic Versioning.

1.1.0 (Mar 15, 2022)

Enhancements

• Added arm64 simulator support to the Live Player SDK.
• This version of Player SDK is built using Xcode 13.0.0.
• Reduced occurrences of freezing during quality switches when playing recorded content.

Bug fixes

• Fixed stuttering when playing a stream from a source media playlist.
• Fixed rare crashes that could occur during app termination and media-service reset event.
• Fixed warning that umbrella header for module 'TwilioLivePlayer' does not include header 'TPLDefaultLogger.h'

1.0.1 (December 10, 2021)

Enhancements

• Added new Logger APIs. Developers can now implement Logger protocol and supply custom logger by setting the Player.logger property. If no custom logger is supplied, the SDK will use DefaultLogger by default. The Player SDK will send the log messages to the Logger instance based on the log level set using the player.logLevel property.

Bug fixes

• Fixed a bug where a loaded stream could play without the play method being called, during a network reconnect.
• Improved player stability by reducing occurrences of rare crashes.

1.0.0 (October 19, 2021)

We are making 1.0.0 Generally Available following a successful private beta period. Thank you to all of our private beta users for providing feedbacks on Twilio Live Player SDK.

• Twilio Live Player SDK API docs
• Twilio Live docs

Size Impact

1.0.0-preview10 (October 6, 2021)

Breaking API Update

• Moved all SDK APIs from TwilioPlayer package to TwilioLivePlayer.
• Improved the PlayerView APIs. You can render media content on of a stream by setting a playerView property on a Player.

player.playerView = playerView

Bug fixes and Improvements

• Improved the performance of the player's adaptive bitrate streaming algorithm.
• Improved player stability by reducing occurrences of rare crashes.
• Fixed an issue in which the memory heap size of the player continues to increase during playback until the player is deallocated.
• Fixed a potential deadlock when there is animation on top of video playback (e.g., a UI animation or GIF image).
• Fixed a potential crash during media-services reset events.
• Updated background-video handling to not decode content if the output surface is not set.
• Reduced iOS library file size through optimization.
• Improved playback behavior when there is bad data in the video by ignoring it and continuing playback rather than stopping playback.
• Fixed an issue where a loaded stream could play without the play method being called during a network reconnect.
• Fixed an issue where the player stayed in the PLAYING state after a stream disconnect, instead of moving to the ENDED state.

Size Impact

1.0.0-preview9 (August 6, 2021)

Features

• This release supports playing video contents of a live stream. The PlayerView class is subclass of UIView. To render a stream on your iPhone screen, instantiate a PlayerView and set the player property.

playerView.player = self.player

Bug fixes

• Fixed a bug where UI elements were not interactable when placed on a PlayerView.

Size Impact

1.0.0-preview8 (August 4, 2021)

Breaking API Changes

• Player.connect(...) has been updated to accept a Twilio Access Token with a PlaybackGrant whose type is a JSON object instead of a stringified JSON. Providing a playback grant as stringified JSON as recommended from 1.0.0-preview5 through 1.0.0-preview7 will result in an Player.Error.accessTokenInvalidError error.

Size Impact

1.0.0-preview7 (July 28, 2021)

Changes

• The SDK will now retry connecting to a stream when a recoverable error is detected upon the invocation of Player.connect(...).

Size Impact

1.0.0-preview6 (July 22, 2021)

API Updates

• Defined new error codes

• Removed Player.Error.UnknownError error code.

Bug fixes

• Fixed a potential crash during media-services reset events.
• Stop quality reporting when playerDidFailWithError is emitted.

Size Impact

1.0.0-preview5 (July 9, 2021)

Breaking API Changes

• Player.connect(accessToken: token, delegate: observer) has been updated to accept a Twilio Access Token with a PlaybackGrant. Please note that the 1.0.0-preview5 Player SDKs are not backwards compatible with the previously generated AccessTokens.
• Removed .connecting player state. The TwilioPlayer.connect(..) API returns a Player in .idle state.
• Removed playerSid property from Player, TelemetryDataConnection, TelemetryDataPlayback, TelemetryDataPlaybackQuality, TelemetryDataPlaybackState and TimedMetadataTelemetry classes.

Size Impact

1.0.0-preview4 (July 1, 2021)

API Updates

Added a static property Player.isHighLatencyReductionEnabled that is true by default. The Player SDK considers a player.liveLatency value greater than 3 seconds as an occurrence of high latency. When this property is enabled, the Player SDK will periodically inspect player.liveLatency and perform the following when high latency is observed:

1. If the live latency is between 3 and 5 seconds, the Player will increase the playback rate to a value that should not be perceptible to a user. The increased playback rate will allow the Player to catch up to the live source, and will be reverted once the live latency drops below 3 seconds. Application of this strategy may result in audio pitch distortion.

2. If the live latency is greater than or equal to 5 seconds, the Player will seek ahead to near the end of the Player's buffered content. The user will notice skips in the media content when this strategy is applied.

New telemetry events

Size Impact

1.0.0-preview3 (June 16, 2021)

Enhancements

Telemetry

The Telemetry API enables applications to subscribe to event and metric data collected by the Player SDK. Telemetry data emitted by the Player SDK can be used to track stream quality, triage issues, and better understand your application's Player SDK usage.

Typed Data Events

The Player SDK represents telemetry data as strongly typed classes. Reference the table below for a summary of the currently reported events.

Usage

The following snippets demonstrate a few examples of how to use the Telemetry API.

Telemetry Logger

The following snippet demonstrates the simplest Telemetry example: Logging all Telemetry events emitted by the Player SDK

let log: OSLog = OSLog.init(subsystem: "com.example.logger", category: "CodeSnippet")

// Subscribe the logger to events
Player.telemetry.subscribe(subscriber)

extension Subscriber: TelemetrySubscriber {
    func didReceiveTelemetryData(_ data: TelemetryData) {
        os_log("TELEMETRY : %@", log: log,  type:.default, "\(data)")
    }
}

// .. When your app no longer wants telemetry data, unsubscribe
Player.telemetry.unsubscribe(subscriber)

Track High Latency

The following snippet demonstrates an example of checking experience quality by tracking any instances of high latency.

Player.telemetry.subscribe(subscriber, predicate: { data in
    if let summary = data as? TelemetryDataPlaybackQualitySummary {
        return summary.playerLiveLatency.value > 3_000_000
    }
    return false;
})

extension Subscriber: TelemetrySubscriber {
    func didReceiveTelemetryData(_ data: TelemetryData) {
        yourAppAnalytics.track("high-latency-detected")
    }
}

Track Connection Errors

The following snippet demonstrates an example of using TelemetryPredicate's to filter on specific Telemetry events.

Player.telemetry.subscribe(subscriber, predicate: { data in
    return data is TelemetryDataConnectionError 
})

extension Subscriber: TelemetrySubscriber {
    func didReceiveTelemetryData(_ data: TelemetryData) {
        yourAppAnalytics.track("connection-error-detected")
    }
}

Size Impact

1.0.0-preview2 (June 3, 2021)

API Updates

• Removed TwilioPlayerSDK class. TwilioPlayerSDK.sdkVersion(), TwilioPlayerSDK.logLevel and TwilioPlayerSDK.connect(accessToken:playerDelegate:) has been moved to Player class. Reference the following snippet to update your application.

1.0.0-preview2

Player.sdkVersion

let player = Player.connect(accessToken: token, delegate: self)

1.0.0-preview1

TwilioPlayerSDK.sdkVersion

let player = TwilioPlayerSDK.connect(accessToken: token, delegate: self)  

• Added playerNetworkDidBecomeUnavailable to the PlayerDelegate protocol. This callback will be invoked when the Player loses network connectivity. Playback is now automatically paused when the network connection is lost, and it is resumed when the connection is restored. Use the playerNetworkDidBecomeUnavailable delegate method to observe network state changes.
• Player.connect(..) throws an exception if the runtime IVS SDK version does not match the build time version.
• PlayerStats.qualities has been moved to Player.availableQualities.
• Player.quality is a writable property now.
• Added Player.streamerSid property for the PlayerStreamer SID.

Enhancements

• Playback is now automatically paused when the network connection is lost, and it is resumed when the connection is restored.
• Improved the accuracy of Player.liveLatency.
• Improved the Adaptive Bitrate Streaming algorithm to improve stream quality more quickly when network connections improve.

Bug fixes

• Improved player stability.
• Fixed an issue which caused an iOS memory increase that could happen over time.
• Added graceful handling of audio hardware problems. Playback is now automatically paused in the event of a media-services reset notification (AVAudioSessionMediaServicesWereResetNotification). Note that a playback error may still occur if media is playing when the reset occurs.
• Added audio-session interruption handling. Playback is now automatically paused when an audio-session interruption begins. When the interruption ends, playback automatically resumes if the player was previously playing and the interruption options indicate that the app should resume playback.

Size Impact

1.0.0-preview1 (April 22, 2021)

The Twilio Player iOS SDK lets you play a stream in your native iOS application.

Connect to a stream

You can connect to a stream with an Access Token using the TwilioPlayerSDK.connect(accessToken:delegate:) API. The connect API returns a Player object in connecting state. You can receive the Player events by passing a PlayerDelegate to the connect API.

AVAudioSession Configuration

Before connecting to a stream, set the AVAudioSession.category to playback and activate the AVAudioSession.

do {
    try AVAudioSession.sharedInstance().setCategory(.playback)
    try AVAudioSession.sharedInstance().setActive(true)
} catch {
    print("!!️ Could not setup AVAudioSession: \(error)")
}

Connect API

let player = TwilioPlayerSDK.connect(accessToken: token, delegate: self)

Playing a stream

When the Player's state changes, the SDK will notify you by invoking playerDidChangePlayerState method on the PlayerDelegate. When the Player is in ready state, you can begin playback by calling play() API.

func playerDidChangePlayerState(player: Player, playerState state: Player.State) {
    if state == .ready {
        player.play()
    }
}

Pause

You can pause a stream by invoking pause() API on a Player.

Timed metadata

Timed Metadata represents data synchronized to a media stream. When timed metadata is received, the Player SDK will notify you by invoking playerDidReceiveTimedMetadata method on the PlayerDelegate.

func playerDidReceiveTimedMetadata(player: Player, metadata: TimedMetadata) {
    print("Received time metadata = \(metadata)")
}

Volume and Mute

• You can audio mute a stream locally by setting the player.mute property to true.
• To change the volume of a stream, set player.volume property. Default is set to 1.0, which is the maximum volume.

PreviewView

The PreviewView class is subclass of UIView. To render a stream on your iPhone screen, instantiate a PreviewView and set the player property.

previewView.player = self.player

Playing a stream in background

When the SDK is playing a stream, the Player SDK will continue playing audio when the app backgrounded if the app's .plist file supports audio background mode.

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

If you are rendering a stream using PreviewView, to continue audio in when the app is backgrounded you should reset previewView.player when the app goes to background.

@objc private func applicationDidEnterBackground(notification: Notification) {
    playerView.player = nil
}

@objc private func applicationDidBecomeActive(notification: Notification) {
    playerView.player = player
}

Network handoff

The player SDK supports the network handoff. Your app may receive playerWillRebuffer callback on PlayerDelegate during the network network handoff.

Size Impact