Overview

Navigation methods read and move the queue cursor. Moving the cursor triggers load() on the newly-selected item (unless the player is idle or disposed). A monotonic _currentEpoch guard prevents in-flight loads from overwriting a newer navigation.

item(target?, opts?)

Read or write the active queue cursor.

Read: item() returns the active playlist item, or undefined when the queue is empty.

Write: item(target, opts?) moves the cursor to target. target may be:

• A BasePlaylistItem reference
• An item id (string or number)
• A zero-based index number
• A predicate function (item) => boolean

Fires beforeMutation (cancellable). Emits the current event when the cursor moves. Calls load() on the selected item (deferred to after ready() when called during setup). If opts.autoplay is true, play() is called after load resolves.

Events emitted: current with { item, index }

import type {
  ActionOptions,
  BaseEventMap,
  BasePlaylistItem,
  IPlayer,
  WithCurrentItem,
} from '@nomercy-entertainment/nomercy-player-core';

// item() getter lives on WithCurrentItem.
// The setter overload is on concrete players (NMVideoPlayer, NMMusicPlayer).
// Intersect both here so the example compiles against the kit surface.
type PlayerWithItemCursor<T extends BasePlaylistItem = BasePlaylistItem> =
  IPlayer<BaseEventMap>
  & WithCurrentItem<T>
  & { item(target: T | string | number | ((item: T) => boolean), opts?: ActionOptions): void };

declare const player: PlayerWithItemCursor<BasePlaylistItem>;

// move by id
player.item('sintel');

// move by index
player.item(2);

// move by predicate
player.item((item) => item.title === 'Tears of Steel');

// move and autoplay
player.item(0, { autoplay: true });

index()

Return the zero-based index of the currently active item, or -1 when the queue is empty.

Returns: number

seekToIndex(position, opts?)

Navigate to a playlist item by 1-based ordinal position. seekToIndex(1) loads the first item; seekToIndex(queueLength()) loads the last.

Out-of-range values are silently ignored. Fires beforeMutation / current lifecycle (same as item(target)).

Throws: RangeError when position is not a positive integer.

// jump to track 3
player.seekToIndex(3);

next(opts?) / previous(opts?)

See Transport, next and previous for the full method spec including repeat-mode behaviour. These are listed here because they move the cursor and load the adjacent item.

peekNext() / peekPrevious()

Read-only look-ahead without cursor mutation. See Queue Methods, peekNext and peekPrevious.

See also

• Queue Methods, queue, queueAppend, queueClear
• Transport, next, previous, and repeat mode
• Events Reference, current, queue:exhausted