Android: Enable Lock-Screen Controls #539

123mpozzi · 2024-10-18T09:07:04Z

Description

Implement the lock-screen controls in Android (via the MediaSession API) to make the system display the current media information on the lock-screen, and the control-center.

Additionally, this PR also introduces background-playback support

PR-planning

✅ iOS part: iOS: Enable Lock-Screen Controls #532
📍 Android part
Both will be merged together on a base branch

Overview pics

Changes

Implement lock-screen controls

Use a MediaSession service to hold a strong reference to the player instance
Add serializers for LockScreenControlConfig
Update manifest permissions to allow running the background service

Implement Background playback

Slightly change the PlayerView lifecycle to prevent auto-pausing the background playback on app minimize
- Fix playerEventRelay being null in some scenarios

2 new samples

Both of them allows you to have playback without the main app being opened

Lock-Screen Controls (media session)
- No background playback, so it pauses the app on minimizing it
Background Playback
- It does not pause the playback when minimizing the app
- Has lock-screen controls enabled (since we need a notification, we favor lock-screen controls)

Note

Note: both samples will destroy the player instance (hence destroying the lock-screen widgets) when going back to the homepage. That is expected, a more advanced sample could be part of a follw-up (e.g. letting the widget live in the homescreen as well, until we open a sample with media session disabled).

Config Flags Design

LockScreenControlConfig.isEnabled decides whether the service starts or not
PlayerConfig.PlaybackConfig.isBackgroundPlaybackEnabled decides whether to detach the player from the view
- LockScreenControlConfig.isEnabled has to be true for background playback to work, since it needs a notification

Testing

Please do some manual testing, with a physical device if possible 🙏

Important

A snapshot build of the Android SDK is necessary until Lock-Screen is completely released there.
Direct-message me for a quick patch file

Things to look for

Lock-Screen Controls (use the new "Lock-Screen Control" sample)

widget is created
- in notification-centre
- in lock-screen
minimizing the app stops the playback
- when re-opening the app, the player data is synced (e.g. current playback time)

Background Playback feature (use the new "Background Playback" sample)

widget is created
- in notification-centre
- in lock-screen
minimizing the app does NOT stop the playback
- when re-opening the app, the player data is synced (e.g. current playback time)
does not work without media session being enabled as well (via LockScreenControlConfig)

Activity lifecycle changes

basic samples have no background playback
- by default
- after running the new samples
basic samples playerview is not empty after running the new samples

Checklist

🗒 CHANGELOG entry - entry added already in base PR

To implement lock-screen controls, a player instance must be 'kept alive', so that the player is not garbage-collected or destroyed by the system when the view is destroyed. There are 2 ways to do this: - init the player on the service itself (like in the Android SDK sample) - init the player as usual, and somehow pass it to the service, to store an additional reference This first version implements the second option. The app has 1 strong reference, and the service has 1 strong reference to the player. So that whenever the app dies, the background playback still goes on. Current Issues: - Whenever the app gets back, the player instance should get fetched back as well! - Another limitation with this implementation is that we're calling `setupMediaSession` on `player.ts`'s `inizitalize()`. But when changing sources (e.g. playback view, click back, playback view), the source in the media session does not get overridden with the source from the new view.

Via native by using player module Note: The actual media session module can just be a native one (like offline module) as it is just called via native (player module)

This module will be Android-only.

The old player was not getting destroyed when a new one is being put in charge of the media session

This has to be handled via the activity lifecycle. Took `BackgroundPlaybackScreen` from Android SDK samples as the example Also fix `playerEventRelay` being null in some conditions

As modules represent something native that can be re-used from the JS side, but this is not the case here

123mpozzi · 2024-10-18T10:26:02Z

android/src/main/java/com/bitmovin/player/reactnative/RNPlayerView.kt

+            EVENT_CLASS_TO_REACT_NATIVE_NAME_MAPPING,
+            ::emitEventFromPlayer,
+        )
+


I had to move playerEventRelay initialization here because it was null during the first invocations of onStop in the activity lifecycle.
This is due to the custom setPlayer we have, which also sets playerEventRelay

Limitation section will need an update once the lock-screen implementation into Android SDK is finished

123mpozzi · 2024-10-18T12:31:59Z

src/lockScreenControlConfig.ts

Note that the Limitations section is not modified.
It will be update once the lock-screen feature is fully released on the Android SDK

A 'fake' media session was being initialized here because the Android SDK by a design mistake had mediaSession as not nullable.

123mpozzi · 2024-10-24T08:25:08Z

android/src/main/java/com/bitmovin/player/reactnative/converter/JsonConverter.kt

+fun ReadableMap.toLockScreenControlConfig(): LockScreenControlConfig = LockScreenControlConfig().apply {
+    withBoolean("isEnabled") { isEnabled = it }
+}
+


This config is a cross-platform wrapper, it does not exist in either native SDK.
It acts as a common name to reach the feature

…re/android-extend-mediasession-for-simple-bg-playback # Conflicts: # android/src/main/java/com/bitmovin/player/reactnative/BackgroundPlaybackManager.kt

With Mario

AS media session is only the widget API

As it is not related to background playback

As it is - good user experience on iOS - necessary on Android after certain OS version

And reduce scope where possible

As they're actually directly related to media session instead now

…trols Enhance lock screen controls

123mpozzi · 2024-10-25T13:40:05Z

android/src/main/java/com/bitmovin/player/reactnative/PlayerModule.kt

+        val enableMediaSession = playerConfigJson?.getMap("lockScreenControlConfig")
+            ?.toLockScreenControlConfig()?.isEnabled ?: false
+        enableBackgroundPlayback = playerConfigJson?.getMap("playbackConfig")
+            ?.getBoolean("isBackgroundPlaybackEnabled") ?: false


This needs special mapping as it is a React-Native (and iOS as well) flag

123mpozzi added 11 commits October 18, 2024 10:52

Move the player instance creation to the service

1579ed5

Bind the player correctly to the service on player creation

dc1f4bf

Via native by using player module Note: The actual media session module can just be a native one (like offline module) as it is just called via native (player module)

Remove media session module from typescript

f08ca29

This module will be Android-only.

Fix media session player not getting replaced properly

07a70c6

The old player was not getting destroyed when a new one is being put in charge of the media session

Introduce the lock-screen controls sample

257ca00

Revert changes to basic playback

ae88186

Fix auto-pausing when minimizing the app

140317a

This has to be handled via the activity lifecycle. Took `BackgroundPlaybackScreen` from Android SDK samples as the example Also fix `playerEventRelay` being null in some conditions

Fix every sample having background playback

904d8c0

Fix every sample having background playback after service is on

34f63e1

Cleanup code

7fde45f

123mpozzi self-assigned this Oct 18, 2024

123mpozzi changed the base branch from development to feature/enable-lock-screen-controls October 18, 2024 09:07

123mpozzi added 3 commits October 18, 2024 11:14

Cleanup unnecessary code and comments

5c04e05

Remove unnecessary decorator

ec76873

Make the connection manager a normal class instead of a module

9a39c49

As modules represent something native that can be re-used from the JS side, but this is not the case here

123mpozzi commented Oct 18, 2024

View reviewed changes

123mpozzi added 2 commits October 18, 2024 12:28

Add newline at end of the file

2d14fb7

Update docs with android details

40be6a7

Limitation section will need an update once the lock-screen implementation into Android SDK is finished

123mpozzi commented Oct 18, 2024

View reviewed changes

123mpozzi mentioned this pull request Oct 18, 2024

iOS: Enable Lock-Screen Controls #532

Open

1 task

123mpozzi marked this pull request as ready for review October 18, 2024 12:37

123mpozzi requested a review from a team as a code owner October 18, 2024 12:37

123mpozzi added 7 commits October 23, 2024 13:49

Simplify LockScreenControlConfig serialization

e239fce

Update docs for bg-playback support on Android

a3698fd

Add bg playback sample

44008f9

temp: tentative changes

64a572c

Unify most of the logic for bg and mediasession

96eafe9

Rename bg manager more generic and run ktlint

fca2dda

Remove unnecessary onCreate

08d0dd5

A 'fake' media session was being initialized here because the Android SDK by a design mistake had mediaSession as not nullable.

Format

c78df51

123mpozzi commented Oct 24, 2024

View reviewed changes

123mpozzi and others added 12 commits October 24, 2024 10:27

Merge branch 'feature/android-enable-lock-screen-controls' into featu…

d534946

…re/android-extend-mediasession-for-simple-bg-playback # Conflicts: # android/src/main/java/com/bitmovin/player/reactnative/BackgroundPlaybackManager.kt

pair-programming : just use one service, destroy media session

30e5466

Remove simple bg service

a0c9e86

pair-programming session to unify services

f2659cc

With Mario

Rename service

8a80b44

AS media session is only the widget API

Make media session independent of background playback

6181e74

As it is not related to background playback

Simplify since media session can be on without bg playback

89f856f

Enable lock-screen to provide a notification

62c7c42

As it is - good user experience on iOS - necessary on Android after certain OS version

Use simpler names for variables

b7e672f

And reduce scope where possible

Add note about Android needing a notification for bg playback

496edd9

Rename BackgroundPlaybackService-related classes and vars

5c3bb13

As they're actually directly related to media session instead now

Merge pull request #543 from bitmovin/feature/enhance-lock-screen-con…

1233369

…trols Enhance lock screen controls

123mpozzi mentioned this pull request Oct 25, 2024

Android: support Background Playback #541

Closed

1 task

123mpozzi commented Oct 25, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Android: Enable Lock-Screen Controls #539

Android: Enable Lock-Screen Controls #539

123mpozzi commented Oct 18, 2024 •

edited

Loading

123mpozzi Oct 18, 2024 •

edited

Loading

123mpozzi Oct 18, 2024

123mpozzi Oct 24, 2024

123mpozzi Oct 25, 2024

Android: Enable Lock-Screen Controls #539

Are you sure you want to change the base?

Android: Enable Lock-Screen Controls #539

Conversation

123mpozzi commented Oct 18, 2024 • edited Loading

Description

PR-planning

Overview pics

Changes

Implement lock-screen controls

Implement Background playback

2 new samples

Config Flags Design

Testing

Things to look for

Lock-Screen Controls (use the new "Lock-Screen Control" sample)

Background Playback feature (use the new "Background Playback" sample)

Activity lifecycle changes

Checklist

123mpozzi Oct 18, 2024 • edited Loading

Choose a reason for hiding this comment

123mpozzi Oct 18, 2024

Choose a reason for hiding this comment

123mpozzi Oct 24, 2024

Choose a reason for hiding this comment

123mpozzi Oct 25, 2024

Choose a reason for hiding this comment

123mpozzi commented Oct 18, 2024 •

edited

Loading

123mpozzi Oct 18, 2024 •

edited

Loading