Menu

Expand
Rate this page:

iOS Player SDK Changelog

We are no longer allowing new customers to onboard to Twilio Live. Effective November 30, 2023, Twilio Live will End of Life. We have created this Migration Guide to help you identify an alternative solution for your use case.

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'
Architecture Compressed Size Uncompressed Size
Universal 0.8 MB 1.9 MB
arm64 0.8 MB 1.9 MB

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.
Architecture Compressed Size Uncompressed Size
Universal 0.8 MB 1.9 MB
arm64 0.8 MB 1.9 MB

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.

Size Impact

Architecture Compressed Size Uncompressed Size
Universal 0.5 MB 1.2 MB
arm64 0.5 MB 1.2 MB

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

Architecture Compressed Size Uncompressed Size
Universal 0.5 MB 1.2 MB
arm64 0.5 MB 1.2 MB

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

Architecture Compressed Size Uncompressed Size
Universal 1.7 MB 3.7 MB
arm64 1.7 MB 3.7 MB

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

Architecture Compressed Size Uncompressed Size
Universal 1.7 MB 3.7 MB
arm64 1.7 MB 3.7 MB

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

Architecture Compressed Size Uncompressed Size
Universal 1.7 MB 3.7 MB
arm64 1.7 MB 3.7 MB

1.0.0-preview6 (July 22, 2021)

API Updates

  • Defined new error codes
Code Player.Error Description
56000 Player.Error.playbackMediaError An error occurred playing back media content
56001 Player.Error.playbackAuthorizationError A network resource is not authorized
56002 Player.Error.playbackInvalidDataError Data or input is invalid
56003 Player.Error.playbackInvalidParameterError A method parameter is invalid
56004 Player.Error.playbackInvalidStateError The Player or an internal object is in an invalid state
56005 Player.Error.playbackNetworkError A network error occurred
56006 Player.Error.playbackNetworkIOError A network I/O error occurred
56007 Player.Error.playbackStreamNotAvailableError The stream is not available
56008 Player.Error.playbackTooManyStreamingRequestsError The current-viewers limit was reached
56009 Player.Error.playbackNotSupportedError A method or feature is not supported
56010 Player.Error.playbackNoSourceError There is no source for the Player to play
56011 Player.Error.playbackTimeoutError The Player timed out performing an operation
  • 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

Architecture Compressed Size Uncompressed Size
Universal 1.7 MB 3.6 MB
arm64 1.7 MB 3.6 MB

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

Architecture Compressed Size Uncompressed Size
Universal 1.7 MB 3.6 MB
arm64 1.7 MB 3.6 MB

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
Telemetry Data Reporting Details
TelemetryDataPlaybackQualityHighLatencyReductionApplied Reported when the SDK applies the low latency reduction strategy.
TelemetryDataPlaybackQualityHighLatencyReductionReverted Reported when the SDK reverts the low latency reduction strategy.

Size Impact

Architecture Compressed Size Uncompressed Size
Universal 1.7 MB 3.6 MB
arm64 1.7 MB 3.6 MB

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.

Telemetry Data Reporting Details
TelemetryDataConnectionConnecting Reported when Player.connect(...) is called
TelemetryDataConnectionConnected Reported when the Player has a playback token
TelemetryDataConnectionNetworkUnavailable Reported when playerNetworkDidBecomeUnavailable is invoked
TelemetryDataConnectionDisconnected Reported when is Player.dealloc() is called
TelemetryDataConnectionError Reported when playerDidFailWithError is invoked in the .connecting state
TelemetryDataPlaybackPlayed Reported when player.play() is called
TelemetryDataPlaybackPaused Reported when player.pause() is called
TelemetryDataPlaybackVolumeSet Reported when player.volume is set
TelemetryDataPlaybackMuted Reported when player.muted is set to true
TelemetryDataPlaybackUnmuted Reported when player.muted is set to false
TelemetryDataPlaybackError TelemetryDataPlayback
TelemetryDataPlaybackRebuffering Reported when playerWillRebuffer is invoked
TelemetryDataPlaybackQualitySummary Reported every three seconds while the player is .buffering or .playing state
TelemetryDataPlaybackQualitySet Reported when player.quality is set
TelemetryDataPlaybackQualityChanged Reported when playerdidChangeQuality is invoked
TelemetryDataPlaybackQualityVideoSizeChanged Reported when playerVideoSizeChanged is invoked
TelemetryDataPlaybackStateChanged ``
TelemetryDataTimedMetadataReceived Reported when playerDidReceiveTimedMetadata is invoked
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

Architecture Compressed Size Uncompressed Size
Universal 1.7 MB 3.6 MB
arm64 1.7 MB 3.6 MB

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

Architecture Compressed Size Uncompressed Size
Universal 1.7 MB 3.6 MB
arm64 1.7 MB 3.6 MB

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

Architecture Compressed Size Uncompressed Size
Universal 0.4 MB 1.0 MB
arm64 0.4 MB 1.0 MB
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Loading Code Sample...
        
        
        

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        thanks-feedback-gif