@persian-caesar/discord-player NPM

discord-player

Discord music player.

Introduction

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.ts implementation that extends EventEmitter and emits fixed, well-typed events
A src/types.ts file defining MusicPlayerEvent (as an enum), the payload interfaces for each event, and a TypedEmitter interface for full type-safety

You can install, import, and start listening to player events in seconds, without touching raw channel messaging.

Installation

npm install --save @persian-caesar/discord-player

Note: 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-downloader ffmpeg-static @discordjs/opus libsodium-wrappers

Quick Start (TypeScript)

import { 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, 50, {
  autoLeaveOnEmptyQueue: true,
  autoLeaveOnIdleMs: 300_000,
});

// Listen for events
player.on(MusicPlayerEvent.Start, ({ url, history, metadata }) => {
  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");

Quick Start (JavaScript)

// @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, 50, {
  autoLeaveOnEmptyQueue: true,
  autoLeaveOnIdleMs: 300_000,
});

player.on(MusicPlayerEvent.Start, ({ url, history, metadata }) => {
  console.log("▶️ Now playing:", url);
});

player.play("https://youtu.be/dQw4w9WgXcQ");

API Reference

`class MusicPlayer`

Constructor

new MusicPlayer(
  channel: VoiceChannel,
  initialVolume?: number,        // default: 100 => 100%
  options?: MusicPlayerOptions,  // { autoLeaveOnEmptyQueue?: boolean, autoLeaveOnIdleMs?: number }
)

autoLeaveOnEmptyQueue (default true): automatically disconnect when queue ends
autoLeaveOnIdleMs (default 5 * 60_000 ms): time before auto-disconnect on idle

Methods

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

`enum MusicPlayerEvent`

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[]; metadata: TrackMetadata; }
QueueAdd      → { url: string; queue: TrackMetadata[] }
Pause/Resume  → no payload
VolumeChange  → { volume: number }
Skip/Previous → { history: string[] }
Shuffle       → { queue: TrackMetadata[] }
LoopQueue/Track → { enabled: boolean }
Finish        → { history: string[] }
Disconnect    → no payload
Error         → Error instance

For full payload definitions, see src/types.ts.