Skip to main content
Version: Next


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. Do not call this more than once in the lifetime of your app.

Note that on Android this method must only be called while the app is in the foreground, otherwise it will throw an error with code 'android_cannot_setup_player_in_background'. In this case you can wait for the app to be in the foreground and try again.

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.androidAudioContentTypeAndroidAudioContentTypeThe audio content type indicates to the android system how you intend to use audio in your app.AndroidAudioContentType.Music
options.iosCategoryIOSCategoryAVAudioSession.Category for iOS. Sets on play()IOSCategory.Playback
options.iosCategoryOptionsIOSCategoryOptions[]AVAudioSession.CategoryOptions for iOS. Sets on play()[]
options.iosCategoryModeIOSCategoryModeAVAudioSession.Mode for iOS. Sets on play()default
options.autoHandleInterruptionsbooleanIndicates whether the player should automatically handle audio interruptions.false
options.autoUpdateMetadatabooleanIndicates whether the player should automatically update now playing metadata data in control center / notification.true


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.