Expo Audio (expo-audio)

Guide for using

expo-audio

to implement audio playback and recording in React Native apps.

Overview

• Package:

  expo-audio

  (replaces deprecated

  expo-av

  )
• Platform: Android, iOS, tvOS, Web
• Bundled version: ~1.1.1
• Documentation: https://docs.expo.dev/versions/latest/sdk/audio/

Installation

npx expo install expo-audio

Configuration

app.json Plugin Configuration

Add the

expo-audio

plugin to your

app.json

:

{
 "expo": {
  "plugins": [
   [
    "expo-audio",
    {
     "microphonePermission": "Allow $(PRODUCT_NAME) to access your microphone.",
     "recordAudioAndroid": true
    }
   ]
  ]
 }
}

Configurable properties:

• microphonePermission

  (iOS only): String for NSMicrophoneUsageDescription. Set to

  false

  to disable.

• recordAudioAndroid

  (Android only): Boolean to enable RECORD_AUDIO permission (default:

  true

  )

Background Audio (iOS)

For background audio playback on iOS, add

UIBackgroundModes

to

app.json

:

{
 "expo": {
  "ios": {
   "infoPlist": {
    "UIBackgroundModes": ["audio"]
   }
  }
 }
}

Core Concepts

AudioPlayer

The

AudioPlayer

class handles audio playback. You can create players using:

• useAudioPlayer()

  hook (recommended for React components)

• createAudioPlayer()

  function (for imperative usage outside components)

AudioRecorder

The

AudioRecorder

class handles audio recording. Use:

• useAudioRecorder()

  hook (recommended for React components)

Usage Patterns

Playing Sounds (React Hook - Recommended)

Use

useAudioPlayer

hook in React components:

import { Button, View } from "react-native";
import { useAudioPlayer } from "expo-audio";

const audioSource = require("./assets/sound.mp3");

export default function App() {
 const player = useAudioPlayer(audioSource);

 return (
  <View>
   <Button title="Play" onPress={() => player.play()} />
   <Button title="Pause" onPress={() => player.pause()} />
   <Button
    title="Replay"
    onPress={() => {
     player.seekTo(0);
     player.play();
    }}
   />
  </View>
 );
}

Important: Unlike

expo-av

,

expo-audio

doesn't automatically reset playback position when audio finishes. After

play()

, the player stays paused at the end. To replay, call

seekTo(seconds)

to reset position.

Playing Sounds (Imperative - Outside Components)

For imperative usage (e.g., utility functions), use

createAudioPlayer

:

import { AudioPlayer, createAudioPlayer, setAudioModeAsync } from "expo-audio";

let player: AudioPlayer | null = null;

export async function loadSound(uri: string): Promise<void> {
 // Configure audio mode
 await setAudioModeAsync({
  playsInSilentMode: true,
  allowsRecording: false,
 });

 // Create player
 player = createAudioPlayer({ uri });
}

export async function playSound(volume: number = 1.0): Promise<void> {
 if (!player) {
  await loadSound("https://example.com/sound.mp3");
 }

 if (player) {
  player.volume = volume;
  player.seekTo(0);
  player.play();
 }
}

export async function releaseSound(): Promise<void> {
 if (player) {
  player.release();
  player = null;
 }
}

⚠️ Memory Management: When using

createAudioPlayer

, you must manually call

release()

when done to prevent memory leaks.

Recording Sounds

import { useEffect, useState } from "react";
import { Button, View } from "react-native";
import {
 AudioModule,
 RecordingPresets,
 setAudioModeAsync,
 useAudioRecorder,
 useAudioRecorderState,
} from "expo-audio";

export default function App() {
 const audioRecorder = useAudioRecorder(RecordingPresets.HIGH_QUALITY);
 const recorderState = useAudioRecorderState(audioRecorder);

 const record = async () => {
  await audioRecorder.prepareToRecordAsync();
  audioRecorder.record();
 };

 const stopRecording = async () => {
  // Recording available on `audioRecorder.uri`
  await audioRecorder.stop();
 };

 useEffect(() => {
  (async () => {
   const status = await AudioModule.requestRecordingPermissionsAsync();
   if (!status.granted) {
    Alert.alert("Permission to access microphone was denied");
   }

   await setAudioModeAsync({
    playsInSilentMode: true,
    allowsRecording: true,
   });
  })();
 }, []);

 return (
  <View>
   <Button
    title={recorderState.isRecording ? "Stop Recording" : "Start Recording"}
    onPress={recorderState.isRecording ? stopRecording : record}
   />
  </View>
 );
}

AudioPlayer API

Properties

• volume

  : Number (0.0 to 1.0) - Current playback volume

• isPlaying

  : Boolean - Whether audio is currently playing

• isLoaded

  : Boolean - Whether audio source is loaded

• duration

  : Number - Total duration in seconds (null if not loaded)

• currentTime

  : Number - Current playback position in seconds

Methods

• play()

  : Start or resume playback

• pause()

  : Pause playback

• seekTo(seconds: number)

  : Seek to specific position

• release()

  : Release player resources (required for

  createAudioPlayer

  )

Event Listeners

Use

useAudioPlayerStatus()

hook to react to player state changes:

import { useAudioPlayer, useAudioPlayerStatus } from "expo-audio";

const player = useAudioPlayer(source);
const status = useAudioPlayerStatus(player);

// status.isPlaying, status.currentTime, status.duration, etc.

AudioRecorder API

Methods

• prepareToRecordAsync(options?)

  : Prepare recorder with options

• record()

  : Start recording

• stop()

  : Stop recording (returns URI)

• pause()

  : Pause recording

• release()

  : Release recorder resources

Recording Presets

import { RecordingPresets } from "expo-audio";

// Available presets:
RecordingPresets.HIGH_QUALITY;
RecordingPresets.LOW_QUALITY;

Audio Mode Configuration

Use

setAudioModeAsync()

to configure audio behavior:

import { setAudioModeAsync } from "expo-audio";

await setAudioModeAsync({
 playsInSilentMode: true, // Play even when device is in silent mode
 allowsRecording: false, // Allow recording (required for recording)
 interruptionMode: "duck", // 'duck' | 'mix' | 'doNotMix'
});

Common Patterns

Preload Audio on App Start

// app/_layout.tsx
import { useEffect } from "react";
import { loadGongSound, unloadGongSound } from "../lib/audio";

export default function RootLayout() {
 useEffect(() => {
  loadGongSound();
  return () => {
   unloadGongSound();
  };
 }, []);

 return <Stack />;
}

Play Sound with Volume Control

import { createAudioPlayer, setAudioModeAsync } from "expo-audio";

let player: AudioPlayer | null = null;

export async function playSound(volume: number = 1.0): Promise<void> {
 if (!player) {
  await setAudioModeAsync({ playsInSilentMode: true });
  player = createAudioPlayer({ uri: "https://example.com/sound.mp3" });
 }

 if (player) {
  player.volume = volume;
  player.seekTo(0);
  player.play();
 }
}

Replay Sound (Reset Position)

// Important: expo-audio doesn't auto-reset position
player.seekTo(0); // Reset to beginning
player.play(); // Play from start

Migration from expo-av

Key Differences

1. No auto-reset:

   expo-audio

   doesn't reset position when playback finishes. Call

   seekTo(0)

   to replay.
2. Hook-based API: Prefer

   useAudioPlayer()

   over

   Audio.Sound.createAsync()

3. Direct property access: Use

   player.volume = 0.5

   instead of

   player.setVolumeAsync(0.5)

4. Simplified API: Fewer methods, more direct property access

Migration Example

Before (expo-av):

const { sound } = await Audio.Sound.createAsync({ uri });
await sound.setVolumeAsync(0.5);
await sound.setPositionAsync(0);
await sound.playAsync();

After (expo-audio):

const player = createAudioPlayer({ uri });
player.volume = 0.5;
player.seekTo(0);
player.play();

Web Considerations

• MediaRecorder on Chrome may produce WebM files missing duration metadata (known Chromium issue)
• Consider using polyfills like

  kbumsik/opus-media-recorder

  for better browser compatibility
• Web browsers require HTTPS for microphone access (MediaDevices getUserMedia security)

Permissions

Request Recording Permissions

import { AudioModule } from "expo-audio";

const status = await AudioModule.requestRecordingPermissionsAsync();
if (!status.granted) {
 // Handle permission denied
}

Check Permission Status

const status = await AudioModule.getRecordingPermissionsAsync();
// status.granted, status.canAskAgain, etc.

Best Practices

1. Use hooks in components: Prefer

   useAudioPlayer()

   in React components for automatic lifecycle management
2. Release resources: Always call

   release()

   when using

   createAudioPlayer()

   manually
3. Reset position for replay: Call

   seekTo(0)

   before replaying sounds
4. Configure audio mode: Set

   playsInSilentMode: true

   for meditation/notification sounds
5. Handle errors: Wrap audio operations in try-catch blocks
6. Preload sounds: Load sounds on app start for better UX

References

• Expo Audio Documentation
• Expo Audio GitHub
• Migration from expo-av