This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo Audio (expo-av)
A library that provides an API to implement audio playback and recording in apps.
Deprecated: The
Audiocomponent fromexpo-av, which is documented on this page, has now been deprecated and replaced by an improved version inexpo-audio. Learn aboutexpo-audio.
Audio from expo-av allows you to implement audio playback and recording in your app.
Note that audio automatically stops if headphones/bluetooth audio devices are disconnected.
See the playlist example app for an example on the media playback API, and the recording example app for an example of the recording API.
Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
Usage
Playing sounds
Recording sounds
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" ] } } } }
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
prepareToRecordAsyncwill 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 { Audio } from 'expo-av';
Constants
Type: Record<string, RecordingOptions>
Constant which contains definitions of the two preset examples of RecordingOptions, as implemented in the Audio SDK.
HIGH_QUALITY
RecordingOptionsPresets.HIGH_QUALITY = { isMeteringEnabled: true, android: { extension: '.m4a', outputFormat: AndroidOutputFormat.MPEG_4, audioEncoder: AndroidAudioEncoder.AAC, sampleRate: 44100, numberOfChannels: 2, bitRate: 128000, }, ios: { extension: '.m4a', outputFormat: IOSOutputFormat.MPEG4AAC, audioQuality: IOSAudioQuality.MAX, sampleRate: 44100, numberOfChannels: 2, bitRate: 128000, linearPCMBitDepth: 16, linearPCMIsBigEndian: false, linearPCMIsFloat: false, }, web: { mimeType: 'audio/webm', bitsPerSecond: 128000, }, };
LOW_QUALITY
RecordingOptionsPresets.LOW_QUALITY = { isMeteringEnabled: true, android: { extension: '.3gp', outputFormat: AndroidOutputFormat.THREE_GPP, audioEncoder: AndroidAudioEncoder.AMR_NB, sampleRate: 44100, numberOfChannels: 2, bitRate: 128000, }, ios: { extension: '.caf', audioQuality: IOSAudioQuality.MIN, sampleRate: 44100, numberOfChannels: 2, bitRate: 128000, linearPCMBitDepth: 16, linearPCMIsBigEndian: false, linearPCMIsFloat: false, }, web: { mimeType: 'audio/webm', bitsPerSecond: 128000, }, };
Hooks
Check or request permissions to record audio.
This uses both requestPermissionAsync and getPermissionsAsync to interact with the permissions.
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [permissionResponse, requestPermission] = Audio.usePermissions();
Classes
Warning: Experimental for web.
This class represents an audio recording. After creating an instance of this class, prepareToRecordAsync
must be called in order to record audio. Once recording is finished, call stopAndUnloadAsync. Note that
only one recorder is allowed to exist in the state between prepareToRecordAsync and stopAndUnloadAsync
at any given time.
Note that your experience must request audio recording permissions in order for recording to function.
See the Permissions module for more details.
Additionally, audio recording is not supported in the iOS Simulator.
A newly constructed instance of Audio.Recording.
Example
const recording = new Audio.Recording(); try { await recording.prepareToRecordAsync(Audio.RecordingOptionsPresets.HIGH_QUALITY); await recording.startAsync(); // You are now recording! } catch (error) { // An error occurred! }
Recording Methods
Creates and starts a recording using the given options, with optional onRecordingStatusUpdate and progressUpdateIntervalMillis.
const { recording, status } = await Audio.Recording.createAsync( options, onRecordingStatusUpdate, progressUpdateIntervalMillis ); // Which is equivalent to the following: const recording = new Audio.Recording(); await recording.prepareToRecordAsync(options); recording.setOnRecordingStatusUpdate(onRecordingStatusUpdate); await recording.startAsync();
Promise<RecordingObject>A Promise that is rejected if creation failed, or fulfilled with the following dictionary if creation succeeded.
Example
try { const { recording: recordingObject, status } = await Audio.Recording.createAsync( Audio.RecordingOptionsPresets.HIGH_QUALITY ); // You are now recording! } catch (error) { // An error occurred! }
Creates and loads a new Sound object to play back the Recording. Note that this will only succeed once the Recording
is done recording and stopAndUnloadAsync() has been called.
Promise<SoundObject>A Promise that is rejected if creation failed, or fulfilled with the SoundObject.
Returns a list of available recording inputs. This method can only be called if the Recording has been prepared.
Promise<RecordingInput[]>A Promise that is fulfilled with an array of RecordingInput objects.
Returns the currently-selected recording input. This method can only be called if the Recording has been prepared.
Promise<RecordingInput>A Promise that is fulfilled with a RecordingInput object.
Gets the status of the Recording.
Promise<RecordingStatus>A Promise that is resolved with the RecordingStatus object.
Gets the local URI of the Recording. Note that this will only succeed once the Recording is prepared
to record. On web, this will not return the URI until the recording is finished.
null | stringA string with the local URI of the Recording, or null if the Recording is not prepared
to record (or, on Web, if the recording has not finished).
Pauses recording. This method can only be called if the Recording has been prepared.
This is only available on Android API version 24 and later.
Promise<RecordingStatus>A Promise that is fulfilled when recording has paused, or rejects if recording could not be paused.
If the Android API version is less than 24, the Promise will reject. The promise is resolved with the
RecordingStatus of the recording.
Loads the recorder into memory and prepares it for recording. This must be called before calling startAsync().
This method can only be called if the Recording instance has never yet been prepared.
Promise<RecordingStatus>A Promise that is fulfilled when the recorder is loaded and prepared, or rejects if this failed. If another Recording exists
in your experience that is currently prepared to record, the Promise will reject. If the RecordingOptions provided are invalid,
the Promise will also reject. The promise is resolved with the RecordingStatus of the recording.
Sets the current recording input.
Promise<void>A Promise that is resolved if successful or rejected if not.
Sets a function to be called regularly with the RecordingStatus of the Recording.
onRecordingStatusUpdate will be called when another call to the API for this recording completes (such as prepareToRecordAsync(),
startAsync(), getStatusAsync(), or stopAndUnloadAsync()), and will also be called at regular intervals while the recording can record.
Call setProgressUpdateInterval() to modify the interval with which onRecordingStatusUpdate is called while the recording can record.
voidSets the interval with which onRecordingStatusUpdate is called while the recording can record.
See setOnRecordingStatusUpdate for details. This value defaults to 500 milliseconds.
voidBegins recording. This method can only be called if the Recording has been prepared.
Promise<RecordingStatus>A Promise that is fulfilled when recording has begun, or rejects if recording could not be started.
The promise is resolved with the RecordingStatus of the recording.
Stops the recording and deallocates the recorder from memory. This reverts the Recording instance
to an unprepared state, and another Recording instance must be created in order to record again.
This method can only be called if the Recording has been prepared.
On Android this method may fail with
E_AUDIO_NODATAwhen called too soon afterstartAsyncand no audio data has been recorded yet. In that case the recorded file will be invalid and should be discarded.
Promise<RecordingStatus>A Promise that is fulfilled when recording has stopped, or rejects if recording could not be stopped.
The promise is resolved with the RecordingStatus of the recording.
Type: Class implements Playback
This class represents a sound corresponding to an Asset or URL.
A newly constructed instance of Audio.Sound.
Example
const sound = new Audio.Sound(); try { await sound.loadAsync(require('./assets/sounds/hello.mp3')); await sound.playAsync(); // Your sound is playing! // Don't forget to unload the sound from memory // when you are done using the Sound object await sound.unloadAsync(); } catch (error) { // An error occurred! }
Method not described below and the rest of the API for
Audio.Soundis the same as the imperative playback API forVideo. See the AV documentation for further information.
Sound Methods
Creates and loads a sound from source.
const { sound } = await Audio.Sound.createAsync( source, initialStatus, onPlaybackStatusUpdate, downloadFirst ); // Which is equivalent to the following: const sound = new Audio.Sound(); sound.setOnPlaybackStatusUpdate(onPlaybackStatusUpdate); await sound.loadAsync(source, initialStatus, downloadFirst);
Promise<SoundObject>A Promise that is rejected if creation failed, or fulfilled with the SoundObject if creation succeeded.
Example
try { const { sound: soundObject, status } = await Audio.Sound.createAsync( require('./assets/sounds/hello.mp3'), { shouldPlay: true } ); // Your sound is playing! } catch (error) { // An error occurred! }
Sets a function to be called during playback, receiving the audio sample as parameter.
voidSets a function to be called whenever the metadata of the sound object changes, if one is set.
voidSets a function to be called regularly with the AVPlaybackStatus of the playback object.
onPlaybackStatusUpdate will be called whenever a call to the API for this playback object completes
(such as setStatusAsync(), getStatusAsync(), or unloadAsync()), nd will also be called at regular intervals
while the media is in the loaded state.
Set progressUpdateIntervalMillis via setStatusAsync() or setProgressUpdateIntervalAsync() to modify
the interval with which onPlaybackStatusUpdate is called while loaded.
voidMethods
Checks user's permissions for audio recording.
Promise<PermissionResponse>A promise that resolves to an object of type PermissionResponse.
Asks the user to grant permissions for audio recording.
Promise<PermissionResponse>A promise that resolves to an object of type PermissionResponse.
We provide this API to customize the audio experience on iOS and Android.
Promise<void>A Promise that will reject if the audio mode could not be enabled for the device.
Audio is enabled by default, but if you want to write your own Audio API in a bare workflow app, you might want to disable the Audio API.
Promise<void>A Promise that will reject if audio playback could not be enabled for the device.
Types
Object passed to the onAudioSampleReceived function. Represents a single sample from an audio source.
The sample contains all frames (PCM Buffer values) for each channel of the audio, so if the audio is stereo (interleaved),
there will be two channels, one for left and one for right audio.
Literal type: union
Acceptable values are: PermissionHookBehavior | Options
The recording extension, sample rate, bitrate, channels, format, encoder, etc. which can be customized by passing options to prepareToRecordAsync().
We provide the following preset options for convenience, as used in the example above. See below for the definitions of these presets.
Audio.RecordingOptionsPresets.HIGH_QUALITYAudio.RecordingOptionsPresets.LOW_QUALITY
We also provide the ability to define your own custom recording options, but we recommend you use the presets,
as not all combinations of options will allow you to successfully prepareToRecordAsync().
You will have to test your custom options on iOS and Android to make sure it's working. In the future,
we will enumerate all possible valid combinations, but at this time, our goal is to make the basic use-case easy (with presets)
and the advanced use-case possible (by exposing all the functionality available on all supported platforms).
Enums
Defines the audio encoding.
Defines the output format.
InterruptionModeAndroid.DoNotMix ＝ 1If this option is set, your experience's audio interrupts audio from other apps.
InterruptionModeIOS.MixWithOthers ＝ 0This is the default option. If this option is set, your experience's audio is mixed with audio playing in background apps.
InterruptionModeIOS.DoNotMix ＝ 1If this option is set, your experience's audio interrupts audio from other apps.
Note: Not all of the iOS formats included in this list of constants are currently supported by iOS, in spite of appearing in the Apple source code. For an accurate list of formats supported by iOS, see Core Audio Codecs and iPhone Audio File Formats.
Check official Apple documentation for more information.
Unified API
The rest of the API on the Sound.Audio is the same as the API for Video component ref. See the AV documentation for more information.