Queue

Control playback order, manipulate the queue, and react to track changes in Nuclear.

Queue API for Plugins

The Queue API gives plugins full control over Nuclear's playback queue. Add tracks, reorder items, control navigation, and subscribe to queue changes—all from your plugin code.

Access the queue via NuclearAPI.Queue.* in your plugin's lifecycle hooks. All queue operations are asynchronous and return Promises.

---

Core concepts

Queue structure

The queue is a list of items with a pointer to the current playback position:

type Queue = {
  items: QueueItem[];        // Ordered list of tracks
  currentIndex: number;      // Position of currently playing item (0-based)
  repeatMode: RepeatMode;    // 'off' | 'all' | 'one'
  shuffleEnabled: boolean;   // Random navigation when true
};

Queue items

Each item in the queue has its own unique ID and tracks its own state:

type QueueItem = {
  id: string;                // UUID for this queue entry
  track: Track;              // Full track metadata
  
  // Playback state
  status: 'idle' | 'loading' | 'success' | 'error';
  error?: string;            // Error message if status is 'error'
  
  // Metadata
  addedAtIso: string;        // ISO timestamp of when added
};

Status lifecycle:

• idle — Item is in queue but hasn't been played yet

• loading — Stream resolution in progress

• success — Stream resolved and ready for playback

• error — All streams failed or playback error occurred

Repeat modes

type RepeatMode = 'off' | 'all' | 'one';

• off — Stop at the end of the queue

• all — Loop back to the beginning when reaching the end

• one — Repeat the current track (handled by playback service, not queue navigation)

Shuffle

When shuffleEnabled is true, goToNext() and goToPrevious() pick random indices instead of sequential ones. The algorithm avoids repeating the same track twice in a row.

---

Quick start

Reading queue state

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

export default {
  async onEnable(api: NuclearPluginAPI) {
    // Get the full queue
    const queue = await api.Queue.getQueue();
    console.log(`Queue has ${queue.items.length} items`);
    console.log(`Currently at index ${queue.currentIndex}`);
    
    // Get just the current item
    const current = await api.Queue.getCurrentItem();
    if (current) {
      console.log(`Now playing: ${current.track.title}`);
      console.log(`Status: ${current.status}`);
    }
  },
};

Adding tracks

Navigation

Subscribing to changes

---

Reference

// Reading
api.Queue.getQueue(): Promise<Queue>
api.Queue.getCurrentItem(): Promise<QueueItem | undefined>

// Adding tracks
api.Queue.addToQueue(tracks: Track[]): Promise<void>
api.Queue.addNext(tracks: Track[]): Promise<void>
api.Queue.addAt(tracks: Track[], index: number): Promise<void>

// Removing tracks
api.Queue.removeByIds(ids: string[]): Promise<void>
api.Queue.removeByIndices(indices: number[]): Promise<void>
api.Queue.clearQueue(): Promise<void>

// Navigation
api.Queue.goToNext(): Promise<void>
api.Queue.goToPrevious(): Promise<void>
api.Queue.goToIndex(index: number): Promise<void>
api.Queue.goToId(id: string): Promise<void>

// Reordering
api.Queue.reorder(fromIndex: number, toIndex: number): Promise<void>

// Modes
api.Queue.setRepeatMode(mode: RepeatMode): Promise<void>
api.Queue.setShuffleEnabled(enabled: boolean): Promise<void>

// State updates
api.Queue.updateItemState(id: string, updates: QueueItemStateUpdate): Promise<void>

// Subscriptions
api.Queue.subscribe(listener: (queue: Queue) => void): () => void
api.Queue.subscribeToCurrentItem(listener: (item: QueueItem | undefined) => void): () => void

---

Best practices

• Use subscriptions for reactive features — subscribe() for queue-wide changes, subscribeToCurrentItem() for playback tracking

• Batch operations — All add/remove methods accept arrays; use them instead of looping

• Clean up subscriptions — Always unsubscribe in onDisable to prevent memory leaks

• Check queue state before navigation — Use getQueue() to verify bounds before calling goToIndex()

• Respect user intent — Don't manipulate shuffle/repeat modes unless your plugin explicitly manages playback

---

Troubleshooting

Symptom	Cause	Fix
"Queue host not available"	Called before plugin loaded or outside runtime	Move to onLoad/onEnable lifecycle hooks
Added tracks disappear on restart	Not using the API, modifying state directly	Only use api.Queue.* methods, never manipulate queue state directly
goToId() does nothing	ID doesn't exist in queue	Verify ID exists by checking queue.items first