or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

audio-playback.mdaudio-reception.mddave-encryption.mdindex.mdnetworking.mdutilities.mdvoice-connections.md
tile.json

tessl/npm-discordjs--voice

Implementation of the Discord Voice API for Node.js with comprehensive audio playback, reception, and end-to-end encryption support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@discordjs/voice@0.19.x

To install, run

npx @tessl/cli install tessl/npm-discordjs--voice@0.19.0

index.mddocs/

@discordjs/voice

@discordjs/voice is a comprehensive TypeScript library that provides a robust implementation of the Discord Voice API for Node.js applications. It enables developers to create, manage, and utilize Discord voice connections with features including audio playback, audio reception, real-time communication, and end-to-end encryption support through the DAVE protocol.

Package Information

  • Package Name: @discordjs/voice
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @discordjs/voice
  • Node.js: >=22.12.0
  • License: Apache-2.0

Core Imports

import {
  joinVoiceChannel,
  createAudioPlayer,
  createAudioResource,
  VoiceConnectionStatus,
  AudioPlayerStatus,
  getVoiceConnection
} from "@discordjs/voice";

For CommonJS:

const {
  joinVoiceChannel,
  createAudioPlayer,
  createAudioResource,
  VoiceConnectionStatus,
  AudioPlayerStatus,
  getVoiceConnection
} = require("@discordjs/voice");

Basic Usage

import {
  joinVoiceChannel,
  createAudioPlayer,
  createAudioResource,
  StreamType,
  demuxProbe,
  getVoiceConnection
} from "@discordjs/voice";
import { createReadStream } from "fs";

// Join a voice channel
const connection = joinVoiceChannel({
  channelId: "123456789012345678",
  guildId: "123456789012345678",
  adapterCreator: guild.voiceAdapterCreator,
});

// Create an audio player
const player = createAudioPlayer();

// Create and play an audio resource
const resource = createAudioResource(createReadStream("audio.mp3"), {
  inputType: StreamType.Arbitrary,
});

player.play(resource);

// Subscribe the connection to the player
connection.subscribe(player);

// Handle player events
player.on(AudioPlayerStatus.Playing, () => {
  console.log("The audio player has started playing!");
});

Architecture

@discordjs/voice is built around several key architectural components:

  • Connection Management: VoiceConnection class manages Discord voice gateway connections and WebSocket/UDP communication
  • Audio System: AudioPlayer and AudioResource classes provide high-level audio playback with automatic stream format detection and conversion
  • Network Layer: Low-level networking classes (Networking, VoiceWebSocket, VoiceUDPSocket) handle Discord voice protocol implementation
  • Receiving System: VoiceReceiver and related classes enable receiving and processing audio from other users
  • Encryption Support: DAVESession provides end-to-end encryption using Discord's DAVE protocol
  • Stream Processing: Transformer graph system automatically converts between audio formats (Opus, OGG, WebM, PCM)
  • State Management: Comprehensive state tracking with EventEmitter patterns for monitoring connection and player status

Capabilities

Voice Connection Management

Core functionality for establishing and managing Discord voice connections, including joining channels, handling disconnections, and managing connection state.

function joinVoiceChannel(options: CreateVoiceConnectionOptions & JoinVoiceChannelOptions): VoiceConnection;

function getVoiceConnection(guildId: string, group?: string): VoiceConnection | undefined;

function getVoiceConnections(group?: string): ReadonlyMap<string, VoiceConnection>;

interface CreateVoiceConnectionOptions {
  adapterCreator: DiscordGatewayAdapterCreator;
  daveEncryption?: boolean;
  debug?: boolean;
  decryptionFailureTolerance?: number;
}

interface JoinVoiceChannelOptions {
  channelId: string;
  guildId: string;
  group?: string;
  selfDeaf?: boolean;
  selfMute?: boolean;
}

Voice Connections

Audio Playback System

Comprehensive audio playback functionality with support for multiple audio formats, automatic stream processing, and advanced playback control features.

function createAudioPlayer(options?: CreateAudioPlayerOptions): AudioPlayer;

function createAudioResource<T>(
  input: Readable | string,
  options?: CreateAudioResourceOptions<T>
): AudioResource<T>;

interface CreateAudioPlayerOptions {
  behaviors?: {
    noSubscriber?: NoSubscriberBehavior;
    maxMissedFrames?: number;
  };
  debug?: boolean;
}

enum AudioPlayerStatus {
  Idle = "idle",
  Buffering = "buffering", 
  Playing = "playing",
  Paused = "paused",
  AutoPaused = "autopaused"
}

Audio Playback

Audio Reception

Functionality for receiving and processing audio streams from other users in voice channels, with support for per-user audio streams and speaking state tracking.

interface VoiceReceiver {
  readonly voiceConnection: VoiceConnection;
  readonly ssrcMap: SSRCMap;
  readonly speaking: SpeakingMap;
  readonly subscriptions: Map<string, AudioReceiveStream>;
}

enum EndBehaviorType {
  Manual,
  AfterSilence,
  AfterInactivity
}

interface VoiceUserData {
  audioSSRC: number;
  userId: string;
  videoSSRC?: number;
}

Audio Reception

Low-Level Networking

Direct access to networking components for advanced use cases, including WebSocket and UDP socket management, protocol handling, and connection state control.

class Networking extends EventEmitter {
  constructor(connectionOptions: ConnectionOptions, options: NetworkingOptions);
  destroy(): void;
  prepareAudioPacket(opusPacket: Buffer): Buffer | undefined;
  dispatchAudio(): boolean;
  setSpeaking(speaking: boolean): void;
}

enum NetworkingStatusCode {
  OpeningWs,
  Identifying,  
  UdpHandshaking,
  SelectingProtocol,
  Ready,
  Resuming,
  Closed
}

Networking

End-to-End Encryption

DAVE protocol implementation for secure voice communication with user verification, key management, and encrypted audio transmission.

class DAVESession extends EventEmitter {
  constructor(protocolVersion: number, userId: string, channelId: string, options: DAVESessionOptions);
  getVerificationCode(userId: string): Promise<string>;
  encrypt(packet: Buffer): Buffer;
  decrypt(packet: Buffer, userId: string): Buffer | null;
  destroy(): void;
}

function getMaxProtocolVersion(): number | null;

End-to-End Encryption

Utility Functions

Helper utilities for state management, dependency reporting, stream probing, and gateway adapter integration.

function entersState<T extends AudioPlayer | VoiceConnection>(
  target: T,
  status: AudioPlayerStatus | VoiceConnectionStatus,
  timeoutOrSignal: AbortSignal | number
): Promise<T>;

function generateDependencyReport(): string;

function demuxProbe(
  stream: Readable,
  probeSize?: number,
  validator?: (opusHead: Buffer) => boolean
): Promise<ProbeInfo>;

Utilities

Common Types

// Connection States
enum VoiceConnectionStatus {
  Signalling = "signalling",
  Connecting = "connecting", 
  Ready = "ready",
  Disconnected = "disconnected",
  Destroyed = "destroyed"
}

enum VoiceConnectionDisconnectReason {
  WebSocketClose,
  AdapterUnavailable,
  EndpointRemoved,
  Manual
}

// Audio Types
enum StreamType {
  Arbitrary = "arbitrary",
  Raw = "raw",
  Opus = "opus",
  OggOpus = "ogg/opus",
  WebmOpus = "webm/opus"
}

enum NoSubscriberBehavior {
  Pause = "pause",
  Play = "play",
  Stop = "stop"
}

// Gateway Adapter
type DiscordGatewayAdapterCreator = (
  methods: DiscordGatewayAdapterLibraryMethods
) => DiscordGatewayAdapterImplementerMethods;

interface DiscordGatewayAdapterLibraryMethods {
  destroy(): void;
  onVoiceServerUpdate(data: GatewayVoiceServerUpdateDispatchData): void;
  onVoiceStateUpdate(data: GatewayVoiceStateUpdateDispatchData): void;
}

interface DiscordGatewayAdapterImplementerMethods {
  destroy(): void;
  sendPayload(payload: any): boolean;
}