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
MediaSessionServiceto manage system media controls and playback notifications. The SDK supplies playlist metadata throughMediaItem.
Enable background audio
Follow these steps to enable background audio using the default playback notification:
-
In your app's AndroidManifest.xml, declare the two required foreground-service permissions and the recommended
POST_NOTIFICATIONSpermission shown below. On Android 13 and later, requestPOST_NOTIFICATIONSat 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
MediaServicewithandroid:exported="false"andandroid:foregroundServiceType="mediaPlayback". You do not need to declare this service in your app's manifest.If your app already declares
MediaServicewithandroid:exported="true", delete that declaration (recommended) oradd tools:replace="android:exported"to prevent a manifest-merger error.If your app subclasses
MediaService, declare your subclass in your manifest withandroid:exported="false"andandroid:foregroundServiceType="mediaPlayback".Troubleshooting: If a required foreground-service permission is missing, the SDK logs an error under the
MediaServicetag identifying the missing permission.
-
After initializing your
JWPlayer, callMediaServiceController.enable(...)from yourAppCompatActivityto enable background audio.MediaServiceController.enable(this, player, null); - (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:
-
Extend
ServiceMediaApito define custom buttons usingNotificationButtonand 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. } } } -
Enable background audio with your custom
ServiceMediaApiimplementation.MediaServiceController.enable( this, player, new CustomMediaApi(player) );
Call invalidateNotificationButtons() when a custom button's state changes and the notification needs to refresh.
Notification button behaviorAndroid 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.
Updated 7 days ago
