NwPlayer Interface

10min
Welcome to the NwPlayer Interface documentation! This is the prime interface for integrating your custom external player with our SDK. Whether using ExoPlayer, another media player, or a custom-built player, the NwPlayer interface acts as a wrapper, allowing our SDK to recognize and interact with your player. 
This interface is your gateway to controlling playback, managing player states, and ensuring seamless integration with the SDK. In this guide, we will walk you through the key properties and functions of the NwPlayer interface, along with examples and best practices to help you implement it effectively. 
Why NwPlayer is Critical
The NwPlayer interface is the backbone of your external player integration. It defines how the SDK interacts with your player, from playback control to lifecycle management. By implementing this interface, you ensure your player works seamlessly with the SDK, providing a consistent user experience. 
Key Properties and Functions
Below, we will break down the most important properties and functions of the NwPlayer interface, along with examples and use cases. 
bitrate: Long
Purpose: Represents the current bitrate of the media stream.
Why It is Important: During camera switching or quality changes, the bitrate ensures that the player adapts to the new stream without compromising quality.
What It Does: This example code initializes a bandwidthMeter with 50% of the initial bitrate, ensuring smooth transitions during camera switches.
Kotlin
private val bandwidthMeter by lazy {  
    val initBitrate = (bitrate * 0.5).toLong()  // Use 50% of the initial bitrate  
    Timber.tag("EstimatedBandwidth").d("Exoplayer: bandwidthMeter $initBitrate || initialBitrateEstimate: $bitrate")  
    DefaultBandwidthMeter.Builder(context).setInitialBitrateEstimate(initBitrate).build().apply {  
        addEventListener(mainHandler, this@ExternalNwPlayer)  
    }  
}  
private val bandwidthMeter by lazy {  
    val initBitrate = (bitrate * 0.5).toLong()  // Use 50% of the initial bitrate  
    Timber.tag("EstimatedBandwidth").d("Exoplayer: bandwidthMeter $initBitrate || initialBitrateEstimate: $bitrate")  
    DefaultBandwidthMeter.Builder(context).setInitialBitrateEstimate(initBitrate).build().apply {  
        addEventListener(mainHandler, this@ExternalNwPlayer)  
    }  
}  
﻿
disableAudio: Boolean and disableVideo: Boolean
Purpose These properties turn off audio or video playback during a global audio-based event.
Why It’s Important: In a global audio event, the SDK initializes two independent players:
One is for audio-only playback (no video rendering is needed).
One is for video playback (no audio is needed).
To optimize performance and resource usage:
For the audio-only player, video rendering should be disabled (disableVideo = true).
For the video player, audio should be disabled (disableAudio = true).
This ensures that each player only handles the necessary components, reducing unnecessary resource consumption.
Disabling Audio:
When disableAudio is true, the player’s audio track is disabled, and the volume is set to 0 (Optional).
Kotlin
override var disableAudio: Boolean = false  
    set(value) {  
        volume = if (value) 0.0f else 1.0f  // Mute the player if audio is disabled  
        field = value  
    }
override var disableAudio: Boolean = false  
    set(value) {  
        volume = if (value) 0.0f else 1.0f  // Mute the player if audio is disabled  
        field = value  
    }
﻿
Disabling Video: 
When disableVideo is true, the player’s video track is disabled, and no video is rendered.
Kotlin
fun generateExoplayerBuilder(....): ExoPlayer {
    ...
    val trackSelector = DefaultTrackSelector(context, videoTrackSelectionFactory)
    val parametersBuilder = DefaultTrackSelector.Parameters.Builder(context)

// Disable audio or video tracks based on the properties  
    when {
        disableAudio -> {
            parametersBuilder.setRendererDisabled(C.TRACK_TYPE_AUDIO, true)  // Disable audio track  
        }
        disableVideo -> {
            parametersBuilder.setRendererDisabled(C.TRACK_TYPE_VIDEO, true)  // Disable video track  
        }
    }

    trackSelector.setParameters(parametersBuilder.build())

// Initialize ExoPlayer with the configured track selector  
    return ExoPlayer.Builder(context)
        .setBandwidthMeter(bandwidthMeter)
        .setTrackSelector(trackSelector)
        .setLoadControl(loadControl)
        .setLivePlaybackSpeedControl(livePlaybackSpeedControl)
        .build()
}
fun generateExoplayerBuilder(....): ExoPlayer {
    ...
    val trackSelector = DefaultTrackSelector(context, videoTrackSelectionFactory)
    val parametersBuilder = DefaultTrackSelector.Parameters.Builder(context)

// Disable audio or video tracks based on the properties  
    when {
        disableAudio -> {
            parametersBuilder.setRendererDisabled(C.TRACK_TYPE_AUDIO, true)  // Disable audio track  
        }
        disableVideo -> {
            parametersBuilder.setRendererDisabled(C.TRACK_TYPE_VIDEO, true)  // Disable video track  
        }
    }

    trackSelector.setParameters(parametersBuilder.build())

// Initialize ExoPlayer with the configured track selector  
    return ExoPlayer.Builder(context)
        .setBandwidthMeter(bandwidthMeter)
        .setTrackSelector(trackSelector)
        .setLoadControl(loadControl)
        .setLivePlaybackSpeedControl(livePlaybackSpeedControl)
        .build()
}
﻿
What It Does:
The trackSelector is configured to disable either the audio or video renderer based on the values of disableAudio and disableVideo.
This ensures that the player only processes the required tracks, improving efficiency.
onPause() and onResume()
Purpose: These functions handle the player’s lifecycle when the app goes to the background or comes to the foreground.
Why It’s Important: Properly managing the player’s lifecycle ensures efficient resource usage and a smooth user experience.
What It Does: This example code
onResume: Prepares the player for playback when the app comes to the foreground.
onPause: Stops the player to prevent unnecessary resource usage when the app goes to the background.

Kotlin
override fun onResume() {  
    Timber.tag(LOG_TAG).d("onResume")  
    exoPlayer.prepare()  // Prepare the player when the app resumes  
}  

override fun onPause() {  
    Timber.tag(LOG_TAG).d("onPause")  
    stop()  // Stop the player when the app goes to the background  
}  
override fun onResume() {  
    Timber.tag(LOG_TAG).d("onResume")  
    exoPlayer.prepare()  // Prepare the player when the app resumes  
}  

override fun onPause() {  
    Timber.tag(LOG_TAG).d("onPause")  
    stop()  // Stop the player when the app goes to the background  
}  
﻿
NwPlayer Interface: Functions and Properties
Here is a complete list of the NwPlayer interface’s functions and properties, along with their responsibilities: 
playbackObject: PlaybackObject
Represents the media content to be played, including metadata, URLs, and DRM configurations.
playerListener: NwPlayerListener
NwPlayerListener A listener that communicates player events (e.g., buffering, errors, state changes) to the SDK. Please read "NwPlayerListener Interface" and how to call and utilize the functions of NwPlayerListener in detail.
nwPlayerView: NwPlayerView?
Provides the player's UI view for rendering video content. Please read "NwPlayer View" on how to set NwPlayerView in detail.
bitrate: Long
Represents the current bitrate of the media stream.
speed: Float
Controls the playback speed of the media.
volume: Float
Controls the audio volume of the player.
disableAudio: Boolean
Disables audio of a video playback in a Global Audio event
disableVideo: Boolean
Disables video of a audio playback in a Global Audio event
duration: Long
Returns the total duration of the media in milliseconds.
position: Long
Returns the current playback position in milliseconds.
buffer: Long
Returns the current buffered position in milliseconds.
prepare()
Prepares the player for playback, including initializing the player and setting up the media source.
resume()
Resumes playback from the current position.
pause()
Pauses playback at the current position.
seekTo(offsetMs: Long)
Seeks to a specific position, offsetMs in the media (in milliseconds).
stop()
Stops playback and releases resources associated with the player.
release()
Releases all resources held by the player.
onResume()
Called when the player should resume playback after being paused (e.g. when the app comes to the foreground).
onPause()
Called when the player should pause playback (e.g. when the app goes to the background).
Key Takeaways
Here is what you need to remember when implementing the NwPlayer interface: 
Bitrate Management: 
Use the bitrate property to ensure smooth transitions during camera switches or quality changes.
Global Audio Events:
Use disableAudio and disableVideo to optimize player performance during global audio events.
Muting Audio:
When disableAudio is true, set the volume to 0 to mute the player.
Disabling Tracks:
Use DefaultTrackSelector to disable unnecessary tracks (audio or video) during player initialization.
Resource Efficiency:
Disabling unused tracks reduces resource consumption and improves performance.
Lifecycle Management: 
Implement onResume() and onPause() to manage the player’s lifecycle efficiently.
Player Events: 
Use the playerListener to communicate player events to the SDK.
UI Integration: 
Provide a custom player view using nwPlayerView.
﻿
Integrating NwPlayer
NwPlayerView View