Live Player Android S D K
The Twilio Live Player Android SDK lets you play a stream in your native Android application.
Installation
To add the Twilio Live Player Android SDK to your app, add the library to your app's build.gradle
as shown below.
allprojects {
repositories {
mavenCentral()
}
}
implementation "com.twilio:live-player-android:1.0.1"
The Twilio Live Player Android SDK requires at minimum Java 8+ and Android API 21+.
Usage
The following snippets provide demonstrations on how to use the Player Android SDK in an app. For more details about streaming content, visit the Programmable Media documentation.
Connecting a Player and Handling Events
Once your app acquires a Twilio access token, you can connect to a stream.
val player = Player.connect(context, "access token", object : PlayerListener {
/**
* The player instance is returned in the PlayerState.CONNECTING state after calling connect.
*/
override fun onStateChanged(player: Player, playerState: PlayerState) {
when (playerState) {
PlayerState.IDLE -> {
/**
* The player has successfully authenticated and is loading the stream. This
* state is also reached as a result of calling player.pause().
*/
}
PlayerState.READY -> {
/**
* The player is ready to playback the stream.
*/
}
PlayerState.PLAYING -> {
/**
* The player is now playing a stream. This state occurs as a result of calling
* player.play().
*/
}
PlayerState.BUFFERING -> {
/**
* The player is buffering content.
*/
}
PlayerState.ENDED -> {
/**
* The stream has ended.
*/
}
}
}
override fun onFailed(player: Player, playerException: PlayerException) {
/**
* An error occurred connecting the player or loading a stream.
*/
}
})
Managing Playback
The following snippets demonstrate how to manage playback in your app.
/**
* Once the Player reaches the PlayerState.READY state after initially calling
* Player.connect(...), an application can invoke play(). The player will then transition to
* the PlayerState.PLAYING state once playback successfully begins.
*
* play() can also be called during the PlayerState.IDLE state only after transitioning as a result
* of calling pause().
*/
player.play()
/**
* To pause playback, invoke pause(). The player will transition to PlayerState.IDLE
* until playback is resumed with a subsequent call to play().
*/
player.pause()
/**
* Playback audio can be muted by updating the isMuted property.
*/
player.isMuted = true
/**
* The playback volume can also be adjusted. Updating the isMuted property has no effect
* on the volume property. Once a stream is un-muted, playback will ensue with the last set
* player volume.
*/
player.volume = 0.25f
Using the PlayerView
The PlayerView
subclasses a TextureView
. To render a stream in your app, instantiate a PlayerView
and set the player.playerView
property.
val player = Player.connect(...)
player.playerView = playerView
Using TimedMetadata
When your application inserts TimedMetadata into a stream, the player will emit the onTimedMetadata
callback if the player is in the PlayerState.PLAYING state
. TimedMetadata
will not be received if the player is paused and any data inserted while a player is paused will not be received once the player is resumed.
val playerListener = object : PlayerListener {
override fun onTimedMetadata(player: Player, metadata: TimedMetadata) {
/**
* Handle the data
*/
}
}
Disconnecting a Player
In order to free resources, the player should be disconnected when your application no longer requires the instance.
/**
* Disconnect the player and transition the player to the PlayerState.ENDED state. The player object
* is no longer usable.
*/
player.disconnect()
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.
Type | Reporting Details |
Connection.Connecting | Reported when Player.connect(...) is called |
Connection.Connected | Reported when the Player is connected to Twilio Media Service |
Connection.NetworkUnavailable | Reported when onNetworkUnavailable is invoked |
Connection.Disconnected | Reported when Player.disconnect() is called |
Connection.Error | Reported when onFailed is invoked in the CONNECTING state |
Playback.Played | Reported when player.play() is called |
Playback.Paused | Reported when player.pause() is called |
Playback.VolumeSet | Reported when player.volume is set |
Playback.Muted | Reported when player.isMuted is set to true |
Playback.Unmuted | Reported when player.isMuted is set to false |
Playback.Error | Reported when onFailed is invoked in the following states: IDLE, READY, PLAYING, BUFFERING |
Playback.Rebuffering | Reported when onRebuffering is invoked |
PlaybackQuality.Summary | Reported every three seconds while the player is BUFFERING or PLAYING |
PlaybackQuality.QualitySet | Reported when player.quality is set |
PlaybackQuality.QualityChanged | Reported when onQualityChanged is invoked |
PlaybackQuality.VideoSizeChanged | Reported when onVideoSizeChanged is invoked |
PlaybackQuality.HighLatencyReductionApplied | Reported when the SDK applies a high latency reduction strategy. |
PlaybackQuality.HighLatencyReductionReverted | Reported when the SDK reverts all high latency reduction strategies. |
PlaybackState.Changed | Each state is reported when onStateChanged is invoked |
TimedMetadataTelemetry.Received | Reported when onTimedMetadata 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
val telemetryLogger: TelemetrySubscriber = {
Log.d("PlayerSdkTelemetry", it.toString())
}
// Subscribe the logger to events
Player.telemetry.subscribe(telemetryLogger)
// .. When your app no longer wants telemetry events, unsubscribe
Player.telemetry.unsubscribe(telemetryLogger)
Track High Latency
The following snippet demonstrates an example of checking experience quality by tracking any instances of high latency.
Player.telemetry.subscribe({
if (it is TelemetryData.PlaybackQuality.Summary && it.playerLiveLatency 3000) {
yourAppsAnalytics.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({ yourAppAnalytics.track("connection-error-detected") }) {
it is TelemetryData.Connection.Error
}
Threading Contract
The Player Android SDK does not provide thread safety. Developers should use a Player
instance from a single thread. Typically, this will be the UI thread. All callbacks will be emitted on the same thread that called Player.connect(...)
. The SDK does log warnings if a threading violation is detected.
val player = Player.connect(...)
/**
* This will result in a warning log!
*/
Thread {
player.isMuted = true
}.start()