Use when working with Hoshimi TypeScript Lavalink v4 client, player queue management, Seyfert voice integration, or audio filters.
Docs: https://hoshimi-web.vercel.app/docs TypeDoc API: https://hoshimi-web.vercel.app/core-api/index.html GitHub: https://github.com/Ganyu-Studios/Hoshimi npm: https://www.npmjs.com/package/hoshimi
Hoshimi is a TypeScript-first Lavalink v4 client with clean architecture, strict typing, and practical extension points.
| Abstraction | Role |
|---|---|
| Hoshimi (Manager) | Entry point — creates players, searches, manages nodes |
| Node | Represents one Lavalink server instance |
| Player | Per-guild playback controller with an attached queue |
| Queue | Track queue with add/clear/skip/shuffle operations |
| FilterManager | Audio filters: nightcore, karaoke, EQ, volume, etc. |
| LyricsManager | Lyrics fetching and live subscription |
| SourceRegistry | Register and resolve custom search source aliases |
| Structures | Factory for overriding Player, Node, Queue, Track, etc. |
Hoshimi throws typed errors at the appropriate layer: ManagerError, NodeError, PlayerError, RestError, ResolveError, StorageError, OptionError.
bun add hoshimi
| Guide | What it covers |
|---|---|
| Quick Start | Create a manager, init on ready, forward voice packets, search/queue/play flow |
| Bot Integration | createHoshimi, init(), voice packet forwarding, per-guild player lifecycle; createPlayer is idempotent per guild |
| Events and Gateway | NodeReady, PlayerCreate, QueueEnd hooks; production checklist — forward all voice packets, persist session state, clean up on QueueEnd/PlayerDestroy |
| Player Lifecycle | Create/reuse players, search and play, runtime controls (pause/seek/skip/volume/loop), disconnect() vs destroy() |
| Guide | What it covers |
|---|---|
| Search and Sources | manager.search() vs player.search(), SearchOptions, SearchSources, LoadType branching (Track / Search / Playlist / Empty / Error) |
| Source Registry | SourceRegistry.register(), resolve(), isRegistered(), createIdentifier(); register custom source aliases at bootstrap |
| Tracks and Resolution | Track (resolved) vs UnresolvedTrack (title/author only); isResolved() / isUnresolved() type guards; mixed queue inputs |
| Node Operations | nodeManager.getLeastUsed() for load balancing, node.decode.single/multiple(), node.rest for low-level REST calls |
| Queue and Storage | Queue operations (add, shift, shuffle, clear, current, history); in-memory defaults; custom QueueStorageAdapter pattern (Redis example); what to persist vs what to clear on teardown |
| Filters and Lyrics | Nightcore, karaoke, EQ, volume filters; reset before switching presets; lyrics fetch/subscribe/cleanup pattern; plugin vs dspx filter manager distinction |
| Guide | What it covers |
|---|---|
| Custom Structures | Override Player, Node, Queue, Track, LyricsManager via Structures factory at bootstrap; module augmentation for typed custom properties |
| Structure Types | PlayerStructure, TrackStructure, NodeStructure and other *Structure aliases for type-safe extensions |
| Errors and Recovery | Error class hierarchy; instanceof handling pattern; pre-flight checks (isUseable, voice channel existence, queue.isEmpty()); persist vs clear on teardown |
The TypeDoc reference documents:
State, LoopMode, LoadType, SearchSources, FilterType, TrackEndReason, DestroyReasons, OpCodes, and moreAwaitable, DeepRequired, Nullable, Prettify, *Structure aliases, custom search sources