Guides
Plan-enterprise-icon
Expo Application Services
API Reference

AV

Note that for Video, all of these operations are also available via props on the component, but we recommend using this imperative playback API for most applications where finer control over the state of the video playback is needed.
Try the playlist example app (source code is on GitHub) to see an example usage of the playback API for both Audio.Sound and Video.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb
Status-success-iconStatus-success-iconStatus-success-iconStatus-success-iconStatus-success-icon

Installation

Terminal
→ npx expo install expo-av

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Usage

In 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

...
_handleVideoRef = component => {
  const playbackObject = component;
  ...
}

...

render() {
  return (
    ...
      <Video
        ref={this._handleVideoRef}
        ...
      />
    ...
  )
}
...
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?
    }

    ... // etc
  }
};

... // Load the playbackObject and obtain the reference.
playbackObject.setOnPlaybackStatusUpdate(this._onPlaybackStatusUpdate);
...

Example: Loop media exactly 20 times

const N = 20;
...

_onPlaybackStatusUpdate = (playbackStatus) => {
  if (playbackStatus.didJustFinish) {
    if (this.state.numberOfLoops == N - 1) {
      playbackObject.setIsLooping(false);
    }
    this.setState({ numberOfLoops: this.state.numberOfLoops + 1 });
  }
};

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

API

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.

  • Undo-iconPromise<AVPlaybackStatus>

A Promise that is fulfilled with the AVPlaybackStatus of the playbackObject.

setStatusAsync(status)

NameTypeDescription
statusAVPlaybackStatusToSet

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.

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.

loadAsync(source, initialStatus, downloadAsync)

NameTypeDescription
sourceAVPlaybackSource

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.

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 }).

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.

playFromPositionAsync(positionMillis, tolerances)

NameTypeDescription
positionMillisnumber

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.

replayAsync(status)

NameTypeDescription
statusAVPlaybackStatusToSet

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.

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)

NameTypeDescription
isLoopingboolean

A boolean describing if the media should play once (false) or loop indefinitely (true).

This is equivalent to playbackObject.setStatusAsync({ isLooping }).

setIsMutedAsync(isMuted)

NameTypeDescription
isMutedboolean

A boolean describing if the audio of this media should be muted.

This is equivalent to playbackObject.setStatusAsync({ isMuted }).

setPositionAsync(positionMillis, tolerances)

NameTypeDescription
positionMillisnumber

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 }).

setProgressUpdateIntervalAsync(progressUpdateIntervalMillis)

NameTypeDescription
progressUpdateIntervalMillisnumber

The new minimum interval in milliseconds between calls of onPlaybackStatusUpdate. See setOnPlaybackStatusUpdate() for details.

This is equivalent to playbackObject.setStatusAsync({ progressUpdateIntervalMillis }).

setRateAsync(rate, shouldCorrectPitch, pitchCorrectionQuality)

NameTypeDescription
ratenumber

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.

shouldCorrectPitchboolean

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

This is equivalent to playbackObject.setStatusAsync({ rate, shouldCorrectPitch, pitchCorrectionQuality }).

setVolumeAsync(volume, audioPan)

NameTypeDescription
volumenumber

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'

stopAsync()

This is equivalent to playbackObject.setStatusAsync({ shouldPlay: false, positionMillis: 0 }).

unloadAsync()

Unloads the media from memory. loadAsync() must be called again in order to be able to play the media.

Info-icon

This cleanup function will be automatically called in the Video component's componentWillUnmount.

A Promise that is fulfilled with the AVPlaybackStatus of the playbackObject once it is unloaded, or rejects if unloading failed.

Types

AVMetadata

Object passed to the onMetadataUpdate function.

NameTypeDescription
title
(optional)
stringA string with the title of the sound object.

AVPlaybackSource

The following forms of source are supported:

  • A dictionary of the form AVPlaybackSourceObject. The overrideFileExtensionAndroid property may come in handy if the player receives an URL like example.com/play which redirects to example.com/player.m3u8. Setting this property to m3u8 would allow the Android player to properly infer the content type of the media and use proper media file reader.
  • require('path/to/file') for a media file asset in the source code directory.
  • An Asset object for a media file asset.

The iOS developer documentation lists the audio and video formats supported on iOS.

There are two sets of audio and video formats supported on Android: formats supported by ExoPlayer and formats supported by Android's MediaPlayer. Expo uses ExoPlayer implementation by default. To use MediaPlayer, add androidImplementation: 'MediaPlayer' to the initial status of the AV object.

Acceptable values are: number, AVPlaybackSourceObject, Asset.

AVPlaybackSourceObject

One of the possible forms of the AVPlaybackSource.

NameTypeDescription
headers
(optional)
Record<string, string>An optional headers object passed in a network request.
overrideFileExtensionAndroid
(optional)
stringOnly for:
Android-iconAndroid

An optional string overriding extension inferred from the URL.
uristringA network URL pointing to a media file.

AVPlaybackStatus

This is the structure returned from all playback API calls and describes the state of the playbackObject at that point in time. It can take a form of AVPlaybackStatusSuccess or AVPlaybackStatusError based on the playbackObject load status.

Acceptable values are: AVPlaybackStatusError, AVPlaybackStatusSuccess.

AVPlaybackStatusError

NameTypeDescription
androidImplementation
(optional)
stringOnly for:
Android-iconAndroid

Underlying implementation to use (when set to MediaPlayer it uses Android's MediaPlayer, uses ExoPlayer otherwise). You may need to use this property if you're trying to play an item unsupported by ExoPlayer (formats supported by ExoPlayer, formats supported by Android's MediaPlayer).Note that setting this property takes effect only when the AV object is just being created (toggling its value later will do nothing).
error
(optional)
stringA string only present if the playbackObject just encountered a fatal error and forced unload. Populated exactly once when an error forces the object to unload.
isLoadedfalseA boolean set to false.

AVPlaybackStatusSuccess

NameTypeDescription
androidImplementation
(optional)
stringOnly for:
Android-iconAndroid

Underlying implementation to use (when set to MediaPlayer it uses Android's MediaPlayer, uses ExoPlayer otherwise). You may need to use this property if you're trying to play an item unsupported by ExoPlayer (formats supported by ExoPlayer, formats supported by Android's MediaPlayer).Note that setting this property takes effect only when the AV object is just being created (toggling its value later will do nothing).
audioPannumberThe current audio panning value of the audio for this media.
didJustFinishbooleanA boolean describing if the media just played to completion at the time that this status was received. When the media plays to completion, the function passed in setOnPlaybackStatusUpdate() is called exactly once with didJustFinish set to true. didJustFinish is never true in any other case.
durationMillis
(optional)
numberThe duration of the media in milliseconds. This is only present if the media has a duration.
Info-icon
Note that in some cases, a media file's duration is readable on Android, but not on iOS.
isBufferingbooleanA boolean describing if the media is currently buffering.
isLoadedtrueA boolean set to true.
isLoopingbooleanA boolean describing if the media is currently looping.
isMutedbooleanA boolean describing if the audio of this media is currently muted.
isPlayingbooleanA boolean describing if the media is currently playing.
pitchCorrectionQuality
(optional)
PitchCorrectionQualityiOS time pitch algorithm setting. See setRateAsync for details.
playableDurationMillis
(optional)
numberThe position until which the media has been buffered into memory. Like durationMillis, this is only present in some cases.
positionMillisnumberThe current position of playback in milliseconds.
progressUpdateIntervalMillisnumberThe minimum interval in milliseconds between calls of onPlaybackStatusUpdate. See setOnPlaybackStatusUpdate() for details.
ratenumberThe current rate of the media.
seekMillisToleranceAfter
(optional)
number-
seekMillisToleranceBefore
(optional)
number-
shouldCorrectPitchbooleanA boolean describing if we are correcting the pitch for a changed rate.
shouldPlaybooleanA boolean describing if the media is supposed to play.
uristringThe location of the media source.
volumenumberThe current volume of the audio for this media.

AVPlaybackStatusToSet

This is the structure passed to setStatusAsync() to modify the state of the playbackObject.

NameTypeDescription
androidImplementation
(optional)
stringOnly for:
Android-iconAndroid

Underlying implementation to use (when set to MediaPlayer it uses Android's MediaPlayer, uses ExoPlayer otherwise). You may need to use this property if you're trying to play an item unsupported by ExoPlayer (formats supported by ExoPlayer, formats supported by Android's MediaPlayer).Note that setting this property takes effect only when the AV object is just being created (toggling its value later will do nothing).
audioPan
(optional)
numberOnly for:
Android-iconAndroid

The current audio panning value of the audio for this media.
Info-icon
Note that this only affect the audio of this playbackObject and do NOT affect the system volume. Also note that this is only available when the video was loaded using androidImplementation: 'MediaPlayer'
isLooping
(optional)
booleanA boolean describing if the media is currently looping.
isMuted
(optional)
booleanA boolean describing if the audio of this media is currently muted.
Info-icon
Note that this only affect the audio of this playbackObject and do NOT affect the system volume.
pitchCorrectionQuality
(optional)
PitchCorrectionQualityiOS time pitch algorithm setting. See setRateAsync for details.
positionMillis
(optional)
numberThe current position of playback in milliseconds.
progressUpdateIntervalMillis
(optional)
numberThe minimum interval in milliseconds between calls of onPlaybackStatusUpdate. See setOnPlaybackStatusUpdate() for details.
rate
(optional)
numberOnly for:
Android-iconAndroid API 23+
Apple-iconiOS

The current rate of the media.
seekMillisToleranceAfter
(optional)
number-
seekMillisToleranceBefore
(optional)
number-
shouldCorrectPitch
(optional)
booleanA boolean describing if we are correcting the pitch for a changed rate.
shouldPlay
(optional)
booleanA boolean describing if the media is supposed to play.
volume
(optional)
numberThe current volume of the audio for this media.
Info-icon
Note that this only affect the audio of this playbackObject and do NOT affect the system volume.

AVPlaybackTolerance

NameTypeDescription
toleranceMillisAfter
(optional)
number-
toleranceMillisBefore
(optional)
number-

Enums

PitchCorrectionQuality

Check official Apple documentation for more information.

PitchCorrectionQuality.High

Equivalent to AVAudioTimePitchAlgorithmSpectral.

PitchCorrectionQuality.Low

Equivalent to AVAudioTimePitchAlgorithmLowQualityZeroLatency.

PitchCorrectionQuality.Medium

Equivalent to AVAudioTimePitchAlgorithmTimeDomain.

  • Message-iconAsk a question on the forums about AV
  • Github-iconView open bug reports for AV
  • Code-iconView source code for AV
  • Build-iconView package in npm Registry
  • Edit-iconEdit this page

Was this doc helpful?