expo-audio（世博音响）

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