@harmonia-audio/voice 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,638 @@
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+import { RtpHeader } from '@harmonia-audio/native';
+
+/**
+ * Adapter methods for communicating with the Discord gateway.
+ *
+ * @example
+ * ```ts
+ * const adapter: DiscordGatewayAdapter = {
+ *   sendPayload(payload) {
+ *     guild.shard.send(payload);
+ *     return true;
+ *   },
+ *   destroy() {
+ *     // cleanup
+ *   },
+ * };
+ * ```
+ */
+interface DiscordGatewayAdapter {
+    sendPayload(payload: DiscordGatewayPayload): boolean;
+    destroy(): void;
+}
+/**
+ * Gateway payload to send for voice state updates.
+ *
+ * @example
+ * ```ts
+ * adapter.sendPayload({
+ *   op: 4,
+ *   d: { guild_id: '...', channel_id: '...', self_mute: false, self_deaf: false }
+ * });
+ * ```
+ */
+interface DiscordGatewayPayload {
+    op: number;
+    d: Record<string, unknown>;
+}
+/**
+ * Factory function that creates an adapter and returns lifecycle methods.
+ *
+ * @example
+ * ```ts
+ * const adapterCreator: DiscordGatewayAdapterCreator = (methods) => {
+ *   client.on('voiceStateUpdate', methods.onVoiceStateUpdate);
+ *   client.on('voiceServerUpdate', methods.onVoiceServerUpdate);
+ *   return adapter;
+ * };
+ * ```
+ */
+type DiscordGatewayAdapterCreator = (methods: {
+    onVoiceStateUpdate(data: VoiceStateUpdateData): void;
+    onVoiceServerUpdate(data: VoiceServerUpdateData): void;
+    destroy(): void;
+}) => DiscordGatewayAdapter;
+/** Data from a voice state update event. */
+interface VoiceStateUpdateData {
+    channel_id: string | null;
+    guild_id: string;
+    session_id: string;
+    user_id: string;
+}
+/** Data from a voice server update event. */
+interface VoiceServerUpdateData {
+    token: string;
+    guild_id: string;
+    endpoint: string | null;
+}
+
+/**
+ * Voice connection states.
+ *
+ * @example
+ * ```ts
+ * if (connection.state === VoiceConnectionState.Ready) {
+ *   // connection is ready
+ * }
+ * ```
+ */
+declare enum VoiceConnectionState {
+    Idle = "idle",
+    Signalling = "signalling",
+    Connecting = "connecting",
+    Ready = "ready",
+    Resuming = "resuming",
+    Disconnected = "disconnected",
+    Destroyed = "destroyed"
+}
+/**
+ * Audio player states.
+ *
+ * @example
+ * ```ts
+ * if (player.state === AudioPlayerState.Playing) {
+ *   player.pause();
+ * }
+ * ```
+ */
+declare enum AudioPlayerState {
+    Idle = "idle",
+    Buffering = "buffering",
+    Playing = "playing",
+    Paused = "paused",
+    AutoPaused = "autopaused"
+}
+/**
+ * Events emitted by a voice connection.
+ *
+ * @example
+ * ```ts
+ * connection.on('stateChange', (oldState, newState) => {
+ *   console.log(`${oldState} -> ${newState}`);
+ * });
+ * ```
+ */
+interface VoiceConnectionEvents {
+    stateChange: [oldState: VoiceConnectionState, newState: VoiceConnectionState];
+    ready: [];
+    disconnected: [];
+    destroyed: [];
+    error: [error: Error];
+}
+/**
+ * Events emitted by an audio player.
+ *
+ * @example
+ * ```ts
+ * player.on('stateChange', (oldState, newState) => {
+ *   console.log(`${oldState} -> ${newState}`);
+ * });
+ * ```
+ */
+interface AudioPlayerEvents {
+    stateChange: [oldState: AudioPlayerState, newState: AudioPlayerState];
+    idle: [];
+    error: [error: Error];
+}
+
+/** Represents a playable audio source. */
+interface PlayableResource {
+    read(): Buffer | null;
+    readonly ended: boolean;
+    destroy(): void;
+}
+/**
+ * Options for creating an audio player.
+ *
+ * @example
+ * ```ts
+ * const player = new AudioPlayer({ noSubscriber: 'pause' });
+ * ```
+ */
+interface AudioPlayerOptions {
+    readonly noSubscriber?: "pause" | "stop" | "play";
+}
+/**
+ * Plays audio resources and dispatches packets to voice connections.
+ *
+ * @example
+ * ```ts
+ * import { AudioPlayer } from '@harmonia/voice';
+ *
+ * const player = new AudioPlayer();
+ * player.play(resource);
+ *
+ * player.on('idle', () => {
+ *   console.log('Playback finished');
+ * });
+ * ```
+ */
+declare class AudioPlayer extends EventEmitter {
+    private _state;
+    private resource;
+    private connections;
+    private playbackTimer;
+    private readonly noSubscriberBehavior;
+    constructor(options?: AudioPlayerOptions);
+    /**
+     * Current player state.
+     *
+     * @example
+     * ```ts
+     * if (player.state === AudioPlayerState.Playing) { ... }
+     * ```
+     */
+    get state(): AudioPlayerState;
+    /**
+     * Start playing an audio resource.
+     *
+     * @example
+     * ```ts
+     * player.play(audioResource);
+     * ```
+     */
+    play(resource: PlayableResource): void;
+    /**
+     * Pause playback.
+     *
+     * @example
+     * ```ts
+     * player.pause();
+     * ```
+     */
+    pause(): void;
+    /**
+     * Resume playback.
+     *
+     * @example
+     * ```ts
+     * player.resume();
+     * ```
+     */
+    resume(): void;
+    /**
+     * Stop playback and release the resource.
+     *
+     * @example
+     * ```ts
+     * player.stop();
+     * ```
+     */
+    stop(): void;
+    /** @internal */
+    addConnection(connection: VoiceConnection): void;
+    /** @internal */
+    removeConnection(connection: VoiceConnection): void;
+    private startPlaybackLoop;
+    private processFrame;
+    private stopInternal;
+    private transitionTo;
+}
+
+/**
+ * Options for the audio receiver.
+ *
+ * @example
+ * ```ts
+ * const receiver = connection.getReceiver();
+ * ```
+ */
+interface AudioReceiverOptions {
+    readonly autoDecodeOpus?: boolean;
+}
+/**
+ * A readable stream of audio from a specific user.
+ *
+ * @example
+ * ```ts
+ * const stream = receiver.subscribe('user-id');
+ * stream.on('data', (pcm) => { ... });
+ * ```
+ */
+declare class UserAudioStream extends Readable {
+    readonly userId: string;
+    constructor(userId: string);
+    _read(): void;
+}
+/**
+ * Receives and routes incoming audio from voice connections.
+ *
+ * @example
+ * ```ts
+ * const receiver = connection.getReceiver();
+ * const stream = receiver.subscribe('user-id');
+ *
+ * stream.on('data', (pcm: Buffer) => {
+ *   // Process received audio
+ * });
+ * ```
+ */
+declare class AudioReceiver extends EventEmitter {
+    private readonly connection;
+    private readonly ssrcMap;
+    private readonly userSsrcMap;
+    private readonly subscriptions;
+    constructor(connection: VoiceConnection);
+    /**
+     * Subscribe to audio from a specific user.
+     *
+     * @param userId - The Discord user ID to receive audio from
+     * @returns A readable stream of PCM audio from that user
+     *
+     * @example
+     * ```ts
+     * const stream = receiver.subscribe('123456789');
+     * stream.pipe(fileWriteStream);
+     * ```
+     */
+    subscribe(userId: string): UserAudioStream;
+    /**
+     * Unsubscribe from a user's audio.
+     *
+     * @example
+     * ```ts
+     * receiver.unsubscribe('123456789');
+     * ```
+     */
+    unsubscribe(userId: string): void;
+    /** @internal */
+    mapSsrcToUser(ssrc: number, userId: string): void;
+    /** @internal */
+    removeUser(userId: string): void;
+    /** @internal */
+    handlePacket(rawPacket: Buffer, decryptedPayload: Buffer): void;
+    /**
+     * Destroy all streams and clean up.
+     *
+     * @example
+     * ```ts
+     * receiver.destroy();
+     * ```
+     */
+    destroy(): this;
+}
+
+/**
+ * Options for creating a voice connection.
+ *
+ * @example
+ * ```ts
+ * const options: VoiceConnectionOptions = {
+ *   guildId: '123456789',
+ *   channelId: '987654321',
+ *   selfDeaf: false,
+ *   selfMute: false,
+ * };
+ * ```
+ */
+interface VoiceConnectionOptions {
+    readonly guildId: string;
+    readonly channelId: string;
+    readonly selfDeaf?: boolean;
+    readonly selfMute?: boolean;
+    readonly adapterCreator: DiscordGatewayAdapterCreator;
+}
+/**
+ * Manages a voice connection to a Discord voice channel.
+ *
+ * @example
+ * ```ts
+ * import { VoiceConnection } from '@harmonia/voice';
+ *
+ * const connection = new VoiceConnection({
+ *   guildId: '123',
+ *   channelId: '456',
+ *   adapterCreator: guild.voiceAdapterCreator,
+ * });
+ *
+ * connection.on('ready', () => {
+ *   console.log('Connected to voice!');
+ * });
+ * ```
+ */
+declare class VoiceConnection extends EventEmitter {
+    private _state;
+    private readonly guildId;
+    private channelId;
+    private readonly selfDeaf;
+    private readonly selfMute;
+    private adapter;
+    private sessionId;
+    private voiceToken;
+    private endpoint;
+    private ws;
+    private udpSocket;
+    private ssrc;
+    private remoteIp;
+    private remotePort;
+    private localIp;
+    private localPort;
+    private secretKey;
+    private encryptionMode;
+    private sequence;
+    private timestamp;
+    private nonceCounter;
+    private heartbeatInterval;
+    private heartbeatNonce;
+    private missedHeartbeats;
+    private lastHeartbeatAck;
+    private subscribedPlayer;
+    private audioThread;
+    private ringBuffer;
+    private readonly receiver;
+    private voiceStateResolve;
+    private voiceServerResolve;
+    constructor(options: VoiceConnectionOptions);
+    /**
+     * Current connection state.
+     *
+     * @example
+     * ```ts
+     * if (connection.state === VoiceConnectionState.Ready) { ... }
+     * ```
+     */
+    get state(): VoiceConnectionState;
+    /**
+     * Get the audio receiver for this connection.
+     *
+     * @example
+     * ```ts
+     * const receiver = connection.getReceiver();
+     * ```
+     */
+    getReceiver(): AudioReceiver;
+    /**
+     * Subscribe an audio player to this connection.
+     *
+     * @example
+     * ```ts
+     * connection.subscribe(player);
+     * ```
+     */
+    subscribe(player: AudioPlayer): void;
+    /**
+     * Unsubscribe the current audio player.
+     *
+     * @example
+     * ```ts
+     * connection.unsubscribe();
+     * ```
+     */
+    unsubscribe(): void;
+    /**
+     * Destroy the connection and clean up all resources.
+     *
+     * @example
+     * ```ts
+     * connection.destroy();
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Send an Opus packet through the voice connection.
+     *
+     * @example
+     * ```ts
+     * connection.sendOpusPacket(opusBuffer);
+     * ```
+     */
+    sendOpusPacket(opusPacket: Buffer): void;
+    private sendVoiceStateUpdate;
+    private handleVoiceStateUpdate;
+    private handleVoiceServerUpdate;
+    private tryConnect;
+    private connectWebSocket;
+    private sendIdentify;
+    private handleGatewayMessage;
+    private handleReady;
+    private connectUdp;
+    private performIpDiscovery;
+    private handleUdpMessage;
+    private handleIpDiscoveryResponse;
+    private handleSessionDescription;
+    private handleSpeaking;
+    private handleClientConnect;
+    private handleClientDisconnect;
+    private handleHello;
+    private handleHeartbeatAck;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /**
+     * Set the speaking flags.
+     *
+     * @example
+     * ```ts
+     * connection.setSpeaking(1); // speaking
+     * ```
+     */
+    setSpeaking(flags: number): void;
+    private wsSend;
+    private transitionTo;
+    private cleanup;
+}
+
+/**
+ * Options for joining a voice channel.
+ *
+ * @example
+ * ```ts
+ * const connection = joinVoiceChannel({
+ *   guildId: '123',
+ *   channelId: '456',
+ *   adapterCreator: guild.voiceAdapterCreator,
+ * });
+ * ```
+ */
+interface JoinVoiceChannelOptions {
+    readonly guildId: string;
+    readonly channelId: string;
+    readonly selfDeaf?: boolean;
+    readonly selfMute?: boolean;
+    readonly adapterCreator: DiscordGatewayAdapterCreator;
+}
+/**
+ * Join a Discord voice channel and return a VoiceConnection.
+ *
+ * @example
+ * ```ts
+ * import { joinVoiceChannel } from '@harmonia/voice';
+ *
+ * const connection = joinVoiceChannel({
+ *   guildId: interaction.guildId,
+ *   channelId: member.voice.channelId,
+ *   adapterCreator: guild.voiceAdapterCreator,
+ * });
+ * ```
+ */
+declare function joinVoiceChannel(options: JoinVoiceChannelOptions): VoiceConnection;
+
+/**
+ * Get a voice connection by guild ID.
+ *
+ * @example
+ * ```ts
+ * const connection = getVoiceConnection('guild-id');
+ * ```
+ */
+declare function getVoiceConnection(guildId: string): VoiceConnection | undefined;
+/**
+ * Get all active voice connections.
+ *
+ * @example
+ * ```ts
+ * const all = getVoiceConnections();
+ * ```
+ */
+declare function getVoiceConnections(): ReadonlyMap<string, VoiceConnection>;
+
+/**
+ * Available encryption modes for voice connections.
+ *
+ * @example
+ * ```ts
+ * connection.setEncryptionMode(EncryptionMode.XSalsa20Poly1305);
+ * ```
+ */
+declare enum EncryptionMode {
+    XSalsa20Poly1305 = "xsalsa20_poly1305",
+    XSalsa20Poly1305Suffix = "xsalsa20_poly1305_suffix",
+    XSalsa20Poly1305Lite = "xsalsa20_poly1305_lite",
+    AeadAes256Gcm = "aead_aes256_gcm",
+    AeadXChaCha20Poly1305 = "aead_xchacha20_poly1305_rtpsize"
+}
+/** Parsed RTP packet. */
+interface RtpPacket {
+    header: RtpHeader;
+    payload: Buffer;
+    nonce: Buffer;
+}
+
+/**
+ * Error class for all voice-related errors in harmonia.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await connection.connect();
+ * } catch (error) {
+ *   if (error instanceof HarmoniaVoiceError) {
+ *     console.error(error.code);
+ *   }
+ * }
+ * ```
+ */
+declare class HarmoniaVoiceError extends Error {
+    readonly code: string;
+    readonly context: Record<string, unknown>;
+    constructor(code: string, message: string, context?: Record<string, unknown>);
+}
+
+/**
+ * Options for creating an audio resource.
+ *
+ * @example
+ * ```ts
+ * const resource = createAudioResource('./song.pcm', {
+ *   inputType: 'pcm',
+ * });
+ * ```
+ */
+interface AudioResourceOptions {
+    readonly inputType?: "opus" | "pcm" | "raw";
+    readonly inlineVolume?: boolean;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Audio resource that can be played by an AudioPlayer.
+ *
+ * @example
+ * ```ts
+ * const resource = createAudioResource(readableStream, { inputType: 'pcm' });
+ * player.play(resource);
+ * ```
+ */
+declare class AudioResource implements PlayableResource {
+    private readonly stream;
+    private readonly packets;
+    private _ended;
+    private draining;
+    constructor(stream: Readable);
+    /**
+     * Read the next Opus packet.
+     *
+     * @example
+     * ```ts
+     * const packet = resource.read();
+     * ```
+     */
+    read(): Buffer | null;
+    /** Whether the resource has finished producing packets. */
+    get ended(): boolean;
+    /**
+     * Destroy the resource and release underlying streams.
+     *
+     * @example
+     * ```ts
+     * resource.destroy();
+     * ```
+     */
+    destroy(): void;
+}
+/**
+ * Create an AudioResource from various input types.
+ *
+ * @example
+ * ```ts
+ * import { createAudioResource } from '@harmonia/voice';
+ * import { createReadStream } from 'fs';
+ *
+ * const resource = createAudioResource(createReadStream('./audio.pcm'), {
+ *   inputType: 'pcm',
+ * });
+ * ```
+ */
+declare function createAudioResource(input: Readable | string | Buffer, options?: AudioResourceOptions): AudioResource;
+
+export { AudioPlayer, type AudioPlayerEvents, type AudioPlayerOptions, AudioPlayerState, AudioReceiver, type AudioReceiverOptions, type AudioResourceOptions, type DiscordGatewayAdapter, type DiscordGatewayAdapterCreator, EncryptionMode, HarmoniaVoiceError, type JoinVoiceChannelOptions, type RtpPacket, VoiceConnection, type VoiceConnectionEvents, type VoiceConnectionOptions, VoiceConnectionState, createAudioResource, getVoiceConnection, getVoiceConnections, joinVoiceChannel };