# How to Enable Picture-in-Picture (PiP) Mode in SmartTube: A Complete Developer Guide

> Learn how to enable Picture-in-Picture PiP mode in SmartTube with this developer guide. Discover manifest declarations, runtime checks, and the enterPipMode() method for seamless background playback.

- Repository: [Yuriy L/SmartTube](https://github.com/yuliskov/SmartTube)
- Tags: how-to-guide
- Published: 2026-09-14

---

**SmartTube enables Picture-in-Picture mode through a combination of manifest declarations in [`AndroidManifest.xml`](https://github.com/yuliskov/SmartTube/blob/main/AndroidManifest.xml), runtime checks via `Helpers.isPictureInPictureSupported()`, and the `enterPipMode()` method in `PlaybackActivity`, which triggers when users select PiP as the background playback mode.**

Picture-in-Picture (PiP) allows users to continue watching videos in a floating window while navigating other applications on their Android TV or mobile device. According to the yuliskov/SmartTube source code, implementing this feature requires coordinating Android system capabilities with the app's playback engine and activity lifecycle. The implementation spans manifest declarations, runtime permission checks, and UI state management across multiple components.

## Manifest Configuration for PiP Support

Before SmartTube can enter PiP mode, the Android system requires explicit declaration in the app manifest. This informs the OS that the playback activity supports floating window behavior.

In [`smarttubetv/src/main/AndroidManifest.xml`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/AndroidManifest.xml), the `PlaybackActivity` declaration includes the crucial `android:supportsPictureInPicture` attribute:

```xml
<activity
    android:name=".tv.ui.playback.PlaybackActivity"
    android:label="@string/app_name"
    android:supportsPictureInPicture="true"
    android:configChanges="keyboard|keyboardHidden|navigation|orientation|screenSize|smallestScreenSize"
    ... />

```

Setting `android:supportsPictureInPicture="true"` is mandatory for Android N (API 24) and above. Without this flag, calls to `enterPictureInPictureMode()` will fail silently or throw exceptions.

## Runtime Capability Verification

SmartTube defensively checks device capabilities before attempting to enter PiP mode. The helper method `Helpers.isPictureInPictureSupported()` performs runtime validation to ensure the device runs Android N (API 24) or higher and that the activity properly declares PiP support in its manifest.

This check guards against crashes on older devices or incompatible Android TV implementations. The method returns `true` only when the system can safely enter PiP mode, allowing the app to fall back to standard background audio playback on unsupported devices.

## Implementing the PiP Entry Point

The core logic for entering PiP mode resides in [`PlaybackActivity.java`](https://github.com/yuliskov/SmartTube/blob/main/PlaybackActivity.java). The `enterPipMode()` method orchestrates the transition, handling version-specific API differences and user preference checks.

Located in [`smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/playback/PlaybackActivity.java`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/playback/PlaybackActivity.java), this method demonstrates the complete flow:

```java
@TargetApi(24)
private void enterPipMode() {
    if (Helpers.isPictureInPictureSupported(this) && wannaEnterToPip()) {
        try {
            if (Build.VERSION.SDK_INT >= 26) {
                PictureInPictureParams.Builder params = new PictureInPictureParams.Builder();
                // Optional: set aspect ratio, custom actions, or source rect hint
                enterPictureInPictureMode(params.build());
            } else {
                // Legacy API for Android N (API 24-25)
                enterPictureInPictureMode();
            }
        } catch (Exception e) {
            Log.e(TAG, e.getMessage());
        }
    }
}

```

Key implementation details include:

- **The `wannaEnterToPip()` guard**: This internal check verifies that `PlayerData` has `BACKGROUND_MODE_PIP` selected and confirms the activity is not already in PiP mode.
- **Version branching**: Android O (API 26) introduced `PictureInPictureParams` for customizing the PiP window aspect ratio and actions. Older versions use the parameterless `enterPictureInPictureMode()` method.
- **Exception safety**: The try-catch block prevents crashes if the system denies PiP entry due to memory constraints or policy restrictions.

## Configuring Background Playback Mode

PiP activation depends on the user's background playback preference stored in `PlayerData`. The app must explicitly set the background mode to `PlayerEngine.BACKGROUND_MODE_PIP` to allow the `wannaEnterToPip()` check to succeed.

To programmatically enable PiP as the default background behavior:

```java
PlayerData playerData = PlayerData.instance(context);
playerData.setBackgroundMode(PlayerEngine.BACKGROUND_MODE_PIP);

```

This setting persists across sessions and controls whether the app enters PiP mode automatically when the user presses the home button or triggers the back action during playback. Users can also toggle this manually via Settings → Background playback → PiP in the SmartTube interface.

## Handling PiP Lifecycle Events

When the system transitions to or from PiP mode, SmartTube must adapt its UI components. The `PlaybackActivity` overrides `onPictureInPictureModeChanged()` to propagate state changes to the playback fragment:

```java
@Override
public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode) {
    super.onPictureInPictureModeChanged(isInPictureInPictureMode);
    if (mPlaybackFragment != null) {
        mPlaybackFragment.onPIPChanged(isInPictureInPictureMode);
    }
}

```

The fragment's `onPIPChanged()` method then adjusts the visibility of controls, hiding full-screen overlays and displaying minimal playback controls suitable for the smaller window:

```java
@Override
public void onPIPChanged(boolean isInPip) {
    if (isInPip) {
        hideFullScreenOverlay();
        showMinimalControls();
    } else {
        showFullScreenOverlay();
    }
}

```

## Key Source Files for PiP Implementation

Understanding the complete PiP architecture requires familiarity with these specific files in the yuliskov/SmartTube repository:

- **[`smarttubetv/src/main/AndroidManifest.xml`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/AndroidManifest.xml)**: Contains the `android:supportsPictureInPicture="true"` declaration for `PlaybackActivity`.
- **[`smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/playback/PlaybackActivity.java`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/playback/PlaybackActivity.java)**: Houses the `enterPipMode()` entry point and lifecycle callbacks.
- **[`common/src/main/java/com/liskovsoft/smartyoutubetv2/common/prefs/PlayerData.java`](https://github.com/yuliskov/SmartTube/blob/main/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/prefs/PlayerData.java)**: Manages the `BACKGROUND_MODE_PIP` preference and persistence.
- **[`common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/Helpers.java`](https://github.com/yuliskov/SmartTube/blob/main/common/src/main/java/com/liskovsoft/smartyoutubetv2/common/misc/Helpers.java)**: Provides the `isPictureInPictureSupported()` utility method for runtime capability detection.

## Summary

Enabling Picture-in-Picture in SmartTube requires coordination across the Android manifest, runtime system checks, and user preference management:

- Declare `android:supportsPictureInPicture="true"` in [`AndroidManifest.xml`](https://github.com/yuliskov/SmartTube/blob/main/AndroidManifest.xml) for the playback activity.
- Verify device compatibility using `Helpers.isPictureInPictureSupported()` before attempting entry.
- Set the background mode to `PlayerEngine.BACKGROUND_MODE_PIP` via `PlayerData` to permit PiP activation.
- Implement `enterPipMode()` in `PlaybackActivity` with version-specific logic for Android O+ versus older versions.
- Handle lifecycle changes through `onPictureInPictureModeChanged()` to adapt the UI for floating window constraints.

## Frequently Asked Questions

### What is the minimum Android version required for PiP in SmartTube?

SmartTube requires Android N (API 24) or higher for Picture-in-Picture functionality. The `Helpers.isPictureInPictureSupported()` method explicitly checks for this API level, and the `enterPipMode()` method uses the `@TargetApi(24)` annotation to prevent compilation errors on older SDKs.

### Why doesn't PiP activate when I press the home button?

PiP only activates when the background playback mode is explicitly set to `BACKGROUND_MODE_PIP` in `PlayerData`. If the mode is set to background audio only (`BACKGROUND_MODE_SOUND`) or disabled, the `wannaEnterToPip()` check returns false. Verify the setting in the app's preferences or programmatically set it using `playerData.setBackgroundMode(PlayerEngine.BACKGROUND_MODE_PIP)`.

### How do I customize the PiP window aspect ratio on Android O and above?

For Android O (API 26) and higher, modify the `PictureInPictureParams.Builder` in `enterPipMode()` before calling `enterPictureInPictureMode()`. You can set the aspect ratio using `params.setAspectRatio(new Rational(width, height))` and add custom actions using `params.setActions(actionsList)`.

### Where does SmartTube handle UI changes when entering PiP mode?

UI adaptations occur in the `onPIPChanged()` method of the playback fragment, triggered via `PlaybackActivity.onPictureInPictureModeChanged()`. This pattern ensures that full-screen overlays hide and minimal controls appear immediately when the activity enters PiP mode, and reverse when returning to full screen.