Introduction

Hoshimi is a TypeScript-first Lavalink v4 client focused on clean architecture, strict typing and practical extension points.

Why Hoshimi?

• Type-safe Lavalink client with comprehensive typings and type guards.
• Clear separation between manager, node, player, queue and storage.
• Ready for custom structures and adapter-based persistence.

Install

pnpm add hoshimi

Quick Setup

import { Hoshimi } from 'hoshimi';

const hoshimi = new Hoshimi({
  nodes: [
    {
      host: 'localhost',
      port: 2333,
      password: 'youshallnotpass',
    },
  ],
  sendPayload(guildId, payload) {
    // Forward payload to your gateway implementation.
    return gatewaySend(guildId, payload);
  },
});

Documentation Map

• Quick Start: minimal setup and first playback flow.
• Bot Integration: how to wire gateway payloads and player creation.
• Events and Gateway: event model and voice packet forwarding.
• Player Lifecycle: play, pause, skip, seek and loop behavior.
• Search and Sources: search patterns and source selection strategy.
• Source Registry: custom source registration and identifier building.
• Tracks and Resolution: resolved/unresolved track handling and type guards.
• Node Operations: node selection, health and decode/search operations.
• Queue and Storage: queue workflows and persistence adapters.
• Filters and Lyrics: audio filter chains and lyrics subscription lifecycle.
• Custom Structures: overriding built-in structures safely.
• Structure Types: inferred structure aliases and extension-safe typing.
• Errors and Recovery: expected runtime failures and recovery patterns.
• Core API (TypeDoc): complete generated API reference for classes, types and members.