@harmonia-audio/codec 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,425 @@
+import { Transform, TransformCallback } from 'node:stream';
+
+/**
+ * Opus application modes.
+ *
+ * @example
+ * ```ts
+ * const encoder = new OpusEncoder({
+ *   sampleRate: 48000,
+ *   channels: 2,
+ *   application: 'audio',
+ * });
+ * ```
+ */
+type OpusApplication = "voip" | "audio" | "restricted_lowdelay";
+/**
+ * Opus signal type hints.
+ *
+ * @example
+ * ```ts
+ * encoder.setSignal('music');
+ * ```
+ */
+type OpusSignalType = "voice" | "music";
+/**
+ * Configuration options for creating an Opus encoder.
+ *
+ * @example
+ * ```ts
+ * const options: OpusEncoderOptions = {
+ *   sampleRate: 48000,
+ *   channels: 2,
+ *   application: 'audio',
+ *   bitrate: 128000,
+ * };
+ * ```
+ */
+interface OpusEncoderOptions {
+    readonly sampleRate: (typeof OPUS_SAMPLE_RATES)[number];
+    readonly channels: (typeof OPUS_CHANNELS)[number];
+    readonly application: OpusApplication;
+    readonly bitrate?: number;
+    readonly complexity?: number;
+    readonly fec?: boolean;
+    readonly packetLossPercent?: number;
+    readonly dtx?: boolean;
+    readonly vbr?: boolean;
+    readonly signal?: OpusSignalType;
+}
+/**
+ * Configuration options for creating an Opus decoder.
+ *
+ * @example
+ * ```ts
+ * const decoder = new OpusDecoder({ sampleRate: 48000, channels: 2 });
+ * ```
+ */
+interface OpusDecoderOptions {
+    readonly sampleRate: (typeof OPUS_SAMPLE_RATES)[number];
+    readonly channels: (typeof OPUS_CHANNELS)[number];
+}
+/** Valid Opus sample rates. */
+declare const OPUS_SAMPLE_RATES: readonly [8000, 12000, 16000, 24000, 48000];
+/** Valid Opus channel counts. */
+declare const OPUS_CHANNELS: readonly [1, 2];
+/** Valid Opus frame durations in milliseconds. */
+declare const OPUS_FRAME_DURATIONS: readonly [2.5, 5, 10, 20, 40, 60];
+/** Discord's required Opus sample rate. */
+declare const DISCORD_OPUS_SAMPLE_RATE: 48000;
+/** Discord's required Opus channel count (stereo). */
+declare const DISCORD_OPUS_CHANNELS: 2;
+/** Discord's standard Opus frame duration in milliseconds. */
+declare const DISCORD_OPUS_FRAME_DURATION: 20;
+/** Discord Opus frame size in samples per channel. */
+declare const DISCORD_OPUS_FRAME_SIZE: 960;
+
+/**
+ * High-performance Opus encoder backed by native Rust bindings.
+ *
+ * @example
+ * ```ts
+ * import { OpusEncoder } from '@harmonia/codec';
+ *
+ * const encoder = new OpusEncoder({
+ *   sampleRate: 48000,
+ *   channels: 2,
+ *   application: 'audio',
+ * });
+ *
+ * const encoded = encoder.encode(pcmBuffer);
+ * ```
+ */
+declare class OpusEncoder {
+    private readonly native;
+    private readonly _sampleRate;
+    private readonly _channels;
+    private readonly _application;
+    constructor(options: OpusEncoderOptions);
+    /**
+     * Encode 16-bit PCM audio to Opus.
+     *
+     * @param pcm - Buffer containing interleaved 16-bit signed integer PCM samples
+     * @returns Encoded Opus packet
+     *
+     * @example
+     * ```ts
+     * const opus = encoder.encode(pcmBuffer);
+     * ```
+     */
+    encode(pcm: Buffer): Buffer;
+    /**
+     * Encode 32-bit float PCM audio to Opus.
+     *
+     * @param pcm - Buffer containing interleaved 32-bit float PCM samples
+     * @returns Encoded Opus packet
+     *
+     * @example
+     * ```ts
+     * const opus = encoder.encodeFloat(floatPcmBuffer);
+     * ```
+     */
+    encodeFloat(pcm: Buffer): Buffer;
+    /**
+     * Set the encoder bitrate in bits per second.
+     *
+     * @example
+     * ```ts
+     * encoder.setBitrate(128000);
+     * ```
+     */
+    setBitrate(bitrate: number): void;
+    /**
+     * Get the current encoder bitrate.
+     *
+     * @example
+     * ```ts
+     * const bitrate = encoder.getBitrate();
+     * ```
+     */
+    getBitrate(): number;
+    /**
+     * Set encoding complexity (0-10, higher = better quality but slower).
+     *
+     * @example
+     * ```ts
+     * encoder.setComplexity(10);
+     * ```
+     */
+    setComplexity(complexity: number): void;
+    /**
+     * Get the current encoding complexity.
+     *
+     * @example
+     * ```ts
+     * const complexity = encoder.getComplexity();
+     * ```
+     */
+    getComplexity(): number;
+    /**
+     * Enable or disable forward error correction.
+     *
+     * @example
+     * ```ts
+     * encoder.setFec(true);
+     * ```
+     */
+    setFec(enabled: boolean): void;
+    /**
+     * Check if FEC is enabled.
+     *
+     * @example
+     * ```ts
+     * const fecEnabled = encoder.getFec();
+     * ```
+     */
+    getFec(): boolean;
+    /**
+     * Set expected packet loss percentage for FEC optimization.
+     *
+     * @example
+     * ```ts
+     * encoder.setPacketLossPercent(10);
+     * ```
+     */
+    setPacketLossPercent(percent: number): void;
+    /**
+     * Enable or disable discontinuous transmission.
+     *
+     * @example
+     * ```ts
+     * encoder.setDtx(true);
+     * ```
+     */
+    setDtx(enabled: boolean): void;
+    /**
+     * Enable or disable variable bitrate.
+     *
+     * @example
+     * ```ts
+     * encoder.setVbr(true);
+     * ```
+     */
+    setVbr(enabled: boolean): void;
+    /**
+     * Set the signal type hint.
+     *
+     * @example
+     * ```ts
+     * encoder.setSignal('music');
+     * ```
+     */
+    setSignal(signal: OpusSignalType): void;
+    /**
+     * Reset the encoder state.
+     *
+     * @example
+     * ```ts
+     * encoder.reset();
+     * ```
+     */
+    reset(): void;
+    /** The sample rate this encoder operates at. */
+    get sampleRate(): number;
+    /** The number of channels this encoder operates with. */
+    get channels(): number;
+    /** The application mode this encoder was configured with. */
+    get application(): OpusApplication;
+}
+
+/**
+ * High-performance Opus decoder backed by native Rust bindings.
+ *
+ * @example
+ * ```ts
+ * import { OpusDecoder } from '@harmonia/codec';
+ *
+ * const decoder = new OpusDecoder({ sampleRate: 48000, channels: 2 });
+ * const pcm = decoder.decode(opusPacket);
+ * ```
+ */
+declare class OpusDecoder {
+    private readonly native;
+    private readonly _sampleRate;
+    private readonly _channels;
+    constructor(options: OpusDecoderOptions);
+    /**
+     * Decode an Opus packet to 16-bit PCM.
+     *
+     * @param opusData - The Opus-encoded packet
+     * @returns Buffer containing decoded 16-bit PCM samples
+     *
+     * @example
+     * ```ts
+     * const pcm = decoder.decode(opusPacket);
+     * ```
+     */
+    decode(opusData: Buffer): Buffer;
+    /**
+     * Decode an Opus packet to 32-bit float PCM.
+     *
+     * @param opusData - The Opus-encoded packet
+     * @returns Buffer containing decoded 32-bit float PCM samples
+     *
+     * @example
+     * ```ts
+     * const pcm = decoder.decodeFloat(opusPacket);
+     * ```
+     */
+    decodeFloat(opusData: Buffer): Buffer;
+    /**
+     * Decode with forward error correction from a previous packet.
+     *
+     * @param opusData - The Opus packet to attempt FEC recovery from
+     * @param frameSize - Number of samples per channel expected
+     * @returns Buffer containing recovered PCM
+     *
+     * @example
+     * ```ts
+     * const recovered = decoder.decodeFec(previousPacket, 960);
+     * ```
+     */
+    decodeFec(opusData: Buffer, frameSize: number): Buffer;
+    /**
+     * Perform packet loss concealment (no input packet available).
+     *
+     * @param frameSize - Number of samples per channel to generate
+     * @returns Buffer containing concealed PCM
+     *
+     * @example
+     * ```ts
+     * const concealed = decoder.decodePlc(960);
+     * ```
+     */
+    decodePlc(frameSize: number): Buffer;
+    /**
+     * Reset the decoder state.
+     *
+     * @example
+     * ```ts
+     * decoder.reset();
+     * ```
+     */
+    reset(): void;
+    /** The sample rate this decoder operates at. */
+    get sampleRate(): number;
+    /** The number of channels this decoder produces. */
+    get channels(): number;
+}
+
+/**
+ * Transform stream that encodes PCM to Opus.
+ *
+ * @example
+ * ```ts
+ * import { OpusEncoderStream } from '@harmonia/codec';
+ *
+ * const stream = new OpusEncoderStream({
+ *   sampleRate: 48000,
+ *   channels: 2,
+ *   application: 'audio',
+ * });
+ *
+ * pcmSource.pipe(stream).on('data', (opusPacket) => {
+ *   // handle encoded packet
+ * });
+ * ```
+ */
+declare class OpusEncoderStream extends Transform {
+    private readonly encoder;
+    private readonly frameSize;
+    private readonly frameSizeBytes;
+    private pendingBuffer;
+    constructor(options: OpusEncoderOptions);
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+}
+/**
+ * Transform stream that decodes Opus to PCM.
+ *
+ * @example
+ * ```ts
+ * import { OpusDecoderStream } from '@harmonia/codec';
+ *
+ * const stream = new OpusDecoderStream({ sampleRate: 48000, channels: 2 });
+ *
+ * opusSource.pipe(stream).on('data', (pcm) => {
+ *   // handle decoded PCM
+ * });
+ * ```
+ */
+declare class OpusDecoderStream extends Transform {
+    private readonly decoder;
+    constructor(options: OpusDecoderOptions);
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+}
+
+/**
+ * Utilities for inspecting Opus packets without decoding.
+ *
+ * @example
+ * ```ts
+ * import { OpusPacket } from '@harmonia/codec';
+ *
+ * const channels = OpusPacket.getChannels(opusData);
+ * const frames = OpusPacket.getFrameCount(opusData);
+ * ```
+ */
+declare class OpusPacket {
+    /**
+     * Get the number of channels from an Opus packet header.
+     *
+     * @example
+     * ```ts
+     * const channels = OpusPacket.getChannels(opusPacket);
+     * ```
+     */
+    static getChannels(packet: Buffer): number;
+    /**
+     * Get the number of frames in an Opus packet.
+     *
+     * @example
+     * ```ts
+     * const frameCount = OpusPacket.getFrameCount(opusPacket);
+     * ```
+     */
+    static getFrameCount(packet: Buffer): number;
+    /**
+     * Get samples per frame for a given sample rate.
+     *
+     * @example
+     * ```ts
+     * const spf = OpusPacket.getSamplesPerFrame(opusPacket, 48000);
+     * ```
+     */
+    static getSamplesPerFrame(packet: Buffer, sampleRate: number): number;
+    private constructor();
+}
+
+/**
+ * Error thrown by Opus codec operations.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   encoder.encode(buffer);
+ * } catch (error) {
+ *   if (error instanceof HarmoniaCodecError) {
+ *     console.error(error.code, error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class HarmoniaCodecError extends Error {
+    /**
+     * Machine-readable error code.
+     */
+    readonly code: string;
+    /**
+     * Additional context about the error.
+     */
+    readonly context: Record<string, unknown>;
+    constructor(code: string, message: string, context?: Record<string, unknown>);
+}
+
+export { DISCORD_OPUS_CHANNELS, DISCORD_OPUS_FRAME_DURATION, DISCORD_OPUS_FRAME_SIZE, DISCORD_OPUS_SAMPLE_RATE, HarmoniaCodecError, OPUS_CHANNELS, OPUS_FRAME_DURATIONS, OPUS_SAMPLE_RATES, type OpusApplication, OpusDecoder, type OpusDecoderOptions, OpusDecoderStream, OpusEncoder, type OpusEncoderOptions, OpusEncoderStream, OpusPacket, type OpusSignalType };