NwPlayer Interface
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.
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.
Below, we will break down the most important properties and functions of the NwPlayer interface, along with examples and use cases.
- 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.
- 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).
- Disabling Video:
- When disableVideo is true, the player’s video track is disabled, and no video is rendered.
- 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.
- 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.
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).
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.