Audio Player API

The audioPlayer namespace provides playback commands, queue operations, state queries, and player event subscriptions.

Interface

interface AudioPlayerApi {
  setup(options?: SetupOptions): Promise<void>;
  add(options: AddOptions): Promise<PlaybackSnapshot>;
  remove(options: RemoveOptions): Promise<PlaybackSnapshot>;
  reset(): Promise<PlaybackSnapshot>;
  play(): Promise<void>;
  pause(): Promise<void>;
  stop(): Promise<void>;
  seekTo(options: SeekToOptions): Promise<void>;
  skipTo(options: SkipToOptions): Promise<PlaybackSnapshot>;
  skipToNext(): Promise<void>;
  skipToPrevious(): Promise<void>;
  getState(): Promise<PlaybackState>;
  getPosition(): Promise<number>;
  getDuration(): Promise<number | null>;
  getCurrentTrack(): Promise<Track | null>;
  getQueue(): Promise<QueueSnapshot>;
  getSnapshot(): Promise<PlaybackSnapshot>;
  getCapabilities(): Promise<BindingCapabilitiesSnapshot>;
  addListener<E extends AudioPlayerEventName>(
    eventName: E,
    listener: AudioPlayerListener<E>
  ): Promise<BindingListenerHandle>;
  removeAllListeners(): Promise<void>;
}

Methods

`setup(options?)`

Initializes the native plugin. MUST be called before any other playback operations.

await audioPlayer.setup({
  headerGroups: [
    {
      id: 'premium-us',
      headers: { Authorization: 'Bearer shared-token' },
    },
  ],
});

options is optional. If omitted, setup runs without shared header-group registration.

Parameters:

Parameter	Type	Required	Description
`headerGroups`	`HeaderGroup[]`	No	Setup-scoped shared static headers referenced later by `Track.headerGroupId`.

Returns: Promise<void>

`add(options)`

Appends tracks to the playback queue.

const snapshot = await audioPlayer.add({
  tracks: [
    { id: 'track-1', url: 'https://example.com/audio-1.mp3', title: 'Track One' },
    { id: 'track-2', url: 'https://example.com/audio-2.mp3', title: 'Track Two' },
  ],
  startIndex: 0, // optional: position to activate after insertion
});

Parameters:

Parameter	Type	Required	Description
`tracks`	`Track[]`	Yes	Tracks to append in insertion order.
`startIndex`	`number`	No	Queue index to activate after insertion.

Returns: Promise<PlaybackSnapshot>

`remove(options)`

Removes queue entries by ID or index.

// Remove by track ID
await audioPlayer.remove({ id: 'track-1' });

// Remove by index
await audioPlayer.remove({ index: 0 });

Parameters:

Parameter	Type	Required	Description
`id`	`string`	No	Track identifier to remove.
`index`	`number`	No	Queue index to remove.

Returns: Promise<PlaybackSnapshot>

`reset()`

Clears the queue and stops playback.

await audioPlayer.reset();

Returns: Promise<PlaybackSnapshot>

`play()`

Starts or resumes playback.

await audioPlayer.play();

Returns: Promise<void>

`pause()`

Pauses playback.

await audioPlayer.pause();

Returns: Promise<void>

`stop()`

Stops playback and resets position.

await audioPlayer.stop();

Returns: Promise<void>

`seekTo(options)`

Seeks to a specific position.

await audioPlayer.seekTo({ position: 30.5 }); // 30.5 seconds

Parameters:

Parameter	Type	Required	Description
`position`	`number`	Yes	Target playback position in seconds.

Returns: Promise<void>

`skipTo(options)`

Skips to a specific queue index.

const snapshot = await audioPlayer.skipTo({ index: 2 });

Parameters:

Parameter	Type	Required	Description
`index`	`number`	Yes	Queue index to activate.

Returns: Promise<PlaybackSnapshot>

`skipToNext()`

Skips to the next track in the queue.

await audioPlayer.skipToNext();

Returns: Promise<void>

`skipToPrevious()`

Skips to the previous track in the queue.

await audioPlayer.skipToPrevious();

Returns: Promise<void>

`getState()`

Queries the current playback state.

const state = await audioPlayer.getState();
// 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'buffering' | 'ended' | 'error'

Returns: Promise<PlaybackState>

`getPosition()`

Queries the current playback position in seconds.

const position = await audioPlayer.getPosition();

Returns: Promise<number>

`getDuration()`

Queries the current track duration.

const duration = await audioPlayer.getDuration();
// number | null (null for live/unknown duration)

Returns: Promise<number | null>

`getCurrentTrack()`

Queries the active track.

const track = await audioPlayer.getCurrentTrack();

Returns: Promise<Track | null>

`getQueue()`

Queries the current queue state.

const queue = await audioPlayer.getQueue();

Returns: Promise<QueueSnapshot>

`getSnapshot()`

Queries the complete playback state.

const snapshot = await audioPlayer.getSnapshot();

Returns: Promise<PlaybackSnapshot>

`getCapabilities()`

Queries runtime-supported capabilities.

const caps = await audioPlayer.getCapabilities();
// { supported: ['play', 'pause', 'stop', 'seek', 'skip-next', 'skip-previous'] }

Returns: Promise<BindingCapabilitiesSnapshot>

`addListener(eventName, listener)`

Registers a listener for player lifecycle events.

const handle = await audioPlayer.addListener('playback-state-changed', (payload) => {
  console.log('State changed:', payload.state);
});

// Remove listener when done
await handle.remove();

Parameters:

Parameter	Type	Required	Description
`eventName`	`AudioPlayerEventName`	Yes	Event to subscribe to.
`listener`	`AudioPlayerListener<E>`	Yes	Callback with typed payload.

Returns: Promise<BindingListenerHandle>

`removeAllListeners()`

Removes all registered player listeners.

await audioPlayer.removeAllListeners();

Returns: Promise<void>

Type definitions

`AddOptions`

interface AddOptions {
  tracks: Track[];
  startIndex?: number;
}

`SetupOptions`

interface SetupOptions {
  headerGroups?: HeaderGroup[];
}

`HeaderGroup`

interface HeaderGroup {
  id: string;
  headers: Record<string, string>;
}

`RemoveOptions`

interface RemoveOptions {
  id?: string;
  index?: number;
}

`SeekToOptions`

interface SeekToOptions {
  position: number;
}

`SkipToOptions`

interface SkipToOptions {
  index: number;
}

`BindingCapabilitiesSnapshot`

interface BindingCapabilitiesSnapshot {
  supported: Capability[];
}

`BindingListenerHandle`

interface BindingListenerHandle {
  remove(): Promise<void> | void;
}