Introduction
A typed Lavalink v4 client for modern music bots.
Hoshimi is a TypeScript-first Lavalink v4 client built with strict typing, clean architecture, and extensibility in mind — easy to use and always up to date.
New to Lavalink?
Lavalink is a standalone audio-sending node. Hoshimi talks to it over REST and WebSocket and hands you a fully typed API, so you build music bots without touching the wire protocol yourself.
Why Hoshimi?
Type-safe
Comprehensive typings and type guards catch mistakes before they ship — not at runtime. Even filter payloads are checked per filter.
Modular
Nodes, players, queues and storage are separate concerns you can override safely.
Batteries included
Autoplay (YouTube & Spotify), live lyrics, audio filters and session resumption out of the box.
Extensible
Sources, plugins and filters are registries: add your own, or send a fork's filter with no registration at all.
Install
pnpm add hoshimiHoshimi runs on Node.js 22+, Bun 1.3+, or Deno 2.5+ (unstable).
First steps
Create the manager with your node list and a sendPayload function that forwards
voice updates through your Discord gateway connection.
import { } from 'hoshimi';
const = new ({
: [
{
: 'localhost',
: 2333,
: 'youshallnotpass',
},
],
(, ) {
return (, );
},
});Where to go next
Setup & Integration
Wire Hoshimi into your bot's lifecycle and forward voice packets.
Player Lifecycle
Search, queue, play, pause, skip, seek and tear down players.
Filters
Presets, plugin filters, and anything your fork exposes — typed per filter.
API Reference
Every public class, function, interface and type — generated from source.