Audio Browser

Appearance

features/player ​

AndroidAudioContentType ​

ts
type AndroidAudioContentType = "music" | "speech" | "sonification" | "movie" | "unknown";

AndroidAudioContentType options:

AndroidAudioOffloadSettings ​

Properties ​

PropertyTypeDescription
gaplessSupportRequired?booleanWhether gapless playback support is required for offload. Enables smooth transitions between tracks without silence gaps. Default true
rateChangeSupportRequired?booleanWhether playback rate change support is required for offload. Enables variable playback speeds (0.5x, 1.25x, 2x, etc.) during offload. Default true

AndroidOptions ​

Properties ​

PropertyTypeDescription
appKilledPlaybackBehaviorAppKilledPlaybackBehaviorWhether the audio playback notification is also removed when the playback stops. If stoppingAppPausesPlayback is set to false, this will be ignored.
skipSilencebooleanWhether to automatically skip silent audio segments during playback. When enabled, the player will detect and skip over periods of silence. Default false
shufflebooleanWhether shuffle mode is enabled for queue playback. When enabled, tracks will be played in random order. Default false
ratingTypeRatingTypeThe rating type to use for ratings. Determines how star ratings and thumbs up/down are handled.
notificationButtonsNotificationButtonLayout | nullSlot-based button layout for Android notifications. Provides explicit control over which buttons appear in which positions. When not specified, button layout is derived from capabilities. Platform android

AndroidPlayerWakeMode ​

ts
type AndroidPlayerWakeMode = "none" | "local" | "network";

AndroidWakeMode options:

  • 'none': No wake locks are held. The device may go to sleep during playback.
  • 'local': Holds a PowerManager.WakeLock during playback to prevent CPU sleep. Suitable for local media playback with the screen off.
  • 'network': Holds both PowerManager.WakeLock and WifiManager.WifiLock during playback. Suitable for streaming media over WiFi with the screen off.

AndroidSetupPlayerOptions ​

Properties ​

PropertyTypeDescription
minBuffernumberMinimum duration of media that the player will attempt to buffer in ms. Throws Will throw if min buffer is higher than max buffer. Default 50000
audioOffloadboolean | AndroidAudioOffloadSettingsAudio offload configuration for power-efficient playback. - true: Enable with default settings (gapless and rate change support required) - false: Disable audio offload - { gaplessSupportRequired?, rateChangeSupportRequired? }: Enable with custom requirements Audio offload moves audio processing to dedicated hardware when available, saving battery during longer playbacks, especially with screen off. Requirements determine which features must be supported for offload to activate: - gaplessSupportRequired: Smooth track transitions without silence - rateChangeSupportRequired: Variable playback speeds (0.5x, 1.25x, 2x, etc.) See https://developer.android.com/media/media3/exoplayer/track-selection#audioOffload
maxBuffernumberMaximum duration of media that the player will attempt to buffer in ms. Max buffer may not be lower than min buffer. Throws Will throw if max buffer is lower than min buffer. Default 50000
backBuffernumberDuration in ms that should be kept in the buffer behind the current playhead time. Default 0
playBuffernumberDuration of media in ms that must be buffered for playback to start or resume following a user action such as a seek. Default 2500
rebufferBuffernumber | nullDuration of media in ms that must be buffered for playback to resume after a rebuffer (when the buffer runs empty during playback). When null (the default), uses automatic mode: - Starts at playBuffer value - On rebuffer, measures how fast the buffer drained - Calculates how much buffer is needed to sustain 60s of playback - Increases threshold accordingly (up to 8000ms max) - Resets when changing tracks Set to a number for a fixed threshold in ms. Should be >= playBuffer, otherwise playback may rebuffer repeatedly (resuming with less buffer than initial start). Default null (automatic)
maxCacheSizenumberMaximum cache size in MB. Default 0
audioContentTypeAndroidAudioContentTypeThe audio content type indicates to the android system how you intend to use audio in your app. With audioContentType: AndroidAudioContentType.Speech, the audio will be paused during short interruptions, such as when a message arrives. Otherwise the playback volume is reduced while the notification is playing. Default AndroidAudioContentType.Music
handleAudioBecomingNoisybooleanWhether the player should automatically pause when audio becomes noisy (e.g., when headphones are unplugged). Default true
wakeModeAndroidPlayerWakeModeWake mode for the player to use. Determines whether wake locks are held to keep the CPU and/or WiFi active during playback. Default 'none'

AndroidUpdateOptions ​

Properties ​

PropertyTypeDescription
appKilledPlaybackBehavior?AppKilledPlaybackBehaviorWhether the audio playback notification is also removed when the playback stops. If stoppingAppPausesPlayback is set to false, this will be ignored.
skipSilence?booleanWhether to automatically skip silent audio segments during playback. When enabled, the player will detect and skip over periods of silence. Default false
shuffle?booleanWhether shuffle mode is enabled for queue playback. When enabled, tracks will be played in random order. Default false
ratingType?RatingTypeThe rating type to use for ratings. Determines how star ratings and thumbs up/down are handled.
notificationButtons?NotificationButtonLayout | nullSlot-based button layout for Android notifications. Provides explicit control over which buttons appear in which positions. When not specified, button layout is derived from capabilities. Platform android

AppKilledPlaybackBehavior ​

ts
type AppKilledPlaybackBehavior = 
  | "continue-playback"
  | "pause-playback"
  | "stop-playback-and-remove-notification";

AppKilledPlaybackBehavior options:

  • 'continue-playback': This option will continue playing audio in the background when the app is removed from recents. The notification remains. This is the default.
  • 'pause-playback': This option will pause playing audio in the background when the app is removed from recents. The notification remains and can be used to resume playback.
  • 'stop-playback-and-remove-notification': This option will stop playing audio in the background when the app is removed from recents. The notification is removed and can't be used to resume playback. Users would need to open the app again to start playing audio.

FeedbackOptions ​

Properties ​

PropertyTypeDescription
isActivebooleanMarks wether the option should be marked as active or "done"
titlestringThe title to give the action (relevant for iOS)

IOSCategory ​

ts
type IOSCategory = 
  | "playback"
  | "playAndRecord"
  | "multiRoute"
  | "ambient"
  | "soloAmbient"
  | "record";

IOSCategory options:

IOSCategoryMode ​

ts
type IOSCategoryMode = 
  | "default"
  | "gameChat"
  | "measurement"
  | "moviePlayback"
  | "spokenAudio"
  | "videoChat"
  | "videoRecording"
  | "voiceChat"
  | "voicePrompt";

IOSCategoryMode options:

IOSCategoryOptions ​

ts
type IOSCategoryOptions = 
  | "mixWithOthers"
  | "duckOthers"
  | "interruptSpokenAudioAndMixWithOthers"
  | "allowBluetooth"
  | "allowBluetoothA2DP"
  | "allowAirPlay"
  | "defaultToSpeaker";

IOSCategoryOptions options:

IOSCategoryPolicy ​

ts
type IOSCategoryPolicy = "default" | "longFormAudio" | "longFormVideo";

IOSCategoryPolicy options:

IOSSetupPlayerOptions ​

Properties ​

PropertyTypeDescription
buffer?numberPreferred forward buffer duration in ms. When set to 0 (default), AVPlayer chooses an appropriate level of buffering automatically. Setting this to a value greater than 0 disables automaticallyWaitsToMinimizeStalling. Read more from Apple Documentation Default 0
category?IOSCategoryAVAudioSession.Category for iOS. Sets on play().
categoryMode?IOSCategoryModeThe audio session mode, together with the audio session category, indicates to the system how you intend to use audio in your app. You can use a mode to configure the audio system for specific use cases such as video recording, voice or video chat, or audio analysis. Sets on play(). See https://developer.apple.com/documentation/avfoundation/avaudiosession/1616508-mode
categoryOptions?IOSCategoryOptions[]AVAudioSession.CategoryOptions for iOS. Sets on play().
categoryPolicy?IOSCategoryPolicyAVAudioSession.RouteSharingPolicy for iOS. Sets on play().

NativeUpdateOptions ​

Properties ​

PropertyTypeDescription
android?NitroAndroidUpdateOptionsAndroid-specific configuration options
forwardJumpInterval?numberJump forward interval in seconds when using jump forward controls. Default 15
backwardJumpInterval?numberJump backward interval in seconds when using jump backward controls. Default 15
progressUpdateEventInterval?number | nullHow often progress events are emitted in seconds. When null, progress events are disabled. Default null
capabilities?PlayerCapabilities-
iosPlaybackRates?number[]Supported playback rates for the playback-rate capability. Platform ios

NitroAndroidUpdateOptions ​

Properties ​

PropertyType
appKilledPlaybackBehavior?AppKilledPlaybackBehavior
skipSilence?boolean
shuffle?boolean
ratingType?RatingType
notificationButtons?NotificationButtonLayout | null

NotificationButton ​

ts
type NotificationButton = 
  | "skip-to-previous"
  | "skip-to-next"
  | "jump-backward"
  | "jump-forward"
  | "favorite";

Buttons that can be assigned to Android notification button slots. These represent the interactive buttons users can tap in the notification.

NotificationButtonLayout ​

ts
type NotificationButtonLayout = object;

Configuration for notification button layout on Android. Allows explicit control over which buttons appear in which slots.

Slot behavior:

  • Omit a slot: Derive from capabilities (smart default)
  • Set to null: Explicitly empty slot
  • Set to button: Show that button in that slot

Example ​

typescript
// Podcast-style: jump buttons as primary
notificationButtons: {
  back: 'jump-backward',
  forward: 'jump-forward',
  overflow: ['favorite']
}

// Music-style: skip as primary, jump as secondary
notificationButtons: {
  back: 'skip-to-previous',
  forward: 'skip-to-next',
  backSecondary: 'jump-backward',
  forwardSecondary: 'jump-forward'
}

Properties ​

back? ​

ts
optional back: NotificationButton | null;

Primary back position (SLOT_BACK) - typically previous track or jump backward

forward? ​

ts
optional forward: NotificationButton | null;

Primary forward position (SLOT_FORWARD) - typically next track or jump forward

backSecondary? ​

ts
optional backSecondary: NotificationButton | null;

Secondary back position (SLOT_BACK_SECONDARY)

forwardSecondary? ​

ts
optional forwardSecondary: NotificationButton | null;

Secondary forward position (SLOT_FORWARD_SECONDARY)

overflow? ​

ts
optional overflow: NotificationButton[];

Additional buttons in overflow area (SLOT_OVERFLOW)

useOptions() ​

ts
function useOptions(): Options;

Hook that returns the current player options and updates when they change.

Returns ​

Options

The current player options

getOptions() ​

ts
function getOptions(): Options;

Gets the current player options with resolved defaults. Returns all current option values - use this to read the current state.

Returns ​

Options

The current player options with all properties resolved to their current values

Example ​

typescript
const options = getOptions();
if (options.repeatMode === 'track') {
  // Handle track repeat mode
}

updateOptions() ​

ts
function updateOptions(options): void;

Updates the configuration for the components. Pass only the properties you want to change - all properties are optional.

Parameters ​

ParameterTypeDescription
optionsUpdateOptionsThe partial options to update. Only changed properties need to be specified.

Returns ​

void

See ​

getOptions to get current options

Example ​

typescript
// Update single property
updateOptions({ repeatMode: 'track' });

// Disable specific capabilities
updateOptions({
  capabilities: { shuffleMode: false },
  progressUpdateEventInterval: 0.5
});

onOptionsChanged ​

ts
const onOptionsChanged: NativeUpdatedValue<Options>;

Subscribes to player options changes.

Param ​

Called when the player options change

Returns ​

Cleanup function to unsubscribe

Options ​

Current player options with resolved defaults. This is what you receive from getOptions() - all properties are present with their current values. Platform-specific properties (android/ios) are only available on their respective platforms.

Example ​

typescript
const options = getOptions();
console.log(options.repeatMode); // 'off'
console.log(options.capabilities); // { shuffleMode: false } - only disabled caps shown
console.log(options.android?.skipSilence); // true (Android only)
console.log(options.ios?.likeOptions); // { isActive: false, title: 'Like' } (iOS only)

Properties ​

PropertyTypeDescription
android?AndroidOptionsAndroid-specific configuration options with resolved defaults (only present on Android)
forwardJumpIntervalnumberJump forward interval in seconds when using jump forward controls. Default 15
backwardJumpIntervalnumberJump backward interval in seconds when using jump backward controls. Default 15
progressUpdateEventIntervalnumber | nullHow often progress events are emitted in seconds. When null, progress events are disabled. Default null
capabilitiesPlayerCapabilitiesThe capabilities that the player has. All capabilities are enabled by default - this shows which ones are disabled.
repeatModeRepeatModeThe current repeat mode of the player. Default RepeatMode.Off

PartialAndroidSetupPlayerOptions ​

ts
type PartialAndroidSetupPlayerOptions = object;

Android-specific player setup options.

Properties ​

minBuffer? ​

ts
optional minBuffer: number;

Minimum duration of media that the player will attempt to buffer in ms.

Throws ​

Will throw if min buffer is higher than max buffer.

Default ​
ts
50000

audioOffload? ​

ts
optional audioOffload: boolean | AndroidAudioOffloadSettings;

Enable audio offload for power-efficient playback.

When enabled, audio decoding is offloaded to dedicated hardware, reducing CPU usage and extending battery life during long playback sessions.

  • true: Enable with default settings (gapless + rate change support required)
  • false/undefined: Disabled
  • { gaplessSupportRequired: boolean, rateChangeSupportRequired: boolean }: Enable with specific requirements for gapless playback and playback rate changes
Default ​
ts
false

maxBuffer? ​

ts
optional maxBuffer: number;

Maximum duration of media that the player will attempt to buffer in ms. Max buffer may not be lower than min buffer.

Throws ​

Will throw if max buffer is lower than min buffer.

Default ​
ts
50000

backBuffer? ​

ts
optional backBuffer: number;

Duration in ms that should be kept in the buffer behind the current playhead time.

Default ​
ts
0

playBuffer? ​

ts
optional playBuffer: number;

Duration of media in ms that must be buffered for playback to start or resume following a user action such as a seek.

Default ​
ts
2500

rebufferBuffer? ​

ts
optional rebufferBuffer: number | null;

Duration of media in ms that must be buffered for playback to resume after a rebuffer (when the buffer runs empty during playback).

When null (the default), uses automatic mode:

  • Starts at playBuffer value
  • On rebuffer, measures how fast the buffer drained
  • Calculates how much buffer is needed to sustain 60s of playback
  • Increases threshold accordingly (up to 8000ms max)
  • Resets when changing tracks

Set to a number for a fixed threshold in ms. Should be >= playBuffer, otherwise playback may rebuffer repeatedly (resuming with less buffer than initial start).

Default ​
ts
null (automatic)

maxCacheSize? ​

ts
optional maxCacheSize: number;

Maximum cache size in MB.

Default ​
ts
0

audioContentType? ​

ts
optional audioContentType: AndroidAudioContentType;

The audio content type indicates to the android system how you intend to use audio in your app.

With audioContentType: AndroidAudioContentType.Speech, the audio will be paused during short interruptions, such as when a message arrives. Otherwise the playback volume is reduced while the notification is playing.

Default ​
ts
AndroidAudioContentType.Music

handleAudioBecomingNoisy? ​

ts
optional handleAudioBecomingNoisy: boolean;

Whether the player should automatically pause when audio becomes noisy (e.g., when headphones are unplugged).

Default ​
ts
true

wakeMode? ​

ts
optional wakeMode: AndroidPlayerWakeMode;

Wake mode for the player to use.

Determines whether wake locks are held to keep the CPU and/or WiFi active during playback.

Default ​
ts
'none'

PartialIOSSetupPlayerOptions ​

Properties ​

PropertyTypeDescription
buffer?numberPreferred forward buffer duration in ms. When set to 0 (default), AVPlayer chooses an appropriate level of buffering automatically. Setting this to a value greater than 0 disables automaticallyWaitsToMinimizeStalling. Read more from Apple Documentation Default 0
category?IOSCategoryAVAudioSession.Category for iOS. Sets on play().
categoryMode?IOSCategoryModeThe audio session mode, together with the audio session category, indicates to the system how you intend to use audio in your app. You can use a mode to configure the audio system for specific use cases such as video recording, voice or video chat, or audio analysis. Sets on play(). See https://developer.apple.com/documentation/avfoundation/avaudiosession/1616508-mode
categoryOptions?IOSCategoryOptions[]AVAudioSession.CategoryOptions for iOS. Sets on play().
categoryPolicy?IOSCategoryPolicyAVAudioSession.RouteSharingPolicy for iOS. Sets on play().

PartialSetupPlayerOptions ​

Properties ​

PropertyTypeDescription
android?PartialAndroidSetupPlayerOptionsAndroid-specific configuration options for setup
ios?PartialIOSSetupPlayerOptionsiOS-specific configuration options for setup
autoUpdateMetadata?booleanIndicates whether the player should automatically update now playing metadata data in control center / notification. Defaults to true.
retry?boolean | RetryConfigRetry policy for load errors (network failures, timeouts, etc.) - true: Retry indefinitely with exponential backoff (2 minute timeout) - false/undefined: No automatic retry (default) - { maxRetries: n }: Retry up to n times with exponential backoff - { maxRetries: n, maxRetryDurationMs: m }: Retry with custom timeout Exponential backoff delays: 1s → 1.5s → 2.3s → 3.4s → 5s (capped) Default false

PlayerCapabilities ​

Player capabilities control which media controls are available to the user. All capabilities are enabled by default - only specify ones you want to disable.

Example ​

typescript
// Disable shuffle and repeat for a simple player
updateOptions({
  capabilities: {
    shuffleMode: false,
    repeatMode: false,
  }
})

Properties ​

PropertyTypeDescription
play?booleanEnable play control. Default true
pause?booleanEnable pause control. Default true
stop?booleanEnable stop control. Default true
seekTo?booleanEnable seek-to-position control (scrubbing in timeline). Default true
skipToNext?booleanEnable skip to next track control. Default true
skipToPrevious?booleanEnable skip to previous track control. Default true
jumpForward?booleanEnable jump forward control (configurable via forwardJumpInterval). Typically used for podcast/audiobook apps. Default false
jumpBackward?booleanEnable jump backward control (configurable via backwardJumpInterval). Typically used for podcast/audiobook apps. Default false
favorite?booleanEnable favorite/like control. On iOS: appears in Control Center. On Android: can be assigned to notification button slots. Default true
shuffleMode?booleanEnable shuffle mode toggle. Default true
repeatMode?booleanEnable repeat mode toggle. Default true
playbackRate?booleanEnable playback rate control. On iOS: appears in Control Center and CarPlay. Default true

PlayerOptions ​

Properties ​

PropertyTypeDescription
android?AndroidSetupPlayerOptionsAndroid-specific configuration options for setup
ios?PartialIOSSetupPlayerOptionsiOS-specific configuration options for setup
autoUpdateMetadatabooleanIndicates whether the player should automatically update now playing metadata data in control center / notification. Defaults to true.
retry?boolean | RetryConfigRetry policy for load errors (network failures, timeouts, etc.) - true: Retry indefinitely with exponential backoff (2 minute timeout) - false/undefined: No automatic retry (default) - { maxRetries: n }: Retry up to n times with exponential backoff - { maxRetries: n, maxRetryDurationMs: m }: Retry with custom timeout Exponential backoff delays: 1s → 1.5s → 2.3s → 3.4s → 5s (capped) Default false

RetryConfig ​

ts
type RetryConfig = object;

Configuration for retry behavior.

Properties ​

maxRetries ​

ts
maxRetries: number;

Maximum number of retry attempts before giving up.

maxRetryDurationMs? ​

ts
optional maxRetryDurationMs: number;

Maximum duration in milliseconds to keep retrying before giving up. This prevents surprising playback resumption after long periods offline.

Default ​
ts
120000 (2 minutes)

setupPlayer() ​

ts
function setupPlayer(options): Promise<void>;

Initializes the player with the specified options.

Parameters ​

ParameterTypeDescription
optionsPartialSetupPlayerOptionsThe options to initialize the player with.

Returns ​

Promise<void>

UpdateOptions ​

Partial options for updating player configuration. Only specify the properties you want to change - all properties are optional. Use null to reset properties to their defaults.

Example ​

typescript
// Update only repeat mode
updateOptions({ repeatMode: 'track' });

// Disable specific capabilities
updateOptions({
  capabilities: { shuffleMode: false, repeatMode: false }
});

// Disable progress events by setting to null
updateOptions({
  progressUpdateEventInterval: null
});

// Platform-specific options
updateOptions({
  android: { skipSilence: true },
  ios: { likeOptions: { isActive: true, title: 'Love' } }
});

Properties ​

PropertyTypeDescription
android?AndroidUpdateOptionsAndroid-specific configuration options
forwardJumpInterval?numberJump forward interval in seconds when using jump forward controls. Default 15
backwardJumpInterval?numberJump backward interval in seconds when using jump backward controls. Default 15
progressUpdateEventInterval?number | nullHow often progress events are emitted in seconds. When null, progress events are disabled. Default null
capabilities?PlayerCapabilitiesPlayer capabilities to enable or disable. All capabilities are enabled by default - only specify ones you want to disable. Example // Disable shuffle and repeat updateOptions({ capabilities: { shuffleMode: false, repeatMode: false, } })
iosPlaybackRates?number[]Supported playback rates for the playback-rate capability. Used by CarPlay and lock screen rate controls. Platform ios Default [0.5, 1.0, 1.5, 2.0]