TypeScript Types Reference for React Native Audio Pro

All types are exported directly from react-native-audio-pro with full TypeScript support. Import only what you need — every interface and type alias is tree-shakeable and ships with inline JSDoc comments to power your IDE’s autocomplete.

import type {
  AudioProTrack,
  AudioProConfigureOptions,
  AudioProPlayOptions,
  AudioProHeaders,
  AudioProEvent,
  AudioProEventCallback,
  AudioProStateChangedPayload,
  AudioProTrackEndedPayload,
  AudioProPlaybackErrorPayload,
  AudioProProgressPayload,
  AudioProSeekCompletePayload,
  AudioProPlaybackSpeedChangedPayload,
  AudioProQueueChangedPayload,
  AudioProNotificationButton,
  AmbientAudioPlayOptions,
  AudioProAmbientEvent,
  AudioProAmbientEventCallback,
  AudioProAmbientErrorPayload,
  AudioProEqualizerBand,
  AudioProEqualizerPreset,
} from 'react-native-audio-pro';

Track

`AudioProArtwork`

type AudioProArtwork = string;

A type alias for artwork URLs and local file paths. Used as the type for AudioProTrack.artwork. Accepting string directly means any URL scheme (https://, file://) or local asset path is valid.

`AudioProTrack`

Represents a single audio track. Pass this to queue methods such as AudioPro.addMediaItems(), AudioPro.setMediaItems(), or AudioPro.addMediaItemsAt().

string

required

Unique identifier for the track. Used internally for queue management and deduplication.

url

string

required

Remote URL or local file path to the audio resource.

title

string

required

Display title shown in the notification and lock screen media controls.

artwork

AudioProArtwork (string)

required

URL or local file path for the track artwork. Displayed in the notification and lock screen.

album

string

Optional album name. Displayed in some media control surfaces.

artist

string

Optional artist name. Displayed in the notification and lock screen media controls.

[key: string]

unknown

Any additional custom properties are allowed. Useful for passing metadata through event payloads without a separate lookup.

const track: AudioProTrack = {
  id: 'track-001',
  url: 'https://cdn.example.com/audio/episode-42.mp3',
  title: 'Episode 42: Deep Dive',
  artwork: 'https://cdn.example.com/artwork/episode-42.jpg',
  album: 'The Deep Dive Podcast',
  artist: 'Jane Smith',
  // custom properties
  episodeNumber: 42,
  durationSeconds: 3600,
};

Configuration

`AudioProConfigureOptions`

Passed to AudioPro.configure() to set global player behaviour. All fields are optional — unset fields fall back to documented defaults.

contentType

AudioProContentType

Declares the kind of audio content. Affects platform-level audio routing and optimisations. Defaults to AudioProContentType.MUSIC.

debug

boolean

Enables verbose native logging to aid development. Default: false.

debugIncludesProgress

boolean

When debug is true, also logs every PROGRESS event. Can be noisy — disable in most debug sessions. Default: false.

progressIntervalMs

number

How often (in milliseconds) the player emits PROGRESS events. Default: 1000 (1 second).

skipIntervalMs

number

Duration (in milliseconds) used by the rewind/forward skip buttons in the notification and lock screen. Default: 30000 (30 seconds).

repeatMode

AudioProRepeatMode

Sets the initial repeat mode for the queue. Can be changed at runtime via AudioPro.setRepeatMode().

shuffleMode

boolean

Sets the initial shuffle state. Can be toggled at runtime via AudioPro.setShuffleModeEnabled().

maxCacheSize

number

Maximum on-disk cache size in bytes. This is a global setting and may only take effect on first initialisation. Default: 524288000 (500 MB).

cacheEnabled

boolean

Enables or disables the audio cache. Changing this setting requires a session restart to take full effect. Default: true.

skipSilence

boolean

Automatically skips silent sections during playback. Android only. Default: false.

Playback Options

`AudioProPlayOptions`

Passed as the optional argument to AudioPro.play() to control how playback starts.

autoPlay

boolean

When true, playback begins immediately after the track is loaded. When false, the player loads the track and enters STOPPED state.

headers

AudioProHeaders

Custom HTTP headers for network requests. See AudioProHeaders below.

startTimeMs

number

Position in milliseconds at which playback should begin. Useful for resuming a track.

addTrack

boolean

When true, the track is appended to the queue rather than replacing it.

`AudioProHeaders`

Custom HTTP headers sent when fetching audio streams and artwork. Both fields are independent — you can send headers for audio only, artwork only, or both.

audio

Record<string, string>

Headers attached to the audio stream request (e.g. Authorization, X-Custom-Token).

artwork

Record<string, string>

Headers attached to the artwork image request.

const options: AudioProPlayOptions = {
  autoPlay: true,
  startTimeMs: 120000, // resume at 2 minutes
  headers: {
    audio: { Authorization: 'Bearer my-token' },
    artwork: { Authorization: 'Bearer my-token' },
  },
};

AudioPro.play(options);

Notification Buttons

`AudioProNotificationButton`

A union type of string literals representing the buttons that can appear in the media notification and lock screen controls. Pass an array of these to AudioPro.setNotificationButtons().

type AudioProNotificationButton =
  | 'PLAY'
  | 'PAUSE'
  | 'PREV'
  | 'NEXT'
  | 'LIKE'
  | 'DISLIKE'
  | 'SAVE'
  | 'BOOKMARK'
  | 'REWIND_30'
  | 'FORWARD_30';

Value	Description
`PLAY`	Play button
`PAUSE`	Pause button
`PREV`	Previous track
`NEXT`	Next track
`LIKE`	Like / thumbs-up action
`DISLIKE`	Dislike / thumbs-down action
`SAVE`	Save to library action
`BOOKMARK`	Bookmark action
`REWIND_30`	Rewind 30 seconds
`FORWARD_30`	Fast-forward 30 seconds

Custom action buttons (LIKE, DISLIKE, SAVE, BOOKMARK, REWIND_30, FORWARD_30) fire an AudioProEventType.CUSTOM_ACTION event. Read the payload.action field to identify which button was pressed.

Event Types

`AudioProEvent`

The single event shape emitted by the main audio player. Your AudioProEventCallback receives this object for every player event.

type

AudioProEventType

required

Identifies which event occurred. See AudioProEventType.

track

AudioProTrack | null

required

The track that was active when the event fired. null for REMOTE_NEXT and REMOTE_PREV events when no track is loaded.

payload

object

Event-specific data. The fields present depend on the type. See the payload interfaces below for the full shape of each event.

Show payload fields

state

AudioProState

Present on STATE_CHANGED events.

position

number

Playback position in milliseconds. Present on STATE_CHANGED, PROGRESS, TRACK_ENDED, and SEEK_COMPLETE events.

duration

number

Total track duration in milliseconds. Present on STATE_CHANGED, PROGRESS, TRACK_ENDED, and SEEK_COMPLETE events.

bufferedPosition

number

Buffered position in milliseconds. Present on PROGRESS events.

error

string

Human-readable error message. Present on PLAYBACK_ERROR events.

errorCode

number

Numeric error code. See AudioProErrorCode. Present on PLAYBACK_ERROR events.

recoverable

boolean

Whether the player can continue after the error. Present on PLAYBACK_ERROR events.

cause

string

Optional underlying exception message. Present on PLAYBACK_ERROR events.

speed

number

New playback speed multiplier. Present on PLAYBACK_SPEED_CHANGED events.

index

number

Queue index of the track where the error occurred. Present on PLAYBACK_ERROR events.

action

string

The notification button identifier that was pressed (e.g. 'LIKE', 'SAVE'). Present on CUSTOM_ACTION events.

timerDuration

number

The duration (ms) the sleep timer was set for. Present on SLEEP_TIMER_COMPLETE events.

size

number

Current queue size. Present on QUEUE_CHANGED events.

currentIndex

number

Index of the currently active track in the queue. Present on QUEUE_CHANGED events.

audioSessionId

number

The new audio session ID. Present on AUDIO_SESSION_CHANGED events. Use this with a native equalizer or visualizer.

Payload Interfaces

Each payload interface represents the strongly-typed shape of AudioProEvent.payload for a specific event type. Use these when you need precise types inside a switch/case handler.

`AudioProStateChangedPayload`

Emitted with AudioProEventType.STATE_CHANGED.

state

AudioProState

required

The new player state.

position

number

required

Current playback position in milliseconds at the moment of the state change.

duration

number

required

Total track duration in milliseconds.

`AudioProTrackEndedPayload`

Emitted with AudioProEventType.TRACK_ENDED.

position

number

required

Final playback position in milliseconds when the track ended.

duration

number

required

Total track duration in milliseconds.

`AudioProPlaybackErrorPayload`

Emitted with AudioProEventType.PLAYBACK_ERROR.

error

string

required

Human-readable error message from the underlying player.

errorCode

AudioProErrorCode | number

JS-friendly error code mapped from Media3 error codes. See AudioProErrorCode.

recoverable

boolean

true means the player is still usable and may retry automatically. false means the session has failed.

cause

string

Optional cause string from the underlying native exception.

index

number

Queue index of the track where the error occurred.

`AudioProProgressPayload`

Emitted with AudioProEventType.PROGRESS on the interval set by progressIntervalMs.

position

number

required

Current playback position in milliseconds.

duration

number

required

Total track duration in milliseconds.

bufferedPosition

number

required

How many milliseconds of audio have been buffered ahead of the current position.

`AudioProSeekCompletePayload`

Emitted with AudioProEventType.SEEK_COMPLETE after a seek operation finishes.

position

number

required

The position in milliseconds where playback resumed after the seek.

duration

number

required

Total track duration in milliseconds.

triggeredBy

AudioProTriggerSource

required

Indicates whether the seek was initiated by your app/user code (USER) or by the system/remote controls (SYSTEM).

`AudioProPlaybackSpeedChangedPayload`

Emitted with AudioProEventType.PLAYBACK_SPEED_CHANGED.

speed

number

required

The new playback speed as a multiplier (e.g. 1.0 = normal, 1.5 = 1.5×, 0.75 = 75%).

`AudioProQueueChangedPayload`

Emitted with AudioProEventType.QUEUE_CHANGED whenever the queue is modified (add, remove, move, or clear).

size

number

required

Total number of tracks now in the queue.

currentIndex

number

required

Zero-based index of the currently active track in the updated queue.

Callback Types

`AudioProEventCallback`

type AudioProEventCallback = (event: AudioProEvent) => void;

Pass a function matching this signature to AudioPro.addEventListener(). The callback is called on the JS thread for every player event.

`AudioProAmbientEventCallback`

type AudioProAmbientEventCallback = (event: AudioProAmbientEvent) => void;

Pass a function matching this signature to AudioPro.addAmbientListener().

Ambient Audio Types

`AmbientAudioPlayOptions`

Passed to AudioPro.ambientPlay() to configure ambient (secondary) audio playback.

url

string

required

Remote URL or local file path for the ambient audio resource.

loop

boolean

When true, the ambient track loops indefinitely until AudioPro.ambientStop() is called. Defaults to true.

`AudioProAmbientEvent`

The event shape emitted by the ambient player. Your AudioProAmbientEventCallback receives this object.

type

AudioProAmbientEventType

required

Identifies which ambient event occurred. See AudioProAmbientEventType.

payload

object

Optional event-specific data.

Show payload fields

error

string

Error message. Present on AMBIENT_ERROR events.

`AudioProAmbientErrorPayload`

Strongly-typed shape of the payload for AudioProAmbientEventType.AMBIENT_ERROR events.

error

string

required

Human-readable description of the ambient playback error. The ambient player is automatically cleaned up after an error.

Equalizer Types

`AudioProEqualizerBand`

Describes a single frequency band in the 10-band equalizer.

frequency

number

required

Centre frequency of the band in Hz (e.g. 31, 1000, 16000).

label

string

required

Human-readable label for the band (e.g. '31Hz', '1kHz', '16kHz').

`AudioProEqualizerPreset`

Describes a named equalizer preset with per-band gain values.

name

string

required

Display name for the preset (e.g. 'Rock', 'Vocal Clarity (Adv)').

string

required

Stable identifier used to look up and apply the preset (e.g. 'rock', 'adv-vocal-clarity').

gains

number[]

required

Array of 10 gain values in dB, one per band ordered from 31 Hz to 16 kHz.

description

string

Optional prose description of the preset’s sonic character. All advanced presets include a description.

AudioPro

Types & Enums

TypeScript Types Reference for React Native Audio Pro

Track

`AudioProArtwork`

`AudioProTrack`

Configuration

`AudioProConfigureOptions`

Playback Options

`AudioProPlayOptions`

`AudioProHeaders`

Notification Buttons

`AudioProNotificationButton`

Event Types

`AudioProEvent`

Payload Interfaces

`AudioProStateChangedPayload`

`AudioProTrackEndedPayload`

`AudioProPlaybackErrorPayload`

`AudioProProgressPayload`

`AudioProSeekCompletePayload`

`AudioProPlaybackSpeedChangedPayload`

`AudioProQueueChangedPayload`

Callback Types

`AudioProEventCallback`

`AudioProAmbientEventCallback`

Ambient Audio Types

`AmbientAudioPlayOptions`

`AudioProAmbientEvent`

`AudioProAmbientErrorPayload`

Equalizer Types

`AudioProEqualizerBand`

`AudioProEqualizerPreset`

Build docs developers (and LLMs) love

AudioPro

Types & Enums

Documentation Index

​Track

​AudioProArtwork

​AudioProTrack

​Configuration

​AudioProConfigureOptions

​Playback Options

​AudioProPlayOptions

​AudioProHeaders

​Notification Buttons

​AudioProNotificationButton

​Event Types

​AudioProEvent

​Payload Interfaces

​AudioProStateChangedPayload

​AudioProTrackEndedPayload

​AudioProPlaybackErrorPayload

​AudioProProgressPayload

​AudioProSeekCompletePayload

​AudioProPlaybackSpeedChangedPayload

​AudioProQueueChangedPayload

​Callback Types

​AudioProEventCallback

​AudioProAmbientEventCallback

​Ambient Audio Types

​AmbientAudioPlayOptions

​AudioProAmbientEvent

​AudioProAmbientErrorPayload

​Equalizer Types

​AudioProEqualizerBand

​AudioProEqualizerPreset

Build docs developers (and LLMs) love

Track

`AudioProArtwork`

`AudioProTrack`

Configuration

`AudioProConfigureOptions`

Playback Options

`AudioProPlayOptions`

`AudioProHeaders`

Notification Buttons

`AudioProNotificationButton`

Event Types

`AudioProEvent`

Payload Interfaces

`AudioProStateChangedPayload`

`AudioProTrackEndedPayload`

`AudioProPlaybackErrorPayload`

`AudioProProgressPayload`

`AudioProSeekCompletePayload`

`AudioProPlaybackSpeedChangedPayload`

`AudioProQueueChangedPayload`

Callback Types

`AudioProEventCallback`

`AudioProAmbientEventCallback`

Ambient Audio Types

`AmbientAudioPlayOptions`

`AudioProAmbientEvent`

`AudioProAmbientErrorPayload`

Equalizer Types

`AudioProEqualizerBand`

`AudioProEqualizerPreset`