Enable background audio (Android)

Allow viewers to continue listening to content when your app is in the background

Background audio allows viewers to continue listening to media when they leave your app or lock their device.

Starting with Android SDK 4.28.0, background audio uses AndroidX Media3 MediaSessionService to manage system media controls and playback notifications. The SDK supplies playlist metadata through MediaItem.



Enable background audio

Follow these steps to enable background audio using the default playback notification:

  1. In your app's AndroidManifest.xml, declare the two required foreground-service permissions and the recommended POST_NOTIFICATIONS permission shown below. On Android 13 and later, request POST_NOTIFICATIONS at runtime. Until the user grants permission, the playback notification is hidden, but playback continues.

    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    The JWX SDK automatically declares MediaService with android:exported="false" and android:foregroundServiceType="mediaPlayback". You do not need to declare this service in your app's manifest.

    If your app already declares MediaService with android:exported="true", delete that declaration (recommended) or add tools:replace="android:exported" to prevent a manifest-merger error.

    If your app subclasses MediaService, declare your subclass in your manifest with android:exported="false" and android:foregroundServiceType="mediaPlayback".

    Troubleshooting: If a required foreground-service permission is missing, the SDK logs an error under the MediaService tag identifying the missing permission.


  1. After initializing your JWPlayer, call MediaServiceController.enable(...) from your AppCompatActivity to enable background audio.

    MediaServiceController.enable(this, player, null);
  2. (Optional) Customize notification buttons.

The SDK automatically binds the background audio service and manages its lifecycle. It unbinds the service when the activity is destroyed, so you do not need to call unbindService().

Destroying the activity ends background audio. If a configuration change, such as screen rotation, destroys and recreates the activity, call enable(...) again in onCreate(). This is not necessary if the activity handles the configuration change without being destroyed.

Passing null uses the default media controls. For a complete implementation example, see the Background Audio Best Practice App.


Customize notification buttons

The SDK provides standard playback controls through Media3. To add custom notification buttons, follow these steps:

  1. Extend ServiceMediaApi to define custom buttons using NotificationButton and handle button interactions.

    For example, the following implementation adds a Like button. Replace the drawable resource and button-handling logic with your application's implementation.

    public class CustomMediaApi extends ServiceMediaApi {
    
        public CustomMediaApi(JWPlayer player) {
            super(player);
        }
    
        @Override
        public List<NotificationButton> getNotificationButtons(Context context) {
            List<NotificationButton> buttons =
                new ArrayList<>(super.getNotificationButtons(context));
    
            buttons.add(
                new NotificationButton.Builder(
                    "like",
                    R.drawable.ic_like,
                    "Like"
                ).build()
            );
    
            return buttons;
        }
    
        @Override
        public void onNotificationButtonClick(String buttonId) {
            if ("like".equals(buttonId)) {
                // Handle the custom button action.
            }
        }
    }
  2. Enable background audio with your custom ServiceMediaApi implementation.

    MediaServiceController.enable(
        this,
        player,
        new CustomMediaApi(player)
    );

Call invalidateNotificationButtons() when a custom button's state changes and the notification needs to refresh.

Notification button behavior

Android controls which buttons appear in media notifications. Android 12 and earlier display up to five notification actions, including standard playback controls.

On Android 13 and later, the system manages button placement, may show only some of your custom buttons, and does not display disabled custom buttons.


For available configuration options and platform limitations, see the NotificationButton and ServiceMediaApi API references.



Use an existing manual implementation

Applications that use MediaServiceController.Builder() can continue managing background audio manually.

MediaServiceController controller =
    new MediaServiceController.Builder(this, player).build();

// When playback begins:
controller.bindService();

// In the activity's onDestroy():
controller.unbindService();

Unlike MediaServiceController.enable(...), this approach requires the application to manage binding and unbinding.

Existing implementations of ServiceMediaApi.addNotificationActions() and getCompactActions() also remain supported, although NotificationButton is recommended for new custom controls.

On Android 13 and later, an action that opens an Activity may not respond when tapped from the system media controls while your app is in the background. Use NotificationButton and onNotificationButtonClick() for those actions.

With Media3, the media session supplies the notification's title, text, and artwork. Changes made to the NotificationCompat.Builder inside addNotificationActions(), other than the actions themselves, are no longer used. The small icon, notification ID, and notification channel configured through NotificationHelper still apply.

For more information, see the MediaServiceController API reference.


Did this page help you?
© 2007- Longtail Ad Solutions, Inc.