React Native Track Player

https://rntp.dev/docs/
Admin
React Native Track Player is a module for adding audio playback capabilities to React Native...
Tokens:83,549
Snippets:852
Trust Score:6.1
Update:11 months ago
Show doc for...
Tokens:
Raw
### Setup Player (JavaScript)

Source: https://rntp.dev/docs/next/basics/getting-started

Initializes the React Native Track Player. This setup process is generally very fast and should be completed before attempting to interact with any other player functions to ensure stability.

```javascript
import TrackPlayer from 'react-native-track-player';  
  
await TrackPlayer.setupPlayer()  
// The player is ready to be used  
```

--------------------------------

### Web Setup: Install Mux.js (Yarn)

Source: https://rntp.dev/docs/basics/installation

Installs mux.js using Yarn. This is an optional step for web deployment, specifically when dealing with HLS streams and requiring transmuxing.

```bash
yarn add mux.js
```

--------------------------------

### React Native Track Player: Update Player Options

Source: https://rntp.dev/docs/basics/getting-started

This example shows how to configure media control capabilities and notification icons for the lockscreen and notification using `TrackPlayer.updateOptions`. It allows customization of playback controls and their appearance on Android.

```javascript
import TrackPlayer, { Capability } from 'react-native-track-player';

TrackPlayer.updateOptions({
    // Media controls capabilities
    capabilities: [
        Capability.Play,
        Capability.Pause,
        Capability.SkipToNext,
        Capability.SkipToPrevious,
        Capability.Stop,
    ],

    // Capabilities that will show up when the notification is in the compact form on Android
    compactCapabilities: [Capability.Play, Capability.Pause],

    // Icons for the notification on Android (if you don't like the default ones)
    playIcon: require('./play-icon.png'),
    pauseIcon: require('./pause-icon.png'),
    stopIcon: require('./stop-icon.png'),
    previousIcon: require('./previous-icon.png'),
    nextIcon: require('./next-icon.png'),
    icon: require('./notification-icon.png')
});
```

--------------------------------

### Playback Service Implementation (JavaScript)

Source: https://rntp.dev/docs/next/basics/getting-started

An example implementation of a playback service file. This service needs to be registered for the React Native Track Player module to work, although its specific functionalities are utilized elsewhere in the application, such as in event handling.

```javascript
// service.js  
module.exports = async function() {  
    // This service needs to be registered for the module to work  
    // but it will be used later in the "Receiving Events" section  
}
```

--------------------------------

### Configure Track Player Capabilities

Source: https://rntp.dev/docs/next/basics/getting-started

This example demonstrates how to update the options for React Native Track Player, specifically configuring the media control capabilities that will be available on the lockscreen and notifications. It imports `Capability` from the library to define these options.

```javascript
import TrackPlayer, { Capability } from 'react-native-track-player';  
  
TrackPlayer.updateOptions({
    // Media controls capabilities  
    capabilities: [  
        Capability.Play,  
        Capability.Pause,  
        Capability.SkipToNext,  
        Capability.SkipToPrevious,  
        Capability.Stop,  
    ],
});
```

--------------------------------

### Web Setup: Install Mux.js (NPM)

Source: https://rntp.dev/docs/basics/installation

Installs mux.js using NPM, which may be necessary for enabling transmuxing support with HLS streams and MPEG2-TS content on the web platform.

```bash
npm install --save mux.js
```

--------------------------------

### iOS Native Dependencies Setup

Source: https://rntp.dev/docs/3.2/basics/installation

Navigates to the iOS directory and installs native dependencies using CocoaPods. This step is crucial for iOS applications after installing the library.

```bash
cd ios && pod install  
```

--------------------------------

### iOS Setup: Install Native Dependencies

Source: https://rntp.dev/docs/2.1/basics/installation

Navigates to the 'ios' directory and installs native dependencies for iOS using CocoaPods. This command is essential after installing the React Native Track Player for iOS projects.

```bash
cd ios && pod install
```

--------------------------------

### Web Setup: Install Shaka Player (NPM)

Source: https://rntp.dev/docs/basics/installation

Installs shaka-player, an optional peer dependency for React Native Track Player's web implementation, using NPM. This is required for web platform deployment.

```bash
npm install --save shaka-player
```

--------------------------------

### Player Setup and Options

Source: https://rntp.dev/docs/api/functions/player

Methods for initializing the player with options and updating its configuration.

```APIDOC
## `setupPlayer(options)`

### Description
Initializes the player with the provided options.

### Method
`setupPlayer`

### Parameters
#### Request Body
- **options** (`PlayerOptions`) - Required - The configuration options for the player.

### Request Example
```json
{
  "options": { ... } 
}
```

### Response
#### Success Response (200)
- **void** - Indicates successful player setup.

## `updateOptions(options)`

### Description
Updates the configuration for the player components. Note that these parameters are different from those set during `setupPlayer()`. Parameters not listed here will not be applied.

### Method
`updateOptions`

### Parameters
#### Request Body
- **options** (`UpdateOptions`) - Required - The new configuration options for the player.

### Request Example
```json
{
  "options": { ... } 
}
```

### Response
#### Success Response (200)
- **void** - Indicates successful option update.
```

--------------------------------

### Web Setup: Install Shaka Player (Yarn)

Source: https://rntp.dev/docs/basics/installation

Installs shaka-player, an optional peer dependency for React Native Track Player's web implementation, using Yarn. This command is for users who prefer Yarn for package management.

```bash
yarn add shaka-player
```

--------------------------------

### Change Playback State (JavaScript)

Source: https://rntp.dev/docs/next/basics/getting-started

Provides examples of controlling the playback state of the React Native Track Player. Functions include playing, pausing, resetting the player, seeking to a specific time, and adjusting the volume.

```javascript
TrackPlayer.play();  
TrackPlayer.pause();  
TrackPlayer.reset();  
  
// Seek to 12.5 seconds:  
TrackPlayer.seekTo(12.5);  
  
// Set volume to 50%:  
TrackPlayer.setVolume(0.5);  
```

--------------------------------

### Setup Player and Add Track with React Native Track Player

Source: https://rntp.dev/docs/intro

This example demonstrates how to set up the player, add a track with its metadata (URL, title, artist, artwork), and configure repeat mode using the React Native Track Player library. It utilizes asynchronous functions for player setup and track addition.

```javascript
import TrackPlayer, { RepeatMode } from 'react-native-track-player';  
  
// Creates the player  
const setup = async () => {  
  await TrackPlayer.setupPlayer({});  
  
  await TrackPlayer.add({
    url: require('track.mp3'),
    title: 'Track Title',
    artist: 'Track Artist',
    artwork: require('track.png')  
  });  
  
  TrackPlayer.setRepeatMode(RepeatMode.Queue);
};
```

--------------------------------

### Player Setup and Options

Source: https://rntp.dev/docs/3.2/api/functions/player

Functions to set up the player with initial options and update player configurations.

```APIDOC
## `setupPlayer(options)`

### Description
Accepts a `PlayerOptions` object to initialize the player.

### Method
`setupPlayer`

### Endpoint
N/A (Client-side function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (PlayerOptions) - Required - Configuration options for the player.

### Request Example
```json
{
  "options": { ... } 
}
```

### Response
#### Success Response (200)
No specific return value documented, assumed to resolve on successful setup.

#### Response Example
N/A

## `updateOptions(options)`

### Description
Accepts a `MetadataOptions` object to update the player's configuration. Note that these parameters are different from those set in `setupPlayer()` and only listed parameters will be applied.

### Method
`updateOptions`

### Endpoint
N/A (Client-side function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (MetadataOptions) - Required - Configuration options to update.

### Request Example
```json
{
  "options": { ... } 
}
```

### Response
#### Success Response (200)
No specific return value documented, assumed to resolve on successful update.

#### Response Example
N/A
```

--------------------------------

### Control Track Queue (JavaScript)

Source: https://rntp.dev/docs/next/basics/getting-started

Demonstrates various methods for managing the track queue in React Native Track Player. This includes skipping to specific tracks, navigating between next/previous tracks, removing tracks by index, and retrieving all tracks currently in the queue.

```javascript
// Skip to a specific track index:  
await TrackPlayer.skip(trackIndex);  
  
// Skip to the next track in the queue:  
await TrackPlayer.skipToNext();  
  
// Skip to the previous track in the queue:  
await TrackPlayer.skipToPrevious();  
  
// Remove two tracks from the queue:  
await TrackPlayer.remove([trackIndex1, trackIndex2]);  
  
// Retrieve the track objects in the queue:  
const tracks = await TrackPlayer.getQueue();  
console.log(`First title: ${tracks[0].title}`);  
```

--------------------------------

### Handle Playback Events (JavaScript)

Source: https://rntp.dev/docs/next/basics/getting-started

Shows how to subscribe to and handle playback events from React Native Track Player using the `useTrackPlayerEvents` hook. This example specifically listens for `Event.PlaybackActiveTrackChanged` to update the displayed track title in a React Native component.

```javascript
import TrackPlayer, { Event } from 'react-native-track-player';  
  
const PlayerInfo = () => {  
    const [trackTitle, setTrackTitle] = useState<string>();  
  
    // do initial setup, set initial trackTitle..  
  
    useTrackPlayerEvents([Event.PlaybackActiveTrackChanged], async event => {  
        if (event.type === Event.PlaybackActiveTrackChanged && event.track != null) {  
            const {title} = event.track || {};  
            setTrackTitle(title);  
        }  
    });  
  
    return (  
        <Text>{trackTitle}</Text>  
    );  
}  
```

--------------------------------

### Setup React Native Track Player

Source: https://rntp.dev/docs/3.1/intro

This code snippet demonstrates how to set up and configure the React Native Track Player. It initializes the player, adds a track with metadata, and sets the repeat mode. Ensure 'react-native-track-player' is installed and required.

```javascript
import TrackPlayer, { RepeatMode } from 'react-native-track-player';

// Creates the player
const setup = async () => {
  await TrackPlayer.setupPlayer({});

  await TrackPlayer.add({
    url: require('track.mp3'),
    title: 'Track Title',
    artist: 'Track Artist',
    artwork: require('track.png')
  });

  TrackPlayer.setRepeatMode(RepeatMode.Queue);
};

```

--------------------------------

### Install React Native Track Player (Stable - NPM)

Source: https://rntp.dev/docs/3.2/basics/installation

Installs the stable version of React Native Track Player using NPM. This is the standard method for adding the library to your project.

```bash
npm install --save react-native-track-player  
```

--------------------------------

### React Native Track Player: Display Progress Bar

Source: https://rntp.dev/docs/basics/getting-started

This snippet demonstrates how to use the `useProgress` hook from 'react-native-track-player' to get playback progress and display it along with a progress bar. It assumes the existence of `formatTime` and `ProgressBar` components.

```javascript
import TrackPlayer, { useProgress } from 'react-native-track-player';

const MyPlayerBar = () => {
    const progress = useProgress();

    return (
            // Note: formatTime and ProgressBar are just examples:
            <View>
                <Text>{formatTime(progress.position)}</Text>
                <ProgressBar
                    progress={progress.position}
                    buffered={progress.buffered}
                />
            </View>
        );

}
```

--------------------------------

### Register Playback Service and Setup Player

Source: https://rntp.dev/docs/3.2/basics/getting-started

Registers the playback service and sets up the player. This is a fundamental step for the module to function correctly. Ensure setup is complete before other player interactions.

```javascript
// AppRegistry.registerComponent(...);
TrackPlayer.registerPlaybackService(() => require('./service'));

// service.js
module.exports = async function() {
    // This service needs to be registered for the module to work
    // but it will be used later in the "Receiving Events" section
}

import TrackPlayer from 'react-native-track-player';

await TrackPlayer.setupPlayer()
// The player is ready to be used
```

--------------------------------

### Install React Native Track Player (Stable - Yarn)

Source: https://rntp.dev/docs/3.2/basics/installation

Installs the stable version of React Native Track Player using Yarn. This command is an alternative to the NPM installation for projects using Yarn.

```bash
yarn add react-native-track-player  
```

--------------------------------

### Add Tracks to Queue (JavaScript)

Source: https://rntp.dev/docs/next/basics/getting-started

Demonstrates how to add tracks to the playback queue in React Native Track Player. Tracks can be loaded from network URLs, app bundles, or the file system. Each track object requires properties like 'url', 'title', and 'artist'.

```javascript
var track1 = {  
    url: 'http://example.com/avaritia.mp3', // Load media from the network  
    title: 'Avaritia',  
    artist: 'deadmau5',  
    album: 'while(1<2)',  
    genre: 'Progressive House, Electro House',  
    date: '2014-05-20T07:00:00+00:00', // RFC 3339  
    artwork: 'http://example.com/cover.png', // Load artwork from the network  
    duration: 402 // Duration in seconds  
};  
  
const track2 = {  
    url: require('./coelacanth.ogg'), // Load media from the app bundle  
    title: 'Coelacanth I',  
    artist: 'deadmau5',  
    artwork: require('./cover.jpg'), // Load artwork from the app bundle  
    duration: 166  
};  
  
const track3 = {  
    url: 'file:///storage/sdcard0/Downloads/artwork.png', // Load media from the file system  
    title: 'Ice Age',  
    artist: 'deadmau5',  
     // Load artwork from the file system:  
    artwork: 'file:///storage/sdcard0/Downloads/cover.png',  
    duration: 411  
};  
  
// You can then [add](https://rntp.dev/docs/api/functions/queue#addtracks-insertbeforeindex) the items to the queue  
await TrackPlayer.add([track1, track2, track3]);  
```

--------------------------------

### Install React Native Track Player (Stable) with NPM

Source: https://rntp.dev/docs/2.1/basics/installation

Installs the stable version of React Native Track Player using the NPM package manager. This is the recommended method for production environments.

```bash
npm install --save react-native-track-player
```

--------------------------------

### Install React Native Track Player (Nightly - NPM)

Source: https://rntp.dev/docs/basics/installation

Installs the nightly build of React Native Track Player using NPM. This is for users who need the latest unreleased features or bug fixes, available from the main branch.

```bash
npm install --save react-native-track-player@nightly
```

--------------------------------

### Install React Native Track Player (Nightly - Yarn)

Source: https://rntp.dev/docs/basics/installation

Installs the nightly build of React Native Track Player using Yarn. This command provides access to the latest development version for Yarn users.

```bash
yarn add react-native-track-player@nightly
```

--------------------------------

### Register Playback Service (JavaScript)

Source: https://rntp.dev/docs/next/basics/getting-started

Registers a playback service for the React Native Track Player. This is a crucial step for the module to function correctly and should be done early in the app's initialization, typically in the index.js file.

```javascript
// AppRegistry.registerComponent(...);  
TrackPlayer.registerPlaybackService(() => require('./service'));  
```

--------------------------------

### Install React Native Track Player (Nightly - NPM)

Source: https://rntp.dev/docs/3.2/basics/installation

Installs the nightly version of React Native Track Player using NPM. This is for users who need the latest updates directly from the main branch.

```bash
npm install --save react-native-track-player@nightly  
```

--------------------------------

### Install React Native Track Player (Nightly - Yarn)

Source: https://rntp.dev/docs/3.2/basics/installation

Installs the nightly version of React Native Track Player using Yarn. This command provides access to the most recent, unreleased changes.

```bash
yarn add react-native-track-player@nightly  
```

--------------------------------

### React Native Track Player Setup and Initialization

Source: https://rntp.dev/docs/2.1/basics/getting-started

Initializes the React Native Track Player. This setup method should complete before any other `TrackPlayer` functions are called to ensure stability. It's typically called after registering the playback service.

```javascript
import TrackPlayer from 'react-native-track-player';

await TrackPlayer.setupPlayer()
// The player is ready to be used
```

--------------------------------

### Player Initialization and Configuration

Source: https://rntp.dev/docs/2.1/api/functions/lifecycle

Initializes the audio player with specific options. This function must be called before using other player functionalities. Options provided here are specific to the player's setup and differ from those updated via `updateOptions()`.

```APIDOC
## `setupPlayer(options: PlayerOptions)`

### Description
Initializes the player with the specified options. These options do not apply to all platforms. Options other than those listed will not be applied. This function should always be called (even without options) before using the player. If the player is already initialized, the promise resolves instantly.

### Method
`setupPlayer`

### Parameters
#### Request Body
- **options** (`PlayerOptions`) - Required - The options for player initialization.
  - **minBuffer** (`number`) - Optional - Minimum time in seconds to buffer. Default: 15 (android), automatic (ios).
  - **maxBuffer** (`number`) - Optional - Maximum time in seconds to buffer. Default: 50.
  - **playBuffer** (`number`) - Optional - Minimum time in seconds to buffer before starting playback. Default: 2.5.
  - **backBuffer** (`number`) - Optional - Time in seconds to keep buffered behind the current playhead. Default: 0.
  - **maxCacheSize** (`number`) - Optional - Maximum cache size in kilobytes. Default: 0.
  - **iosCategory** (`IOSCategory`) - Optional - AVAudioSession.Category for iOS. Default: `playback`.
  - **iosCategoryOptions** (`IOSCategoryOptions[]`) - Optional - AVAudioSession.CategoryOptions for iOS. Default: `[]`.
  - **iosCategoryMode** (`IOSCategoryMode`) - Optional - AVAudioSession.Mode for iOS. Default: `default`.
  - **waitForBuffer** (`boolean`) - Optional - Whether to delay playback to minimize stalling on iOS. Default: `false`.
  - **autoUpdateMetadata** (`boolean`) - Optional - Whether to automatically update now playing metadata. Default: `true`.

### Response
#### Success Response (Promise Resolved)
Returns a `Promise` that resolves when the player is initialized.

### Request Example
```json
{
  "options": {
    "minBuffer": 15,
    "maxBuffer": 50,
    "iosCategory": "playback",
    "autoUpdateMetadata": true
  }
}
```

### Response Example
```json
// Promise resolves with no specific value on success

```

--------------------------------

### Install React Native Track Player (Stable) with Yarn

Source: https://rntp.dev/docs/2.1/basics/installation

Installs the stable version of React Native Track Player using the Yarn package manager. This is an alternative to NPM for managing project dependencies.

```bash
yarn add react-native-track-player
```

--------------------------------

### Install React Native Track Player (Unstable) with Yarn

Source: https://rntp.dev/docs/2.1/basics/installation

Installs the unstable (development) version of React Native Track Player using Yarn. This allows developers to test the latest features before they are officially released.

```bash
yarn add react-native-track-player#dev
```

--------------------------------

### Get Player Information (JavaScript)

Source: https://rntp.dev/docs/next/basics/getting-started

Retrieves current playback state, track index, track object details, and remaining duration using React Native Track Player functions. This snippet demonstrates how to check if the player is currently playing and log information about the current track and its remaining time.

```javascript
  
import TrackPlayer, { State } from 'react-native-track-player';  
  
const playback = await TrackPlayer.getPlaybackState();  
if (playback.state === State.Playing) {  
    console.log('The player is playing');  
};  
  
let trackIndex = await TrackPlayer.getCurrentTrack();  
let trackObject = await TrackPlayer.getTrack(trackIndex);  
console.log(`Title: ${trackObject.title}`);  
  
const position = await TrackPlayer.getPosition();  
const duration = await TrackPlayer.getDuration();  
console.log(`${duration - position} seconds left.`);  
```

--------------------------------

### Install React Native Track Player (Unstable) with NPM

Source: https://rntp.dev/docs/2.1/basics/installation

Installs the unstable (development) version of React Native Track Player using NPM. This version may contain new features or bug fixes but is not recommended for production use.

```bash
npm install --save react-native-track-player#dev
```

--------------------------------

### Player Setup API

Source: https://rntp.dev/docs/3.2/api/functions/lifecycle

Initializes the React Native Track Player with specified options. This function must be called before using any other player functions.

```APIDOC
## `setupPlayer(options: PlayerOptions)`

### Description
Initializes the player with the specified options. These options do not apply to all platforms. Options other than those listed below will not be applied. You should always call this function (even without any options set) before using the player to make sure everything is initialized. If the player is already initialized, the promise will resolve instantly.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **options** (`PlayerOptions`) - Required - The options for the player.
  - **minBuffer** (`number`) - Optional - Minimum time in seconds that needs to be buffered. Default: 15 (android), automatic (ios).
  - **maxBuffer** (`number`) - Optional - Maximum time in seconds that needs to be buffered. Default: 50.
  - **playBuffer** (`number`) - Optional - Minimum time in seconds that needs to be buffered to start playing. Default: 2.5.
  - **backBuffer** (`number`) - Optional - Time in seconds that should be kept in the buffer behind the current playhead time. Default: 0.
  - **maxCacheSize** (`number`) - Optional - Maximum cache size in kilobytes. Default: 0.
  - **iosCategory** (`IOSCategory`) - Optional - AVAudioSession.Category for iOS. Sets on `play()`. Default: `playback`.
  - **iosCategoryOptions** (`IOSCategoryOptions[]`) - Optional - AVAudioSession.CategoryOptions for iOS. Sets on `play()`. Default: `[]`.
  - **iosCategoryMode** (`IOSCategoryMode`) - Optional - AVAudioSession.Mode for iOS. Sets on `play()`. Default: `default`.
  - **autoUpdateMetadata** (`boolean`) - Optional - Indicates whether the player should automatically update now playing metadata data in control center / notification. Default: true.

### Request Example
```javascript
import TrackPlayer from 'react-native-track-player';

await TrackPlayer.setupPlayer({
  minBuffer: 20
});
```

### Response
#### Success Response (Promise Resolved)
- **void** - The promise resolves when the player is successfully initialized.

#### Response Example
```javascript
// Promise resolves without a specific return value on success
TrackPlayer.setupPlayer().then(() => console.log('Player initialized'));
```
```

--------------------------------

### Setup and Add Track using React Native Track Player

Source: https://rntp.dev/docs/3.2/intro

This JavaScript code snippet demonstrates how to set up the player, add a track with its metadata, and configure the repeat mode for a queue. It utilizes the 'react-native-track-player' library and requires local assets for the audio and artwork.

```javascript
import TrackPlayer, { RepeatMode } from 'react-native-track-player';  
  
// Creates the player  
const setup = async () => {  
  await TrackPlayer.setupPlayer({});  
  
  await TrackPlayer.add({
    url: require('track.mp3'),  
    title: 'Track Title',  
    artist: 'Track Artist',  
    artwork: require('track.png')  
  });  
  
  TrackPlayer.setRepeatMode(RepeatMode.Queue);  
};  

```

--------------------------------

### Setup Player and Add Track with React Native Track Player

Source: https://rntp.dev/docs/2.1/intro

This JavaScript snippet demonstrates how to set up the player, add a track with metadata, and configure repeat mode using the React Native Track Player library. It requires the 'react-native-track-player' package and utilizes async/await for player operations.

```javascript
import TrackPlayer, { RepeatMode } from 'react-native-track-player';  
  
// Creates the player  
const setup = async () => {  
  await TrackPlayer.setupPlayer({});  
  
  await TrackPlayer.add({
    url: require('track.mp3'),  
    title: 'Track Title',  
    artist: 'Track Artist',  
    artwork: require('track.png')  
  });  
  
  TrackPlayer.setRepeatMode(RepeatMode.Queue);
};  

```

--------------------------------

### Install React Native Track Player (Stable)

Source: https://rntp.dev/docs/3.1/basics/installation

Installs the stable version of React Native Track Player using NPM or Yarn. This is the recommended method for most projects.

```bash
npm install --save react-native-track-player
```

```bash
yarn add react-native-track-player
```

--------------------------------

### Install React Native Track Player (Nightly)

Source: https://rntp.dev/docs/3.1/basics/installation

Installs the nightly build of React Native Track Player using NPM or Yarn. This is for users who need the latest features or bug fixes before an official release.

```bash
npm install --save react-native-track-player@nightly
```

```bash
yarn add react-native-track-player@nightly
```

--------------------------------

### Install expo-build-properties for HTTP Streaming

Source: https://rntp.dev/docs/next/guides/with-expo

Installs the `expo-build-properties` package, which is necessary to configure Android build settings. This is used to enable HTTP streaming, which is disallowed by default on newer Android versions.

```bash
expo install expo-build-properties
```

--------------------------------

### Player Initialization API

Source: https://rntp.dev/docs/3.1/api/functions/lifecycle

Initializes the React Native Track Player with provided options. This function must be called before using other player functions to ensure proper setup.

```APIDOC
## `setupPlayer(options: PlayerOptions)`

### Description
Initializes the player with the specified options. These options do not apply to all platforms. Options other than those listed will not be applied. This function should always be called before using the player.

### Method
Call (or use corresponding native module method)

### Endpoint
N/A (This is a JavaScript function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (`PlayerOptions`) - Required - The options object for player initialization.
  - **minBuffer** (`number`) - Optional - Minimum time in seconds to buffer. Default: 15 (android), automatic (ios).
  - **maxBuffer** (`number`) - Optional - Maximum time in seconds to buffer. Default: 50.
  - **playBuffer** (`number`) - Optional - Minimum time in seconds to buffer before playback starts. Default: 2.5.
  - **backBuffer** (`number`) - Optional - Time in seconds to keep in buffer behind the current playhead. Default: 0.
  - **maxCacheSize** (`number`) - Optional - Maximum cache size in kilobytes. Default: 0.
  - **iosCategory** (`IOSCategory`) - Optional - AVAudioSession.Category for iOS. Sets on `play()`. Default: `playback`.
  - **iosCategoryOptions** (`IOSCategoryOptions[]`) - Optional - AVAudioSession.CategoryOptions for iOS. Sets on `play()`. Default: `[]`.
  - **iosCategoryMode** (`IOSCategoryMode`) - Optional - AVAudioSession.Mode for iOS. Sets on `play()`. Default: `default`.
  - **autoUpdateMetadata** (`boolean`) - Optional - Indicates if player should automatically update now playing metadata. Default: true.

### Request Example
```json
{
  "options": {
    "minBuffer": 15,
    "maxBuffer": 50,
    "playBuffer": 2.5,
    "backBuffer": 0,
    "maxCacheSize": 0,
    "iosCategory": "playback",
    "iosCategoryOptions": [],
    "iosCategoryMode": "default",
    "autoUpdateMetadata": true
  }
}
```

### Response
#### Success Response (Promise resolves)
- **None** (The function returns a Promise that resolves when initialization is complete or if already initialized.)

#### Response Example
```json
// Promise resolves without a specific value on success
```
```

--------------------------------

### play()

Source: https://rntp.dev/docs/next/api/functions/player

Plays or resumes the current track. This function starts or continues playback from the current position.

```APIDOC
## play()

### Description
Plays or resumes the current track.

### Method
Function Call

### Returns
`Promise<void>`
```

--------------------------------

### Playback Rate and Progress

Source: https://rntp.dev/docs/api/functions/player

Methods for getting and setting the playback rate, and retrieving playback progress.

```APIDOC
## `setRate(rate)`

### Description
Sets the playback rate.

### Method
`setRate`

### Parameters
#### Path Parameters
- **rate** (`number`) - Required - The playback rate (1 is regular speed). Consider setting `pitchAlgorithm` for rates above 2.

### Response
#### Success Response (200)
- **Promise<void>** - Indicates the playback rate has been set.

## `getRate()`

### Description
Gets the current playback rate.

### Method
`getRate`

### Response
#### Success Response (200)
- **Promise<number>** - The current playback rate (1 is regular speed).

## `getProgress()`

### Description
Gets the playback progress of the active track.

### Method
`getProgress`

### Response
#### Success Response (200)
- **Promise<Progress>** - An object containing playback progress information.
```

--------------------------------

### Player API - Volume and Rate Control

Source: https://rntp.dev/docs/3.1/api/functions/player

Methods for getting and setting the player's volume and playback rate.

```APIDOC
## `setVolume(volume)`

### Description
Sets the volume of the player.

### Method
`setVolume`

### Parameters
#### Path Parameters
- **volume** (`number`) - Required - The volume in a range from 0 to 1.

## `getVolume()`

### Description
Gets the volume of the player.

### Method
`getVolume`

### Response
#### Success Response (200)
- **volume** (`number`) - The current volume level (0 to 1).

### Response Example
```json
{
  "volume": 0.8
}
```

## `setRate(rate)`

### Description
Sets the playback rate.

### Method
`setRate`

### Parameters
#### Path Parameters
- **rate** (`number`) - Required - The playback rate where 1 is the regular speed.

## `getRate()`

### Description
Gets the playback rate.

### Method
`getRate`

### Response
#### Success Response (200)
- **rate** (`number`) - The current playback rate (1 is regular speed).

### Response Example
```json
{
  "rate": 1.5
}
```
```

--------------------------------

### setupPlayer(options)

Source: https://rntp.dev/docs/next/api/functions/player

Sets up the player with the given options. Accepts a `PlayerOptions` object to configure the player's initial state and behavior.

```APIDOC
## setupPlayer(options)

### Description
Sets up the player with the given options.

### Method
Function Call

### Parameters
- **options** (`PlayerOptions` object) - Required - Configuration object for the player.

### Returns
`Promise<void>`
```

--------------------------------

### Build React Native Variants for FireOS

Source: https://rntp.dev/docs/guides/amazon-fire-support

This example provides `package.json` scripts to build React Native applications using specific build variants for Google and Amazon platforms. It includes commands for both debug and release builds, utilizing the `--variant` parameter.

```json
"scripts": {
  "android-google": "react-native run-android --variant=googleDebug",
  "android-amazon": "react-native run-android --variant=amazonDebug",
  "android-release-google": "react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle && react-native run-android --variant=googleRelease",
  "android-release-amazon": "react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle && react-native run-android --variant=amazonRelease",
  ...
}

```

--------------------------------

### Lifecycle: setupPlayer

Source: https://rntp.dev/docs/next/api/functions/lifecycle

Initializes the player with the specified options. This should only be called once and before using other player methods. Note that on Android, this method must only be called when the app is in the foreground.

```APIDOC
## `setupPlayer(options: PlayerOptions)`

### Description
Initializes the player with the specified options. These options do not apply to all platforms, see chart below. Options other than those listed below will not be applied. This function should only be called once in the lifetime of your app.

Note that on Android this method must only be called while the app is in the foreground, otherwise it will throw an error with code `'android_cannot_setup_player_in_background'`. In this case you can wait for the app to be in the foreground and try again.

### Method
`setupPlayer`

### Parameters
#### Request Body
- **options** (PlayerOptions) - Required - The options for the player.
  - **minBuffer** (number) - Optional - Minimum time in seconds that needs to be buffered. Default: 15 (android), automatic (ios).
  - **maxBuffer** (number) - Optional - Maximum time in seconds that needs to be buffered. Default: 50.
  - **playBuffer** (number) - Optional - Minimum time in seconds that needs to be buffered to start playing. Default: 2.5.
  - **backBuffer** (number) - Optional - Time in seconds that should be kept in the buffer behind the current playhead time. Default: 0.
  - **maxCacheSize** (number) - Optional - Maximum cache size in kilobytes. Default: 0.
  - **androidAudioContentType** (AndroidAudioContentType) - Optional - The audio content type indicates to the android system how you intend to use audio in your app. Default: `AndroidAudioContentType.Music`.
  - **iosCategory** (IOSCategory) - Optional - AVAudioSession.Category for iOS. Sets on `play()`. Default: `IOSCategory.Playback`.
  - **iosCategoryOptions** (IOSCategoryOptions[]) - Optional - AVAudioSession.CategoryOptions for iOS. Sets on `play()`. Default: `[]`.
  - **iosCategoryMode** (IOSCategoryMode) - Optional - AVAudioSession.Mode for iOS. Sets on `play()`. Default: `default`.
  - **autoHandleInterruptions** (boolean) - Optional - Indicates whether the player should automatically handle audio interruptions. Default: false.
  - **autoUpdateMetadata** (boolean) - Optional - Indicates whether the player should automatically update now playing metadata data in control center / notification. Default: true.

### Returns
`Promise`
```

--------------------------------

### Player Initialization and Options

Source: https://rntp.dev/docs/4.0/api/functions/player

Functions to set up and update the player's configuration.

```APIDOC
## `setupPlayer(options)`

### Description
Initializes the player with the provided options.

### Method
`TrackPlayer.setupPlayer`

### Endpoint
N/A (Function Call)

### Parameters
#### Request Body
- **options** (PlayerOptions) - Required - An object containing player configuration.

### Request Example
```json
{
  "options": {
    "...player options..."
  }
}
```

### Response
#### Success Response (void)
Returns a promise that resolves when the player is set up.

## `updateOptions(options)`

### Description
Updates the player's configuration. Note that parameters other than those listed will not be applied.

### Method
`TrackPlayer.updateOptions`

### Endpoint
N/A (Function Call)

### Parameters
#### Request Body
- **options** (UpdateOptions) - Required - An object containing updated player configuration.

### Request Example
```json
{
  "options": {
    "...update options..."
  }
}
```

### Response
#### Success Response (void)
Returns a promise that resolves when the options are updated.
```

--------------------------------

### Player Initialization API

Source: https://rntp.dev/docs/4.0/api/functions/lifecycle

Initializes the audio player with configuration options. This function should be called once at the beginning of the app's lifecycle.

```APIDOC
## `setupPlayer(options: PlayerOptions)`

### Description
Initializes the player with the specified options. These options do not apply to all platforms and should be reviewed for compatibility. This function should be called only once and before any other player functions.

Note: On Android, this method must only be called while the app is in the foreground. Otherwise, it will throw an error. You can wait for the app to be in the foreground and try again.

### Method
`setupPlayer`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (`PlayerOptions`) - Required - The configuration options for the player.
  - **minBuffer** (`number`) - Optional - Minimum time in seconds that needs to be buffered. Default: 15 (android), automatic (ios).
  - **maxBuffer** (`number`) - Optional - Maximum time in seconds that needs to be buffered. Default: 50.
  - **playBuffer** (`number`) - Optional - Minimum time in seconds that needs to be buffered to start playing. Default: 2.5.
  - **backBuffer** (`number`) - Optional - Time in seconds that should be kept in the buffer behind the current playhead time. Default: 0.
  - **maxCacheSize** (`number`) - Optional - Maximum cache size in kilobytes. Default: 0.
  - **androidAudioContentType** (`AndroidAudioContentType`) - Optional - Indicates to the android system how you intend to use audio. Default: `AndroidAudioContentType.Music`.
  - **iosCategory** (`IOSCategory`) - Optional - AVAudioSession.Category for iOS. Sets on `play()`. Default: `IOSCategory.Playback`.
  - **iosCategoryOptions** (`IOSCategoryOptions[]`) - Optional - AVAudioSession.CategoryOptions for iOS. Sets on `play()`. Default: `[]`.
  - **iosCategoryMode** (`IOSCategoryMode`) - Optional - AVAudioSession.Mode for iOS. Sets on `play()`. Default: `default`.
  - **autoHandleInterruptions** (`boolean`) - Optional - Indicates whether the player should automatically handle audio interruptions. Default: `false`.
  - **autoUpdateMetadata** (`boolean`) - Optional - Indicates whether the player should automatically update now playing metadata data. Default: `true`.

### Request Example
```json
{
  "options": {
    "minBuffer": 15,
    "maxBuffer": 50,
    "playBuffer": 2.5,
    "autoHandleInterruptions": false,
    "androidAudioContentType": "Music"
  }
}
```

### Response
#### Success Response (200)
- **Promise** (`Promise<void>`) - Resolves when the player is successfully initialized.

#### Response Example
(No specific JSON example for success, as it returns a Promise)
```

--------------------------------

### updateOptions(options)

Source: https://rntp.dev/docs/next/api/functions/player

Updates the configuration for the components. ⚠️ These parameters are different than the ones set using `setupPlayer()`. Parameters other than those listed below will not be applied.

```APIDOC
## updateOptions(options)

### Description
Updates the configuration for the components.

### Method
Function Call

### Parameters
- **options** (`UpdateOptions` object) - Required - Configuration object for updating the player.

### Returns
`Promise<void>`
```

--------------------------------

### Remove TrackPlayer.destroy() and TrackPlayer.stop()

Source: https://rntp.dev/docs/4.0/v3-migration

In v3, the `destroy` and `stop` methods have been removed from the TrackPlayer API. This code example indicates that all existing usages of these methods should be removed from the project.

```javascript
// remove all usages of ".destroy()" and ".stop()"
```

--------------------------------

### Platform Support: Miscellaneous Features

Source: https://rntp.dev/docs/next/basics/platform-support

Details the support for miscellaneous features such as Media Controls, Caching, and Background Mode across Android, iOS, and Web.

```APIDOC
## Platform Support: Miscellaneous Features

This section covers the platform compatibility for various additional features.

### Feature Support

| Feature        | Android | iOS | Web |
|----------------|---------|-----|-----|
| Media Controls | ✅      | ✅  | ❌  |
| Caching        | ✅      | ❌  | ❌  |
| Background Mode¹ | ✅      | ✅  | ❌  |

¹: Refer to the 'Background Mode' documentation for more details.
```

--------------------------------

### getPlaybackState()

Source: https://rntp.dev/docs/next/api/functions/player

Gets the `PlaybackState` of the player.

```APIDOC
## getPlaybackState()

### Description
Gets the `PlaybackState` of the player.

### Method
Function Call

### Returns
`Promise<PlaybackState>`
```

--------------------------------

### Install @expo/metro-runtime for Expo Web

Source: https://rntp.dev/docs/next/guides/with-expo

Installs the `@expo/metro-runtime` package, which is required to enable dynamic imports and server-side rendering support for Expo web applications when using React Native Track Player.

```npm
npm install --save @expo/metro-runtime
```

```yarn
yarn add @expo/metro-runtime
```

--------------------------------

### Player Initialization API

Source: https://rntp.dev/docs/api/functions/lifecycle

Initializes the player with specified options. This method should only be called once and before using other player functionalities. It requires the app to be in the foreground on Android.

```APIDOC
## `setupPlayer(options: PlayerOptions)`

### Description
Initializes the player with the specified options. These options do not apply to all platforms, see chart below. Options other than those listed below will not be applied.
You should always call this function (even without any options set) before using the player to make sure everything is initialized. Do not call this more than once in the lifetime of your app.

Note that on Android this method must only be called while the app is in the foreground, otherwise it will throw an error with code `'android_cannot_setup_player_in_background'`. In this case you can wait for the app to be in the foreground and try again.

### Method
`setupPlayer`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (`PlayerOptions`) - Required - The options for player initialization.
  - **minBuffer** (`number`) - Optional - Minimum time in seconds that needs to be buffered. Default: 15 (android), automatic (ios).
  - **maxBuffer** (`number`) - Optional - Maximum time in seconds that needs to be buffered. Default: 50.
  - **playBuffer** (`number`) - Optional - Minimum time in seconds that needs to be buffered to start playing. Default: 2.5.
  - **backBuffer** (`number`) - Optional - Time in seconds that should be kept in the buffer behind the current playhead time. Default: 0.
  - **maxCacheSize** (`number`) - Optional - Maximum cache size in kilobytes. Default: 0.
  - **androidAudioContentType** (`AndroidAudioContentType`) - Optional - The audio content type indicates to the android system how you intend to use audio in your app. Default: `AndroidAudioContentType.Music`.
  - **iosCategory** (`IOSCategory`) - Optional - AVAudioSession.Category for iOS. Sets on `play()`. Default: `IOSCategory.Playback`.
  - **iosCategoryOptions** (`IOSCategoryOptions[]`) - Optional - AVAudioSession.CategoryOptions for iOS. Sets on `play()`. Default: `[]`.
  - **iosCategoryMode** (`IOSCategoryMode`) - Optional - AVAudioSession.Mode for iOS. Sets on `play()`. Default: `default`.
  - **autoHandleInterruptions** (`boolean`) - Optional - Indicates whether the player should automatically handle audio interruptions. Default: false.
  - **autoUpdateMetadata** (`boolean`) - Optional - Indicates whether the player should automatically update now playing metadata data in control center / notification. Default: true.

### Request Example
```json
{
  "options": {
    "minBuffer": 20,
    "maxBuffer": 60,
    "autoHandleInterruptions": true
  }
}
```

### Response
#### Success Response (200)
- **Promise** - Returns a promise that resolves when the player is set up.

#### Response Example
```json
// Promise resolves
```
```

--------------------------------

### getPlayWhenReady()

Source: https://rntp.dev/docs/next/api/functions/player

Gets the current state of `playWhenReady`.

```APIDOC
## getPlayWhenReady()

### Description
Gets the current state of `playWhenReady`.

### Method
Function Call

### Returns
`Promise<boolean>`
```

--------------------------------

### getProgress()

Source: https://rntp.dev/docs/next/api/functions/player

Gets the playback `Progress` of the active track.

```APIDOC
## getProgress()

### Description
Gets the playback `Progress` of the active track.

### Method
Function Call

### Returns
`Promise<Progress>`
```

--------------------------------

### getRate()

Source: https://rntp.dev/docs/next/api/functions/player

Gets the playback rate, where 1 is the regular speed.

```APIDOC
## getRate()

### Description
Gets the playback rate, where 1 is the regular speed.

### Method
Function Call

### Returns
`Promise<number>`
```

--------------------------------

### AndroidOptions

Source: https://rntp.dev/docs/4.0/api/objects/android-options

Configuration options for the Android media player.

```APIDOC
## AndroidOptions

### Description
Options available for the android player. All options are optional.

### Parameters
#### Request Body
- **appKilledPlaybackBehavior** (AppKilledPlaybackBehavior) - Optional - Define how the audio playback should behave after removing the app from recents (killing it).
- **alwaysPauseOnInterruption** (boolean) - Optional - Whether the `remote-duck` event will be triggered on every interruption. Defaults to `false`.
- **stopForegroundGracePeriod** (number) - Optional - Time in seconds to wait once the player should transition to not considering the service as in the foreground. If playback resumes within this grace period, the service remains in the foreground state. Defaults to `5`.
```

--------------------------------

### getVolume()

Source: https://rntp.dev/docs/next/api/functions/player

Gets the volume of the player. The volume is returned as a number between 0 and 1.

```APIDOC
## getVolume()

### Description
Gets the volume of the player (a number between 0 and 1).

### Method
Function Call

### Returns
`Promise<number>`
```

--------------------------------

### Volume and Rate Control

Source: https://rntp.dev/docs/4.0/api/functions/player

Functions to get and set the player's volume and playback rate.

```APIDOC
## `setVolume(volume)`

### Description
Sets the volume of the player.

### Method
`TrackPlayer.setVolume`

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
- **volume** (number) - Required - The volume in a range from 0 to 1.

### Response
#### Success Response (void)
Returns a promise that resolves when the volume is set.

## `getVolume()`

### Description
Gets the volume of the player.

### Method
`TrackPlayer.getVolume`

### Endpoint
N/A (Function Call)

### Response
#### Success Response (number)
Returns a promise that resolves with the current volume (0 to 1).

## `setRate(rate)`

### Description
Sets the playback rate.

### Method
`TrackPlayer.setRate`

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
- **rate** (number) - Required - The playback rate (1 is regular speed). Consider `PitchAlgorithm.Voice` for high rates.

### Response
#### Success Response (void)
Returns a promise that resolves when the rate is set.

## `getRate()`

### Description
Gets the playback rate.

### Method
`TrackPlayer.getRate`

### Endpoint
N/A (Function Call)

### Response
#### Success Response (number)
Returns a promise that resolves with the current playback rate.
```
Tokens:
Raw