NwPlayerView View
Welcome to the NwPlayerView View documentation. We are excited to help you integrate and configure the player view for your custom NwPlayerView implementation. Whether using ExoPlayer or another media player, this guide will help you create a seamless and visually appealing playback experience for your users.
One key responsibility when integrating an external player with our SDK is providing a custom player view. Unlike other parts of the SDK, we do not provide a default view for external players. That means it is up to you to create and configure the player view to match your app's design and functionality.
In this guide, we will walk you through:
- How do you create and configure the player view using the NwPlayerView interface?
- Important settings like useController and keepScreenOn to avoid common pitfalls.
- How do you properly configure the layout and resize mode to ensure the video is rendered correctly? There is no weird scaling, zooming, or cropping!
The player view is the heart of your video playback experience. It is what your users see and interact with, so getting it right is crucial. Since our SDK does not provide a default view for external players, you must create one that fits your app's needs. This includes:
- Ensuring the video is displayed in the correct aspect ratio.
- Preventing awkward scaling, zooming, or cropping that can ruin the viewing experience.
- Integrating seamlessly with the SDK's custom controller for playback controls.
When implementing the nwPlayerView property in your custom class, there are two critical configurations you must set correctly to ensure a smooth user experience:
- useController
- keepScreenOn
Let us explain why these settings are important and what can go wrong if not set correctly.
- Why It Matters?
- We provide a custom controller in the SDK to handle playback controls like play, pause, and seek.
- If you set useController = true, the player's built-in controller (e.g., ExoPlayer's default controller) will also appear.
- This creates overlapping controllers, which can confuse users and lead to a poor experience.
- What Happens If You Ignore This:
- Users will see two sets of controls—our custom controller and the player's built-in one.
- This can cause UI conflicts and make your app look unpolished.
- What You Should Do:
- Why It Matters:
- When users watch a video, they last want the screen to turn off mid-playback.
- Setting keepScreenOn = true ensures the screen stays active during playback, so users do not have to keep waking their device.
- What Happens If You Ignore This:
- The screen may turn off during playback, which can be frustrating for users, especially during live events or long videos.
- What You Should Do:
To ensure the video looks great on the screen, you must configure the layout parameters and resize the player view mode. Here is an example of how to do it:
- layoutParams:
- What It Does: Defines the size and position of the player view within its parent container.
- What You Should Do:
- Use WRAP_CONTENT for width and height so the view adjusts to the video's dimensions.
- Set gravity = Gravity.CENTER will center the view within its container.
- resizeMode:
- What It Does: Controls how the video is scaled and displayed within the view.
- What You Should Do:
- Use RESIZE_MODE_FIT to ensure the video fits within the view without cropping or stretching.
- This prevents awkward scaling, zooming, or distorted rendering.
- If the layout and resize mode are not configured properly, the video might look:
- Zoomed in or cropped, cutting off parts of the video.
- Stretched or distorted, which can ruin the viewing experience.
- Misaligned, making the video appear off-center or awkwardly positioned.
Here is how you can implement nwPlayerView with all the correct configurations:
Here is a quick reference to all the functions in the NwPlayerView interface and what they do:
- createPlayerView(): View?
- Responsibility: Creates and returns the player’s UI view. This view is used to render the video content.
- Implementation: You can customize this function to return a View that suits your application’s design and requirements. For example, if you use ExoPlayer, you can return a PlayerView configured with your ExoPlayer instance.
Creating and configuring the player view is a core part of integrating an external player with our SDK. Following these guidelines ensures the video is rendered correctly, providing a smooth and visually appealing experience for your users.
Here is what you need to remember:
- Always set useController = false to avoid overlapping controllers and keep the UI clean.
- Always set keepScreenOn = true to prevent the screen from turning off during playback.
- Configure layout and resize mode to avoid weird scaling, zooming, or misalignment.
If you skip these steps, you might have a poor user experience or UI conflicts. So, double-check your implementation to make sure everything is set up correctly.