Discord-Audio-Stream/README.md

Discord Audio Stream

discord-audio-stream is a small TypeScript library for managed Discord voice playback through @discordjs/voice and ffmpeg.

It manages the Discord voice connection, ffmpeg process, raw PCM audio resource, optional renewal, and cleanup. Keep one AudioManager per guild, usually in a Map<string, AudioManager>, and call dispose() when that manager will not be reused.

Support

Create an issue on Gitea or contact fraujulian on Discord.

Installation

Node.js >=24.17.0 and <25 is required.

npm install discord-audio-stream @discordjs/voice @discordjs/opus

Use opusscript@^0.0.8 only as a slower JavaScript fallback when @discordjs/opus cannot be installed.

ffmpeg must be available either on the host PATH or through the optional ffmpeg-static package:

npm install ffmpeg-static

Use ffmpeg.mode: 'native' for PATH-based ffmpeg and ffmpeg.mode: 'static' for ffmpeg-static.

Basic Usage

import { AudioManager } from 'discord-audio-stream';

const manager = new AudioManager({
    connection: {
        guildId: guild.id,
        channelId: voiceChannel.id,
        adapterCreator: guild.voiceAdapterCreator,
    },
    source: {
        type: 'url',
        url: 'https://example.com/live-stream.mp3',
    },
    ffmpeg: {
        mode: 'native',
    },
});

await manager.start();

For a file source:

manager.setSource({
    type: 'file',
    path: 'audio/intro.mp3',
});

await manager.start();

Relative file paths are resolved from process.cwd(). URL sources are validated before playback starts.

For large bots, queue many simultaneous starts so the host does not spawn too many ffmpeg processes in the same tick.

Lifecycle

manager.setConnection(connectionOptions);
manager.setSource(source);

await manager.start(); // connect() + play()
manager.pause();
manager.resume();
await manager.stop(); // stops playback and destroys the voice connection
manager.dispose(); // final cleanup; the manager cannot be reused

connect() joins the configured voice channel. play(source?) starts playback on an existing connection. Use start() when you want both.

For scoped playback, AudioManager supports explicit resource management:

{
    using manager = new AudioManager(options);
    await manager.start();
} // disposed automatically

API

type AudioManagerOptions = {
    ffmpeg?: {
        mode?: 'native' | 'static';
        executablePath?: string;
        inputArgs?: readonly string[];
        outputArgs?: readonly string[];
    };
    connection?: {
        guildId: string;
        channelId: string;
        adapterCreator: DiscordGatewayAdapterCreator;
    };
    source?: { type: 'url'; url: string } | { type: 'file'; path: string };
    renewIntervalMs?: number | false;
    connectTimeoutMs?: number;
    onError?: (error: Error) => void;
    volume?: {
        enabled?: boolean;
        initialPercent?: number;
    };
};

connectTimeoutMs and numeric renewIntervalMs values must be whole milliseconds from 1 through 2_147_483_647. volume.initialPercent must be a finite number from 0 through 100 and requires volume.enabled: true.

Defaults

Option	Default
ffmpeg.mode	'native'
connectTimeoutMs	20_000
renewIntervalMs	false
volume.enabled	false

Methods

Method	Description
setConnection(options)	Sets the target for the next connect() or start() call.
setSource(source)	Sets the source for the next play() or start() call.
connect()	Joins the configured Discord voice channel.
play(source?)	Starts playback on an existing connection.
start()	Connects and starts playback.
pause()	Pauses active playback.
resume()	Resumes paused playback.
stop()	Stops playback, clears renewal, and destroys the voice connection.
setVolume(percent)	Sets volume from 0 to 100; requires volume.enabled: true.
dispose()	Idempotently releases timers, ffmpeg, streams, player state, and voice connection.
[Symbol.dispose]()	Enables automatic cleanup with TypeScript's using declaration.

State

manager.state; // 'idle' | 'connecting' | 'ready' | 'playing' | 'paused' | 'stopped' | 'disposed'
manager.isPlaying;
manager.isConnected;

Audio Options

Inline volume has runtime cost in @discordjs/voice, so it is disabled by default.

const manager = new AudioManager({
    connection,
    source,
    volume: {
        enabled: true,
        initialPercent: 50,
    },
});

await manager.start();
manager.setVolume(25);

Calling setVolume() without volume.enabled: true throws AudioManagerStateError.

Default ffmpeg output is raw Discord-compatible PCM: s16le, 48000 Hz, 2 channels.

You can override ffmpeg arguments through ffmpeg.inputArgs and ffmpeg.outputArgs. When you override them, you are responsible for keeping the output compatible with StreamType.Raw.

Connection renewal is disabled by default because @discordjs/voice handles recoverable disconnects. Set renewIntervalMs only when an application has a measured need for periodic restarts. stop() and dispose() always clear the renewal timer.

Errors

The package exports these error classes:

• AudioManagerError
• AudioManagerConfigError
• AudioManagerStateError
• FfmpegProcessError

Configuration problems, such as a missing source or invalid URL, throw AudioManagerConfigError. Invalid lifecycle operations, such as calling pause() while nothing is playing, throw AudioManagerStateError.

Use onError to observe asynchronous audio player and voice connection errors. The manager cleans up failed playback and unrecoverable connections before invoking the callback.

onError does not handle rejected connect(), play(), or start() calls. Await and catch those calls explicitly.

Development

npm ci
npm run check
npm run build

Contributors

~ FrauJulian - Julian Lechner - CODEOWNER

Enjoy the package?

Give it a star on Gitea!