Skip to main content
Version: Next

Events

All event types are made available through the named export Event:

import { Event } from 'react-native-track-player';

Player

PlaybackState

Fired when the state of the player changes.

ParamTypeDescription
stateStateThe new state

PlaybackActiveTrackChanged

The new event also includes the full track objects for the newly active and last tracks.

ParamTypeDescription
lastIndexnumber | undefinedThe index of previously active track.
lastTrackTrack | undefinedThe previously active track or undefined when there wasn't a previously active track.
lastPositionnumberThe position of the previously active track in seconds.
indexnumber | undefinedThe newly active track index or undefined if there is no longer an active track.
trackTrack | undefinedThe newly active track or undefined if there is no longer an active track.

PlaybackQueueEnded

Fired when the queue reaches the end.

ParamTypeDescription
tracknumberThe previous track index. Might be null
positionnumberThe previous track position in seconds

PlaybackMetadataReceived

⚠️ Deprecated: Please use AudioChapterMetadataReceived, AudioTimedMetadataReceived, AudioCommonMetadataReceived.

Fired when the current track receives metadata encoded in. (e.g. ID3 tags, Icy Metadata, Vorbis Comments or QuickTime metadata).

ParamTypeDescription
sourcestringThe metadata source (id3, icy, icy-headers, vorbis-comment, quicktime)
titlestringThe track title. Might be null
urlstringThe track url. Might be null
artiststringThe track artist. Might be null
albumstringThe track album. Might be null
datestringThe track date. Might be null
genrestringThe track genre. Might be null

PlaybackProgressUpdated

⚠️ Note: This event is only emitted if you specify a non-zero progressUpdateEventInterval value in your player options.

Fired at the progressUpdateEventInterval if the player is playing and if a progressUpdateEventInterval has been specified.

ParamTypeDescription
positionnumberSee getProgress
durationnumberSee getProgress
bufferednumberSee getProgress
tracknumberThe current index in the queue of the track.

PlaybackError

Fired when an error occurs.

ParamTypeDescription
codestringThe error code
messagestringThe error message

PlaybackPlayWhenReadyChanged

Fired when the playWhenReady property is changed.

ParamTypeDescription
playWhenReadybooleanThe current value of playWhenReady

⚠️PlaybackTrackChanged

⚠️ Deprecated: Please use PlaybackActiveTrackChanged.

Fired when a track is changed.

ParamTypeDescription
tracknumberThe previous track index. Might be null
positionnumberThe previous track position in seconds
nextTracknumberThe next track index. Might be null

Media Controls

RemotePlay

Fired when the user presses the play button. Only fired if the Capability.Play is allowed.

RemotePlayId

Fired when the user selects a track from an external device. Required for Android Auto support. Only fired if the Capability.PlayFromId is allowed.

ParamTypeDescription
idstringThe track id

RemotePlaySearch

Fired when the user searches for a track (usually voice search). Required for Android Auto support. Only fired if the Capability.PlayFromSearch is allowed.

Every parameter except query is optional and may not be provided. In the case where query is empty, feel free to select any track to play.

ParamTypeDescription
querystringThe search query
focusstringThe focus of the search. One of artist, album, playlist or genre
titlestringThe track title
artiststringThe track artist
albumstringThe track album
genrestringThe track genre
playliststringThe track playlist

RemotePause

Fired when the user presses the pause button. Only fired if the Capability.Pause is allowed or if there's a change in outputs (e.g.: headphone disconnected).

RemoteStop

Fired when the user presses the stop button. Only fired if the Capability.Stop is allowed.

RemoteSkip

Fired when the user skips to a track in the queue. Only fired if the Capability.Skip is allowed.

ParamTypeDescription
indexnumberThe track index

RemoteNext

Fired when the user presses the next track button. Only fired if the Capability.SkipToNext is allowed.

RemotePrevious

Fired when the user presses the previous track button. Only fired if the Capability.SkipToPrevious is allowed.

RemoteSeek

Fired when the user changes the position of the timeline. Only fired if the Capability.SeekTo is allowed.

ParamTypeDescription
positionnumberThe position to seek to in seconds

RemoteSetRating

Fired when the user changes the rating for the track. Only fired if the Capability.SetRating is allowed.

ParamTypeDescription
ratingDepends on the Rating TypeThe rating that was set

RemoteJumpForward

Fired when the user presses the jump forward button. Only fired if the Capability.JumpForward is allowed.

ParamTypeDescription
intervalnumberThe number of seconds to jump forward. It's usually the forwardJumpInterval set in the options.

RemoteJumpBackward

Fired when the user presses the jump backward button. Only fired if the Capability.JumpBackward is allowed.

ParamTypeDescription
intervalnumberThe number of seconds to jump backward. It's usually the backwardJumpInterval set in the options.

RemoteLike (iOS only)

Fired when the user presses the like button in the now playing center. Only fired if the likeOptions is set in updateOptions.

RemoteDislike (iOS only)

Fired when the user presses the dislike button in the now playing center. Only fired if the dislikeOptions is set in updateOptions.

RemoteBookmark (iOS only)

Fired when the user presses the bookmark button in the now playing center. Only fired if the bookmarkOptions is set in updateOptions.

RemoteDuck

Fired when the audio is interrupted. For example when a phone call arrives, a clock or calender sounds, or another app starts playing audio.

We recommend to set autoHandleInterruptions: true in TrackPlayer.setupPlayer. This way toggling playback is handled automatically.

By default autoHandleInterruptions is set to false (default) in TrackPlayer.setupPlayer, which means your app is expected to respond to this event in the following situations:

  • When the event is triggered with paused set to true, on Android playback should be paused. When permanent is also set to true, on Android the player should stop playback.
  • When the event is triggered and paused is set to false, the player may resume playback.
ParamTypeDescription
pausedbooleanOn Android when true the player should pause playback, when false the player may resume playback. On iOS when true the playback was paused and when false the player may resume playback.
permanentbooleanWhether the interruption is permanent. On Android the player should stop playback.

Metadata

AudioCommonMetadataReceived

Fired when the current track receives metadata encoded in - static metadata not tied to a time. Usually received at start.

Received data will be AudioCommonMetadataReceivedEvent.

AudioTimedMetadataReceived

Fired when the current track receives metadata encoded in - dynamic metadata tied to a time. Events may be emitted over time.

Received data will be AudioMetadataReceivedEvent.

AudioChapterMetadataReceived (iOS only)

Fired when the current track receives metadata encoded in - chapter overview data. Usually received at start.

Received data will be AudioMetadataReceivedEvent.