Skip to main content
Version: 2.1


setupPlayer(options: PlayerOptions)

Initializes the player with the specified options. These options do not apply to all platforms, see chart below.

These options are different than the ones set using updateOptions(). Options other than those listed below will not be applied.

You should always call this function (even without any options set) before using the player to make sure everything is initialized.

If the player is already initialized, the promise will resolve instantly.

Returns: Promise

optionsPlayerOptionsThe options
options.minBuffernumberMinimum time in seconds that needs to be buffered15 (android), automatic (ios)
options.maxBuffernumberMaximum time in seconds that needs to be buffered50
options.playBuffernumberMinimum time in seconds that needs to be buffered to start playing2.5
options.backBuffernumberTime in seconds that should be kept in the buffer behind the current playhead time.0
options.maxCacheSizenumberMaximum cache size in kilobytes0
options.iosCategoryIOSCategoryAVAudioSession.Category for iOS. Sets on play()playback
options.iosCategoryOptionsIOSCategoryOptions[]AVAudioSession.CategoryOptions for iOS. Sets on play()[]
options.iosCategoryModeIOSCategoryModeAVAudioSession.Mode for iOS. Sets on play()default
options.waitForBufferbooleanIndicates whether the player should automatically delay playback in order to minimize stalling. If you notice that network media immediately pauses after it buffers, setting this to true may help.false
options.autoUpdateMetadatabooleanIndicates whether the player should automatically update now playing metadata data in control center / notification.true


Destroys the player, cleaning up its resources. After executing this function, you won't be able to use the player anymore, unless you call setupPlayer() again.


Register the playback service. The service will run as long as the player runs.

This function should only be called once, and should be registered right after registering your React application with AppRegistry.

You should use the playback service to register the event handlers that must be directly tied to the player, as the playback service might keep running when the app is in background.

serviceProviderfunctionThe function that must return an async service function.

useTrackPlayerEvents(events: Event[], handler: Handler)

Hook that fires on the specified events.

You can find a list of events in the events section.