rn-audio-player

rn-audio-player is a feature-rich package that allows apps to play audio from URL or file. Right now we are supporting IOS and Android. You can find the sample app using this here.

🚀 Why Use This Package?

When there are existing solutions like expo-av, react-native-music-player, etc., this package stands out due to:

• Integrated UI: Comes with a fully functional full-page player and mini player.
• Customizable Components: UI elements are fully themeable to match your app's design.
• Background Playback: Supports audio playback in the background with media controls.
• Powerful Hook: Use the usePlayer hook to build your own custom UI with full control over the player state.
• Context API Support: Manage multiple media sessions effortlessly using our player context.

📦 Installation

Note: Requires Node.js v18+

npm install @liftoffllc/rn-audio-player
# or
yarn add @liftoffllc/rn-audio-player

⚙️ Prerequisites

iOS Permissions

Add the following to your Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>We need access to the microphone for audio playback</string>
<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
  <string>processing</string>
  <string>fetch</string>
  <string>remote-notification</string>
</array>

If you plan to use the AudioPlayer or MiniPlayer components, they rely on react-native-vector-icons, so you’ll need to install and add the following permission to your Info.plist file.

npm install react-native-vector-icons
# or
yarn add react-native-vector-icons

<key>UIAppFonts</key>
<array>
  <string>Ionicons.ttf</string>
</array>

🛠️ Xcode Configuration

• Open your project in Xcode.

• Go to the General tab → Frameworks, Libraries, and Embedded Content.

• Add the following:

  • AVFoundation.framework
  • AVFAudio.framework
  • CoreMedia.framework
  • MediaPlayer.framework

🧩 Props

AudioPlayer & MiniPlayer Props

| Prop | Type | Description | | ------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------- | | trackInfo | object | Required. Metadata like title, artist | | containerStyle | ViewStyle | Style for the outer container. | | iconStyle | object | Style for control icons | | mediaStyle | object | Style for media section (thumbnail etc.) | | contentStyle | object | Style for title/artist metadata | | iconComponents | object | Custom icon components for controls. ex: playIcon, pauseIcon, previousIcon, repeatIcon etc | | sourceUrl, filePath | string | URL or file path to the audio | | autoPlay | boolean | Auto start playback on load | | repeat | boolean | Whether to repeat the track | | shouldShowControls | boolean | Show or hide control buttons | | shouldShowMedia | boolean | Show or hide media thumbnail | | shouldShowContent | boolean | Show or hide content (title/artist) | | shouldShowDuration | boolean | Show or hide audio duration | | customProgressIndicator | ReactNode | Custom component to show progress | | customControls | ReactNode | Custom component to render controls | | onPlay | () => void | Callback when playback starts. | | onPause | () => void | Callback when playback is paused. | | onSeek | (time: number) => void | Callback when seeking to a specific time. | | onNext | () => void | Callback when skipping to the next track. | | onPrevious | () => void | Callback when going to the previous track. | | onSeekForward | () => void | Callback when seeking forward. | | onSeekBackward | () => void | Callback when seeking backward. | | onFinished | () => void | Callback when track finishes playing. | | seekInterval | number | Interval (in ms) for to seek. Default: 3000 |

🧪 Usage

usePlayer Hook

import { usePlayer } from '@liftoffllc/rn-audio-player';

const { play, pause, stop, seek, toggleRepeat, loadContent } = usePlayer({
  repeat: false,
  autoPlay: false,
  seekInterval: 10,
  shouldPlayInBackground: true,
  onPlay: () => {
    console.log('play');
  },
  onPause: () => {
    console.log('pause');
  },
  onSeek: (time: number) => {
    console.log('seek', time);
  },
  onNext: () => {
    console.log('next');
  },
  onPrevious: () => {
    console.log('previous');
  },
  onSeekForward: () => {
    console.log('seekForward');
  },
  onSeekBackward: () => {
    console.log('seekBackward');
  },
  onFinished: () => {
    console.log('finished');
  },
  onStop: () => {
    console.log('stop');
  },
  onReady: () => {
    console.log('ready');
  },
  onProgress: (progress: number) => {
    console.log('progress', progress);
  },
});

Context Wrapper

import { PlayerProvider } from '@liftoffllc/rn-audio-player';

export default function App() {
  return (
    <PlayerProvider>
      <MyApp />
    </PlayerProvider>
  );
}

AudioPlayer Component

import { AudioPlayer } from '@liftoffllc/rn-audio-player';

<AudioPlayer
  trackInfo={{
    title: 'John doe Title',
    artist: 'John doe',
    album: 'John doe Album',
    url: 'https://dl.espressif.com/dl/audio/ff-16b-1c-8000hz.mp3',
    artwork:
      'https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQAu2qz2_GGhotIzQJvsAY-GHK6NRmZzDDWCw&s',
  }}
/>;

MiniPlayer Component

import { MiniPlayer } from '@liftoffllc/rn-audio-player';

<MiniPlayer
  trackInfo={{
    title: 'John doe Title',
    artist: 'John doe',
    album: 'John doe Album',
    url: 'https://dl.espressif.com/dl/audio/ff-16b-1c-8000hz.mp3',
    artwork:
      'https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQAu2qz2_GGhotIzQJvsAY-GHK6NRmZzDDWCw&s',
  }}
/>;

Contributing

For bugs, feature requests, or contributions, please create an issue or submit a pull request.

License

Developed by LiftOff LLC Engineering 🚀