Simple Android Customization

When you need to adapt the JWP player's appearance and behavior while maintaining its core functionality, you can customize the default UI through the SDK's configuration framework. This approach lets you modify visual elements, control component visibility, and adjust layouts while preserving the robust underlying playback engine.

Developers commonly use UI customization to enhance the player experience and align it with their application needs:

• Visual Integration: Replacing default icons, modifying color schemes, and updating themes to match your app's design language
• Component Control: Configuring player elements and adjusting their layout to create a focused viewing experience
• Brand Alignment: Updating text elements, adjusting control sizes, and fine-tuning backgrounds to maintain consistent branding

This customization approach is ideal for apps that need to maintain the player's proven interaction patterns while adapting its look and feel.

🔑

For more fundamental changes to the player's interface or behavior, consider implementing a custom UI instead.

Understand the customization mechanisms

The SDK provides three ways to customize the player UI.

UiConfig uiConfig = new UiConfig.Builder()
    .displayAllControls()
    .hide(UiGroup.CONTROLBAR)
    .build();

// In res/values/colors.xml
<color name="jw_icons_active">#FF5733</color>

// In res/values/dimens.xml
<dimen name="jw_large_icon">48dp</dimen>

// In res/values/styles.xml
<style name="JWIcon.ControlbarFullscreen">
    <item name="android:layout_width">48dp</item>
    <item name="android:layout_height">48dp</item>
</style>

Customization Options

The following sections present examples of common UI customizations.

💡

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

Background

Customize component backgrounds through drawables or style overrides.

<!-- res/drawable/bg_jw_menu.xml -->

<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="rectangle">  
    <solid android:color="#FF5733" />  
    <corners android:radius="8dp" />  
</shape>

<style name="JWView.Menu.Cast">
    <item name="android:background">@drawable/bg_jw_menu</item>
</style>

Color

Define your color scheme using resource or style overrides.

<!-- res/values/colors.xml -->

<color name="jw_icons_active">#FF5733</color>  
<color name="jw_icons_inactive">#CCCCCC</color>  
<color name="jw_buffer_start">#333333</color>  
<color name="jw_buffer_end">#666666</color>

<style name="JWText.ControlbarPosition">
    <item name="android:textColor">#FF5733</item>
</style>

Component Visibility

Control which groups of UI element display.

UiConfig uiConfig = new UiConfig.Builder()  
    .displayAllControls() // Show all UI elements by default  
    .hide(UiGroup.NEXT_UP) // Hide the NextUp preview group  
    .build();

PlayerConfig config = new PlayerConfig.Builder()  
    .uiConfig(uiConfig)  
    .build();

💡

The following table lists common UI elements. The Android Styling Guide Reference lists all the available UI elements that can be customized.

Icon

Replace default icons by creating matching vector drawables.

<!-- res/drawable/ic_jw_play.xml -->

<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="24dp"
    android:height="24dp"
    android:viewportWidth="24.0"
    android:viewportHeight="24.0">  
    <path
        android:fillColor="#FF000000"
        android:pathData="M8,5v14l11,-7z"/>  
</vector>

💡

The following table lists common icon resources. The Android Styling Guide Reference lists all the available icons that can be customized.

Size

Control UI element dimensions through resources or styles.

<!-- res/values/dimens.xml -->

<dimen name="jw_large_icon">80dp</dimen>    <!-- Main center controls -->  
<dimen name="jw_small_icon">24dp</dimen>    <!-- Control bar icons -->

<!-- Center controls -->

<style name="JWContainer.CenterControlsCombo">
    <item name="android:layout_width">100dp</item>
    <item name="android:layout_height">100dp</item>
</style>

<!-- Text elements -->

<style name="JWText.ControlbarPosition">
    <item name="android:layout_width">wrap_content</item>
    <item name="android:layout_height">32dp</item>
</style>

<!-- Menu items -->

<style name="JWMenuItem">
    <item name="android:layout_height">48dp</item>
    <item name="android:layout_width">match_parent</item>
</style>

Text

Customize player text through string resources.

<!-- res/values/strings.xml -->

<string name="jwplayer_next_up_countdown">Next video in %d</string>  
<string name="jwplayer_learn_more">More Info</string>

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.

Resource Management

• Review default styles in values.xml before implementing overrides to understand required properties.
• Use vector drawables for icons to ensure quality across screen densities and maintain consistent resource naming patterns.

Style Implementation

• When overriding styles, redefine all necessary properties from the original style definition.
• Document style overrides and their relationships to maintain clarity across your implementation.
• Use consistent sizing units (dp).

State Handling

• Verify custom colors, backgrounds, and visibility settings work appropriately across all player states.
• Ensure hidden elements remain hidden during state changes and custom UI elements maintain proper accessibility.

Testing Compatibility

• Test your customizations across different screen sizes and orientations.
• Verify that custom backgrounds and UI elements maintain proper layout during device rotation and respect system UI bounds.