react-native-track-player

Starting with V5, react-native-track-player is commercially licensed.

• Personal and educational use: Free.
• Commercial use: Requires a paid license (see rntp.dev/pricing).

Compatibility Note: V5 is a complete rewrite and is not backwards-compatible with V4. V5 is built on JSI, meaning methods like getProgress(), getQueue(), and isPlaying() return synchronously.

Install the package using npm. For iOS, you must also run pod install in the ios directory. Android links automatically.

Requirements:

• React Native 0.74 or later
• New Architecture enabled (Fabric + TurboModules)

npm install @rntp/player

# For iOS
cd ios && pod install

For iOS, you must first install CocoaPods dependencies. If this is a new project or you have updated native dependencies, run bundle install followed by bundle exec pod install. Then, use one of the following commands to build and launch the application on an iOS Simulator or connected device:

# Install CocoaPods dependencies
# (Run this if you haven't or after updating native deps)
bundle install
bundle exec pod install

# Build and run using npm
npm run ios

# OR using Yarn
yarn ios

If you need to perform a full reload to reset the app state, use the following platform-specific shortcuts:

• Android: Press the <kbd>R</kbd> key twice or select "Reload" from the Dev Menu (accessed via <kbd>Ctrl</kbd> + <kbd>M</kbd> on Windows/Linux or <kbd>Cmd ⌘</kbd> + <kbd>M</kbd> on macOS).
• iOS: Press <kbd>R</kbd> in the iOS Simulator.

Before running the application, you must start Metro, the JavaScript build tool for React Native. Run the following command from the root of the project:

# Using npm
npm start

# OR using Yarn
yarn start

With Metro running, use one of the following commands to build and launch the application on an Android emulator or connected device:

# Using npm
npm run android

# OR using Yarn
yarn android

To use the player, first initialize it using TrackPlayer.setupPlayer(). This should be called once at app startup (on Android, ensure this is called while the app is in the foreground). Then, use setMediaItems() to load your tracks and play() to start playback.

import TrackPlayer from '@rntp/player';

// 1. Set up the player (call once at app startup, in the foreground on Android)
await TrackPlayer.setupPlayer({
  contentType: 'music',
  handleAudioBecomingNoisy: true,
  android: { wakeMode: 'network' },
});

// 2. Add tracks and play
await TrackPlayer.setMediaItems([
  {
    url: 'https://example.com/track.mp3',
    title: 'Track Title',
    artist: 'Artist Name',
    artwork: 'https://example.com/artwork.jpg',
  },
]);

TrackPlayer.play();

The library provides several hooks to reactively access the player's state and progress in your UI components:

• useIsPlaying(): Returns the current playing state.
• useProgress(): Returns the current playback position and duration.
• useActiveMediaItem(): Returns the currently active track metadata.

// 3. Use hooks in your UI
import { useIsPlaying, useProgress, useActiveMediaItem } from '@rntp/player';

function PlayerUI() {
  const { playing } = useIsPlaying();
  const { position, duration } = useProgress();
  const track = useActiveMediaItem();

  return (/* your player UI */);
}