kazagumo

library3.4.3jsnpmunverified

A Shoukaku wrapper for Lavalink with built-in queue support. Current stable version: 3.4.3. Active development, monthly releases. Differentiators: integrates Shoukaku's voice handling with a robust track queue, supports multiple players, and exposes a simple event-driven API for Discord music bots. Alternative to erela.js or Magma, but built specifically for Shoukaku/Lavalink v4.

messaging

npm install kazagumo

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KAZAGUMO

kazagumo

messagingjavascriptv3.4.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Kazagumo

✓ import { Kazagumo } from 'kazagumo'

✗ const Kazagumo = require('kazagumo').default

Default export is named Kazagumo in v3+. Use named import.

KazagumoPlayer

✓ import { KazagumoPlayer } from 'kazagumo'

✗ import { Player } from 'kazagumo'

Player class is exported as KazagumoPlayer to avoid naming conflicts.

KazagumoQueue

✓ import { KazagumoQueue } from 'kazagumo'

✗ import { Queue } from 'kazagumo'

Queue class is exported as KazagumoQueue.

Initializes Kazagumo with Shoukaku connectors, connects to Lavalink, and plays a track.

import { Kazagumo } from 'kazagumo'; import { Connectors } from 'shoukaku'; const kazagumo = new Kazagumo({ plugins: [], defaultSearchEngine: 'youtube', enableClustering: false, shoukakuOptions: { nodeResolver: (nodes) => nodes.first(), reconnectTries: 5, restTimeout: 10000, }, }, new Connectors.DiscordJS(client), [ { name: 'Node1', url: 'localhost:2333', auth: process.env.LAVALINK_PASSWORD ?? '' }, ]); kazagumo.on('playerCreate', (player) => { console.log('Player created:', player.guildId); }); await kazagumo.connect(); const player = kazagumo.createPlayer({ guildId: '123', voiceId: '456' }); const result = await kazagumo.search('Never Gonna Give You Up', { requester: 'user' }); if (result.tracks.length) player.queue.add(result.tracks[0]);

Debug

Known issues

breakingKazagumo v3 requires Shoukaku v4 and Lavalink v4. Upgrading from v2 will break calls to player.play() and search() return shape.

fix

Update to Shoukaku v4 and adjust for Lavalink v4 API changes.

affects: >=3.0.0 <3.0.0

deprecatedThe 'useLibrary' method has been deprecated in favor of a new plugin system added in v3.2.0.

fix

Replace 'useLibrary' calls with plugin registration via the 'plugins' array in constructor.

affects: >=3.2.0

gotchaKazagumo is ESM-only, cannot be required with require(). If using CommonJS, use dynamic import.

fix

Use `const { Kazagumo } = await import('kazagumo');` or set type:"module" in package.json.

affects: >=3.0.0

breakingThe 'player.on' events have new argument signatures in v3. For example, 'trackEnd' now provides reason object.

fix

Listen to 'trackEnd' with (player, track, reason) instead of (player, track).

affects: >=3.0.0

deprecatedThe method 'player.play()' now accepts an options object rather than multiple parameters.

fix

Use `player.play({ track: track, startTime: 0, endTime: 0 });`.

affects: >=3.0.0

Errors

Common errors & fixes

Cannot find module 'kazagumo'

Package not installed or ESM-only and used with require()

fix

Run npm install kazagumo. If using CommonJS, use dynamic import: const { Kazagumo } = await import('kazagumo');

TypeError: kazagumo.createPlayer is not a function

Using incorrect import or kazagumo not initialized with connectors

fix

Ensure you import { Kazagumo } from 'kazagumo' and pass a valid connector instance (e.g., new Connectors.DiscordJS(client)) as the second constructor argument.

Lavalink node connection failed: Error: connect ECONNREFUSED

Lavalink server not running or wrong URL/auth

fix

Check Lavalink server is online and the node options (url, auth) are correct in the array passed to Kazagumo constructor.

Property 'queue' does not exist on type 'KazagumoPlayer'

Player object not fully initialized or using TypeScript without latest types

fix

Install kazagumo@latest and ensure your player was created via kazagumo.createPlayer(). Access queue after player emits 'playerCreate'.

Upgrade

Version history

3.4.3latest on npm

Audit

Dependencies

shoukakuoptionalPeer dependency for Lavalink voice connections

discord.jsoptionalOptional peer for Discord bot integration

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Takiyo0/Kazagumo ↗

packagekazagumo ↗

homepagehttps://takiyo0.github.io/Kazagumo ↗