Player context

The context uses Node.js AsyncLocalStorage. It belongs to one Player, so several Players do not share an active queue.

import { useHistory, useMainPlayer, usePlayer, useQueue } from 'discord-player';

await player.context.provide({ guildId }, async () => {
  const mainPlayer = useMainPlayer();
  const node = usePlayer();
  const queue = useQueue();
  const history = useHistory();

  console.log(mainPlayer.options, node?.isPaused(), queue?.currentTrack?.title, history?.size);
});

The context stays available across await inside the callback.

HooksCopy Anchor Link

Every node argument accepts a guild ID, a guild-like object ({ id } or { guildId }), or a GuildQueue instance. Without it, the hook uses the guild or queue supplied to provide().

await player.context.provide({ guildId }, async () => {
  const [getMetadata, setMetadata] = useMetadata<{ locale: string }>();
  const [getVolume, setVolume] = useVolume();

  setMetadata((previous) => ({ ...previous, locale: 'en' }));
  await setVolume((previous) => previous + 10);
});

TimelineCopy Anchor Link

useTimeline() returns a live view of the queue. Reading a property reflects current playback; controlling it awaits Remedia.

const timeline = useTimeline();

if (timeline) {
  console.log(timeline.track?.title, timeline.timestamp?.current.label, timeline.volume, timeline.paused);

  await timeline.pause();
  await timeline.resume();
  await timeline.setVolume(80);
  await timeline.setPosition(30_000);
}

Control methods return Promise<boolean>. pause(), resume(), and setPosition() return false when the queue has no active session or Track. setVolume() resolves after Remedia applies the percentage.

Pass { ignoreFilters: true } to read the source media position instead of Remedia's filtered output clock. Remedia does not expose the duration multiplier of tempo-changing filters, so timestamp.total always reflects the source duration. Pass { node } to target another queue.

const sourceTimeline = useTimeline({ node: guildId, ignoreFilters: true });

Outside a contextCopy Anchor Link

Background jobs have no async context. Pass the guild or queue explicitly:

const queue = useQueue(guildId);
const node = usePlayer({ guildId });
const history = useHistory(queueInstance);

Calling a guild-scoped hook without a context, guild, or node throws IllegalHookInvocationError with code ERR_ILLEGAL_HOOK_INVOCATION. It never guesses a guild.

When a Player is destroyed, the fallback moves to the next active Player.