Android SDK (Core)
...
Integrate External Player
Integrating NwPlayer

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

  • onStateChange(playbackObject: PlaybackObject, isPlaying: Boolean)
    • When to Call: Call this in onPlayWhenReadyChanged(), part of ExoPlayer's Player.Listener.
    • Example:
Kotlin

  • onBuffering, onStarted, onSeekCompleted, onPlayerEnded
    • When to Call: Call these in onPlaybackStateChanged(), part of ExoPlayer's Player.Listener.
    • Example:
Kotlin
Kotlin

  • onBandwidthUpdate(player: NwPlayer, bitrateEstimate: Long)
    • When to Call: Call this in onBandwidthSample(), part of ExoPlayer's BandwidthMeter.EventListener.
    • Example:
Kotlin

  • onError(player: NwPlayer, exception: Exception)
    • When to Call: Call this whenever an error occurs, for example, in ExoPlayer's onPlayerErrorChanged() or onPlayerError().
    • Example:
Kotlin


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

  • BandwidthMeter.EventListener:
    • This is required to listen to bandwidth updates.
    • Add the listener to your DefaultBandwidthMeter:
Kotlin


All NwPlayerListener Functions

Here is a quick reference to all the functions in the NwPlayerListener interface and what they do:

  1. onPrepared(player: NwPlayer)
    • It is called when the Player was prepared to start playback.
  2. onStarted(player: NwPlayer)
    • It is called when playback starts.
  3. onBuffering(player: NwPlayer, isBuffering: Boolean)
    • It is called, is the Player buffering, or has they finished buffering?
  4. onBandwidthUpdate(player: NwPlayer, bitrateEstimate: Long)
    • It is called when the estimated bandwidth changes.
  5. onStateChange(playbackObject: PlaybackObject, isPlaying: Boolean)
    • It is called when the Player’splayer's playback state changes (e.g., playing or paused).
  6. onSeekCompleted(player: NwPlayer)
    • It is called when a seek operation is completed.
  7. onStopped(player: NwPlayer)
    • It is called when playback is stopped.
  8. onPlayerEnded(player: NwPlayer)
    • It is called when playback reaches the end of the media.
  9. onError(player: NwPlayer, exception: Exception)
    • Called when an error occurs during playback.

Key Takeaways

Here is what you need to remember:

  1. 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.
  2. Implement Player.Listener and BandwidthMeter.EventListener:
    • These are mandatory for listening to playback events and bandwidth updates.
  3. Add the listeners to your player and bandwidth meter:
    • Use exoPlayer.addListener(this) and bandwidthMeter.addEventListener(mainHandler, this).
  4. Handle errors gracefully:
    • Always call onError when something goes wrong so that the SDK can handle it properly.