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 implementLogger
protocol and supply custom logger by setting thePlayer.logger
property. If no custom logger is supplied, the SDK will useDefaultLogger
by default. The Player SDK will send the log messages to theLogger
instance based on the log level set using theplayer.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 toTwilioLivePlayer
. - Improved the PlayerView APIs. You can render media content on of a stream by setting a
playerView
property on aPlayer
.
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 ofUIView
. To render a stream on your iPhone screen, instantiate aPlayerView
and set theplayer
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 from1.0.0-preview5
through1.0.0-preview7
will result in anPlayer.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. TheTwilioPlayer.connect(..)
API returns aPlayer
in.idle
state. - Removed
playerSid
property fromPlayer
,TelemetryDataConnection
,TelemetryDataPlayback
,TelemetryDataPlaybackQuality
,TelemetryDataPlaybackState
andTimedMetadataTelemetry
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:
-
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.
-
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
andTwilioPlayerSDK.connect(accessToken:playerDelegate:)
has been moved toPlayer
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 thePlayerDelegate
protocol. This callback will be invoked when thePlayer
loses network connectivity. Playback is now automatically paused when the network connection is lost, and it is resumed when the connection is restored. Use theplayerNetworkDidBecomeUnavailable
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 toPlayer.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 totrue
. - 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 |
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.