Events & Packet Forwarding

This guide covers event wiring and the production checklist to ensure clean state during playback and reconnects.

Listening to Events

Subscribe to manager events using EventNames constants. Key events include node readiness, player creation, and queue completion.

import { EventNames, Hoshimi } from 'hoshimi';

declare const manager: Hoshimi;

manager.on(EventNames.NodeReady, (node, retries) => {
  console.log(`Node ${node.id} ready (retry #${retries})`);
});

manager.on(EventNames.PlayerCreate, (player) => {
  console.log(`Player created for guild ${player.guildId}`);
});

manager.on(EventNames.QueueEnd, (player) => {
  console.log(`Queue ended for guild ${player.guildId}`);
});

manager.on(EventNames.PlayerDestroy, (player) => {
  console.log(`Player destroyed for guild ${player.guildId}`);
});

Debug Output

Every internal step emits a debug event tagged with the subsystem it came from, which is the fastest way to see what Hoshimi is doing with the wire without attaching a debugger.

import { DebugLevels, EventNames, Hoshimi } from 'hoshimi';

declare const manager: Hoshimi;

manager.on(EventNames.Debug, (level, message) => {
  if (level === DebugLevels.Rest) return; // noisy: one line per request

  console.debug(DebugLevels[level], message);
});

Levels are Manager, Node, Player, Rest, Queue and Test. Node passwords are censored in the messages, so debug output is safe to log.

Production Checklist

Ensure consistent state across your application:

• Initialization: Call manager.init(botUser) once after bot ready event.
• Packet forwarding: Forward all raw voice packets to manager.updateVoiceState() (see Setup & Integration).
• Session persistence: On PlayerUpdate events, save relevant player state (current track, position, loop mode, volume).
• Cleanup: On QueueEnd and PlayerDestroy, clear transient storage (message IDs, lyrics subscriptions, feature flags).