Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/afkcodes/react-native-audio-pro/llms.txt

Use this file to discover all available pages before exploring further.

Background playback is built into React Native Audio Pro — once you complete the platform setup below, audio continues when the screen locks or the app moves to the background. This guide covers the required configuration for both iOS and Android, lock screen remote control events, and how to customize the notification with your own action buttons.

​
iOS Setup

Without the Background Modes capability enabled in Xcode, iOS will suspend your app’s audio process as soon as it leaves the foreground. Complete this step before testing background playback on a real device.
1

Enable Background Modes in Xcode

Open your project in Xcode, select your app Target, then go to Signing & Capabilities. Click + Capability, search for Background Modes, and add it. In the Background Modes section that appears, check Audio, AirPlay, and Picture in Picture.
Target → Signing & Capabilities → + Capability → Background Modes
✓ Audio, AirPlay, and Picture in Picture
2

AVFoundation and MPNowPlayingInfoCenter are automatic

React Native Audio Pro uses AVFoundation for audio playback and MPNowPlayingInfoCenter for the lock screen Now Playing widget. No additional code is required — track metadata (title, artist, artwork, position, duration) is pushed to the system automatically whenever you call play().

​
Android Setup

1

Set compileSdkVersion and targetSdkVersion to 35

Open android/build.gradle and confirm both SDK version values are set to 35:
android {
    compileSdkVersion 35
    defaultConfig {
        targetSdkVersion 35
    }
}
2

Media3 session is automatic

React Native Audio Pro uses Android Media3 for its media session and notification controls. The foreground service and notification channel are managed internally — no extra entries in AndroidManifest.xml are required. The media notification appears automatically when playback begins.

​
Lock Screen Controls

When the user taps the next or previous buttons on the lock screen (or in the notification), the player emits REMOTE_NEXT and REMOTE_PREV events. Use addEventListener to handle them and advance the queue or trigger any other logic in your app. 
import { AudioPro, AudioProEventType } from 'react-native-audio-pro';

const subscription = AudioPro.addEventListener((event) => {
  if (event.type === AudioProEventType.REMOTE_NEXT) {
    // User tapped next on the lock screen
    AudioPro.seekToNextMediaItem();
  }

  if (event.type === AudioProEventType.REMOTE_PREV) {
    // User tapped previous on the lock screen
    AudioPro.seekToPreviousMediaItem();
  }
});

// Clean up when your component unmounts
subscription.remove();

​
Custom Notification Buttons

You can replace the default notification layout with a custom set of action buttons using setNotificationButtons. Call this before or after configure() — changes take effect on the next playback session. 
import { AudioPro } from 'react-native-audio-pro';

AudioPro.setNotificationButtons(['LIKE', 'PREV', 'NEXT', 'BOOKMARK']);
Play and Pause are always included in the notification automatically — you do not need to add them to the array. The maximum total button count (including Play/Pause) is 5.
Available buttons:
ButtonDescription
PLAYPlay button
PAUSEPause button
PREVPrevious track
NEXTNext track
LIKELike / heart icon
DISLIKEDislike / thumbs down icon
SAVESave to playlist
BOOKMARKBookmark icon
REWIND_30Rewind 30 seconds
FORWARD_30Forward 30 seconds

​
Listening for Custom Button Presses

When a custom action button is tapped, the player emits a CUSTOM_ACTION event. The event.payload.action field contains the button name as a string ('LIKE', 'BOOKMARK', etc.). 
import { AudioPro, AudioProEventType } from 'react-native-audio-pro';

AudioPro.setNotificationButtons(['LIKE', 'PREV', 'NEXT', 'BOOKMARK']);

const subscription = AudioPro.addEventListener((event) => {
  if (event.type === AudioProEventType.CUSTOM_ACTION) {
    const action = event.payload?.action;

    if (action === 'LIKE') {
      console.log('User liked the track');
    }

    if (action === 'BOOKMARK') {
      console.log('User bookmarked the track');
    }
  }
});

​
Notification State

After handling a CUSTOM_ACTION event you can update the icon state of togglable buttons (liked, disliked, bookmarked) by calling updateNotificationState. This keeps the notification in sync with your app’s state. 
import { AudioPro, AudioProEventType } from 'react-native-audio-pro';
import { useState, useEffect } from 'react';

export function useNotificationActions() {
  const [liked, setLiked] = useState(false);
  const [bookmarked, setBookmarked] = useState(false);

  useEffect(() => {
    AudioPro.setNotificationButtons(['LIKE', 'PREV', 'NEXT', 'BOOKMARK']);

    const subscription = AudioPro.addEventListener((event) => {
      if (event.type === AudioProEventType.CUSTOM_ACTION) {
        if (event.payload?.action === 'LIKE') {
          setLiked((prev) => !prev);
        }
        if (event.payload?.action === 'BOOKMARK') {
          setBookmarked((prev) => !prev);
        }
      }
    });

    return () => subscription.remove();
  }, []);

  // Sync icon state to the notification whenever values change
  useEffect(() => {
    AudioPro.updateNotificationState({ liked, bookmarked });
  }, [liked, bookmarked]);

  return { liked, bookmarked };
}
updateNotificationState accepts an object with optional boolean fields:
FieldTypeDescription
likedbooleanFilled heart icon when true
dislikedbooleanActive dislike icon when true
bookmarkedbooleanFilled bookmark icon when true

Build docs developers (and LLMs) love

Get started for freeTalk to us