API Reference

class YuKumo {
  constructor(options: ManagerOptions);

  // Lifecycle
  init(): Promise<void>;
  destroy(): Promise<void>;

  // Search
  search(query: string | SearchOptions, source?: string): Promise<SearchResult>;
  lavaSearch(query: string, types?: LavaSearchType[], nodeName?: string): Promise<LavaSearchResult>;
  getLyrics(encodedTrack: string, nodeName?: string): Promise<any>;

  // Player management
  createPlayer(options: YuKumoPlayerCreateOptions): Promise<Player>;
  getPlayer(guildId: string): Player | undefined;
  getPlayers(): Player[];
  hasPlayer(guildId: string): boolean;
  destroyPlayer(guildId: string): Promise<boolean>;

  // Playback
  play(guildId: string, track: TrackData): Promise<void>;
  pause(guildId: string): Promise<void>;
  resume(guildId: string): Promise<void>;
  stop(guildId: string): Promise<void>;
  skip(guildId: string): Promise<TrackData | null>;
  setVolume(guildId: string, volume: number): Promise<void>;

  // Voice
  handleVoiceStateUpdate(data: VoiceStateUpdate): Promise<void>;
  handleVoiceServerUpdate(guildId: string, data: VoiceServerUpdate): Promise<void>;

  // Nodes
  getNode(id: string): Node | undefined;
  getNodes(): Node[];

  // Events
  on<E extends EventName>(event: E, callback: EventCallback<E>): this;

  // Subsystems (public for advanced use)
  readonly nodes: NodeManager;
  readonly players: PlayerManager;
  readonly plugins: PluginManager;
  readonly events: EventDispatcher;
  readonly storage: StorageAdapter;
  readonly voice: VoiceStateTracker;
}

import { RoundRobinSelector, RegionSelector, CustomSelector } from "yukumo";

client.nodes.setSelector(new RoundRobinSelector());

// Region-aware with fallback
client.nodes.setSelector(new RegionSelector("eu", new LeastPenaltySelector()));

// Custom function
client.nodes.setSelector(new CustomSelector((nodes, guildId) => {
  return nodes.find(n => n.state === "connected") ?? null;
}));

const queue = new Queue<TrackData>();
queue.enqueue(track1);
queue.enqueue(track2, 0);
queue.setRepeatMode("queue");
queue.shuffle();
queue.start();

let track;
while ((track = queue.next()) !== null) {
  // process track
}

interface TrackData {
  encoded: string;
  info: TrackInfo;
  pluginInfo: Record<string, unknown>;
  userData?: Record<string, unknown>;
}

interface TrackInfo {
  identifier: string;
  isSeekable: boolean;
  author: string;
  length: number;
  isStream: boolean;
  position: number;
  title: string;
  uri: string | null;
  artworkUrl: string | null;
  isrc: string | null;
  sourceName: string;
}

import { Track } from "yukumo";

// Build + play a track with no server round-trip
const track = Track.build({ title: "My Local Song", author: "Me" });
await player.play(track);

// Encode / decode
const encoded = Track.encode({ title: "Song", author: "Artist", length: 214_000, ... });
const info = Track.decode(encoded);

interface SearchResult {
  loadType: "track" | "playlist" | "search" | "empty" | "error";
  tracks: TrackData[];
  playlistInfo?: { name: string; selectedTrack: number };
  exception?: { message: string; severity: "common" | "suspicious" | "fault" };
}

interface SearchOptions {
  query: string;
  source?: string;
  nodeName?: string;
  requester?: unknown; // stamped onto every returned track's userData (cache hits included)
}

const result = await kumo.search({ query: "lofi", requester: { id: "user-1" } });
result.tracks[0]?.userData?.requester; // { id: "user-1" }

await player.setFilters({ equalizer: [{ band: 0, gain: 0.5 }] });

import { FilterChain, EqualizerFilter, TimescaleFilter } from "yukumo";

const chain = new FilterChain();
chain
  .add(new EqualizerFilter().setBand(0, 0.4))
  .add(new TimescaleFilter().setSpeed(1.25));

player.filters.add(new EqualizerFilter().setBand(0, 0.5));

// Apply bass boost
player.filters.setBassBoost("high");

// Enable nightcore
player.filters.setNightcore();

// Disable a preset
player.filters.setNightcore(false);

// Route audio to mono / left / right, back to stereo to reset
player.filters.setAudioOutput("mono");
player.filters.setAudioOutput("stereo");

interface VoiceStateUpdate {
  guildId: string;
  sessionId: string;
  channelId: string | null;
  userId?: string;
}

interface VoiceServerUpdate {
  token: string;
  endpoint: string | null;
}

interface StorageAdapter {
  get(key: string): Promise<unknown | null>;
  set(key: string, value: unknown): Promise<void>;
  delete(key: string): Promise<boolean>;
  has(key: string): Promise<boolean>;
  clear(): Promise<void>;
}

import { RedisStorage } from "yukumo";

const yukumo = new YuKumo({
  nodes: [...],
  storageAdapter: new RedisStorage({ url: "redis://localhost:6379" }),
});

interface Logger {
  debug(message: string, ...args: unknown[]): void;
  info(message: string, ...args: unknown[]): void;
  warn(message: string, ...args: unknown[]): void;
  error(message: string, ...args: unknown[]): void;
}

type LogLevel = "debug" | "info" | "warn" | "error" | "silent";

import { YuKumo, ConsoleLogger, levelFilteredLogger } from "yukumo";

const yukumo = new YuKumo({
  nodes: [...],
  logger: levelFilteredLogger(new ConsoleLogger(), "info"),
});

interface CacheOptions {
  /** Maximum number of entries to keep in cache (default: 100) */
  maxSize?: number;
  /** Time to live in milliseconds (default: 3600000 / 1 hour) */
  ttl?: number;
}

class SearchCache {
  constructor(options?: CacheOptions);
  get<T extends SearchResult | LavaSearchResult>(key: string): T | null;
  set(key: string, data: SearchResult | LavaSearchResult): void;
  clear(): void;
}

import { SearchCache } from "yukumo";

const cache = new SearchCache({ maxSize: 500, ttl: 1800000 }); // 30 mins

import { parseDuration } from "yukumo";

parseDuration("3:32");    // 212000
parseDuration("1:02:03"); // 3723000
parseDuration("90");      // 90000
parseDuration(90);        // 90000

import { encodeTrackInfo, decodeTrackInfo } from "yukumo";

const encoded = encodeTrackInfo(trackInfo); // Lavalink v4 base64 string
const info = decodeTrackInfo(encoded);      // TrackInfo

import { YuKumo, DiscordJSAdapter } from "yukumo";
import { Client } from "discord.js";

const discordClient = new Client({ intents: [...] });
const yukumo = new YuKumo({ nodes: [...] });

// Adapter handles voice state forwarding automatically
const adapter = new DiscordJSAdapter(discordClient, yukumo);

// Connect to voice via the adapter
adapter.sendVoiceStateUpdate(guildId, voiceChannelId);

import { RawGatewayAdapter } from "yukumo";

const adapter = new RawGatewayAdapter(yukumo);

// Forward raw gateway payloads manually
adapter.handleRawVoiceStateUpdate(rawPayload);
adapter.handleRawVoiceServerUpdate(rawPayload);

interface Plugin {
  name: string;
  version: string;
  init?(): void | Promise<void>;
  start?(): void | Promise<void>;
  destroy?(): void | Promise<void>;
}

import { RestError, PlayerNotConnectedError } from "yukumo";

try {
  await yukumo.play("guildId", track);
} catch (error) {
  if (error instanceof RestError) {
    console.error(`HTTP ${error.statusCode}: ${error.message}`);
  }
  if (error instanceof PlayerNotConnectedError) {
    console.error("Player not connected");
  }
}

import { DestroyReasons } from "yukumo";
// QueueEmpty · NodeDestroy · NodeDeleted · LavalinkNoVoice · NodeReconnectFail
// Disconnected · PlayerReconnectFail · ChannelDeleted · DisconnectAllNodes
// TrackErrorMaxTracksErroredPerTime · TrackStuckMaxTracksErroredPerTime
// EmptyVoiceChannel · ManualDestroy