Enabling Picture in Picture mode
In order to make use of the Picture in Picture functionality provided by the player, it is first necessary to configure your native application to properly support PiP.
The steps required for each platform are described below.
Android
Declare Picture in Picture support on AndroidManifest.xml
Open android/app/src/main/AndroidManifest.xml
and set android:supportsPictureInPicture
to true
on your main activity's manifest. Also, specify that your activity handles layout configuration changes so that your activity doesn't relaunch when layout changes occur during PiP mode transitions:
<activity android:name=".MainActivity"
android:supportsPictureInPicture="true"
android:configChanges=
"screenSize|smallestScreenSize|screenLayout|orientation"
...
iOS
Set background modes capability
Make sure to add the UIBackgroundModes
key to the dict
section of your Info.plist
:
<key>UIBackgroundModes</key>
<array>
<string>audio</string>
</array>
This step can also be performed from Xcode.
Configure audio session on app startup
Configure your app's AudioSession
category to playback
during the main component's initialization:
import { AudioSession } from 'bitmovin-player-react-native';
// App's root component
const App = () => {
useEffect(() => {
// Set your app's `AudioSession` category to `playback` on initialization.
// Please, note even though this step is required for iOS it won't take any effect on Android.
AudioSession.setCategory('playback').catch((error) => {
// Handle any native error that might occur during this process.
handleError(error);
});
});
// ...
return /* ... */;
};
This step is required in order to properly enable background playback on iOS. Without it, the Picture in Picture option appears on the player UI, but has no effect when used.
You can read more about it in Apple's documentation.
Showing the Picture in Picture UI option
Now that your native application is properly configured to support PiP, the player instance in your JavaScript code can be configured to show the Picture in Picture option in the Player UI.
Simply create aPictureInPictureConfig
and set it to the PlayerView
instance via a PlayerViewConfig
:
const playerViewConfig: PlayerViewConfig = {
pictureInPictureConfig: {
isEnabled: true,
},
};
<PlayerView
player={player}
config={playerViewConfig}
/>
Adjust the UI for Picture in Picture mode on Android
Since PiP mode on Android is just a whole Activity displayed in a small floating window this usually means hiding all the UI elements except for the PlayerView
. You can do this by listening to onPictureInPictureEnter
and onPictureInPictureExit
events to track the current PiP state and use it to adjust the UI.
const onPictureInPictureEnterEvent = useCallback(() => {
setIsInPictureInPicture(true);
}, []);
const onPictureInPictureExitEvent = useCallback(() => {
setIsInPictureInPicture(false);
}, []);
// Since PiP on Android is basically just the whole activity fitted in a small
// floating window, we only want to render the player and hide any other UI.
let renderOnlyPlayerView = Platform.OS === 'android' && isInPictureInPicture;
return (
<>
{renderOnlyPlayerView ? null : <Toolbar/>}
<PlayerView
player={player}
config={playerViewConfig}
onPictureInPictureEnter={onPictureInPictureEnterEvent}
onPictureInPictureExit={onPictureInPictureExitEvent}
/>
</>
)
You can read more about PiP on Android here.
Supported Picture in Picture events
The supported Picture in Picture events on PlayerView
are:
onPictureInPictureEnter
onPictureInPictureExit
iOS only:
onPictureInPictureEntered
onPictureInPictureExited
Android only
onPictureInPictureAvailabilityChanged
Refer to events.ts for more details.
Updated 9 months ago