Android SDK (Core)
...
Integrate External Player
Integrating NwPlayer
NwPlayerListener Interface
12 min
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 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 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 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 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 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 exoplayer addlistener(this) bandwidthmeter eventlistener this is required to listen to bandwidth updates add the listener to your defaultbandwidthmeter 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