Audio API Expo plugin

What is Audio API Expo plugin

The Audio API Expo plugin allows to set certain permissions and background audio related settings in developer friendly way.

Type definitions

interface Options {
  iosMicrophonePermission?: string;
  iosBackgroundMode: boolean;
  androidPermissions: string[];
  androidForegroundService: boolean;
  androidFSTypes: string[];
  androidFSStopWithTask: boolean;
}

How to use it?

Add react-native-audio-api expo plugin to your app.json or app.config.js.

app.json

{
  "plugins": [
    [
      "react-native-audio-api",
      {
        "iosBackgroundMode": true,
        "iosMicrophonePermission": "This app requires access to the microphone to record audio.",
        "androidPermissions" : [
          "android.permission.MODIFY_AUDIO_SETTINGS",
          "android.permission.FOREGROUND_SERVICE",
          "android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"
        ],
        "androidForegroundService": true,
        "androidFSTypes": [
          "mediaPlayback"
        ]
      }
    ]
  ]
}

app.config.js

export default {
  ...
  "plugins": [
    [
      "react-native-audio-api",
      {
        "iosBackgroundMode": true,
        "iosMicrophonePermission": "This app requires access to the microphone to record audio.",
        "androidPermissions" : [
          "android.permission.MODIFY_AUDIO_SETTINGS",
          "android.permission.FOREGROUND_SERVICE",
          "android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"
        ],
        "androidForegroundService": true,
        "androidFSTypes": [
          "mediaPlayback"
        ]
      }
    ]
  ]
};

Options

iosBackgroundMode

Defaults to true.

Allows app to play audio in the background on iOS.

iosMicrophonePermission

Defaults to undefined.

Allows to specify a custom microphone permission message for iOS. If not specified it will be omitted in the Info.plist.

androidPermissions

Defaults to

[
  'android.permission.FOREGROUND_SERVICE',
  'android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK'
]

Allows to specify certain android app permissions to apply.

Permissions:

• android.permission.POST_NOTIFICATIONS - Required by Foreground Services on Android 13+ to post notifications.

• android.permission.FOREGROUND_SERVICE - Allows an app to run a Foreground Service

• android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK - Allows an app to run a Foreground Service specifically for continues audio or video playback.

• android.permission.FOREGROUND_SERVICE_MICROPHONE - Allows an app to run a Foreground Service specifically for continues microphone capture from the background.

• android.permission.MODIFY_AUDIO_SETTINGS - Allows an app to modify global audio settings.

• android.permission.INTERNET - Allows applications to open network sockets.

• android.permission.RECORD_AUDIO - Allows an application to record audio.

androidForegroundService

Defaults to true

Allows app to use Foreground Service options specified by user, it permits app to play audio in the background on Android.

androidFSTypes

Allows user to specify appropriate Foreground Service type.

Types description

• mediaPlayback - Continue audio or video playback from the background.

• microphone - Continue microphone capture from the background, such as voice recorders or communication apps.

  Runtime prerequisites:

  • Request and be granted the RECORD_AUDIO runtime permission.

androidFSStopWithTask

Defaults to true

Controls the android:stopWithTask attribute of the Foreground Service injected by the plugin. With the default value (true), the service stops when the user swipes the app away from the recents screen.

Set it to false to emit android:stopWithTask="false" on the service entry — on task removal the service keeps running, which keeps the app process (and e.g. an in-progress recording) alive.

info

The Foreground Service only exists while a library notification is shown, so this option has an effect only if a notification (e.g. via RecordingNotificationManager.show()) is displayed before the user closes the app. See keeping the recording alive when the app is closed for the full set of requirements.