Skip to content

shipgirlproject/Shoukaku

Repository files navigation

Shoukaku

A stable and updated wrapper around Lavalink

Discord npm Github Stars GitHub issues Snyk Vulnerabilities for npm package NPM

The ShipGirl Project, feat Shoukaku; ⓒ Azur Lane

Features

✅ Stable

✅ Documented

✅ Updated

✅ Extendable

✅ ESM & CommonJS supported

✅ Very cute (Very Important)

Supported Libraries

Refer to /src/connectors for list of supported libraries + how to support other libraries

Installation

npm install shoukaku

Documentation

https://shoukaku.shipgirl.moe/

Small code snippet examples

Initializing the library (Using Connector Discord.JS)

const { Client } = require("discord.js");
const { Shoukaku, Connectors } = require("shoukaku");
const Nodes = [
  {
    name: "Localhost",
    url: "localhost:6969",
    auth: "re_aoharu",
  },
];
const client = new Client();
const shoukaku = new Shoukaku(new Connectors.DiscordJS(client), Nodes);

// Always handle "error" events or your program may crash due to uncaught error
shoukaku.on("error", (_, error) => console.error(error));
client.login("token");

// If you want shoukaku to be available on client, then bind it to it, here is one example of it
client.shoukaku = shoukaku;

Never initialize Shoukaku like this, or else she will never initialize, start shoukaku before you call client.login()

client.on("ready", () => {
  client.shoukaku = new Shoukaku(new Connectors.DiscordJS(client), Nodes);
});

Join a voice channel, search for a track, play the track, then disconnect after the track ends

// create a voice connection and player using Shoukaku#joinVoiceChannel
const player = await shoukaku.joinVoiceChannel({
  guildId: "your_guild_id",
  channelId: "your_channel_id",
  shardId: 0, // if unsharded it will always be zero (depending on your library implementation)
});
// player is created, now search for a track
const result = await player.node.rest.resolve("scsearch:snowhalation");
if (!result?.data.length) return;
const metadata = result.tracks.shift();
// play the searched track
await player.playTrack({ track: { encoded: metadata.encoded } });
// wait for track to end
await once(player, 'end');
// leaver the voice channel
await shoukaku.leaveVoiceChannel(player.guildId);

Playing a track and changing a playback option (in this example, volume)

await player.playTrack({ track: { encoded: metadata.encoded } });
await player.setGlobalVolume(50);

Updating the whole player if you don't want to use my helper functions

await player.update({ ...playerOptions });

Setting a custom get node ideal function

const shoukaku = new Shoukaku(
  new Connectors.DiscordJS(client),
  [{ ...yourNodeOptions }],
  {
    ...yourShoukakuOptions,
    nodeResolver: (nodes, connection) => getYourIdealNode(nodes, connection),
  }
);
const player = await shoukaku.joinVoiceChannel({
  guildId: "your_guild_id",
  channelId: "your_channel_id",
  shardId: 0,
});

A full bot example (that dont use timeout to leave the voice channel) can be found at https://github.com/shipgirlproject/Shoukaku?tab=readme-ov-file#full-bot-implementation-of-shoukaku-in-discordjs

Shoukaku's options

Option Type Default Description Notes
resume boolean false If you want to enable resuming when your connection when your connection to lavalink disconnects
resumeTimeout number 30 Timeout before lavalink destroys the players on a disconnect In seconds
resumeByLibrary boolean false If you want to force resume players no matter what even if it's not resumable by lavalink
reconnectTries number 3 Number of tries to reconnect to lavalink before disconnecting
reconnectInterval number 5 Timeout between reconnects In seconds
restTimeout number 60 Maximum amount of time to wait for rest lavalink api requests In seconds
moveOnDisconnect boolean false Whether to move players to a different lavalink node when a node disconnects
userAgent string (auto) Changes the user-agent used for lavalink requests Not recommeded to change
structures Object{rest?, player?} {} Custom structures for shoukaku to use
voiceConnectionTimeout number 15 Maximum amount of time to wait for a join voice channel command In seconds
nodeResolver function function Custom node resolver if you want to have your own method of getting the ideal node

3rd Party Plugins

Name Link Description
Kazagumo Github A wrapper for Shoukaku that has an internal queue system

Open a PR if you want to add your plugin here

Other Links

Support (#Development) | Lavalink

Full bot implementation of Shoukaku in Discord.JS

Kongou

Made with ❤ by

@ichimakase (Saya)