@jaydhimar/react-native-pip/README.md

A React Native library for Picture-in-Picture mode with support for both iOS and Android platforms.

# @jaydhimar/react-native-pip

A React Native library for Picture-in-Picture (PiP) mode support on iOS and Android. This library provides a simple interface to implement PiP functionality in your React Native applications.

## Features

✅ Custom Aspect Ratio Selection
✅ Auto-PiP on Home Button Press
✅ Detect if PiP is Supported
✅ Callbacks for PiP Events

## Requirements

- iOS 14.0 or later
- Android API level 26 (Android 8.0) or later
- React Native 0.63 or later

## Installation

```sh
npm install @jaydhimar/react-native-pip
# or
yarn add @jaydhimar/react-native-pip
```

### Android Setup

Add the following to your `AndroidManifest.xml` inside the `<activity>` tag that hosts your React Native content:

```xml
android:supportsPictureInPicture="true"
android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|screenLayout|uiMode"
```

### iOS Setup

Add the following to your `Info.plist`:

```xml
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>
```

## Usage

```typescript
import PictureInPicture from 'react-native-pip';

// Check if PiP is supported on the device
const isPipSupported = await PictureInPicture.isPipSupported();

// Enter PiP mode with custom aspect ratio
await PictureInPicture.enterPictureInPicture({
  aspectRatio: {
    width: 16,
    height: 9
  },
  autoEnterOnBackground: true // iOS only
});

// Exit PiP mode
await PictureInPicture.exitPictureInPicture();

// Listen to PiP events
const unsubscribeEnter = PictureInPicture.addEventListener('onEnterPip', () => {
  console.log('Entered PiP mode');
});

const unsubscribeExit = PictureInPicture.addEventListener('onExitPip', () => {
  console.log('Exited PiP mode');
});

const unsubscribeError = PictureInPicture.addEventListener('onError', (error) => {
  console.error('PiP error:', error);
});

// Clean up event listeners
unsubscribeEnter();
unsubscribeExit();
unsubscribeError();
```

## API Reference

### Methods

#### `isPipSupported(): Promise<boolean>`
Checks if PiP mode is supported on the current device.

#### `enterPictureInPicture(config?: PipConfig): Promise<boolean>`
Enters PiP mode with optional configuration.

#### `exitPictureInPicture(): Promise<boolean>`
Exits PiP mode.

#### `addEventListener(eventType: string, listener: Function): () => void`
Adds an event listener for PiP events. Returns a function to remove the listener.

### Types

```typescript
interface PipConfig {
  aspectRatio?: {
    width: number;
    height: number;
  };
  autoEnterOnBackground?: boolean; // iOS only
}

type PipEvents = {
  onEnterPip?: () => void;
  onExitPip?: () => void;
  onError?: (error: string) => void;
}
```

## Contributing

See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

## License

MIT

---

Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)