Hoshimi (BETA)

A lavalink@v4 client easy to use, up-to-date, and of course

📦 Features

• 📋 V4: Works with lavalink v4 and their features (wip).
• 🔗 Node Manager: Manage nodes, auto least‑used selection, session resume and more.
• ▶️ Autoplay: YouTube and Spotify recommendations out of the box; easily extend with your own function.
• 📝 Lyrics: Control your lyrics with live-lyrics updates; validates required plugins.
• 🌐 REST + WebSocket: Typed REST helpers, player/session control, decode single/multiple tracks.
• 📣 Events: Granular events with debug levels.
• 🧩 Extensible: Override structures with your own ones.
• 🧪 Safety & DX: Strict validation, descriptive errors, TypeScript-first API build, and formatting/linting.
• 📜 Filters: Built-in filters, easy management and easy to use!

⚙️ Requirements

• Runtime - atleast one of:
  • Node.js v22+
  • Bun v1.3+
  • Deno v2.5+ (unstable)

📦 Installation

# Stable... and the development one (unstable)...

# Using NPM
npm install hoshimi # Stable
npm install https://github.com/Ganyu-Studios/Hoshimi.git # Development

# Using PNPM
pnpm install hoshimi
pnpm install https://github.com/Ganyu-Studios/Hoshimi.git

# Using YARN
yarn add hoshimi
yarn add https://github.com/Ganyu-Studios/Hoshimi.git

# Using BUN
bun add hoshimi
bun add https://github.com/Ganyu-Studios/Hoshimi.git

📜 Basic Setup

You can read this or you can follow this one:

import { Hoshimi } from "hoshimi"; // She is all ears!
import { Client } from "seyfert"; // Only example client, you can use whatever you want...

const client = new Client(); // https://www.seyfert.dev/guide

const hoshimi = new Hoshimi({
    nodes: [
        {
            host: "localhost",
            port: 2333,
            password: "youshallnotpass",
        },
    ], // Add more nodes if you want!
    sendPayload(guildId, payload) {
        // Your client send to shard payload function
        client.gateway.send(client.gateway.calculateShardId(guildId), payload);
    },
});

// Bind the manager into your client!
client.hoshimi = hoshimi;

// FOLLOW YOUR CLIENT EVENT IMPLEMENTATION
// THIS IS ONLY A EXAMPLE, NOT A REAL USAGE
client.events.values.READY = {
    __filePath: null,
    data: { name: "ready", once: true },
    run(user, client) {
        client.logger.info(`Logged in as ${user.username}`);
        
        // Call the manager to initialize hoshimi
        hoshimi.init({ ...user, username: user.username });
    },
};

client.events.values.RAW = {
    __filePath: null,
    data: { name: "raw" },
    async run(data, client) {
        // Call the handler on the gateway dispatch events
        await hoshimi.updateVoiceState(data);
    },
};

(async () => {
    await client.start();
})();

💖 Used By

• For now, no one is using it :(

📝 Additional Notes

I am currently working on this package.
This package takes some ideas provided from libraries like:

• 📦 lavalink-client
• 📦 kazagumo
• 📦 distube
• 📦 discord-player
• 📦 shoukaku

I'm taking their job as a base for this project, I love their job, all of them, I just took some stuff because i'm too lazy to make my own.
If anyone of them wants to talk to me to remove their stuff, they can.

But made with my code style and my knowledge and of course up-to-date.

📝 License

Copyright © 2025 Ganyu Studios.

This project is MIT licensed.

• The character and assets are not my property, property of miHoYo Co. Ltd. (HoYoverse)

Made with 🐐❤️💪... A project made by the community, for the community.