Playback

Control audio transport, read playback state, and react to playback changes.

Playback API for plugins

The Playback API controls audio states: play, pause, stop, seek, and subscribe to state changes. It doesn't handle track navigation, use the Queue API for that.

Access playback via api.Playback.* in your plugin's lifecycle hooks. All methods are asynchronous and return Promises.

---

Core concepts

Playback state

Playback state is exposed through a single object:

type PlaybackState = {
  status: PlaybackStatus;
  seek: number;      // Current position in seconds
  duration: number;  // Total duration in seconds
};

type PlaybackStatus = 'playing' | 'paused' | 'stopped';

seek and duration are always in seconds, not milliseconds.

Playback vs. Queue

These two domains divide playback responsibilities:

Domain	Responsibility
Playback	Audio transport: play, pause, stop, seek
Queue	Track navigation: next, previous, shuffle, repeat

---

Usage

Reading state

import type { NuclearPluginAPI } from '@nuclearplayer/plugin-sdk';

export default {
  async onEnable(api: NuclearPluginAPI) {
    const state = await api.Playback.getState();
    api.Logger.info(`Status: ${state.status}`);
    api.Logger.info(`Position: ${state.seek}s / ${state.duration}s`);
  },
};

Transport controls

Seeking

Subscribing

subscribe fires frequently during playback as the seek position updates. Keep your listener lightweight to avoid blocking the UI thread.

---

Reference

// State
api.Playback.getState(): Promise<PlaybackState>

// Transport
api.Playback.play(): Promise<void>
api.Playback.pause(): Promise<void>
api.Playback.stop(): Promise<void>
api.Playback.toggle(): Promise<void>

// Seeking
api.Playback.seekTo(seconds: number): Promise<void>

// Subscriptions
api.Playback.subscribe(listener: PlaybackListener): () => void

Types

type PlaybackStatus = 'playing' | 'paused' | 'stopped';

type PlaybackState = {
  status: PlaybackStatus;
  seek: number;      // Seconds
  duration: number;  // Seconds
};

type PlaybackListener = (state: PlaybackState) => void;