Expo AV

{
  "expo": {
    "plugins": [
        "expo-av",
          "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.
Are you using this library in a bare React Native app?
Learn how to configure the native projects in the installation instructions in the expo-av repository.
Usage
On this page, we reference operations on playbackObjects. Here is an example of obtaining access to the reference for both sound and video:
Example: Audio.Sound
await Audio.setAudioModeAsync({ playsInSilentModeIOS: true });
const playbackObject = new Audio.Sound();
// OR
const { sound: playbackObject } = await Audio.Sound.createAsync(
  { uri: 'http://foo/bar.mp3' },
  { shouldPlay: true }
See the audio documentation for further information on Audio.Sound.createAsync().
Example: Video
%%placeholder-start%%... %%placeholder-end%%
_handleVideoRef = component => {
  const playbackObject = component;
%%placeholder-start%%... %%placeholder-end%%
render() {
  return (
      <Video
        ref={this._handleVideoRef}
      %%placeholder-start%%... %%placeholder-end%%
See the video documentation for further information.
Example: setOnPlaybackStatusUpdate()
_onPlaybackStatusUpdate = playbackStatus => {
  if (!playbackStatus.isLoaded) {
    // Update your UI for the unloaded state
    if (playbackStatus.error) {
      console.log(`Encountered a fatal error during playback: ${playbackStatus.error}`);
      // Send Expo team the error on Slack or the forums so we can help you debug!
  } else {
    // Update your UI for the loaded state
    if (playbackStatus.isPlaying) {
      // Update your UI for the playing state
    } else {
      // Update your UI for the paused state
    if (playbackStatus.isBuffering) {
      // Update your UI for the buffering state
    if (playbackStatus.didJustFinish && !playbackStatus.isLooping) {
      // The player has just finished playing and will stop. Maybe you want to play something else?
    %%placeholder-start%%... %%placeholder-end%%
// Load the playbackObject and obtain the reference.
playbackObject.setOnPlaybackStatusUpdate(this._onPlaybackStatusUpdate);
Example: Loop media exactly 20 times
const N = 20;
%%placeholder-start%%... %%placeholder-end%%
_onPlaybackStatusUpdate = playbackStatus => {
  if (playbackStatus.didJustFinish) {
    if (this.state.numberOfLoops == N - 1) {
      playbackObject.setIsLooping(false);
    this.setState({ numberOfLoops: this.state.numberOfLoops + 1 });
%%placeholder-start%%... %%placeholder-end%%
this.setState({ numberOfLoops: 0 });
// Load the playbackObject and obtain the reference.
playbackObject.setOnPlaybackStatusUpdate(this._onPlaybackStatusUpdate);
playbackObject.setIsLooping(true);
What is seek tolerance and why would I want to use it [iOS only]
When asked to seek an A/V item, native player in iOS sometimes may seek to a slightly different time. This technique, mentioned in Apple documentation, is used to shorten the time of the seekTo call (the player may decide to play immediately from a different time than requested, instead of decoding the exact requested part and playing it with the decoding delay).
If precision is important, you can specify the tolerance with which the player will seek. However, this will result in an increased delay.
import { Audio, Video } from 'expo-av';
Constants
AV._DEFAULT_INITIAL_PLAYBACK_STATUS
Type: AVPlaybackStatusToSet

The default initial AVPlaybackStatusToSet of all Audio.Sound objects and Video components is as follows:
  progressUpdateIntervalMillis: 500,
  positionMillis: 0,
  shouldPlay: false,
  rate: 1.0,
  shouldCorrectPitch: false,
  volume: 1.0,
  isMuted: false,
  isLooping: false,
This default initial status can be overwritten by setting the optional initialStatus in loadAsync() or Audio.Sound.createAsync().




    
Interfaces
AV
AV Methods
getStatusAsync()
Gets the AVPlaybackStatus of the playbackObject.
Returns:
Promise<AVPlaybackStatus>
A Promise that is fulfilled with the AVPlaybackStatus of the playbackObject.
setStatusAsync(status)
Name
Type
Description
status
AVPlaybackStatusToSet
The new AVPlaybackStatusToSet of the playbackObject, whose values will override the current playback status.

Sets a new AVPlaybackStatusToSet on the playbackObject. This method can only be called if the media has been loaded.
Returns:
Promise<AVPlaybackStatus>




    
A Promise that is fulfilled with the AVPlaybackStatus of the playbackObject once the new status has been set successfully,
or rejects if setting the new status failed. See below for details on AVPlaybackStatus.
Playback
Extends: AV
On the playbackObject reference, the following API is provided.
Playback Methods
loadAsync(source, initialStatus, downloadAsync)
Name
Type
Description
source
AVPlaybackSource
The source of the media.
initialStatus
(optional)
AVPlaybackStatusToSet
The initial intended AVPlaybackStatusToSet of the playbackObject, whose values will override the default initial playback status.
This value defaults to {} if no parameter is passed. For more information see the details on AVPlaybackStatusToSet type
and the default initial playback status.
downloadAsync
(optional)
boolean
If set to true, the system will attempt to download the resource to the device before loading.
This value defaults to true. Note that at the moment, this will only work for sources of the form require('path/to/file') or Asset objects.

Loads the media from source into memory and prepares it for playing. This must be called before calling setStatusAsync()
or any of the convenience set status methods. This method can only be called if the playbackObject is in an unloaded state.
Returns:
Promise<AVPlaybackStatus>
A Promise that is fulfilled with the AVPlaybackStatus of the playbackObject once it is loaded, or rejects if loading failed.
The Promise will also reject if the playbackObject was already loaded. See below for details on AVPlaybackStatus.
pauseAsync()
This is equivalent to playbackObject.setStatusAsync({ shouldPlay: false }).
Returns:
Promise<AVPlaybackStatus>
playAsync()
This is equivalent to playbackObject.setStatusAsync({ shouldPlay: true }).
Playback may not start immediately after calling this function for reasons such as buffering. Make sure to update your UI based
on the isPlaying and isBuffering properties of the AVPlaybackStatus.
Returns:
Promise<AVPlaybackStatus>
playFromPositionAsync(positionMillis, tolerances)
Name
Type
Description
positionMillis
number
The desired position of playback in milliseconds.
tolerances
(optional)
AVPlaybackTolerance
The tolerances are used only on iOS (more details).

This is equivalent to playbackObject.setStatusAsync({ shouldPlay: true, positionMillis, seekMillisToleranceAfter: tolerances.seekMillisToleranceAfter, seekMillisToleranceBefore: tolerances.seekMillisToleranceBefore }).
Playback may not start immediately after calling this function for reasons such as buffering. Make sure to update your UI based
on the isPlaying and isBuffering properties of the AVPlaybackStatus.
Returns:
Promise<AVPlaybackStatus>
replayAsync(status)
Name
Type
Description
status
AVPlaybackStatusToSet
The new AVPlaybackStatusToSet of the playbackObject, whose values will override the current playback status.
positionMillis and shouldPlay properties will be overridden with respectively 0 and true.




    

Replays the playback item. When using playFromPositionAsync(0) the item is seeked to the position at 0 ms.
On iOS this method uses internal implementation of the player and is able to play the item from the beginning immediately.
Returns:
Promise<AVPlaybackStatus>
A Promise that is fulfilled with the AVPlaybackStatus of the playbackObject once the new status has been set successfully,
or rejects if setting the new status failed.
setIsLoopingAsync(isLooping)
Name
Type
Description
isLooping
boolean
A boolean describing if the media should play once (false) or loop indefinitely (true).

This is equivalent to playbackObject.setStatusAsync({ isLooping }).
Returns:
Promise<AVPlaybackStatus>
setIsMutedAsync(isMuted)
Name
Type
Description
isMuted
boolean
A boolean describing if the audio of this media should be muted.

This is equivalent to playbackObject.setStatusAsync({ isMuted }).
Returns:
Promise<AVPlaybackStatus>
setPositionAsync(positionMillis, tolerances)
Name
Type
Description
positionMillis
number
The desired position of playback in milliseconds.
tolerances
(optional)
AVPlaybackTolerance
The tolerances are used only on iOS (more details).

This is equivalent to playbackObject.setStatusAsync({ positionMillis }).
Returns:
Promise<AVPlaybackStatus>
setProgressUpdateIntervalAsync(progressUpdateIntervalMillis)
Name
Type
Description
progressUpdateIntervalMillis
number
The new minimum interval in milliseconds between calls of onPlaybackStatusUpdate.
See setOnPlaybackStatusUpdate() for details.




    

This is equivalent to playbackObject.setStatusAsync({ progressUpdateIntervalMillis }).
Returns:
Promise<AVPlaybackStatus>
setRateAsync(rate, shouldCorrectPitch, pitchCorrectionQuality)
Name
Type
Description
rate
number
The desired playback rate of the media. This value must be between 0.0 and 32.0. Only available on Android API version 23 and later and iOS.
shouldCorrectPitch
boolean
A boolean describing if we should correct the pitch for a changed rate. If set to true, the pitch of the audio will be corrected
(so a rate different than 1.0 will timestretch the audio).
pitchCorrectionQuality
(optional)
PitchCorrectionQuality
iOS time pitch algorithm setting, defaults to Audio.PitchCorrectionQuality.Medium.
Using Audio.PitchCorrectionQuality.Low may cause automatic playback rate changes on iOS >= 17, as AVAudioTimePitchAlgorithmLowQualityZeroLatency is deprecated.

This is equivalent to playbackObject.setStatusAsync({ rate, shouldCorrectPitch, pitchCorrectionQuality }).
Returns:
Promise<AVPlaybackStatus>
setVolumeAsync(volume, audioPan)
Name
Type
Description
volume
number
A number between 0.0 (silence) and 1.0 (maximum volume).
audioPan
(optional)
number
A number between -1.0 (full left) and 1.0 (full right).

This is equivalent to playbackObject.setStatusAsync({ volume, audioPan }).
Note: audioPan is currently only supported on Android using androidImplementation: 'MediaPlayer'
Returns:
Promise<AVPlaybackStatus>
stopAsync()
This is equivalent to playbackObject.setStatusAsync({ shouldPlay: false, positionMillis: 0 }).
Returns:
Promise<AVPlaybackStatus>
unloadAsync()
Unloads the media from memory. loadAsync() must be called again in order to be able to play the media.
This cleanup function will be automatically called in the Video component's componentWillUnmount.
Returns:
Promise<AVPlaybackStatus>
A Promise that is fulfilled with the AVPlaybackStatus of the playbackObject once it is unloaded, or rejects if unloading failed.