lunibee 0.3.3 → 0.4.0

package/dist/voice/libopus.d.ts

@@ -0,0 +1,88 @@
+import { dlopen, FFIType } from "bun:ffi";
+/** `OPUS_APPLICATION_*`: what the encoder tunes for. */
+export declare const OpusApplication: {
+    /** Speech: best for voice chat. */
+    readonly Voip: 2048;
+    /** Music and mixed content (the default). */
+    readonly Audio: 2049;
+    /** Lowest delay; disables the speech modes. */
+    readonly RestrictedLowDelay: 2051;
+};
+export type OpusApplication = (typeof OpusApplication)[keyof typeof OpusApplication];
+declare const SYMBOLS: {
+    readonly opus_encoder_create: {
+        readonly args: readonly [FFIType.int32_t, FFIType.int32_t, FFIType.int32_t, FFIType.ptr];
+        readonly returns: FFIType.ptr;
+    };
+    readonly opus_encode: {
+        readonly args: readonly [FFIType.ptr, FFIType.ptr, FFIType.int32_t, FFIType.ptr, FFIType.int32_t];
+        readonly returns: FFIType.int32_t;
+    };
+    readonly opus_encoder_destroy: {
+        readonly args: readonly [FFIType.ptr];
+        readonly returns: FFIType.void;
+    };
+    readonly opus_decoder_create: {
+        readonly args: readonly [FFIType.int32_t, FFIType.int32_t, FFIType.ptr];
+        readonly returns: FFIType.ptr;
+    };
+    readonly opus_decode: {
+        readonly args: readonly [FFIType.ptr, FFIType.ptr, FFIType.int32_t, FFIType.ptr, FFIType.int32_t, FFIType.int32_t];
+        readonly returns: FFIType.int32_t;
+    };
+    readonly opus_decoder_destroy: {
+        readonly args: readonly [FFIType.ptr];
+        readonly returns: FFIType.void;
+    };
+    readonly opus_strerror: {
+        readonly args: readonly [FFIType.int32_t];
+        readonly returns: FFIType.ptr;
+    };
+    readonly opus_get_version_string: {
+        readonly args: readonly [];
+        readonly returns: FFIType.ptr;
+    };
+};
+type Library = ReturnType<typeof dlopen<typeof SYMBOLS>>["symbols"];
+/**
+ * Opens the system's libopus through `bun:ffi` (once). `null` when it is not
+ * installed: `apt install libopus0`, `brew install opus`, or point
+ * `LUNIBEE_OPUS_LIBRARY` at the library file.
+ */
+export declare function loadLibopus(paths?: readonly string[]): {
+    symbols: Library;
+    path: string;
+} | null;
+/** Whether libopus can be loaded (looked up once). */
+export declare function hasLibopus(): boolean;
+/** @internal Forget the lookup, so tests can change `LUNIBEE_OPUS_LIBRARY`. */
+export declare function resetLibopus(): void;
+/** The libopus version string, e.g. `"libopus 1.5.2"`, or `null` when it is not installed. */
+export declare function libopusVersion(): string | null;
+/**
+ * Lunibee's Opus encoder and decoder for 48 kHz stereo, on the system's
+ * libopus through `bun:ffi`: native speed with nothing to compile. Frees its
+ * native state on `destroy()` (and, as a safety net, when it is collected).
+ */
+export declare class Opus {
+    #private;
+    /** @throws {VoiceError} When libopus is not installed or refuses the settings. */
+    constructor(application?: OpusApplication);
+    /** Where libopus was loaded from. */
+    static get libraryPath(): string;
+    /**
+     * Encodes one 20 ms frame: 960 stereo samples of s16le PCM (3,840 bytes).
+     * @returns The Opus packet (a new array).
+     * @throws {VoiceError} After `destroy()`, for a frame of the wrong size, or when libopus fails.
+     */
+    encode(pcm: Uint8Array): Uint8Array;
+    /**
+     * Decodes one Opus packet to s16le PCM (3,840 bytes for a 20 ms packet).
+     * An empty packet stands for a lost one and is concealed.
+     * @throws {VoiceError} After `destroy()`, or for a corrupt packet.
+     */
+    decode(packet: Uint8Array): Uint8Array;
+    /** Frees the native encoder and decoder. Safe to call twice. */
+    destroy(): void;
+}
+export {};

package/dist/voice/networking.d.ts

@@ -0,0 +1,80 @@
+import { type VoiceEncryptionMode } from "./crypto.js";
+import { DaveSession, loadDave } from "./dave.js";
+import { type VoiceSocketFactory } from "./gateway.js";
+import { type UdpSocketFactory } from "./udp.js";
+/** What Discord sent for one voice session (VOICE_STATE_UPDATE + VOICE_SERVER_UPDATE). */
+export interface VoiceServerInfo {
+    guildId: string;
+    channelId: string;
+    userId: string;
+    sessionId: string;
+    token: string;
+    endpoint: string;
+}
+/** Where a {@link VoiceNetworking} is in its handshake. */
+export type NetworkingState = "opening" | "identifying" | "discovering" | "selecting" | "ready" | "resuming" | "closed";
+/** Options for {@link VoiceNetworking}. */
+export interface VoiceNetworkingOptions {
+    /** Offer DAVE (end-to-end encryption) when `@snazzah/davey` is installed. Default true. Discord requires it outside stage channels. */
+    dave?: boolean;
+    /** Opens the voice WebSocket (tests). */
+    socketFactory?: VoiceSocketFactory;
+    /** Opens the UDP socket (tests). */
+    udpFactory?: UdpSocketFactory;
+    /** Overrides the voice gateway URL built from the endpoint (tests): a URL, or a function of the endpoint. */
+    url?: string | ((endpoint: string) => string);
+    debug?: (message: string) => void;
+    /** @internal A DAVE implementation in place of `@snazzah/davey` (tests). */
+    daveModule?: Awaited<ReturnType<typeof loadDave>>;
+    /** @internal Resume backoff (tests): attempts before giving up, first delay and cap in ms. */
+    resume?: {
+        attempts?: number;
+        delay?: number;
+        maxDelay?: number;
+    };
+}
+/** What a {@link VoiceNetworking} reports. */
+export interface VoiceNetworkingHandlers {
+    state?(state: NetworkingState, previous: NetworkingState): void;
+    /** The session closed for good (not resumable). */
+    close?(code: number, reason: string): void;
+    error?(error: Error): void;
+    /** An Opus frame from another user, decrypted. */
+    audio?(userId: string, frame: Uint8Array): void;
+    /** Op 5 from another user: their SSRC. */
+    speaking?(userId: string, ssrc: number): void;
+    /** Op 13. */
+    clientDisconnect?(userId: string): void;
+}
+/**
+ * One voice server session: the voice gateway handshake (v8), IP discovery,
+ * transport encryption, DAVE, and sending and receiving RTP packets. A new
+ * server (VOICE_SERVER_UPDATE) needs a new instance; a recoverable close
+ * (network loss, voice server crash) resumes on its own.
+ */
+export declare class VoiceNetworking {
+    #private;
+    state: NetworkingState;
+    /** Our SSRC, from READY. */
+    ssrc: number;
+    /** The negotiated encryption mode, once ready. */
+    mode?: VoiceEncryptionMode;
+    constructor(info: VoiceServerInfo, handlers?: VoiceNetworkingHandlers, options?: VoiceNetworkingOptions);
+    /** Heartbeat round trip in ms, or -1. */
+    get ping(): number;
+    /** The DAVE session, when Discord negotiated one. */
+    get dave(): DaveSession | undefined;
+    /** User IDs in the channel, from ops 11 and 13. */
+    get connectedUsers(): ReadonlySet<string>;
+    /** Sends op 5. Only sends when the flag changes. */
+    setSpeaking(speaking: boolean, flags?: number): void;
+    /**
+     * Encrypts one 20 ms Opus frame (DAVE, then transport) and sends it.
+     * Sequence and timestamp advance by one frame either way. A frame DAVE
+     * cannot end-to-end encrypt yet (the MLS group is not ready) is dropped.
+     * @returns Whether it was sent.
+     */
+    sendFrame(frame: Uint8Array): boolean;
+    /** Ends the session: gateway, UDP socket, DAVE state. Safe to call twice. */
+    destroy(): void;
+}

package/dist/voice/ogg.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Reads Opus packets out of an Ogg/Opus stream without decoding them (the
+ * passthrough path: no Opus library, no re-encoding). Skips the OpusHead and
+ * OpusTags headers. Memory is bounded by one page and one packet.
+ * @throws {VoiceError} For an Ogg stream that is not 48 kHz Opus with at most two channels.
+ */
+export declare function demuxOggOpus(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array>;
+/**
+ * Writes Opus packets as an Ogg/Opus stream (48 kHz, stereo), which players
+ * and FFmpeg read. Each packet counts as 20 ms (960 samples), as Discord sends.
+ * Pages hold up to 50 packets (one second).
+ */
+export declare class OggOpusWriter {
+    #private;
+    constructor(serial?: number);
+    /** The two header pages (OpusHead, OpusTags). Write them first. */
+    header(vendor?: string): Uint8Array;
+    /** Adds one packet. @returns A page once 50 packets are buffered, else an empty array. */
+    write(packet: Uint8Array): Uint8Array;
+    /** Writes the buffered packets as a page (empty array when there are none). */
+    flush(): Uint8Array;
+    /** Writes the last page (end-of-stream flag). Further writes throw. */
+    end(): Uint8Array;
+}

package/dist/voice/opus.d.ts

@@ -0,0 +1,18 @@
+/** One 48 kHz stereo Opus encoder and decoder. Call `destroy()` when done. */
+export interface OpusCodec {
+    /** The library behind it: `"libopus"` (the system's, through `bun:ffi`) or `"opusscript"` (WebAssembly). */
+    readonly library: string;
+    /** Encodes one 20 ms frame of s16le PCM (3,840 bytes). */
+    encode(pcm: Uint8Array): Uint8Array;
+    /** Decodes one Opus packet to s16le PCM. */
+    decode(packet: Uint8Array): Uint8Array;
+    destroy(): void;
+}
+/**
+ * Creates an Opus codec: Lunibee's `Opus` on the system's libopus when it is
+ * installed (native speed, nothing to compile), otherwise `opusscript`, an
+ * optional peer dependency. Playing Ogg/Opus files, or anything through
+ * FFmpeg without `inlineVolume` or effects, needs neither.
+ * @throws {VoiceError} If neither is available.
+ */
+export declare function createOpusCodec(): Promise<OpusCodec>;

package/dist/voice/player.d.ts

@@ -0,0 +1,79 @@
+import { Emitter } from "./emitter.js";
+import type { AudioResource } from "./resource.js";
+/** Where an {@link AudioPlayer} is. */
+export declare const AudioPlayerStatus: {
+    /** Nothing to play. */
+    readonly Idle: "idle";
+    /** A resource is loaded but its next frame is not ready yet. */
+    readonly Buffering: "buffering";
+    /** Sending a frame every 20 ms. */
+    readonly Playing: "playing";
+    /** Paused by `pause()`. */
+    readonly Paused: "paused";
+    /** Paused because no subscribed connection can send (`noSubscriber: "pause"`). */
+    readonly AutoPaused: "autopaused";
+};
+export type AudioPlayerStatus = (typeof AudioPlayerStatus)[keyof typeof AudioPlayerStatus];
+/** A destination for a player's frames: a voice connection. */
+export interface AudioSink {
+    /** Whether it can send now. */
+    readonly ready: boolean;
+    sendFrame(frame: Uint8Array): boolean;
+    setSpeaking(speaking: boolean): void;
+}
+/** Options for {@link AudioPlayer}. */
+export interface AudioPlayerOptions {
+    /** With no ready subscriber: `"pause"` (default) waits, `"play"` keeps consuming, `"stop"` stops. */
+    noSubscriber?: "pause" | "play" | "stop";
+    /** Frames the resource may be late in a row before playback fails. Default 250 (5 s). */
+    maxMissedFrames?: number;
+}
+/** What {@link AudioPlayer} emits. */
+export interface AudioPlayerEvents {
+    stateChange: [from: AudioPlayerStatus, to: AudioPlayerStatus];
+    /** The resource failed (an FFmpeg error, a corrupt stream). The player goes idle. */
+    error: [error: Error, resource: AudioResource<unknown>];
+    /** The resource played to its end. */
+    finish: [resource: AudioResource<unknown>];
+}
+/**
+ * Plays {@link AudioResource}s to subscribed connections: one 20 ms Opus
+ * frame per tick, on a self-correcting clock. The clock runs only while
+ * there is something to send; an idle or paused player has no timer.
+ */
+export declare class AudioPlayer extends Emitter<AudioPlayerEvents> {
+    #private;
+    constructor(options?: AudioPlayerOptions);
+    /** Current status. */
+    get state(): AudioPlayerStatus;
+    /** The resource playing (or paused), if any. */
+    get resource(): AudioResource<unknown> | undefined;
+    /** Subscribed connections. */
+    get subscribers(): ReadonlySet<AudioSink>;
+    /** Whether the clock is running (for tests and diagnostics). */
+    get ticking(): boolean;
+    /**
+     * Plays `resource`, replacing (and destroying) the current one.
+     * @throws {VoiceError} If the resource already ended or was played before.
+     */
+    play(resource: AudioResource<unknown>): void;
+    /** Pauses. @param silence Send five silence frames first (default true). @returns Whether it paused. */
+    pause(silence?: boolean): boolean;
+    /** Resumes after `pause()`. @returns Whether it resumed. */
+    unpause(): boolean;
+    /** Alias of {@link unpause}. */
+    resume(): boolean;
+    /**
+     * Stops and destroys the resource. @param force Skip the five silence
+     * frames. @returns Whether anything was playing.
+     */
+    stop(force?: boolean): boolean;
+    /** @internal A connection subscribes. */
+    attach(sink: AudioSink): void;
+    /** @internal A connection unsubscribes. */
+    detach(sink: AudioSink): void;
+    /** @internal A subscriber's readiness changed: leave or enter `autopaused`. */
+    refresh(): void;
+}
+/** Creates an {@link AudioPlayer}. */
+export declare function createAudioPlayer(options?: AudioPlayerOptions): AudioPlayer;

package/dist/voice/protocol.d.ts

@@ -0,0 +1,76 @@
+/** Voice gateway version this package speaks. */
+export declare const VOICE_GATEWAY_VERSION = 8;
+/** Voice gateway opcodes (v8, with the DAVE opcodes 21-31). */
+export declare const VoiceOpcodes: {
+    readonly Identify: 0;
+    readonly SelectProtocol: 1;
+    readonly Ready: 2;
+    readonly Heartbeat: 3;
+    readonly SessionDescription: 4;
+    readonly Speaking: 5;
+    readonly HeartbeatAck: 6;
+    readonly Resume: 7;
+    readonly Hello: 8;
+    readonly Resumed: 9;
+    readonly ClientsConnect: 11;
+    readonly ClientDisconnect: 13;
+    readonly DavePrepareTransition: 21;
+    readonly DaveExecuteTransition: 22;
+    readonly DaveTransitionReady: 23;
+    readonly DavePrepareEpoch: 24;
+    readonly DaveMlsExternalSender: 25;
+    readonly DaveMlsKeyPackage: 26;
+    readonly DaveMlsProposals: 27;
+    readonly DaveMlsCommitWelcome: 28;
+    readonly DaveMlsAnnounceCommitTransition: 29;
+    readonly DaveMlsWelcome: 30;
+    readonly DaveMlsInvalidCommitWelcome: 31;
+};
+export type VoiceOpcodes = (typeof VoiceOpcodes)[keyof typeof VoiceOpcodes];
+/** Voice gateway close codes. */
+export declare const VoiceCloseCodes: {
+    readonly UnknownOpcode: 4001;
+    readonly FailedToDecode: 4002;
+    readonly NotAuthenticated: 4003;
+    readonly AuthenticationFailed: 4004;
+    readonly AlreadyAuthenticated: 4005;
+    readonly SessionNoLongerValid: 4006;
+    readonly SessionTimeout: 4009;
+    readonly ServerNotFound: 4011;
+    readonly UnknownProtocol: 4012;
+    readonly Disconnected: 4014;
+    readonly VoiceServerCrashed: 4015;
+    readonly UnknownEncryptionMode: 4016;
+    readonly DaveProtocolRequired: 4017;
+    readonly BadRequest: 4020;
+    readonly RateLimited: 4021;
+    readonly CallTerminated: 4022;
+};
+export type VoiceCloseCodes = (typeof VoiceCloseCodes)[keyof typeof VoiceCloseCodes];
+/**
+ * Whether a voice gateway close can be resumed (op 7). Codes below 4000
+ * (network or server-side closes) and 4015 (voice server crashed) can; 4006
+ * (session invalid), 4014 (removed from the channel) and every other 4xxx
+ * cannot.
+ */
+export declare function canResumeVoice(code: number): boolean;
+/** RTP payload type Discord uses for Opus. */
+export declare const RTP_OPUS_PAYLOAD_TYPE = 120;
+/** Opus frames are 20 ms of 48 kHz audio. */
+export declare const FRAME_DURATION_MS = 20;
+/** Samples per channel in one 20 ms frame at 48 kHz. */
+export declare const FRAME_SAMPLES = 960;
+/** Bytes of one 20 ms frame of 48 kHz stereo s16le PCM. */
+export declare const PCM_FRAME_BYTES: number;
+/** The Opus frame Discord treats as silence. Five of them end a transmission. */
+export declare const SILENCE_FRAME: Uint8Array;
+/** Speaking flags for op 5. */
+export declare const SpeakingFlags: {
+    readonly Microphone: 1;
+    readonly Soundshare: 2;
+    readonly Priority: 4;
+};
+/** Voice protocol errors. */
+export declare class VoiceError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/voice/receiver.d.ts

@@ -0,0 +1,59 @@
+/** When a {@link VoiceReceiver.subscribe} stream ends. */
+export type ReceiveEnd = {
+    behavior: "manual";
+}
+/** After `duration` ms with no audio (silence frames count as none). Default, 1,000 ms. */
+ | {
+    behavior: "silence";
+    duration?: number;
+};
+/** Options for {@link VoiceReceiver.subscribe}. */
+export interface ReceiveOptions {
+    end?: ReceiveEnd;
+    /** Frames kept for a slow reader; newer frames are dropped beyond it. Default 50 (1 s). */
+    highWaterMark?: number;
+}
+/** Options for {@link VoiceReceiver.record}. */
+export interface RecordOptions {
+    /** When the recording ends. Default `{ behavior: "manual" }`: on `unsubscribe()`, cancel, or when the connection ends. */
+    end?: ReceiveEnd;
+    /** Bytes kept for a slow reader; audio beyond it is replaced by silence. Default 1 MiB. */
+    highWaterMark?: number;
+}
+/**
+ * Receives other users' audio (low level): decrypted Opus packets per user.
+ * SSRCs are mapped to users from op 5; decoding is up to you (`createOpusCodec`).
+ */
+export declare class VoiceReceiver {
+    #private;
+    /** The SSRC Discord assigned to a user, once they spoke. */
+    ssrcOf(userId: string): number | undefined;
+    /** Users who sent audio in the last 100 ms. */
+    get speaking(): ReadonlySet<string>;
+    /** Listens for a user starting or stopping to send audio. */
+    on(event: "start" | "end", listener: (userId: string) => void): this;
+    off(event: "start" | "end", listener: (userId: string) => void): this;
+    /**
+     * A stream of `userId`'s Opus packets. It ends after a second without
+     * audio unless `end.behavior` is `"manual"`; cancelling it unsubscribes.
+     */
+    subscribe(userId: string, options?: ReceiveOptions): ReadableStream<Uint8Array>;
+    /**
+     * Records `userId` as an Ogg/Opus stream (48 kHz stereo) that players and
+     * FFmpeg read: write it to a file with `Bun.write(path, new Response(stream))`.
+     * The audio is not re-encoded. Time the user is silent is kept as silence,
+     * counted from the start of the recording, so recordings of several users
+     * started together line up.
+     */
+    record(userId: string, options?: RecordOptions): ReadableStream<Uint8Array>;
+    /** Ends every stream of `userId`. @returns Whether there was one. */
+    unsubscribe(userId: string): boolean;
+    /** @internal Op 5 told us a user's SSRC. */
+    mapUser(userId: string, ssrc: number): void;
+    /** @internal Op 13: a user left. */
+    forgetUser(userId: string): void;
+    /** @internal A decrypted frame arrived from `userId`. */
+    push(userId: string, frame: Uint8Array): void;
+    /** @internal Ends every stream and forgets every user (the connection left). */
+    close(): void;
+}

package/dist/voice/resource.d.ts

@@ -0,0 +1,102 @@
+import { type AudioEffect } from "./effects.js";
+import { type OpusCodec } from "./opus.js";
+/**
+ * What an input holds:
+ * - `"arbitrary"`: any format FFmpeg reads (needs `ffmpeg` on the PATH);
+ * - `"ogg/opus"`: an Ogg/Opus file or stream, played without re-encoding;
+ * - `"opus"`: one Opus packet (20 ms) per chunk;
+ * - `"raw"`: 48 kHz stereo s16le PCM (needs an Opus library).
+ */
+export type StreamType = "arbitrary" | "ogg/opus" | "opus" | "raw";
+/** What {@link createAudioResource} can play. A string is a file path, or an `http(s)` URL for FFmpeg. */
+export type AudioInput = string | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+/** Options for {@link createAudioResource}. */
+export interface AudioResourceOptions<T = unknown> {
+    /** What the input holds. Default: from the file extension (`.ogg`/`.opus`/`.pcm`), otherwise `"arbitrary"`. */
+    inputType?: StreamType;
+    /** Allow `resource.volume.set()`. Decodes and re-encodes Opus input, so it costs CPU. Default false. */
+    inlineVolume?: boolean;
+    /** Anything you want to keep with the resource (a title, who queued it). */
+    metadata?: T;
+    /** FFmpeg executable. Default `"ffmpeg"`. */
+    ffmpegPath?: string;
+    /** Frames read ahead of playback. Default 10 (200 ms); 1 when `live`. */
+    prefetch?: number;
+    /**
+     * PCM effects (`pitchShift`, `robot`, `echo`, `gain`, or your own), run in
+     * order on every frame. Like `inlineVolume`, they decode and re-encode.
+     * `resource.effects` can be changed while it plays.
+     */
+    effects?: AudioEffect[];
+    /**
+     * A live source (a user's voice from `receiver.subscribe()`): the player
+     * waits for it without counting missed frames, and frames that pile up
+     * beyond 100 ms are dropped to keep the delay low. Default false.
+     */
+    live?: boolean;
+    /** @internal Creates the Opus codec in place of {@link createOpusCodec} (tests). */
+    codecFactory?: () => Promise<OpusCodec>;
+}
+/** Inline volume of a resource created with `inlineVolume: true`. */
+export declare class VolumeControl {
+    /** Linear gain: 1 is unchanged, 0.5 half, 2 double (clipped). */
+    volume: number;
+    /** Sets a linear gain. @throws {RangeError} For a negative or non-finite value. */
+    set(volume: number): void;
+    /** Sets a logarithmic gain in decibels (0 is unchanged). */
+    setDecibels(db: number): void;
+    /** Scales one s16le PCM frame in place. */
+    apply(pcm: Uint8Array): Uint8Array;
+}
+/**
+ * An audio source for an {@link AudioPlayer}: a queue of 20 ms Opus frames
+ * filled ahead of playback. One resource plays once; create another to play
+ * the same input again.
+ */
+export declare class AudioResource<T = unknown> {
+    #private;
+    /** What was passed as `metadata`. */
+    readonly metadata: T;
+    /** Inline volume, when created with `inlineVolume: true`. */
+    readonly volume?: VolumeControl;
+    /** The effects in use, when created with `effects`. Changes apply from the next frame. */
+    readonly effects?: AudioEffect[];
+    /** Whether it is a live source (`live: true`). */
+    readonly live: boolean;
+    /** Milliseconds of this resource the player has sent. */
+    playbackDuration: number;
+    /** Whether the player took its first frame. */
+    started: boolean;
+    /** @internal Use {@link createAudioResource}. */
+    constructor(frames: AsyncGenerator<Uint8Array>, options: {
+        metadata?: T;
+        volume?: VolumeControl;
+        effects?: AudioEffect[];
+        live?: boolean;
+        prefetch?: number;
+        cleanup?: () => void;
+    });
+    /** Whether every frame has been read (or it failed, or was destroyed). */
+    get ended(): boolean;
+    /** Why it ended early, if it failed. */
+    get error(): Error | undefined;
+    /** Whether a frame is ready now. */
+    get readable(): boolean;
+    /**
+     * Takes the next Opus frame. @returns A frame, `undefined` when none is
+     * ready yet (buffering), or `null` when the resource has ended.
+     */
+    read(): Uint8Array | null | undefined;
+    /** Stops reading: ends FFmpeg and the input, frees the codec. Safe to call twice. */
+    destroy(): void;
+}
+/**
+ * Creates an {@link AudioResource} from a file path, a URL (FFmpeg), bytes, a
+ * `ReadableStream` or an async iterable.
+ *
+ * Ogg/Opus input is played as it is (passthrough). PCM input, and anything
+ * with `inlineVolume`, is encoded with Opus (`opusscript`, an optional
+ * peer). Other formats go through FFmpeg, which is killed when
+ * the resource ends or is destroyed.
+ */
+export declare function createAudioResource<T = unknown>(input: AudioInput, options?: AudioResourceOptions<T>): AudioResource<T>;

package/dist/voice/udp.d.ts

@@ -0,0 +1,40 @@
+/** The parts of a UDP socket {@link VoiceUdp} uses; `Bun.udpSocket` provides them. */
+export interface UdpSocketLike {
+    send(data: Uint8Array, port: number, address: string): boolean;
+    close(): void;
+}
+/** Opens a UDP socket that calls `onData` for each datagram. Replace it in tests. */
+export type UdpSocketFactory = (onData: (data: Uint8Array) => void) => Promise<UdpSocketLike>;
+/** The default factory: an IPv4 `Bun.udpSocket` on an ephemeral port. */
+export declare const bunUdpSocket: UdpSocketFactory;
+/** Builds an IP discovery request (type 0x1, length 70) for `ssrc`. */
+export declare function discoveryRequest(ssrc: number): Uint8Array;
+/** Reads an IP discovery response (type 0x2): our external address and port. */
+export declare function parseDiscoveryResponse(packet: Uint8Array): {
+    ip: string;
+    port: number;
+} | undefined;
+/**
+ * The voice UDP socket: sends audio to the voice server, receives other
+ * users' audio, runs IP discovery and a keepalive every 5 s. `close()` ends
+ * the socket and its timer; nothing is left open.
+ */
+export declare class VoiceUdp {
+    #private;
+    private constructor();
+    /** Opens a socket towards the voice server at `ip:port`. */
+    static open(ip: string, port: number, factory?: UdpSocketFactory): Promise<VoiceUdp>;
+    /** Whether `close()` was called. */
+    get closed(): boolean;
+    /** Listens for datagrams. @returns A function that removes the listener. */
+    onPacket(listener: (packet: Uint8Array) => void): () => void;
+    /** Sends one datagram to the voice server. @returns Whether it was handed to the socket. */
+    send(packet: Uint8Array): boolean;
+    /** Asks the voice server for our external address. @throws {VoiceError} On timeout or when closed. */
+    discover(ssrc: number, timeoutMs?: number): Promise<{
+        ip: string;
+        port: number;
+    }>;
+    /** Closes the socket and stops the keepalive. Safe to call twice. */
+    close(): void;
+}

package/dist/ws/close-codes.d.ts

@@ -1,7 +1,7 @@
 /**
  * Discord Gateway close codes.
  *
- * Discord.js-familiar names and numeric values, matching the Discord Gateway
+ * Familiar names and numeric values, matching the Discord Gateway
  * protocol. Exposed so consumers can branch on named codes instead of magic
  * numbers; {@link Gateway} uses them internally to decide resume/identify/stop.
  */

package/dist/ws/index.d.ts

@@ -1,5 +1,5 @@
 import { type SocketFactory } from "./transport.js";
-import { type GatewayPayload, type GatewayProperties, type GatewayPresence, type GatewayIntentResolvable } from "@lunibee/types";
+import { type GatewayPayload, type GatewayProperties, type GatewayPresence, type GatewayIntentResolvable } from "../types/index.js";
 export { classifyFrame, classifyPayload, identifyPayload, resumePayload, heartbeatPayload, type GatewayAction, type ProtocolResult, type ProtocolViolation, type IdentifyOptions, type IdentifyProperties, type IdentifyData, } from "./protocol.js";
 export { WebSocketTransport, type TransportHandlers, type TransportOptions, type SocketFactory, } from "./transport.js";
 export { createDecoder, PlainTextDecoder, ZlibStreamDecoder, type GatewayDecoder, } from "./decoder.js";
@@ -7,10 +7,10 @@ export { GatewayReconnect, classifyCloseCode, FATAL_CLOSE_CODES, IDENTIFY_CLOSE_
 export { GatewayHeartbeat, type HeartbeatOptions, type HeartbeatTimeout, } from "./heartbeat.js";
 export { GatewaySession, type ResumeInfo, type HandshakeIntent, type InvalidationReason, } from "./session.js";
 export { GatewayDispatcher, type GatewayListener } from "./dispatcher.js";
-export { GatewaySendLimiter, SendBudget } from "./send-budget.js";
+export { GatewaySendLimiter } from "./send-budget.js";
 export { GatewayOpcodes } from "./opcodes.js";
 export { GatewayCloseCodes } from "./close-codes.js";
-export { GatewayState, Status, GatewayError } from "./state.js";
+export { GatewayState, GatewayError } from "./state.js";
 import { GatewayState } from "./state.js";
 import { type GatewayListener } from "./dispatcher.js";
 /** Gateway connection configuration. */
@@ -57,6 +57,21 @@ export interface GatewayOptions {
      * Injected to run the Gateway on an alternative transport, or on a stub.
      */
     createSocket?: SocketFactory;
+    /**
+     * Asked before every IDENTIFY the Gateway sends on its own (a reconnect
+     * after a session it cannot resume). The first IDENTIFY after `connect()`
+     * is not gated: whoever called `connect()` already paced it.
+     * `ShardManager` sets it to its cluster's IDENTIFY coordinator.
+     * @internal
+     */
+    identifyGate?: GatewayIdentifyGate;
+}
+/** Hands out IDENTIFY slots to a Gateway; see `GatewayOptions.identifyGate`. @internal */
+export interface GatewayIdentifyGate {
+    /** Resolves when the Gateway may IDENTIFY now. A rejection closes the socket, and the reconnect asks again. */
+    acquire(): Promise<void>;
+    /** The IDENTIFY was sent (or abandoned). */
+    release(): void;
 }
 /** What {@link Gateway.health} reports. */
 export interface GatewayHealth {
@@ -77,7 +92,13 @@ export declare class Gateway {
     ping: number;
     /** Creates a Gateway connection manager. @param options Gateway configuration. @throws {TypeError|RangeError} If configuration is invalid. */
     constructor(options: GatewayOptions);
-    /** Opens the Gateway connection. @param url Gateway WebSocket URL. @returns Promise fulfilled when the socket opens; it rejects with a GatewayError if the Gateway was permanently closed or cannot connect. */
+    /**
+     * Opens the Gateway connection.
+     * @param url Gateway WebSocket URL. Defaults to the URL of the last `connect()`, else Discord's main Gateway.
+     * It is remembered: reconnects that IDENTIFY dial it again, and every reconnect (including a RESUME
+     * on `resume_gateway_url`) carries its query parameters (`v`, `encoding`, `compress`).
+     * @returns Promise fulfilled when the socket opens; it rejects with a GatewayError if the Gateway was permanently closed or cannot connect.
+     */
     connect(url?: string): Promise<void>;
     /** Permanently closes the Gateway connection. */
     close(): void;