discord-player 1.0.0
Install from the command line:
Learn more about npm packages
$ npm install @persian-caesar/discord-player@1.0.0
Install via package.json:
"@persian-caesar/discord-player": "1.0.0"
About this version
Discord music player.
This repository provides a fully-typed MusicPlayer class for Discord self-bots, along with a strongly-typed event system using an enum. You get:
- A single
MusicPlayer.tsimplementation that extendsEventEmitterand emits fixed, well-typed events - A
src/types.tsfile definingMusicPlayerEvent(as anenum), the payload interfaces for each event, and aTypedEmitterinterface for full type-safety
You can install, import, and start listening to player events in seconds, without touching raw channel messaging.
npm install --save @persian-caesar/discord-playerNote: This package provides the player and its types. You still need to install the actual playback libraries as peer dependencies:
npm install @discordjs/voice ytdl-core-discord ytdl-core play-dl @distube/ytdl-core soundcloud-downloaderimport { MusicPlayer, MusicPlayerEvent } from "@persian-caesar/discord-player";
import type { VoiceChannel } from "@persian-caesar/discord-player";
// Assume you already have a VoiceChannel object:
const voiceChannel: VoiceChannel = /* your voice channel instance */;
const player = new MusicPlayer(voiceChannel, 0.5, {
autoLeaveOnEmptyQueue: true,
autoLeaveOnIdleMs: 300_000,
});
// Listen for events
player.on(MusicPlayerEvent.Start, ({ url, history }) => {
console.log(`▶️ Now playing: ${url}`);
});
player.on(MusicPlayerEvent.QueueAdd, ({ url, queue }) => {
console.log(`➕ Added to queue: ${url} (queue length: ${queue.length})`);
});
player.on(MusicPlayerEvent.Finish, ({ history }) => {
console.log("⏹️ Playback finished.");
});
player.on(MusicPlayerEvent.Error, (error) => {
console.error("❌ Player error:", error.message);
});
// Start playing
await player.play("https://youtu.be/dQw4w9WgXcQ");// @persian-caesar/discord-player ships with JSDoc types, so plain JS works too:
const { MusicPlayer, MusicPlayerEvent } = require("@persian-caesar/discord-player");
/**
* @type {import("@persian-caesar/discord-player").VoiceChannel}
*/
const voiceChannel = /* your voice channel instance */;
const player = new MusicPlayer(voiceChannel, 0.5, {
autoLeaveOnEmptyQueue: true,
autoLeaveOnIdleMs: 300000,
});
player.on(MusicPlayerEvent.Start, ({ url, history }) => {
console.log("▶️ Now playing:", url);
});
player.play("https://youtu.be/dQw4w9WgXcQ");new MusicPlayer(
channel: VoiceChannel,
initialVolume?: number, // default: 0.5
options?: MusicPlayerOptions, // { autoLeaveOnEmptyQueue?: boolean, autoLeaveOnIdleMs?: number }
)-
autoLeaveOnEmptyQueue(defaulttrue): automatically disconnect when queue ends -
autoLeaveOnIdleMs(default300_000ms): time before auto-disconnect on idle
| Method | Description |
|---|---|
play(input: string) |
Search & play or enqueue a track |
pause() |
Pause playback |
resume() |
Resume playback |
setVolume(percent: number) |
Set volume (0–200%) |
skip() |
Skip current track |
previous() |
Go back to previous track |
shuffle() |
Shuffle the queue |
toggleLoopQueue() |
Toggle queue repeat |
toggleLoopTrack() |
Toggle single-track repeat |
stop(disconnect?: boolean) |
Stop playback (and optionally disconnect) |
disconnect() |
Force disconnect immediately |
getQueue(): string[] |
Get copy of current queue URLs |
getVolume(): number |
Get current volume as percentage |
export enum MusicPlayerEvent {
Start = "start",
QueueAdd = "queueAdd",
Pause = "pause",
Resume = "resume",
Stop = "stop",
Skip = "skip",
Previous = "previous",
Shuffle = "shuffle",
LoopQueue = "loopQueue",
LoopTrack = "loopTrack",
VolumeChange = "volumeChange",
Finish = "finish",
Disconnect = "disconnect",
Error = "error",
}Each event emits a strongly-typed payload:
// examples of payload shapes
Start → { url: string; history: string[] }
QueueAdd → { url: string; queue: string[] }
Pause/Resume → no payload
VolumeChange → { volume: number }
Skip/Previous → { history: string[] }
Shuffle → { queue: string[] }
LoopQueue/Track → { enabled: boolean }
Finish → { history: string[] }
Disconnect → no payload
Error → Error instanceFor full payload definitions, see src/types.ts.
- Repository: https://github.com/Persian-Caesar/discord-player
- Issues: https://github.com/Persian-Caesar/discord-player/issues
- License: MIT
⌨️ Built with ❤️ by Persian-Caesar. Don’t forget to ⭐️ the repo!
