Skip to main content

Player

These functions control audio playback, including play/pause control, seeking, volume adjustment, and retrieving information about the current state.

Playback Control​

play​

Starts or resumes playback of the current track.

await TrackPlayer.play(): Promise<void>

Example​

// Start or resume playback
await TrackPlayer.play()

pause​

Pauses playback of the current track.

await TrackPlayer.pause(): Promise<void>

Example​

// Pause playback
await TrackPlayer.pause()

stop​

Stops playback and resets the position to the beginning of the track.

await TrackPlayer.stop(): Promise<void>

Example​

// Stop playback completely
await TrackPlayer.stop()

skip​

Skips to the track at the specified index.

await TrackPlayer.skip(index: number): Promise<void>

Parameters​

ParameterTypeRequiredDescription
indexnumberYesIndex of the track to skip to (0-based)

Example​

// Skip to the third track (index 2)
await TrackPlayer.skip(2)

skipToNext​

Skips to the next track in the queue.

await TrackPlayer.skipToNext(): Promise<void>

Example​

// Skip to the next track
await TrackPlayer.skipToNext()

skipToPrevious​

Skips to the previous track in the queue.

await TrackPlayer.skipToPrevious(): Promise<void>

Example​

// Skip to the previous track
await TrackPlayer.skipToPrevious()

Position Control​

seekTo​

Seeks to a specific position in the current track.

await TrackPlayer.seekTo(position: number): Promise<void>

Parameters​

ParameterTypeRequiredDescription
positionnumberYesPosition to seek to in seconds

Example​

// Seek to 30 seconds into the track
await TrackPlayer.seekTo(30)

seekBy​

Seeks forward or backward relative to the current position.

await TrackPlayer.seekBy(offset: number): Promise<void>

Parameters​

ParameterTypeRequiredDescription
offsetnumberYesOffset in seconds (positive for forward, negative for backward)

Example​

// Seek 10 seconds forward
await TrackPlayer.seekBy(10)

// Seek 5 seconds backward
await TrackPlayer.seekBy(-5)

Audio Control​

setVolume​

Sets the playback volume.

await TrackPlayer.setVolume(volume: number): Promise<void>

Parameters​

ParameterTypeRequiredDescription
volumenumberYesVolume level from 0 (mute) to 1 (maximum)

Example​

// Set volume to 50%
await TrackPlayer.setVolume(0.5)

// Mute audio
await TrackPlayer.setVolume(0)

getVolume​

Gets the current volume level.

TrackPlayer.getVolume(): number

Return Value​

Returns a number between 0 and 1 representing the current volume level.

Example​

const currentVolume = TrackPlayer.getVolume()
console.log(`Current volume: ${currentVolume * 100}%`)

setRate​

Sets the playback rate (speed).

await TrackPlayer.setRate(rate: number): Promise<void>

Parameters​

ParameterTypeRequiredDescription
ratenumberYesPlayback rate from 0.25 to 2.0 (1.0 is normal speed)

Example​

// Play at double speed
await TrackPlayer.setRate(2.0)

// Play at half speed
await TrackPlayer.setRate(0.5)

// Reset to normal speed
await TrackPlayer.setRate(1.0)

getRate​

Gets the current playback rate.

TrackPlayer.getRate(): number

Return Value​

Returns a number representing the current playback rate (1.0 is normal speed).

Example​

const currentRate = TrackPlayer.getRate()
console.log(`Playing at ${currentRate}x speed`)

State and Position​

getPlaybackState​

Gets the current playback state.

TrackPlayer.getPlaybackState(): State

Return Value​

Returns one of the State constants.

Example​

import { State } from "react-track-player-web"

const state = TrackPlayer.getPlaybackState()
if (state === State.Playing) {
  console.log("Track is currently playing")
} else if (state === State.Paused) {
  console.log("Track is paused")
}

getPosition​

Gets the current playback position in seconds.

TrackPlayer.getPosition(): number

Return Value​

Returns the current position in seconds.

Example​

const position = TrackPlayer.getPosition()
console.log(`Current position: ${Math.floor(position)} seconds`)

getDuration​

Gets the duration of the current track in seconds.

TrackPlayer.getDuration(): number

Return Value​

Returns the track duration in seconds, or 0 if unknown.

Example​

const duration = TrackPlayer.getDuration()
console.log(`Track duration: ${Math.floor(duration)} seconds`)

getBufferedPosition​

Gets the buffered position of the current track in seconds.

TrackPlayer.getBufferedPosition(): number

Return Value​

Returns the buffered position in seconds.

Example​

const buffered = TrackPlayer.getBufferedPosition()
console.log(`Buffered up to: ${Math.floor(buffered)} seconds`)

getProgress​

Gets comprehensive progress information including position, duration, and buffered status.

TrackPlayer.getProgress(): Progress

Return Value​

Returns a Progress object with the following properties:

{
  position: number // Current position in seconds
  duration: number // Track duration in seconds
  buffered: number // Buffered position in seconds
}

Example​

const progress = TrackPlayer.getProgress()
console.log(
  `Position: ${progress.position}s / ${progress.duration}s (${progress.buffered}s buffered)`
)

Repeat Mode​

setRepeatMode​

Sets the repeat mode for playback.

await TrackPlayer.setRepeatMode(mode: RepeatMode): Promise<void>

Parameters​

ParameterTypeRequiredDescription
modeRepeatModeYesThe repeat mode to set

Example​

import { RepeatMode } from "react-track-player-web"

// No repeat
await TrackPlayer.setRepeatMode(RepeatMode.Off)

// Repeat current track
await TrackPlayer.setRepeatMode(RepeatMode.Track)

// Repeat entire queue
await TrackPlayer.setRepeatMode(RepeatMode.Queue)

getRepeatMode​

Gets the current repeat mode.

TrackPlayer.getRepeatMode(): RepeatMode

Return Value​

Returns one of the RepeatMode constants.

Example​

import { RepeatMode } from "react-track-player-web"

const repeatMode = TrackPlayer.getRepeatMode()
if (repeatMode === RepeatMode.Track) {
  console.log("Currently repeating this track")
} else if (repeatMode === RepeatMode.Queue) {
  console.log("Repeating the entire queue")
} else {
  console.log("Repeat is turned off")
}

Error Handling​

retry​

Retries playback of the current track after an error has occurred.

await TrackPlayer.retry(): Promise<void>

Example​

try {
  // Some operation that might fail
  await TrackPlayer.play()
} catch (error) {
  console.error("Playback error:", error)

  // Try to recover
  try {
    await TrackPlayer.retry()
    console.log("Successfully recovered")
  } catch (retryError) {
    console.error("Failed to recover:", retryError)
  }
}