NwPlayerListener Interface

12min
Welcome to the NwPlayerListener Interface documentation. This page explains how to use the NwPlayerListener to communicate player events to the SDK. If you integrate an external player, this listener is your bridge to ensure the SDK knows what is happening with your Player at every step. 
The NwPlayerListener is super important because it allows the SDK to react to player events like buffering, playback state changes, errors, etc. However, it is not just about implementing the listener but about calling the proper functions at the right moments. If you miss this, your integration might not work as expected, leading to a poor user experience. 
In this guide, we will walk you through:
When and where to call each NwPlayerListener function.
How to properly implement Player.Listener and BandwidthMeter.EventListener in your custom player class.
Key takeaways to ensure you are using the listener correctly. 
Why NwPlayerListener is Critical
The NwPlayerListener is the SDK's way of connecting with your Player. It tells the SDK when the Player is ready, when it is buffering, when playback starts or stops, and when errors occur. If you do not call these listener functions at the right moments, the SDK will not know what is happening, and your app might behave unpredictably. 
For example:
If you don’t call onPrepared, the SDK won’t know when the player is ready to start playback.
If you don’t call onError, the SDK won’t be able to handle playback errors gracefully.
So, let’s dive into how to use this listener properly.
When and Where to Call NwPlayerListener Functions
Here is a breakdown of where and when to call each NwPlayerListener function in your custom player implementation: 
onPrepared(player: NwPlayer)
When to Call: Call this in the prepare() function right after the Player is prepared and ready to start playback.
Example:
Kotlin
override fun prepare() {  
    exoPlayer.prepare()  
    playerListener.onPrepared(this) // Call this after preparing the player  
}  
override fun prepare() {  
    exoPlayer.prepare()  
    playerListener.onPrepared(this) // Call this after preparing the player  
}  
﻿
onStateChange(playbackObject: PlaybackObject, isPlaying: Boolean)
When to Call: Call this in onPlayWhenReadyChanged(), part of ExoPlayer's Player.Listener.
Example:
Kotlin
override fun onPlayWhenReadyChanged(playWhenReady: Boolean, reason: Int) {  
    playerListener.onStateChange(playbackObject, playWhenReady)  
}  
override fun onPlayWhenReadyChanged(playWhenReady: Boolean, reason: Int) {  
    playerListener.onStateChange(playbackObject, playWhenReady)  
}  
﻿
onBuffering, onStarted, onSeekCompleted, onPlayerEnded
When to Call: Call these in onPlaybackStateChanged(), part of ExoPlayer's Player.Listener.
Example:
Kotlin
Kotlin
override fun onPlaybackStateChanged(state: Int) {  
    playerListener.onBuffering(this, state == STATE_BUFFERING)  
    if (state == STATE_READY) {  
        playerListener.onStarted(this)  
        playerListener.onSeekCompleted(this)  
    }  
    if (state == STATE_ENDED) playerListener.onPlayerEnded(this)  
}  
override fun onPlaybackStateChanged(state: Int) {  
    playerListener.onBuffering(this, state == STATE_BUFFERING)  
    if (state == STATE_READY) {  
        playerListener.onStarted(this)  
        playerListener.onSeekCompleted(this)  
    }  
    if (state == STATE_ENDED) playerListener.onPlayerEnded(this)  
}  
﻿
onBandwidthUpdate(player: NwPlayer, bitrateEstimate: Long)
When to Call: Call this in onBandwidthSample(), part of ExoPlayer's BandwidthMeter.EventListener.
Example:
Kotlin
override fun onBandwidthSample(elapsedMs: Int, bytesTransferred: Long, bitrateEstimate: Long) {  
    playerListener.onBandwidthUpdate(this, bitrateEstimate)  
}  
override fun onBandwidthSample(elapsedMs: Int, bytesTransferred: Long, bitrateEstimate: Long) {  
    playerListener.onBandwidthUpdate(this, bitrateEstimate)  
}  
﻿
onError(player: NwPlayer, exception: Exception)
When to Call: Call this whenever an error occurs, for example, in ExoPlayer's onPlayerErrorChanged() or onPlayerError().
Example:
Kotlin
override fun onPlayerErrorChanged(error: PlaybackException?) {  
    if (error != null) {  
        playerListener.onError(this, PlayerException(errorCode = error.errorCode, message = error.message))  
    }  
}  
override fun onPlayerErrorChanged(error: PlaybackException?) {  
    if (error != null) {  
        playerListener.onError(this, PlayerException(errorCode = error.errorCode, message = error.message))  
    }  
}  
﻿
Mandatory Implementations
To use the NwPlayerListener properly, the following in your cust ayer class: 
Player.Listener: 
Listening to playback state changes, play/pause events, and errors are required.
Add the listener to your player instance:
Kotlin
exoPlayer.addListener(this)
exoPlayer.addListener(this)
﻿
BandwidthMeter.EventListener: 
This is required to listen to bandwidth updates.
Add the listener to your DefaultBandwidthMeter:
Kotlin
bandwidthMeter.addEventListener(mainHandler, this)  
bandwidthMeter.addEventListener(mainHandler, this)  
﻿
All NwPlayerListener Functions
Here is a quick reference to all the functions in the NwPlayerListener interface and what they do: 
onPrepared(player: NwPlayer)
It is called when the Player was prepared to start playback.
onStarted(player: NwPlayer)
It is called when playback starts.
onBuffering(player: NwPlayer, isBuffering: Boolean)
It is called, is the Player buffering, or has they finished buffering?
onBandwidthUpdate(player: NwPlayer, bitrateEstimate: Long)
It is called when the estimated bandwidth changes.
onStateChange(playbackObject: PlaybackObject, isPlaying: Boolean)
It is called when the Player’splayer's playback state changes (e.g., playing or paused).
onSeekCompleted(player: NwPlayer)
It is called when a seek operation is completed.
onStopped(player: NwPlayer)
It is called when playback is stopped.
onPlayerEnded(player: NwPlayer)
It is called when playback reaches the end of the media.
onError(player: NwPlayer, exception: Exception)
Called when an error occurs during playback.
Key Takeaways
Here is what you need to remember: 
Call the listener functions at the right moments: 
If you miss calling a function, the SDK will not know what is happening, and your app might behave unpredictably.
Implement Player.Listener and BandwidthMeter.EventListener: 
These are mandatory for listening to playback events and bandwidth updates.
Add the listeners to your player and bandwidth meter: 
Use exoPlayer.addListener(this) and bandwidthMeter.addEventListener(mainHandler, this).
Handle errors gracefully: 
Always call onError when something goes wrong so that the SDK can handle it properly.
﻿
NwPlayerView View
Integrating ExoPlayer