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

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

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

Hide navigation

Ctrl K

Home Guides EAS Reference Learn

Reference version

SDK 54

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:

~1.0.14

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. Setting it to false will disable the permission. | | recordAudioAndroid | true | Only for: Android A boolean that determines whether to enable the RECORD_AUDIO permission on Android. |

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 to 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.RecordingPresets`

Type: { HIGH_QUALITY: [RecordingOptions](https://docs.expo.dev/versions/v54.0.0/sdk/audio#recordingoptions) , LOW_QUALITY: [RecordingOptions](https://docs.expo.dev/versions/v54.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, options)`

| Parameter | Type | Description | | --- | --- | --- | | source(optional) | [AudioSource](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audiosource) | The audio source to load. Can be a local asset via require(), a remote URL, or null for no initial source. Default:null | | options(optional) | [AudioPlayerOptions](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audioplayeroptions) | Audio player configuration options. Default:{} |

Creates an AudioPlayer instance that automatically releases when the component unmounts.

This hook manages the player's lifecycle and ensures it's properly disposed when no longer needed. The player will start loading the audio source immediately upon creation.

Returns:

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

An AudioPlayer instance that's automatically managed by the component lifecycle.

Example

import { useAudioPlayer } from 'expo-audio'; function MyComponent() { const player = useAudioPlayer(require('./sound.mp3')); return ( <Button title="Play" onPress={() => player.play()} /> ); }

Example

import { useAudioPlayer } from 'expo-audio'; function MyComponent() { const player = useAudioPlayer('https://example.com/audio.mp3', { updateInterval: 1000, downloadFirst: true, }); return ( <Button title="Play" onPress={() => player.play()} /> ); }

`useAudioPlayerStatus(player)`

| Parameter | Type | Description | | --- | --- | --- | | player | [AudioPlayer](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audioplayer) | The AudioPlayer instance to monitor. |

Hook that provides real-time playback status updates for an AudioPlayer.

This hook automatically subscribes to playback status changes and returns the current status. The status includes information about playback state, current time, duration, loading state, and more.

Returns:

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

The current AudioStatus object containing playback information.

Example

import { useAudioPlayer, useAudioPlayerStatus } from 'expo-audio'; function PlayerComponent() { const player = useAudioPlayer(require('./sound.mp3')); const status = useAudioPlayerStatus(player); return ( <View> <Text>Playing: {status.playing ? 'Yes' : 'No'}</Text> <Text>Current Time: {status.currentTime}s</Text> <Text>Duration: {status.duration}s</Text> </View> ); }

`useAudioRecorder(options, statusListener)`

| Parameter | Type | Description | | --- | --- | --- | | options | [RecordingOptions](https://docs.expo.dev/versions/v54.0.0/sdk/audio#recordingoptions) | Recording configuration options including format, quality, sample rate, etc. | | statusListener(optional) | (status: [RecordingStatus](https://docs.expo.dev/versions/v54.0.0/sdk/audio#recordingstatus) ) => void | Optional callback function that receives recording status updates. |

Hook that creates an AudioRecorder instance for recording audio.

This hook manages the recorder's lifecycle and ensures it's properly disposed when no longer needed. The recorder is automatically prepared with the provided options and can be used to record audio.

Returns:

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

An AudioRecorder instance that's automatically managed by the component lifecycle.

Example

import { useAudioRecorder, RecordingPresets } from 'expo-audio'; function RecorderComponent() { const recorder = useAudioRecorder( RecordingPresets.HIGH_QUALITY, (status) => console.log('Recording status:', status) ); const startRecording = async () => { await recorder.prepareToRecordAsync(); recorder.record(); }; return ( <Button title="Start Recording" onPress={startRecording} /> ); }

`useAudioRecorderState(recorder, interval)`

| Parameter | Type | Description | | --- | --- | --- | | recorder | [AudioRecorder](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audiorecorder) | The AudioRecorder instance to monitor. | | interval(optional) | number | How often (in milliseconds) to poll the recorder's status. Defaults to 500ms. Default:500 |

Hook that provides real-time recording state updates for an AudioRecorder.

This hook polls the recorder's status at regular intervals and returns the current recording state. Use this when you need to monitor the recording status without setting up a status listener.

Returns:

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

The current RecorderState containing recording information.

Example

import { useAudioRecorder, useAudioRecorderState, RecordingPresets } from 'expo-audio'; function RecorderStatusComponent() { const recorder = useAudioRecorder(RecordingPresets.HIGH_QUALITY); const state = useAudioRecorderState(recorder); return ( <View> <Text>Recording: {state.isRecording ? 'Yes' : 'No'}</Text> <Text>Duration: {Math.round(state.durationMillis / 1000)}s</Text> <Text>Can Record: {state.canRecord ? 'Yes' : 'No'}</Text> </View> ); }

`useAudioSampleListener(player, listener)`

| Parameter | Type | Description | | --- | --- | --- | | player | [AudioPlayer](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audioplayer) | The AudioPlayer instance to sample audio from. | | listener | (data: [AudioSample](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audiosample) ) => void | Function called with each audio sample containing waveform data. |

Hook that sets up audio sampling for an AudioPlayer and calls a listener with audio data.

This hook enables audio sampling on the player (if supported) and subscribes to audio sample updates. Audio sampling provides real-time access to audio waveform data for visualization or analysis.

Note: Audio sampling requires RECORD_AUDIO permission on Android and is not supported on all platforms.

Type: boolean

A boolean describing if we are correcting the pitch for a changed rate.

`volume`

Type: number

The current volume of the audio.

Range: 0.0 to 1.0. For example, 0.0 is completely silent (0%), 0.5 is half volume (50%), and 1.0 is full volume (100%).

Example

import { useAudioPlayer } from 'expo-audio'; export default function App() { const player = useAudioPlayer(source); // Mute the audio player.volume = 0.0; // Set volume to 50% player.volume = 0.5; // Set to full volume player.volume = 1.0; }

AudioPlayer Methods

`clearLockScreenControls()`

Removes this player from lock screen controls if it's currently active. This will clear the lock screen's now playing info.

Returns:

void

`pause()`

Pauses the player.

Returns:

void

`play()`

Start playing audio.

Returns:

void

Type: Class extends [SharedObject](https://docs.expo.dev/versions/v54.0.0/sdk/expo#sharedobjecttype) <[RecordingEvents](https://docs.expo.dev/versions/v54.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/v54.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:

[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) <[RecordingInput](https://docs.expo.dev/versions/v54.0.0/sdk/audio#recordinginput) >

A Promise that is fulfilled with a RecordingInput object.

`getStatus()`

Status of the current recording.

Returns:

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

`pause()`

Pause the recording.

Returns:

void

`prepareToRecordAsync(options)`

| Parameter | Type | | --- | --- | | options(optional) | [Partial](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) <[RecordingOptions](https://docs.expo.dev/versions/v54.0.0/sdk/audio#recordingoptions) > |

Prepares the recording for recording.

Returns:

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

`record(options)`

| Parameter | Type | Description | | --- | --- | --- | | options(optional) | [RecordingStartOptions](https://docs.expo.dev/versions/v54.0.0/sdk/audio#recordingstartoptions) | Optional recording configuration options. |

Starts the recording.

Returns:

void

Deprecated Use record({ forDuration: seconds }) instead.

`recordForDuration(seconds)`

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

Stops the recording once the specified time has elapsed.

Returns:

void

`setInput(inputUid)`

| Parameter | Type | Description | | --- | --- | --- | | inputUid | string | The uid of a RecordingInput. |

Sets the current recording input.

Returns:

void

A Promise that is resolved if successful or rejected if not.

Deprecated Use record({ atTime: seconds }) instead.

`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, options)`

| Parameter | Type | Description | | --- | --- | --- | | source(optional) | [AudioSource](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audiosource) | The audio source to load. Default:null | | options(optional) | [AudioPlayerOptions](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audioplayeroptions) | Audio player configuration options. Default:{} |

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/v54.0.0/sdk/audio#audioplayer)

`Audio.getRecordingPermissionsAsync()`

Checks the current status of recording permissions without requesting them.

This function returns the current permission status for microphone access without triggering a permission request dialog. Use this to check permissions before deciding whether to call requestRecordingPermissionsAsync().

Returns:

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

A Promise that resolves to a PermissionResponse object containing the current permission status.

Example

import { getRecordingPermissionsAsync, requestRecordingPermissionsAsync } from 'expo-audio'; const ensureRecordingPermissions = async () => { const { status } = await getRecordingPermissionsAsync(); if (status !== 'granted') { // Permission not granted, request it const { granted } = await requestRecordingPermissionsAsync(); return granted; } return true; // Already granted };

`Audio.requestRecordingPermissionsAsync()`

Requests permission to record audio from the microphone.

This function prompts the user for microphone access permission, which is required for audio recording functionality. On iOS, this will show the system permission dialog. On Android, this requests the RECORD_AUDIO permission.

Returns:

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

A Promise that resolves to a PermissionResponse object containing the permission status.

Example

import { requestRecordingPermissionsAsync } from 'expo-audio'; const checkPermissions = async () => { const { status, granted } = await requestRecordingPermissionsAsync(); if (granted) { console.log('Recording permission granted'); } else { console.log('Recording permission denied:', status); } };

`Audio.setAudioModeAsync(mode)`

| Parameter | Type | Description | | --- | --- | --- | | mode | [Partial](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) <[AudioMode](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audiomode) > | Partial audio mode configuration object. Only specified properties will be updated. |

Configures the global audio behavior and session settings.

This function allows you to control how your app's audio interacts with other apps, background playback behavior, audio routing, and interruption handling.

Returns:

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

A Promise that resolves when the audio mode has been applied.

Example

import { setAudioModeAsync } from 'expo-audio'; // Configure audio for background playback await setAudioModeAsync({ playsInSilentMode: true, shouldPlayInBackground: true, interruptionModeAndroid: 'duckOthers', interruptionMode: 'mixWithOthers' }); // Configure audio for recording await setAudioModeAsync({ allowsRecording: true, playsInSilentMode: true });

`Audio.setIsAudioActiveAsync(active)`

| Parameter | Type | Description | | --- | --- | --- | | active | boolean | Whether audio should be active (true) or disabled (false). |

Enables or disables the audio subsystem globally.

When set to false, this will pause all audio playback and prevent new audio from playing. This is useful for implementing app-wide audio controls or responding to system events.

Returns:

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

A Promise that resolves when the audio state has been updated.

Example

import { setIsAudioActiveAsync } from 'expo-audio'; // Disable all audio when app goes to background const handleAppStateChange = async (nextAppState) => { if (nextAppState === 'background') { await setIsAudioActiveAsync(false); } else if (nextAppState === 'active') { await setIsAudioActiveAsync(true); } };

Event Subscriptions

`Audio.useAudioSampleListener(player, listener)`

Hook that sets up audio sampling for an AudioPlayer and calls a listener with audio data.

This hook enables audio sampling on the player (if supported) and subscribes to audio sample updates. Audio sampling provides real-time access to audio waveform data for visualization or analysis.

Note: Audio sampling requires RECORD_AUDIO permission on Android and is not supported on all platforms.

Returns:

void

Example

Types

`AndroidAudioEncoder`

Only for:

Android

Literal Type: string

Audio encoder options for Android recording.

Specifies the audio codec used to encode recorded audio on Android. Different encoders offer different quality, compression, and compatibility trade-offs.

`AndroidOutputFormat`

Only for:

Android

Literal Type: string

Audio output format options for Android recording.

Specifies the container format for recorded audio files on Android. Different formats have different compatibility and compression characteristics.

`AudioEvents`

Event types that an AudioPlayer can emit.

These events allow you to listen for changes in playback state and receive real-time audio data. Use player.addListener() to subscribe to these events.

| Property | Type | Description | | --- | --- | --- | | audioSampleUpdate | (data: [AudioSample](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audiosample) ) => void | Fired when audio sampling is enabled and new sample data is available. | | playbackStatusUpdate | (status: [AudioStatus](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audiostatus) ) => void | Fired when the player's status changes (play/pause/seek/load and so on.). |

Deprecated Use AudioPlayerOptions instead. Options for audio loading behavior.

`AudioLoadOptions`

Type: [AudioPlayerOptions](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audioplayeroptions)

`AudioLockScreenOptions`

Options for configuring which playback controls should be displayed on the lock screen.

| Property | Type | Description | | --- | --- | --- | | showSeekBackward(optional) | boolean | Whether the seek backward button should be displayed on the lock screen. | | showSeekForward(optional) | boolean | Whether the seek forward button should be displayed on the lock screen. |

`AudioMetadata`

| Property | Type | Description | | --- | --- | --- | | albumTitle(optional) | string | - | | artist(optional) | string | - | | artworkUrl(optional) | string | - | | title(optional) | string | - |

`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/v54.0.0/sdk/audio#interruptionmode) | Only for: iOS Determines how the audio session interacts with other sessions. | | interruptionModeAndroid | [InterruptionModeAndroid](https://docs.expo.dev/versions/v54.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. |

`AudioPlayerOptions`

Options for configuring audio player behavior.

| Property | Type | Description | | --- | --- | --- | | crossOrigin(optional) | 'anonymous' \| 'use-credentials' | Only for: Web Determines the cross origin policy used by the underlying native view on web. If undefined (default), does not use CORS at all. If set to 'anonymous', the audio will be loaded with CORS enabled. Note that some audio may not play if CORS is enabled, depending on the CDN settings. If you encounter issues, consider adjusting the crossOrigin property. Default:undefined | | downloadFirst(optional) | boolean | Only for: Android iOS Web If set to true, the system will attempt to download the resource to the device before loading. This value defaults to false. Works with: * Local assets from require('path/to/file') * Remote HTTP/HTTPS URLs * Asset objects When enabled, this ensures the audio file is fully downloaded before playback begins. This can improve playback performance and reduce buffering, especially for users managing multiple audio players simultaneously. On Android and iOS, this will download the audio file to the device's tmp directory before playback begins. The system will purge the file at its discretion. On web, this will download the audio file to the user's device memory and make it available for the user to play. The system will usually purge the file from memory after a reload or on memory pressure. On web, CORS restrictions apply to the blob url, so you need to make sure the server returns the Access-Control-Allow-Origin header. | | keepAudioSessionActive(optional) | boolean | Only for: iOS If set to true, the audio session will not be deactivated when this player pauses or finishes playback. This prevents interrupting other audio sources (like videos) when the audio ends. Useful for sound effects that should not interfere with ongoing video playback or other audio. The audio session for this player will not be deactivated automatically when the player finishes playback. > Note: If needed, you can manually deactivate the audio session using setIsAudioActiveAsync(false). Default:false | | updateInterval(optional) | number | Only for: Android iOS Web How often (in milliseconds) to emit playback status updates. Defaults to 500ms. Default:500ms Example import { useAudioPlayer } from 'expo-audio'; export default function App() { const player = useAudioPlayer(source); // High-frequency updates for smooth progress bars const player = useAudioPlayer(source, { updateInterval: 100 }); // Standard updates (default behavior) const player = useAudioPlayer(source, { updateInterval: 500 }); // Low-frequency updates for better performance const player = useAudioPlayer(source, { updateInterval: 1000 }); } |

`AudioSample`

Represents a single audio sample containing waveform data from all audio channels.

Audio samples are provided in real-time when audio sampling is enabled on an AudioPlayer. Each sample contains the raw PCM audio data for all channels (mono has 1 channel, stereo has 2). This data can be used for audio visualization, analysis, or processing.

| Property | Type | Description | | --- | --- | --- | | channels | [AudioSampleChannel[]](https://docs.expo.dev/versions/v54.0.0/sdk/audio#audiosamplechannel) | Array of audio channels, each containing PCM frame data. Stereo audio will have 2 channels (left/right). | | timestamp | number | Timestamp of this sample relative to the audio track's timeline, in seconds. |

`AudioSampleChannel`

Represents audio data for a single channel (for example, left or right in stereo audio).

Contains the raw PCM (Pulse Code Modulation) audio frames for this channel. Frame values are normalized between -1.0 and 1.0, where 0 represents silence.

| Property | Type | Description | | --- | --- | --- | | frames | number[] | Array of PCM audio frame values, each between -1.0 and 1.0. |

`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`

Comprehensive status information for an AudioPlayer.

This object contains all the current state information about audio playback, including playback position, duration, loading state, and playback settings. Used by useAudioPlayerStatus() to provide real-time status updates.

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/v54.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/v54.0.0/sdk/audio#permissionstatus) | Determines the status of the permission. |

`PitchCorrectionQuality`

Only for:

iOS

Literal Type: string

Pitch correction quality settings for audio playback rate changes.

When changing playback rate, pitch correction can be applied to maintain the original pitch. Different quality levels offer trade-offs between processing power and audio quality.

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

`RecorderState`

Current state information for an AudioRecorder.

This object contains detailed information about the recorder's current state, including recording status, duration, and technical details. This is what you get when calling recorder.getStatus() or using useAudioRecorderState().

| Property | Type | Description | | --- | --- | --- | | canRecord | boolean | Whether the recorder is ready and able to record. | | durationMillis | number | Duration of the current recording in milliseconds. | | isRecording | boolean | Whether recording is currently in progress. | | mediaServicesDidReset | boolean | Whether the media services have been reset (typically indicates a system interruption). | | metering(optional) | number | Current audio level/volume being recorded (if metering is enabled). | | url | string \| null | File URL where the recording will be saved, if available. |

`RecordingEvents`

Event types that an AudioRecorder can emit.

These events are used internally by expo-audio hooks to provide real-time status updates. Use useAudioRecorderState() or the statusListener parameter in useAudioRecorder() instead of subscribing directly.

| Property | Type | Description | | --- | --- | --- | | recordingStatusUpdate | (status: [RecordingStatus](https://docs.expo.dev/versions/v54.0.0/sdk/audio#recordingstatus) ) => void | Fired when the recorder's status changes (start/stop/pause/error, and so on). |

`RecordingInput`

Represents an available audio input device for recording.

This type describes audio input sources like built-in microphones, external microphones, or other audio input devices that can be used for recording. Each input has an identifying information that can be used to select the preferred recording source.

| Property | Type | Description | | --- | --- | --- | | name | string | Human-readable name of the audio input device. | | type | string | Type or category of the input device (for example, 'Built-in Microphone', 'External Microphone'). | | uid | string | Unique identifier for the input device, used to select the input ('Built-in Microphone', 'External Microphone') for recording. |

`RecordingOptions`

| Property | Type | Description | | --- | --- | --- | | android | [RecordingOptionsAndroid](https://docs.expo.dev/versions/v54.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/v54.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/v54.0.0/sdk/audio#recordingoptionsweb) | Only for: Web Recording options for the Web platform. |

`RecordingOptionsAndroid`

Only for:

Android

Recording configuration options specific to Android.

Android recording uses MediaRecorder with options for format, encoder, and file constraints. These settings control the output format and quality characteristics.

| Property | Type | Description | | --- | --- | --- | | audioEncoder | [AndroidAudioEncoder](https://docs.expo.dev/versions/v54.0.0/sdk/audio#androidaudioencoder) | The desired audio encoder. See the AndroidAudioEncoder enum for all valid values. | | audioSource(optional) | [RecordingSource](https://docs.expo.dev/versions/v54.0.0/sdk/audio#recordingsource) | The desired audio Source. See the AndroidAudioSource 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/v54.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

Recording configuration options specific to iOS.

iOS recording uses AVAudioRecorder with extensive format and quality options. These settings provide fine-grained control over the recording characteristics.

| Property | Type | Description | | --- | --- | --- | | audioQuality | [AudioQuality](https://docs.expo.dev/versions/v54.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/v54.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

Recording options for the web.

Web recording uses the MediaRecorder API, which has different capabilities compared to native platforms. These options map directly to MediaRecorder settings.

| Property | Type | Description | | --- | --- | --- | | bitsPerSecond(optional) | number | Target bits per second for the recording. | | mimeType(optional) | string | MIME type for the recording (for example, 'audio/webm', 'audio/mp4'). |

`RecordingSource`

Only for:

Android

Literal Type: string

Recording source for android.

An audio source defines both a default physical source of audio signal, and a recording configuration.

camcorder: Microphone audio source tuned for video recording, with the same orientation as the camera if available.
default: The default audio source.
mic: Microphone audio source.
unprocessed: Microphone audio source tuned for unprocessed (raw) sound if available, behaves like default otherwise.
voice_communication: Microphone audio source tuned for voice communications such as VoIP. It will for instance take advantage of echo cancellation or automatic gain control if available.
voice_performance: Source for capturing audio meant to be processed in real time and played back for live performance (e.g karaoke). The capture path will minimize latency and coupling with playback path.
voice_recognition: Microphone audio source tuned for voice recognition.

See: https://developer.android.com/reference/android/media/MediaRecorder.AudioSource

`RecordingStartOptions`

Options for controlling how audio recording is started.

| Property | Type | Description | | --- | --- | --- | | atTime(optional) | number | Only for: iOS The time in seconds to wait before starting the recording. If not provided, recording starts immediately. Platform behavior: * Android: Ignored, recording starts immediately * iOS: Uses native AVAudioRecorder.record(atTime:) for precise timing. * Web: Ignored, recording starts immediately > On iOS, the recording process starts immediately (you'll see status updates), but actual audio capture begins after the specified delay. This is not a countdown, since the recorder is active but silent during the delay period. | | forDuration(optional) | number | Only for: Android iOS Web The duration in seconds after which recording should automatically stop. If not provided, recording continues until manually stopped. |

`RecordingStatus`

Status information for recording operations from the event system.

This type represents the status data emitted by recordingStatusUpdate events. It contains high-level information about the recording session and any errors. Used internally by the event system. Most users should use useAudioRecorderState() instead.

| Property | Type | Description | | --- | --- | --- | | error | string \| null | Error message if an error occurred, null otherwise. | | hasError | boolean | Whether an error occurred during recording. | | id | number | Unique identifier for the recording session. | | isFinished | boolean | Whether the recording has finished (stopped). | | url | string \| null | File URL of the completed recording, if available. |

Enums

`AudioQuality`

Audio quality levels for recording.

Predefined quality levels that balance file size and audio fidelity. Higher quality levels produce better sound but larger files and require more processing power.

`MIN`

AudioQuality.MIN ＝ 0

Minimum quality: smallest file size, lowest fidelity.

`LOW`

AudioQuality.LOW ＝ 32

Low quality: good for voice recordings where file size matters.

`MEDIUM`

AudioQuality.MEDIUM ＝ 64

Medium quality: balanced option for most use cases.

`HIGH`

AudioQuality.HIGH ＝ 96

High quality: good fidelity, larger file size.

`MAX`

AudioQuality.MAX ＝ 127

Maximum quality: best fidelity, largest file size.

`IOSOutputFormat`

Only for:

iOS

Audio output format options for iOS recording.

Comprehensive enum of audio formats supported by iOS for recording. Each format has different characteristics in terms of quality, file size, and compatibility. Some formats like LINEARPCM offer the highest quality but larger file sizes, while compressed formats like AAC provide good quality with smaller files.

`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.