Custom Android UI Implementation

When you need to customize the player's controls, layouts, or behaviors beyond the default options, you can create your own UI components. By implementing custom Views and connecting them to the SDK's ViewModels, you gain granular control over the player experience while maintaining the robust functionality of the underlying playback engine.

Developers commonly implement custom UI components to solve specific challenges and enhance the player experience:

• Unique Layouts: Creating custom player configurations like picture-in-picture modes and multi-view screens to match your app's UX requirements
• Additional Functionality: Adding custom gesture controls, advanced scrubbing, and content overlays to extend the player's capabilities
• Enhanced Branding: Incorporating custom controls and animations that align perfectly with your app's visual design

🔑

For basic changes to the player's interface, consider implementing simple customizations instead.

Create a custom UI

💡

The Android Styling Guide Reference lists all the available resources that can be customized.

Follow these steps to create a custom UI:

1. Use UiConfig to hide the default UI components you plan to replace. This prevents duplicate controls and potential conflicts with your custom implementation.

   Example: Hiding the Control Bar

   UiConfig uiConfig = new UiConfig.Builder()
       .hide(UiGroup.CONTROLBAR) // Hides the control bar
       .build();
   
   PlayerConfig config = new PlayerConfig.Builder()
       .uiConfig(uiConfig)
       .build();
   

2. Define your custom UI components either programmatically or in your app's layout XML.

   Example: Defining a Custom Control Bar in XML

   <LinearLayout
       android:layout_width="match_parent"
       android:layout_height="wrap_content"
       android:orientation="horizontal"
       android:background="@color/black">
   
       <ImageButton
           android:id="@+id/play_button"
           android:layout_width="wrap_content"
           android:layout_height="wrap_content"
           android:src="@drawable/ic_play" />
   
       <SeekBar
           android:id="@+id/progress_bar"
           android:layout_width="0dp"
           android:layout_height="wrap_content"
           android:layout_weight="1" />
   
       <ImageButton
           android:id="@+id/fullscreen_button"
           android:layout_width="wrap_content"
           android:layout_height="wrap_content"
           android:src="@drawable/ic_fullscreen" />
   </LinearLayout>
   
   

3. Add your custom View to the JWPlayerView. Your custom View will overlay the hidden default player components.

   Example: Adding a Custom Control Bar

   // Obtain a reference to the JWPlayerView
   JWPlayerView mPlayerView;
   // If the JWPlayerView is included in your layout XML, retrieve it using its ID
   mPlayerView = findViewById(R.id.demoJWPlayerView);
   
   // Retrieve the custom ControlbarView defined elsewhere in your codebase
   ControlbarView customControlBar = new ControlbarView(this);
   
   // Add the custom control bar to the JWPlayerView. It will overlay the default player components in both normal and fullscreen modes.
   mPlayerView.addView(customControlBar);
   

Handle player state and events

When building custom UI components, you must often respond to player events and state changes. The SDK provides ViewModels for each UI group that expose observable states and event handlers.

The following example shows how to handle player events in your custom UI components using the ControlbarViewModel.

// Obtain a context from the containing activity or another convenient source
Context context;

// Retrieve the ControlbarViewModel, which manages the control bar logic
ControlbarViewModel controlbarViewModel =
    (ControlbarViewModel) mJWPlayer.getViewModelForUiGroup(UiGroup.CONTROLBAR);

// Set up an observer to trigger a function whenever the isLive variable changes
controlbarViewModel.isLive().observe(
    context,
    isLive -> {
        // Handle changes to the isLive state
    }
);

// Listen for multiple events simultaneously
// For example, observe changes to the isMuted variable and trigger a callback
controlbarViewModel.isMuted().observe(
    context,
    isMuted -> {
        // Handle changes to the isMuted state, such as updating an icon or displaying a message
    }
);

Best Practices

When customizing the JWP player's interface, following established best practices ensures your modifications remain robust and maintainable across different devices and player states. These guidelines help you implement customizations that preserve the player's core functionality while achieving your desired visual design.

Testing and Compatibility

• Test your custom UI components across different screen sizes, orientations, and API levels.
• Ensure proper handling of configuration changes and lifecycle events.

State Management

• Keep your custom UI synchronized with player states by observing changes through the ViewModel.
• Handle edge cases like buffering or error states appropriately.

Performance

• Monitor your custom UI's impact on memory usage and frame rates, especially during transitions and animations.
• Consider implementing view recycling for scrollable content.