Skip to main content
Version: Next

AudioRecorder

AudioRecorder is a primary interface for capturing audio. It supports three main modes of operations:

  • File recording: Writing audio data directly to the filesystem.
  • Data callback: Emitting raw audio buffers, that can be used in either further processing or streamed.
  • Graph processing: Connect the recorder with either AudioContext or OfflineAudioContext for further more advanced and/or realtime processing.

Configuration​

To access microphone you need to make sure your app has required permission configuration - check getting started permission section for more information.

Additionally to be able to record audio while application is in the background, you need to enable background mode on iOS and configure foreground service on android.

In an Expo application you can do so through react-native-audio-api expo plugin, e.g.

{
  "plugins": [
    [
      "react-native-audio-api",
      {
        "iosBackgroundMode": true,
        "iosMicrophonePermission": "[YOUR_APP_NAME] requires access to the microphone to record audio.",
        "androidPermissions" : [
          "android.permission.RECORD_AUDIO",
          "android.permission.FOREGROUND_SERVICE",
          "android.permission.FOREGROUND_SERVICE_MICROPHONE",
        ],
        "androidForegroundService": true,
        "androidFSTypes": ["microphone"]
      }
    ]
  ]
}

For more configuration options, check out the Expo plugin section.

Keeping the recording alive when the app is closed
Android
​

By default the foreground service stops when the user swipes the app away from the recents screen (android:stopWithTask="true"), which kills the app process and ends any in-progress recording. You can opt into letting the service — and therefore the process, the JS runtime, and the active recording — survive task removal:

Set the androidFSStopWithTask option of the expo plugin to false:

{
  "plugins": [
    [
      "react-native-audio-api",
      {
        "androidFSStopWithTask": false
      }
    ]
  ]
}

For the recording to actually survive, all of the following must hold:

  • The foreground service only exists while a library notification is shown. Call RecordingNotificationManager.show() while the app is still in the foreground — before the user leaves the app — otherwise there is no service to keep alive.
  • androidFSTypes must include "microphone" (manifest foregroundServiceType="microphone"), and on Android 14+ (API 34) the app needs the android.permission.FOREGROUND_SERVICE_MICROPHONE permission.
  • Android's while-in-use rule applies: microphone access must begin while the app is in the foreground. Starting a recording from the background is not possible.
caution

Even with stopWithTask="false", the system can still kill the process (memory pressure, OEM battery managers). Recording cannot self-restart from the background — the user has to reopen the app. To limit data loss in that case, tune the file-output options androidFlushIntervalMs and rotateIntervalBytes.

A recording that survives task removal can only be controlled from the notification, so give the user a way out: enable the notification's stop action (showStopAction: true) or let them swipe the notification away (dismissible: true). Both stop the recording natively even when no JS is reachable.

When the app is opened again, reconcile the UI with what happened while it was away:

if (AudioRecorder.isRecordingOngoing()) {
  // the recording is still running — re-attach the UI to it
} else {
  const info = AudioRecorder.consumeLastRecordingResult();
  if (info) {
    // the recording was stopped from the notification; info.paths holds the files
  }
}

Examples​

import React, { useState } from 'react';
import { View, Pressable, Text } from 'react-native';
import { AudioRecorder, AudioManager } from 'react-native-audio-api';

AudioManager.setAudioSessionOptions({
  iosCategory: 'record',
  iosMode: 'default',
  iosOptions: [],
});

const audioRecorder = new AudioRecorder();

// Enables recording to file with default configuration
audioRecorder.enableFileOutput();

const MyRecorder: React.FC = () => {
  const [isRecording, setIsRecording] = useState(false);

  const onStart = async () => {
    if (isRecording) {
      return;
    }

    // Make sure the permissions are granted
    const permissions = await AudioManager.requestRecordingPermissions();

    if (permissions !== 'Granted') {
      console.warn('Permissions are not granted');
      return;
    }

    // Activate audio session
    try {
      await AudioManager.setAudioSessionActivity(true);
    } catch (error) {
      console.warn('Could not activate the audio session', error);
      return;
    }

    const result = await audioRecorder.start();
    if (result.status === 'error') {
      console.warn(result.message);
      return;
    }

    console.log('Recording started');
    setIsRecording(true);
  };

  const onStop = async () => {
    if (!isRecording) {
      return;
    }

    const result = await audioRecorder.stop();
    console.log(result);
    setIsRecording(false);
    await AudioManager.setAudioSessionActivity(false);
  };

  return (
    <View>
      <Pressable onPress={isRecording ? onStop : onStart}>
        <Text>{isRecording ? 'Stop' : 'Record'}</Text>
      </Pressable>
    </View>
  );
};

export default MyRecorder;

API​

Method
Description
Constructor​

Creates a new AudioRecorder instance, optionally configuring the platform capture chain - see AudioRecorderOptions. It is preferred to create only a single instance of AudioRecorder for the best performance, memory, and battery consumption. While an idle recorder has minimal impact, switching between separate recorder instances might have a noticeable impact on the device.

import { AudioRecorder } from 'react-native-audio-api';

const audioRecorder = new AudioRecorder();

Full-duplex voice apps (playing audio while recording) need platform echo cancellation on both platforms, otherwise the speaker output leaks back into the microphone:

const audioRecorder = new AudioRecorder({
  androidInputPreset: 'voiceCommunication',
  iosVoiceProcessing: true,
});
start​

(asynchronous)

Starts the stream from the system audio input device. Returns a Promise<Result<{}>> that resolves when recording has started. You can pass an optional AudioRecorderStartOptions object with a fileNameOverride string to provide your own file name.

const result = await audioRecorder.start({
  fileNameOverride: `my_audio_${mySessionId}`,
});

console.log(result.status);
stop​

(asynchronous)

Stops the input stream and cleans up each input access method. Returns a Promise<Result<FileInfo>> that resolves when recording has stopped.

For details on the returned file information, see FileInfo.

const result = await audioRecorder.stop();

if (result.status === 'success') {
  const { paths, duration, size } = result;
} else if (result.status === 'error') {
  console.error(result.message);
}
pause​

Pauses the recording. This is useful when recording to file is active, but you do not want to finalize the file.

  audioRecorder.pause();
resume​

Resumes the recording if it was previously paused; otherwise does nothing.

  audioRecorder.resume();
isRecording​

Returns true if the recorder is in an active recording state.

  const isRecording = audioRecorder.isRecording();
isPaused​

Returns true if the recorder is in a paused state.

  const isPaused = audioRecorder.isPaused();
isRecordingOngoing​

(static)

Returns true while a recording session is ongoing (recording or paused). Native source of truth that needs no reference to the recorder instance, so use it from a remounted screen — e.g. after reopening an app whose recording outlived the app UI — to seed the UI state. It reflects the recorder that acquired the active session on a successful start; a second start() does not displace it.

  if (AudioRecorder.isRecordingOngoing()) {
    // re-attach the UI to the still-running recording
  }
consumeLastRecordingResult​

(static)

Returns the FileInfo stashed by the last successful stop that produced output files, or null if there is none. That includes JS stop, the Android recording notification, and deactivating the iOS audio session mid-recording. Consume-once: the stash is cleared on read, so a second call returns null.

If the recording was already finalized natively, calling stop on an AudioRecorder instance does not return those files — it reports that the recorder is not recording. Read the stashed FileInfo from this method instead.

  const info = AudioRecorder.consumeLastRecordingResult();
  if (info) {
    // the recording was stopped from the notification; info.paths holds the files
  }
onError​

Sets an error callback for internal errors that might happen during file writing, callback invocation, or adapter access.

For details, see OnRecorderErrorEventType.

  audioRecorder.onError((error: OnRecorderErrorEventType) => {
    console.log(error);
  });
clearOnError​

Removes the error callback.

  audioRecorder.clearOnError();

Properties​

Property
Description
options​

AudioRecorderFileOptions | null - the active file-output configuration after enableFileOutput(), or null when file output is disabled. See AudioRecorderFileOptions.

  const fileOptions = audioRecorder.options;
inputLatency​

number - the estimated full input latency in seconds (from analog input to app delivery). Mirrors AudioContext.outputLatency semantics. Calculated using underlying platform properties (AVAudioSession on iOS; Oboe timestamps/burst sizes on Android). Value may change when the audio route changes. Returns 0 when idle.

  const latency = audioRecorder.inputLatency;

Recording to file​

Method
Description
enableFileOutput​

Configures and enables file output with the given options and stream properties. By default, the recorder writes to the cache directory using a high-quality M4A file. Returns Result<{}>.

Must be called while the recorder is idle: the file is created by the next start. During an active (recording or paused) session the call returns an error result and the session keeps the output it started with.

For further information, see AudioRecorderFileOptions.

  audioRecorder.enableFileOutput();
disableFileOutput​

Disables file output and finalizes the currently recorded file if the recorder is active.

  audioRecorder.disableFileOutput();
getCurrentDuration​

Returns the current recording duration (number) when file output is enabled.

  const duration = audioRecorder.getCurrentDuration();

Data callback​

Method
Description
onAudioReady​

Registers a callback that receives raw audio buffers during an active recording session. Returns Result<void>.

The callback is periodically invoked with audio buffers that match the preferred configuration provided in options. These parameters guide how audio data is chunked and delivered, though the exact values may vary depending on device capabilities.

For further information, see AudioRecorderCallbackOptions and OnAudioReadyEventType.

  const sampleRate = 16000;

  audioRecorder.onAudioReady(
    {
      sampleRate,
      bufferLength: 0.1 * sampleRate, // 0.1s of data
      channelCount: 1,
    },
    ({ buffer, numFrames, when }) => {
      // do something with the data
    }
  );
clearOnAudioReady​

Removes the audio data callback and flushes any remaining buffered data through onAudioReady.

  audioRecorder.clearOnAudioReady();

Graph processing​

Method
Description
connect​

Routes captured audio into an audio graph by creating a recorder adapter with BaseAudioContext.createRecorderAdapter(), connecting the recorder to it, and wiring it to destination. Takes the BaseAudioContext used to create the recorder adapter and the destination AudioNode in the audio graph. Returns AudioNode.

  audioRecorder.connect(audioContext, audioContext.destination);
disconnect​

Disconnects AudioRecorder from the audio graph.

  audioRecorder.disconnect();

Types​

AudioRecorderOptions​

interface AudioRecorderOptions {
  androidInputPreset?: AndroidInputPreset;
  iosVoiceProcessing?: boolean;
}
ParameterTypeDefaultDescription
androidInputPreset
Optional
Android
AndroidInputPreset'voiceRecognition'Preprocessing chain applied to the capture stream. The platform default, voiceRecognition, applies no acoustic echo cancellation - use voiceCommunication to engage the platform AEC/NS chain.
iosVoiceProcessing
Optional
iOS
booleanfalseRuns the capture chain through Apple's voice-processing I/O: acoustic echo cancellation, noise suppression and automatic gain control.

Both options are applied when the capture stream is created and cannot be changed afterwards - create a new recorder to switch configuration. Each option is ignored on the other platform.

caution

Voice processing changes the hardware input format and engages a shared platform processing unit, so the resolved sample rate and channel count of the recorded audio may differ from the raw microphone format.

AndroidInputPreset​

type AndroidInputPreset =
  | 'generic'
  | 'camcorder'
  | 'voiceRecognition'
  | 'voiceCommunication'
  | 'unprocessed'
  | 'voicePerformance';

Names of Oboe's InputPreset values, which select the preprocessing chain the capture stream is opened with.

AudioRecorderStartOptions​

interface AudioRecorderStartOptions {
  fileNameOverride?: string;
}
ParameterTypeDescription
fileNameOverride
Optional
stringCustom file name used when recording to file.

AudioRecorderCallbackOptions​

interface AudioRecorderCallbackOptions {
  sampleRate: number;
  bufferLength: number;
  channelCount: number;
}

  • sampleRate - The desired sample rate (in Hz) for audio buffers delivered to the recording callback. Common values include 44100 or 48000 Hz. The actual sample rate may differ depending on hardware and system capabilities.

  • bufferLength - The preferred size of each audio buffer, expressed as the number of samples per channel. Smaller buffers reduce latency but increase CPU load, while larger buffers improve efficiency at the cost of higher latency.

  • channelCount - The desired number of audio channels per buffer. Typically 1 for mono or 2 for stereo recordings.

OnRecorderErrorEventType​

interface OnRecorderErrorEventType {
  message: string;
}

OnAudioReadyEventType​

Represents the data payload received by the audio recorder callback each time a new audio buffer becomes available during recording.

interface OnAudioReadyEventType {
  buffer: AudioBuffer;
  numFrames: number;
  when: number;
}
  • buffer - The audio buffer containing the recorded PCM data. This buffer includes one or more channels of floating-point samples in the range of -1.0 to 1.0.
  • numFrames - The number of audio frames contained in this buffer. A frame represents a single sample across all channels.
  • when - The timestamp (in seconds) indicating when this buffer was captured, relative to the start of the recording session.

File handling​

AudioRecorderFileOptions​

interface AudioRecorderFileOptions {
  channelCount?: number;
  rotateIntervalBytes?: number;

  format?: FileFormat;
  preset?: FilePresetType;

  directory?: FileDirectory;
  subDirectory?: string;
  fileNamePrefix?: string;
  androidFlushIntervalMs?: number;
}
  • channelCount - The desired channel count in the resulting file. not all file formats supports all possible channel counts.
  • rotateIntervalBytes - The threshold size (in bytes) at which the recorder will start writing to a new file. If set to 0 (default), file output rotation is disabled. When active, new files are named with the original prefix appended with a timestamp. You can join the rotated files after recording with concatAudioFiles.
    • Use a large enough value for your format. Very small thresholds rotate often, which increases the chance of audible gaps or muffled joins after concatenation — especially for M4A, where each segment is a separate AAC encode.
    • Practical starting points: ≥ 1 MB for WAV, ≥ 200 KB for M4A (adjust upward if you still hear artifacts at segment boundaries).
    • This option controls segment file size, not RAM usage. For crash-resilience tuning on Android, use androidFlushIntervalMs instead.
  • format - The desired extension and file format of the recorder file. Check: FileFormat below.
  • preset - The desired recorder file properties, you can use either one of built-in properties or tweak low-level parameters yourself. Check FilePresetType for more details.
  • directory - Either FileDirectory.Cache or FileDirectory.Document (default: FileDirectory.Cache). Determines the system directory that the file will be saved to.
  • subDirectory - If configured it will create the recording inside requested directory (default: undefined).
  • fileNamePrefix - Prefix of the recording files without the unique ID (default: recording).
  • androidFlushIntervalMs - How often the recorder should force the system to write data to the device storage (default: 500).
    • Lower values are good for crash-resilience and are more memory friendly.
    • Higher values are more battery - and storage-efficient.

FileFormat​

Describes desired file extension as well as codecs, containers (and muxers!) used to encode the file.

enum FileFormat {
  Wav,
  Caf,
  M4A,
  Flac,
}
Android + FFmpeg

On Android, encoded file output for M4A, FLAC, and CAF uses FFmpeg. When FFmpeg is disabled in the build, only WAV recording to file is supported. iOS uses system AVFoundation for all listed formats. See Runtime flags.

FileInfo​

interface FileInfo {
  paths: string[];
  size: number;
  duration: number;
}
  • paths - Paths to the recorded audio files. When file rotation is disabled it has only one entry, otherwise list of paths to recorder files is returned.
  • size - The file size (in MB).
  • duration - The recording duration (in seconds).

FilePresetType​

Describes the audio format that is used during writing to file as well as encoded final file properties. You can use one of predefined presets, or fully customize the result file, but be aware that the properties aren't limited to only valid configurations, you may find property pairs that will result in error result during recording start (or when enabling the file output during active input session)!

Built-in file presets​

For convenience we have provided a set of most basic file configurations that should cover most of the cases (or at least we hope they will, please raise an issue if you find something lacking or misconfigured!).

Usage​
import { AudioRecorder, FileFormat, FilePreset } from 'react-native-audio-api';

const audioRecorder = new AudioRecorder();

audioRecorder.enableFileOutput({
  format: FileFormat.M4A,
  preset: FilePreset.High,
});
Preset
Description
Lossless​

Writes audio data directly to file without encoding, preserving the maximum audio quality supported by the device. This results in large file sizes, particularly for longer recordings. Available only when using WAV or CAF file formats.

audioRecorder.enableFileOutput({
  format: FileFormat.Caf,
  preset: FilePreset.Lossless,
});
High Quality​

Uses high-fidelity audio parameters with efficient encoding to deliver near-lossless perceptual quality while producing smaller files than fully uncompressed recordings. Suitable for music and high-quality voice capture.

audioRecorder.enableFileOutput({
  format: FileFormat.Flac,
  preset: FilePreset.High,
});
Medium Quality​

Uses balanced audio parameters that provide good perceptual quality while keeping file sizes moderate. Intended for everyday recording scenarios such as voice notes, podcasts, and general in-app audio, where efficiency and compatibility outweigh maximum fidelity.

audioRecorder.enableFileOutput({
  format: FileFormat.M4A,
  preset: FilePreset.Medium,
});
Low Quality​

Uses reduced audio parameters to minimize file size and processing overhead. Designed for cases where speech intelligibility is sufficient and audio fidelity is not critical, such as quick voice notes, background recording, or diagnostic capture.

audioRecorder.enableFileOutput({
  format: FileFormat.M4A,
  preset: FilePreset.Low,
});

Preset customization​

In addition to the predefined presets, you may supply a custom FilePresetType to fine-tune how audio data is written and encoded. This allows you to optimize for specific use cases such as speech-only recording, reduced storage footprint, or faster encoding.

export interface FilePresetType {
  bitRate: number;
  sampleRate: number;
  bitDepth: BitDepth;
  iosQuality: IOSAudioQuality;
  flacCompressionLevel: FlacCompressionLevel;
}
Property
Description
bitRate​

Defines the target bitrate for lossy encoders (for example AAC or M4A). Higher values generally improve perceptual quality at the cost of larger file sizes. This value may be ignored when using lossless formats.

Use caseBitrate (bps)Notes
Very low quality / telemetry32000Bare minimum for speech intelligibility
Low quality voice notes48000Optimized for small files and fast encoding
Standard speech / podcasts64000 – 96000Good balance of clarity and size
Medium quality general audio128000Common default for consumer audio
High quality music / voice160000 – 192000Near-transparent for most listeners
Very high quality256000 – 320000Large files, minimal perceptual loss
sampleRate​

Specifies the sampling frequency used during recording. Higher sample rates capture a wider frequency range but increase processing and storage requirements.

bitDepth​

Controls the PCM bit depth of the recorded audio. Higher bit depths increase dynamic range and precision, primarily affecting uncompressed or lossless output formats.

iosQuality​

Maps the preset to the closest matching quality level provided by iOS native audio APIs, ensuring consistent behavior across Apple devices.

enum IOSAudioQuality {
  Min,
  Low,
  Medium,
  High,
  Max,
}
flacCompressionLevel​

Determines the compression level used when encoding FLAC files. Higher levels reduce file size at the cost of increased CPU usage, without affecting audio quality.

enum FlacCompressionLevel {
  L0,
  L1,
  L2,
  L3,
  L4,
  L5,
  L6,
  L7,
  L8,
}

We are Software Mansion.

Hire us