📄 expo/versions/v53.0.0/sdk/audio

File: audio.md | Updated: 11/15/2025

Source: https://docs.expo.dev/versions/v53.0.0/sdk/audio

Hide navigation

Ctrl K

Home Guides EAS Reference Learn

Reference version

SDK 53

Archive Expo Snack Discord and Forums Newsletter

Expo Audio (expo-audio)

GitHub Changelog npm

A library that provides an API to implement audio playback and recording in apps.

GitHub Changelog npm

Android

iOS

tvOS

Web

Bundled version:

~0.4.9

Copy page

expo-audio is a cross-platform audio library for accessing the native audio capabilities of the device.

Note that audio automatically stops if headphones/bluetooth audio devices are disconnected.

Installation

Terminal

Copy

- npx expo install expo-audio

If you are installing this in an existing React Native app , make sure to install expo in your project.

Configuration in app config

You can configure expo-audio using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG) ). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.

Example app.json with config plugin

app.json

Copy

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

Configurable properties

| Name | Default | Description | | --- | --- | --- | | microphonePermission | "Allow $(PRODUCT_NAME) to access your microphone" | Only for: iOS A string to set the NSMicrophoneUsageDescription permission message. |

Usage

Playing sounds

Copy

Open in Snack

import { View, StyleSheet, Button } from 'react-native'; import { useAudioPlayer } from 'expo-audio'; const audioSource = require('./assets/Hello.mp3'); export default function App() { const player = useAudioPlayer(audioSource); return ( <View style={styles.container}> <Button title="Play Sound" onPress={() => player.play()} /> <Button title="Replay Sound" onPress={() => { player.seekTo(0); player.play(); }} /> </View> ); } const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', backgroundColor: '#ecf0f1', padding: 10, }, });

Note: If you're migrating from expo-av , you'll notice that expo-audio doesn't automatically reset the playback position when audio finishes. After play() , the player stays paused at the end of the sound. To play it again, call seekTo(seconds) to reset the position — as shown in the example above.

Recording sounds

Copy

Open in Snack

import { useState, useEffect } from 'react'; import { View, StyleSheet, Button } from 'react-native'; import { useAudioRecorder, AudioModule, RecordingPresets, setAudioModeAsync, 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 () => { // The recording will be 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'); } setAudioModeAsync({ playsInSilentMode: true, allowsRecording: true, }); })(); }, []); return ( <View style={styles.container}> <Button title={recorderState.isRecording ? 'Stop Recording' : 'Start Recording'} onPress={recorderState.isRecording ? stopRecording : record} /> </View> ); } const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', backgroundColor: '#ecf0f1', padding: 10, }, });

Playing or recording audio in background

iOS

On iOS, audio playback and recording in background is only available in standalone apps, and it requires some extra configuration. On iOS, each background feature requires a special key in UIBackgroundModes array in your Info.plist file. In standalone apps this array is empty by default, so to use background features you will need to add appropriate keys to your app.json configuration.

See an example of app.json that enables audio playback in background:

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

Using the AudioPlayer directly

In most cases, the useAudioPlayer hook should be used to create a AudioPlayer instance. It manages the player's lifecycle and ensures that it is properly disposed of when the component is unmounted. However, in some advanced use cases, it might be necessary to create a AudioPlayer that does not get automatically destroyed when the component is unmounted. In those cases, the AudioPlayer can be created using the createAudioPlayer function. You need be aware of the risks that come with this approach, as it is your responsibility to call the release() method when the player is no longer needed. If not handled properly, this approach may lead to memory leaks.

import { createAudioPlayer } from 'expo-audio'; const player = createAudioPlayer(audioSource);

Notes on web usage

A MediaRecorder issue on Chrome produces WebM files missing the duration metadata. See the open Chromium issue .
MediaRecorder encoding options and other configurations are inconsistent across browsers, utilizing a Polyfill such as kbumsik/opus-media-recorder or ai/audio-recorder-polyfill in your application will improve your experience. Any options passed to prepareToRecordAsync will be passed directly to the MediaRecorder API and as such the polyfill.
Web browsers require sites to be served securely for them to listen to a mic. See MediaDevices getUserMedia() security for more details.

API

import { useAudioPlayer, useAudioRecorder } from 'expo-audio';

Constants

`Audio.AUDIO_SAMPLE_UPDATE`

Type: 'audioSampleUpdate'

`Audio.PLAYBACK_STATUS_UPDATE`

Type: 'playbackStatusUpdate'

`Audio.RECORDING_STATUS_UPDATE`

Type: 'recordingStatusUpdate'

`Audio.RecordingPresets`

Type: Record<string, [RecordingOptions](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recordingoptions) >

Constant which contains definitions of the two preset examples of RecordingOptions, as implemented in the Audio SDK.

`HIGH_QUALITY`

RecordingPresets.HIGH_QUALITY = { extension: '.m4a', sampleRate: 44100, numberOfChannels: 2, bitRate: 128000, android: { outputFormat: 'mpeg4', audioEncoder: 'aac', }, ios: { outputFormat: IOSOutputFormat.MPEG4AAC, audioQuality: AudioQuality.MAX, linearPCMBitDepth: 16, linearPCMIsBigEndian: false, linearPCMIsFloat: false, }, web: { mimeType: 'audio/webm', bitsPerSecond: 128000, }, };

`LOW_QUALITY`

RecordingPresets.LOW_QUALITY = { extension: '.m4a', sampleRate: 44100, numberOfChannels: 2, bitRate: 64000, android: { extension: '.3gp', outputFormat: '3gp', audioEncoder: 'amr_nb', }, ios: { audioQuality: AudioQuality.MIN, outputFormat: IOSOutputFormat.MPEG4AAC, linearPCMBitDepth: 16, linearPCMIsBigEndian: false, linearPCMIsFloat: false, }, web: { mimeType: 'audio/webm', bitsPerSecond: 128000, }, };

Hooks

`useAudioPlayer(source, updateInterval)`

| Parameter | Type | | --- | --- | | source(optional) | [AudioSource](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audiosource) | | updateInterval(optional) | number |

Returns:

[AudioPlayer](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audioplayer)

`useAudioPlayerStatus(player)`

| Parameter | Type | | --- | --- | | player | [AudioPlayer](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audioplayer) |

Returns:

[AudioStatus](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audiostatus)

`useAudioRecorder(options, statusListener)`

| Parameter | Type | | --- | --- | | options | [RecordingOptions](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recordingoptions) | | statusListener(optional) | (status: [RecordingStatus](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recordingstatus) ) => void |

Returns:

[AudioRecorder](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audiorecorder)

`useAudioRecorderState(recorder, interval)`

| Parameter | Type | | --- | --- | | recorder | [AudioRecorder](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audiorecorder) | | interval(optional) | number |

Returns:

[RecorderState](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recorderstate)

`useAudioSampleListener(player, listener)`

The current volume of the audio.

AudioPlayer Methods

`pause()`

Pauses the player.

Returns:

void

`play()`

Start playing audio.

Returns:

void

Type: Class extends [SharedObject](https://docs.expo.dev/versions/v53.0.0/sdk/expo#sharedobject) <[RecordingEvents](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recordingevents) >

AudioRecorder Properties

`currentTime`

Type: number

The current length of the recording, in seconds.

`id`

Type: number

Unique identifier for the recorder object.

`isRecording`

Type: boolean

Boolean value indicating whether the recording is in progress.

`uri`

Literal type: union

The uri of the recording.

Acceptable values are: null | string

AudioRecorder Methods

`getAvailableInputs()`

Returns a list of available recording inputs. This method can only be called if the Recording has been prepared.

Returns:

[RecordingInput[]](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recordinginput)

A Promise that is fulfilled with an array of RecordingInput objects.

`getCurrentInput()`

Returns the currently-selected recording input. This method can only be called if the Recording has been prepared.

Returns:

[RecordingInput](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recordinginput)

A Promise that is fulfilled with a RecordingInput object.

`getStatus()`

`startRecordingAtTime(seconds)`

| Parameter | Type | Description | | --- | --- | --- | | seconds | number | The time in seconds to start recording at. |

Starts the recording at the given time.

Returns:

void

`stop()`

Stop the recording.

Returns:

[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) <void>

Methods

`Audio.createAudioPlayer(source, updateInterval)`

| Parameter | Type | | --- | --- | | source(optional) | [AudioSource](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audiosource) | | updateInterval(optional) | number |

Creates an instance of an AudioPlayer that doesn't release automatically.

For most use cases you should use the useAudioPlayer hook instead. See the Using the AudioPlayer directly section for more details.

Returns:

[AudioPlayer](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audioplayer)

`Audio.getRecordingPermissionsAsync()`

Returns:

[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) <PermissionResponse>

`Audio.requestRecordingPermissionsAsync()`

Returns:

[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) <PermissionResponse>

`Audio.setAudioModeAsync(mode)`

| Parameter | Type | | --- | --- | | mode | [Partial](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) <[AudioMode](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audiomode) > |

Returns:

[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) <void>

`Audio.setIsAudioActiveAsync(active)`

| Parameter | Type | | --- | --- | | active | boolean |

Returns:

[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) <void>

Event Subscriptions

`Audio.useAudioSampleListener(player, listener)`

Returns:

void

Types

`AndroidAudioEncoder`

Only for:

Android

Literal Type: string

`AndroidOutputFormat`

Only for:

Android

Literal Type: string

`AudioEvents`

| Property | Type | Description | | --- | --- | --- | | audioSampleUpdate | (data: [AudioSample](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audiosample) ) => void | - | | playbackStatusUpdate | (status: [AudioStatus](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audiostatus) ) => void | - |

`AudioMode`

| Property | Type | Description | | --- | --- | --- | | allowsRecording(optional) | boolean | Only for: iOS Whether the audio session allows recording. Default:false | | interruptionMode | [InterruptionMode](https://docs.expo.dev/versions/v53.0.0/sdk/audio#interruptionmode) | Only for: iOS Determines how the audio session interacts with other sessions. | | interruptionModeAndroid | [InterruptionModeAndroid](https://docs.expo.dev/versions/v53.0.0/sdk/audio#interruptionmodeandroid) | Only for: Android Determines how the audio session interacts with other sessions on Android. | | playsInSilentMode | boolean | Only for: iOS Determines if audio playback is allowed when the device is in silent mode. | | shouldPlayInBackground(optional) | boolean | Whether the audio session stays active when the app moves to the background. Default:false | | shouldRouteThroughEarpiece | boolean | Only for: Android Whether the audio should route through the earpiece. |

`AudioSample`

| Property | Type | Description | | --- | --- | --- | | channels | [AudioSampleChannel[]](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audiosamplechannel) | - | | timestamp | number | - |

`AudioSampleChannel`

| Property | Type | Description | | --- | --- | --- | | frames | number[] | - |

`AudioSource`

Type: string or number or null or object shaped as below:

| Property | Type | Description | | --- | --- | --- | | assetId(optional) | number | The asset ID of a local audio asset, acquired with the require function. This property is exclusive with the uri property. When both are present, the assetId will be ignored. | | headers(optional) | Record<string, string> | An object representing the HTTP headers to send along with the request for a remote audio source. On web requires the Access-Control-Allow-Origin header returned by the server to include the current domain. | | uri(optional) | string | A string representing the resource identifier for the audio, which could be an HTTPS address, a local file path, or the name of a static audio file resource. |

`AudioStatus`

| Property | Type | Description | | --- | --- | --- | | currentTime | number | - | | didJustFinish | boolean | - | | duration | number | - | | id | number | - | | isBuffering | boolean | - | | isLoaded | boolean | - | | loop | boolean | - | | mute | boolean | - | | playbackRate | number | - | | playbackState | string | - | | playing | boolean | - | | reasonForWaitingToPlay | string | - | | shouldCorrectPitch | boolean | - | | timeControlStatus | string | - |

`BitRateStrategy`

Literal Type: string

Acceptable values are: 'constant' | 'longTermAverage' | 'variableConstrained' | 'variable'

`InterruptionMode`

Literal Type: string

Acceptable values are: 'mixWithOthers' | 'doNotMix' | 'duckOthers'

`InterruptionModeAndroid`

Literal Type: string

Acceptable values are: 'doNotMix' | 'duckOthers'

`PermissionExpiration`

Literal Type: union

Permission expiration time. Currently, all permissions are granted permanently.

Acceptable values are: 'never' | number

`PermissionResponse`

An object obtained by permissions get and request functions.

| Property | Type | Description | | --- | --- | --- | | canAskAgain | boolean | Indicates if user can be asked again for specific permission. If not, one should be directed to the Settings app in order to enable/disable the permission. | | expires | [PermissionExpiration](https://docs.expo.dev/versions/v53.0.0/sdk/audio#permissionexpiration) | Determines time when the permission expires. | | granted | boolean | A convenience boolean that indicates if the permission is granted. | | status | [PermissionStatus](https://docs.expo.dev/versions/v53.0.0/sdk/audio#permissionstatus) | Determines the status of the permission. |

`PitchCorrectionQuality`

Literal Type: string

Acceptable values are: 'low' | 'medium' | 'high'

`RecorderState`

| Property | Type | Description | | --- | --- | --- | | canRecord | boolean | - | | durationMillis | number | - | | isRecording | boolean | - | | mediaServicesDidReset | boolean | - | | metering(optional) | number | - | | url | string \| null | - |

`RecordingEvents`

| Property | Type | Description | | --- | --- | --- | | recordingStatusUpdate | (status: [RecordingStatus](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recordingstatus) ) => void | - |

`RecordingInput`

| Property | Type | Description | | --- | --- | --- | | name | string | - | | type | string | - | | uid | string | - |

`RecordingOptions`

| Property | Type | Description | | --- | --- | --- | | android | [RecordingOptionsAndroid](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recordingoptionsandroid) | Only for: Android Recording options for the Android platform. | | bitRate | number | The desired bit rate. Example 128000 | | extension | string | The desired file extension. Example .caf | | ios | [RecordingOptionsIos](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recordingoptionsios) | Only for: iOS Recording options for the iOS platform. | | isMeteringEnabled(optional) | boolean | A boolean that determines whether audio level information will be part of the status object under the "metering" key. | | numberOfChannels | number | The desired number of channels. Example 2 | | sampleRate | number | The desired sample rate. Example 44100 | | web(optional) | [RecordingOptionsWeb](https://docs.expo.dev/versions/v53.0.0/sdk/audio#recordingoptionsweb) | Only for: Web Recording options for the Web platform. |

`RecordingOptionsAndroid`

Only for:

Android

| Property | Type | Description | | --- | --- | --- | | audioEncoder | [AndroidAudioEncoder](https://docs.expo.dev/versions/v53.0.0/sdk/audio#androidaudioencoder) | The desired audio encoder. See the AndroidAudioEncoder enum for all valid values. | | extension(optional) | string | The desired file extension. Example .caf | | maxFileSize(optional) | number | The desired maximum file size in bytes, after which the recording will stop (but stopAndUnloadAsync() must still be called after this point). Example 65536 | | outputFormat | [AndroidOutputFormat](https://docs.expo.dev/versions/v53.0.0/sdk/audio#androidoutputformat) | The desired file format. See the AndroidOutputFormat enum for all valid values. | | sampleRate(optional) | number | The desired sample rate. Example 44100 |

`RecordingOptionsIos`

Only for:

iOS

| Property | Type | Description | | --- | --- | --- | | audioQuality | [AudioQuality](https://docs.expo.dev/versions/v53.0.0/sdk/audio#audioquality) \| number | The desired audio quality. See the AudioQuality enum for all valid values. | | bitDepthHint(optional) | number | The desired bit depth hint. Example 16 | | bitRateStrategy(optional) | number | The desired bit rate strategy. See the next section for an enumeration of all valid values of bitRateStrategy. | | extension(optional) | string | The desired file extension. Example .caf | | linearPCMBitDepth(optional) | number | The desired PCM bit depth. Example 16 | | linearPCMIsBigEndian(optional) | boolean | A boolean describing if the PCM data should be formatted in big endian. | | linearPCMIsFloat(optional) | boolean | A boolean describing if the PCM data should be encoded in floating point or integral values. | | outputFormat(optional) | string \| [IOSOutputFormat](https://docs.expo.dev/versions/v53.0.0/sdk/audio#iosoutputformat) \| number | The desired file format. See the IOSOutputFormat enum for all valid values. | | sampleRate(optional) | number | The desired sample rate. Example 44100 |

`RecordingOptionsWeb`

Only for:

Web

| Property | Type | Description | | --- | --- | --- | | bitsPerSecond(optional) | number | - | | mimeType(optional) | string | - |

`RecordingStatus`

| Property | Type | Description | | --- | --- | --- | | error | string \| null | - | | hasError | boolean | - | | id | number | - | | isFinished | boolean | - | | url | string \| null | - |

Enums

`AudioQuality`

`MIN`

AudioQuality.MIN ＝ 0

`LOW`

AudioQuality.LOW ＝ 32

`MEDIUM`

AudioQuality.MEDIUM ＝ 64

`HIGH`

AudioQuality.HIGH ＝ 96

`MAX`

AudioQuality.MAX ＝ 127

`IOSOutputFormat`

Only for:

iOS

`MPEGLAYER1`

IOSOutputFormat.MPEGLAYER1 ＝ ".mp1"

`MPEGLAYER2`

IOSOutputFormat.MPEGLAYER2 ＝ ".mp2"

`MPEGLAYER3`

IOSOutputFormat.MPEGLAYER3 ＝ ".mp3"

`MPEG4AAC`

IOSOutputFormat.MPEG4AAC ＝ "aac "

`MPEG4AAC_ELD`

IOSOutputFormat.MPEG4AAC_ELD ＝ "aace"

`MPEG4AAC_ELD_SBR`

IOSOutputFormat.MPEG4AAC_ELD_SBR ＝ "aacf"

`MPEG4AAC_ELD_V2`

IOSOutputFormat.MPEG4AAC_ELD_V2 ＝ "aacg"

`MPEG4AAC_HE`

IOSOutputFormat.MPEG4AAC_HE ＝ "aach"

`MPEG4AAC_LD`

IOSOutputFormat.MPEG4AAC_LD ＝ "aacl"

`MPEG4AAC_HE_V2`

IOSOutputFormat.MPEG4AAC_HE_V2 ＝ "aacp"

`MPEG4AAC_SPATIAL`

IOSOutputFormat.MPEG4AAC_SPATIAL ＝ "aacs"

`AC3`

IOSOutputFormat.AC3 ＝ "ac-3"

`AES3`

IOSOutputFormat.AES3 ＝ "aes3"

`APPLELOSSLESS`

IOSOutputFormat.APPLELOSSLESS ＝ "alac"

`ALAW`

IOSOutputFormat.ALAW ＝ "alaw"

`AUDIBLE`

IOSOutputFormat.AUDIBLE ＝ "AUDB"

`60958AC3`

IOSOutputFormat.60958AC3 ＝ "cac3"

`MPEG4CELP`

IOSOutputFormat.MPEG4CELP ＝ "celp"

`ENHANCEDAC3`

IOSOutputFormat.ENHANCEDAC3 ＝ "ec-3"

`MPEG4HVXC`

IOSOutputFormat.MPEG4HVXC ＝ "hvxc"

`ILBC`

IOSOutputFormat.ILBC ＝ "ilbc"

`APPLEIMA4`

IOSOutputFormat.APPLEIMA4 ＝ "ima4"

`LINEARPCM`

IOSOutputFormat.LINEARPCM ＝ "lpcm"

`MACE3`

IOSOutputFormat.MACE3 ＝ "MAC3"

`MACE6`

IOSOutputFormat.MACE6 ＝ "MAC6"

`AMR`

IOSOutputFormat.AMR ＝ "samr"

`AMR_WB`

IOSOutputFormat.AMR_WB ＝ "sawb"

`DVIINTELIMA`

IOSOutputFormat.DVIINTELIMA ＝ 1836253201

`MICROSOFTGSM`

IOSOutputFormat.MICROSOFTGSM ＝ 1836253233

`QUALCOMM`

IOSOutputFormat.QUALCOMM ＝ "Qclp"

`QDESIGN2`

IOSOutputFormat.QDESIGN2 ＝ "QDM2"

`QDESIGN`

IOSOutputFormat.QDESIGN ＝ "QDMC"

`MPEG4TWINVQ`

IOSOutputFormat.MPEG4TWINVQ ＝ "twvq"

`ULAW`

IOSOutputFormat.ULAW ＝ "ulaw"

`PermissionStatus`

`DENIED`

PermissionStatus.DENIED ＝ "denied"

User has denied the permission.

`GRANTED`

PermissionStatus.GRANTED ＝ "granted"

User has granted the permission.

`UNDETERMINED`

PermissionStatus.UNDETERMINED ＝ "undetermined"

User hasn't granted or denied the permission yet.