@lox-audioserver/node-airplay-sender 0.4.0

package/dist/homekit/tlv.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Type Length Value encoding/decoding, used by HAP as a wire format.
+ * https://en.wikipedia.org/wiki/Type-length-value
+ */
+const Tag = {
+    PairingMethod: 0x00,
+    Username: 0x01,
+    Salt: 0x02,
+    // could be either the SRP client public key (384 bytes) or the ED25519 public key (32 bytes), depending on context
+    PublicKey: 0x03,
+    Proof: 0x04,
+    EncryptedData: 0x05,
+    Sequence: 0x06,
+    ErrorCode: 0x07,
+    BackOff: 0x08,
+    Signature: 0x0a,
+    MFiCertificate: 0x09,
+    MFiSignature: 0x0a,
+    Flags: 0x13,
+};
+function encodeOne(type, data) {
+    let bufferData;
+    if (typeof data === 'number') {
+        bufferData = Buffer.from([data]);
+    }
+    else if (typeof data === 'string') {
+        bufferData = Buffer.from(data);
+    }
+    else {
+        bufferData = data;
+    }
+    if (bufferData.length <= 255) {
+        return Buffer.concat([Buffer.from([type, bufferData.length]), bufferData]);
+    }
+    let leftLength = bufferData.length;
+    let tempBuffer = Buffer.alloc(0);
+    let currentStart = 0;
+    for (; leftLength > 0;) {
+        if (leftLength >= 255) {
+            tempBuffer = Buffer.concat([
+                tempBuffer,
+                Buffer.from([type, 0xff]),
+                bufferData.slice(currentStart, currentStart + 255),
+            ]);
+            leftLength -= 255;
+            currentStart += 255;
+        }
+        else {
+            tempBuffer = Buffer.concat([
+                tempBuffer,
+                Buffer.from([type, leftLength]),
+                bufferData.slice(currentStart, currentStart + leftLength),
+            ]);
+            leftLength = 0;
+        }
+    }
+    return tempBuffer;
+}
+function encode(type, data, ...args) {
+    const encodedTLVBuffer = encodeOne(type, data);
+    if (args.length === 0) {
+        return encodedTLVBuffer;
+    }
+    const nextType = args[0];
+    const nextData = args[1];
+    const remaining = args.slice(2);
+    const remainingTLVBuffer = encode(nextType, nextData, ...remaining);
+    return Buffer.concat([encodedTLVBuffer, remainingTLVBuffer]);
+}
+function decode(data) {
+    const objects = {};
+    let leftLength = data.length;
+    let currentIndex = 0;
+    for (; leftLength > 0;) {
+        const type = data[currentIndex];
+        const length = data[currentIndex + 1];
+        currentIndex += 2;
+        leftLength -= 2;
+        const newData = data.slice(currentIndex, currentIndex + length);
+        if (objects[type]) {
+            objects[type] = Buffer.concat([objects[type], newData]);
+        }
+        else {
+            objects[type] = newData;
+        }
+        currentIndex += length;
+        leftLength -= length;
+    }
+    return objects;
+}
+exports.default = {
+    Tag,
+    encode,
+    decode,
+};

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+import { type AirplayConfig } from './utils/config';
+import { type NtpTimestampInput } from './utils/ntp';
+/**
+ * Configuration for a single AirPlay sender.
+ */
+export interface LoxAirplaySenderOptions {
+    host: string;
+    /** RAOP port (defaults to 5000). */
+    port?: number;
+    /** Display name shown on the receiver. */
+    name?: string;
+    /** AirPlay 1 password; null disables auth. */
+    password?: string | null;
+    /** Initial volume 0–100 (default 50). */
+    volume?: number;
+    /** Explicit RAOP mode; defaults based on airplay2 flag. */
+    mode?: number;
+    /** Additional TXT records to advertise. */
+    txt?: string[];
+    /** Force ALAC encoding even when input is ALAC. */
+    forceAlac?: boolean;
+    /** Enable ALAC encoding pipeline. */
+    alacEncoding?: boolean;
+    /** Input format; pcm triggers encoding, alac passes through. */
+    inputCodec?: 'pcm' | 'alac';
+    /** Enable AirPlay 2 authentication + flags. */
+    airplay2?: boolean;
+    /** Emit verbose transport logs. */
+    debug?: boolean;
+    /** Optional unix ms start time for synced playback. */
+    startTimeMs?: number;
+    /** Optional absolute NTP start time (uint64: sec<<32 | frac). */
+    startTimeNtp?: NtpTimestampInput;
+    /** Logger hook for internal messages. */
+    log?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: unknown) => void;
+    /** Override transport/buffer tuning without patching the module. */
+    config?: Partial<AirplayConfig>;
+    /** Optional override for per-session SSRC/device magic. */
+    deviceMagic?: number;
+    /** Optional override for resend buffer size (packets). */
+    resendBufferSize?: number;
+    /** Optional mute window (ms) after underrun to smooth recovery. */
+    underrunMuteMs?: number;
+}
+/**
+ * Metadata sent to receivers for UI display.
+ */
+export interface AirplayMetadata {
+    title?: string;
+    artist?: string;
+    album?: string;
+    cover?: {
+        data: Buffer;
+        mime?: string;
+    };
+    coverUrl?: string;
+    elapsedMs?: number;
+    durationMs?: number;
+}
+export interface LoxAirplayEvent {
+    event: string;
+    message?: string;
+    detail?: any;
+}
+export declare class LoxAirplaySender extends EventEmitter {
+    private airtunes;
+    private deviceKey;
+    private started;
+    private source;
+    private log?;
+    private lastTrackKey;
+    private lastCoverKey;
+    private lastProgressKey;
+    private lastCoverUrl;
+    private coverFetch?;
+    private artworkTimer?;
+    private pendingArtwork?;
+    private lastTrackChangeAt;
+    /**
+     * Create + start a sender for a single AirPlay device.
+     * Returns true when the pipeline initializes; safe to call multiple times to restart.
+     */
+    start(options: LoxAirplaySenderOptions, onEvent?: (event: LoxAirplayEvent) => void): boolean;
+    /**
+     * Push raw PCM or ALAC frames into the stream.
+     */
+    sendPcm(chunk: Buffer): void;
+    /**
+     * Pipe a readable stream into the sender; auto-stops on end/error.
+     */
+    pipeStream(stream: Readable): void;
+    /** Adjust receiver volume (0–100). */
+    setVolume(volume: number): void;
+    /** Update track metadata immediately without artwork/progress. */
+    setTrackInfo(title: string, artist?: string, album?: string): void;
+    /** Send cover art immediately. */
+    setArtwork(art: Buffer, contentType?: string): void;
+    /** Send playback progress in seconds (elapsed, duration). */
+    setProgress(progress: number, duration: number): void;
+    /**
+     * Convenience to send track info, cover (buffer or URL), and progress.
+     * Deduplicates payloads and staggers artwork on track changes.
+     */
+    setMetadata(payload: AirplayMetadata): Promise<void>;
+    /** Provide a passcode when a receiver requests it. */
+    setPasscode(passcode: string): void;
+    /**
+     * Stop streaming and tear down state/sockets. Safe to call multiple times.
+     */
+    stop(): void;
+    private fetchCover;
+    private sendArtworkNow;
+    private queueArtwork;
+}
+/**
+ * Convenience helper to construct + start a sender in one call.
+ */
+export declare function start(options: LoxAirplaySenderOptions, onEvent?: (event: LoxAirplayEvent) => void): LoxAirplaySender;
+export default LoxAirplaySender;

package/dist/index.js

@@ -0,0 +1,310 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoxAirplaySender = void 0;
+exports.start = start;
+const node_events_1 = require("node:events");
+// Airtunes implementation (node_airtunes2 port) in src/core.
+const index_1 = __importDefault(require("./core/index"));
+const config_1 = __importStar(require("./utils/config"));
+const ntp_1 = require("./utils/ntp");
+class LoxAirplaySender extends node_events_1.EventEmitter {
+    airtunes = null;
+    deviceKey = null;
+    started = false;
+    source = null;
+    log;
+    lastTrackKey = null;
+    lastCoverKey = null;
+    lastProgressKey = null;
+    lastCoverUrl = null;
+    coverFetch;
+    artworkTimer;
+    pendingArtwork;
+    lastTrackChangeAt = 0;
+    /**
+     * Create + start a sender for a single AirPlay device.
+     * Returns true when the pipeline initializes; safe to call multiple times to restart.
+     */
+    start(options, onEvent) {
+        if (this.started) {
+            this.stop();
+        }
+        this.log = options.log;
+        if (options.config) {
+            (0, config_1.applyConfig)(options.config);
+        }
+        const inputCodec = options.inputCodec ?? 'pcm';
+        config_1.default.packet_size = inputCodec === 'alac' ? config_1.default.alac_packet_size : config_1.default.pcm_packet_size;
+        this.airtunes = new index_1.default({
+            packetSize: config_1.default.packet_size,
+            startTimeMs: options.startTimeMs,
+            startTimeNtp: options.startTimeNtp ? (0, ntp_1.toNtpTimestamp)(options.startTimeNtp) : undefined,
+            deviceMagic: options.deviceMagic,
+            resendBufferSize: options.resendBufferSize,
+            underrunMuteMs: options.underrunMuteMs,
+            config: options.config,
+        });
+        this.airtunes.on('device', (key, status, desc) => {
+            onEvent?.({ event: 'device', message: status, detail: { key, desc } });
+        });
+        this.airtunes.on('buffer', (status) => {
+            onEvent?.({ event: 'buffer', message: status });
+        });
+        this.airtunes.on('error', (err) => {
+            onEvent?.({ event: 'error', message: err instanceof Error ? err.message : String(err) });
+        });
+        this.airtunes.on('metrics', (detail) => {
+            onEvent?.({ event: 'metrics', detail });
+        });
+        const dev = this.airtunes.add(options.host, {
+            port: options.port,
+            name: options.name,
+            password: options.password ?? null,
+            volume: options.volume ?? 50,
+            mode: options.mode ?? (options.airplay2 ? 2 : 0),
+            txt: options.txt ?? [],
+            forceAlac: options.forceAlac ?? true,
+            alacEncoding: options.alacEncoding ?? true,
+            inputCodec,
+            airplay2: options.airplay2 ?? false,
+            debug: options.debug ?? false,
+            log: options.log,
+        });
+        this.deviceKey = dev?.key ?? `${options.host}:${options.port ?? 5000}`;
+        this.started = true;
+        return true;
+    }
+    /**
+     * Push raw PCM or ALAC frames into the stream.
+     */
+    sendPcm(chunk) {
+        if (!this.airtunes || !this.started)
+            return;
+        this.airtunes.write(chunk);
+    }
+    /**
+     * Pipe a readable stream into the sender; auto-stops on end/error.
+     */
+    pipeStream(stream) {
+        if (!this.airtunes || !this.started)
+            return;
+        this.source = stream;
+        stream.on('data', (chunk) => this.sendPcm(chunk));
+        stream.on('end', () => this.stop());
+        stream.on('error', () => this.stop());
+    }
+    /** Adjust receiver volume (0–100). */
+    setVolume(volume) {
+        if (!this.airtunes || !this.deviceKey)
+            return;
+        this.airtunes.setVolume(this.deviceKey, volume);
+    }
+    /** Update track metadata immediately without artwork/progress. */
+    setTrackInfo(title, artist, album) {
+        if (!this.airtunes || !this.deviceKey)
+            return;
+        this.airtunes.setTrackInfo(this.deviceKey, title, artist, album);
+    }
+    /** Send cover art immediately. */
+    setArtwork(art, contentType) {
+        if (!this.airtunes || !this.deviceKey)
+            return;
+        this.airtunes.setArtwork(this.deviceKey, art, contentType);
+    }
+    /** Send playback progress in seconds (elapsed, duration). */
+    setProgress(progress, duration) {
+        if (!this.airtunes || !this.deviceKey)
+            return;
+        this.airtunes.setProgress(this.deviceKey, progress, duration);
+    }
+    /**
+     * Convenience to send track info, cover (buffer or URL), and progress.
+     * Deduplicates payloads and staggers artwork on track changes.
+     */
+    async setMetadata(payload) {
+        if (!this.airtunes || !this.deviceKey)
+            return;
+        const title = payload.title ?? '';
+        const artist = payload.artist ?? '';
+        const album = payload.album ?? '';
+        const trackKey = `${title}::${artist}::${album}`;
+        const trackChanged = Boolean(title && trackKey !== this.lastTrackKey);
+        if (trackChanged) {
+            this.setTrackInfo(title, artist, album);
+            this.lastTrackKey = trackKey;
+            this.lastCoverKey = null;
+            this.lastCoverUrl = null;
+            this.lastTrackChangeAt = Date.now();
+        }
+        let coverPayload = payload.cover;
+        const coverUrl = payload.coverUrl;
+        if (!coverPayload?.data && coverUrl) {
+            if (coverUrl !== this.lastCoverUrl && !this.coverFetch) {
+                this.lastCoverUrl = coverUrl;
+                this.lastCoverKey = null;
+                this.coverFetch = this.fetchCover(coverUrl).finally(() => {
+                    this.coverFetch = undefined;
+                });
+            }
+            if (this.coverFetch) {
+                coverPayload = (await this.coverFetch) ?? undefined;
+            }
+        }
+        if (coverPayload?.data) {
+            const coverKey = coverUrl
+                ? `${coverUrl}:${coverPayload.mime ?? 'unknown'}:${coverPayload.data.length}`
+                : `${coverPayload.mime ?? 'unknown'}:${coverPayload.data.length}`;
+            if (coverKey !== this.lastCoverKey) {
+                if (trackChanged) {
+                    this.queueArtwork(coverPayload, coverKey, 200);
+                }
+                else {
+                    this.sendArtworkNow(coverPayload, coverKey);
+                }
+            }
+        }
+        const durationInput = typeof payload.durationMs === 'number' && payload.durationMs > 0 ? payload.durationMs : null;
+        const elapsedInput = typeof payload.elapsedMs === 'number' && payload.elapsedMs >= 0 ? payload.elapsedMs : null;
+        const durationSec = durationInput !== null ? Math.floor(durationInput > 1000 ? durationInput / 1000 : durationInput) : null;
+        const elapsedSecRaw = elapsedInput !== null ? Math.floor(elapsedInput > 1000 ? elapsedInput / 1000 : elapsedInput) : null;
+        if (durationSec !== null && elapsedSecRaw !== null && durationSec > 0) {
+            const elapsedSec = Math.min(Math.max(0, elapsedSecRaw), durationSec);
+            const progressKey = `${elapsedSec}/${durationSec}`;
+            if (progressKey !== this.lastProgressKey) {
+                this.setProgress(elapsedSec, durationSec);
+                this.lastProgressKey = progressKey;
+            }
+        }
+    }
+    /** Provide a passcode when a receiver requests it. */
+    setPasscode(passcode) {
+        if (!this.airtunes || !this.deviceKey)
+            return;
+        this.airtunes.setPasscode(this.deviceKey, passcode);
+    }
+    /**
+     * Stop streaming and tear down state/sockets. Safe to call multiple times.
+     */
+    stop() {
+        if (this.source) {
+            try {
+                this.source.destroy();
+            }
+            catch {
+                // ignore
+            }
+            this.source = null;
+        }
+        this.lastTrackKey = null;
+        this.lastCoverKey = null;
+        this.lastProgressKey = null;
+        this.lastCoverUrl = null;
+        this.lastTrackChangeAt = 0;
+        this.pendingArtwork = undefined;
+        if (this.artworkTimer) {
+            clearTimeout(this.artworkTimer);
+            this.artworkTimer = undefined;
+        }
+        if (this.airtunes) {
+            if (this.deviceKey) {
+                this.airtunes.stop(this.deviceKey);
+            }
+            this.airtunes.stopAll?.(() => undefined);
+            this.airtunes.end?.();
+        }
+        this.airtunes = null;
+        this.deviceKey = null;
+        this.started = false;
+    }
+    async fetchCover(url) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 4000);
+        try {
+            const response = await fetch(url, { signal: controller.signal });
+            if (!response.ok) {
+                this.log?.('warn', 'airplay cover fetch failed', { status: response.status, url });
+                return null;
+            }
+            const mime = response.headers.get('content-type') || undefined;
+            const buffer = Buffer.from(await response.arrayBuffer());
+            if (!buffer.length) {
+                this.log?.('warn', 'airplay cover fetch empty', { url });
+                return null;
+            }
+            return { data: buffer, mime };
+        }
+        catch {
+            this.log?.('warn', 'airplay cover fetch error', { url });
+            return null;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    sendArtworkNow(payload, coverKey) {
+        this.setArtwork(payload.data, payload.mime);
+        this.lastCoverKey = coverKey;
+    }
+    queueArtwork(payload, coverKey, delayMs) {
+        this.pendingArtwork = { ...payload, key: coverKey };
+        if (this.artworkTimer) {
+            clearTimeout(this.artworkTimer);
+        }
+        this.artworkTimer = setTimeout(() => {
+            this.artworkTimer = undefined;
+            const pending = this.pendingArtwork;
+            this.pendingArtwork = undefined;
+            if (!pending)
+                return;
+            if (pending.key === this.lastCoverKey)
+                return;
+            this.sendArtworkNow({ data: pending.data, mime: pending.mime }, pending.key);
+        }, delayMs);
+    }
+}
+exports.LoxAirplaySender = LoxAirplaySender;
+/**
+ * Convenience helper to construct + start a sender in one call.
+ */
+function start(options, onEvent) {
+    const sender = new LoxAirplaySender();
+    sender.start(options, onEvent);
+    return sender;
+}
+exports.default = LoxAirplaySender;

package/dist/utils/alac.d.ts

@@ -0,0 +1,9 @@
+/** PCM packet size (bytes) expected by the encoder. */
+export declare const PCM_PACKET_SIZE: number;
+/** Output ALAC packet size (bytes). */
+export declare const ALAC_PACKET_SIZE: number;
+/**
+ * Encode one PCM frame (16-bit LE stereo, 44.1kHz) into ALAC.
+ * Input must be exactly `PCM_PACKET_SIZE` bytes.
+ */
+export declare function encodePcmToAlac(pcmData: Buffer): Buffer;

package/dist/utils/alac.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALAC_PACKET_SIZE = exports.PCM_PACKET_SIZE = void 0;
+exports.encodePcmToAlac = encodePcmToAlac;
+const config_1 = __importDefault(require("./config"));
+/** PCM packet size (bytes) expected by the encoder. */
+exports.PCM_PACKET_SIZE = config_1.default.pcm_packet_size;
+/** Output ALAC packet size (bytes). */
+exports.ALAC_PACKET_SIZE = config_1.default.alac_packet_size;
+/**
+ * Encode one PCM frame (16-bit LE stereo, 44.1kHz) into ALAC.
+ * Input must be exactly `PCM_PACKET_SIZE` bytes.
+ */
+function encodePcmToAlac(pcmData) {
+    let alacData = Buffer.alloc(exports.ALAC_PACKET_SIZE);
+    const bsize = 352;
+    const frames = 352;
+    const p = new Uint8Array(exports.ALAC_PACKET_SIZE);
+    const input = new Uint32Array(pcmData.length / 4);
+    let j = 0;
+    for (let i = 0; i < pcmData.length; i += 4) {
+        let res = pcmData[i];
+        res |= pcmData[i + 1] << 8;
+        res |= pcmData[i + 2] << 16;
+        res |= pcmData[i + 3] << 24;
+        input[j++] = res;
+    }
+    let pindex = 0;
+    let iindex = 0;
+    p[pindex++] = 1 << 5;
+    p[pindex++] = 0;
+    p[pindex++] = (1 << 4) | (1 << 1) | ((bsize & 0x80000000) >>> 31);
+    p[pindex++] = ((bsize & 0x7f800000) << 1) >>> 24;
+    p[pindex++] = ((bsize & 0x007f8000) << 1) >>> 16;
+    p[pindex++] = ((bsize & 0x00007f80) << 1) >>> 8;
+    p[pindex] = (bsize & 0x0000007f) << 1;
+    p[pindex++] |= (input[iindex] & 0x00008000) >>> 15;
+    let count = frames - 1;
+    while (count--) {
+        const i = input[iindex++];
+        p[pindex++] = (i & 0x00007f80) >>> 7;
+        p[pindex++] = ((i & 0x0000007f) << 1) | ((i & 0x80000000) >>> 31);
+        p[pindex++] = (i & 0x7f800000) >>> 23;
+        p[pindex++] = ((i & 0x007f0000) >>> 15) | ((input[iindex] & 0x00008000) >> 15);
+    }
+    const i = input[iindex];
+    p[pindex++] = (i & 0x00007f80) >>> 7;
+    p[pindex++] = ((i & 0x0000007f) << 1) | ((i & 0x80000000) >>> 31);
+    p[pindex++] = (i & 0x7f800000) >>> 23;
+    p[pindex++] = (i & 0x007f0000) >>> 15;
+    count = (bsize - frames) * 4;
+    while (count--)
+        p[pindex++] = 0;
+    p[pindex - 1] |= 1;
+    p[pindex++] = (7 >>> 1) << 6;
+    const alacSize = pindex;
+    alacData = Buffer.from(p.buffer);
+    return alacData.slice(0, alacSize);
+}

package/dist/utils/alacEncoder.d.ts

@@ -0,0 +1,14 @@
+import { Transform, type TransformCallback } from 'node:stream';
+/**
+ * Transforms PCM (16-bit LE, stereo, 44.1kHz) into fixed-size ALAC frames.
+ * Emits ALAC packets sized per `ALAC_PACKET_SIZE`.
+ */
+export declare class AlacEncoderStream extends Transform {
+    private buffer;
+    /** Create a streaming ALAC encoder for PCM input. */
+    constructor();
+    /**
+     * Buffer PCM until a full frame is available, then emit ALAC.
+     */
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+}

package/dist/utils/alacEncoder.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlacEncoderStream = void 0;
+const node_stream_1 = require("node:stream");
+const alac_1 = require("./alac");
+/**
+ * Transforms PCM (16-bit LE, stereo, 44.1kHz) into fixed-size ALAC frames.
+ * Emits ALAC packets sized per `ALAC_PACKET_SIZE`.
+ */
+class AlacEncoderStream extends node_stream_1.Transform {
+    buffer = Buffer.alloc(0);
+    /** Create a streaming ALAC encoder for PCM input. */
+    constructor() {
+        super();
+    }
+    /**
+     * Buffer PCM until a full frame is available, then emit ALAC.
+     */
+    _transform(chunk, _encoding, callback) {
+        if (!chunk?.length) {
+            callback();
+            return;
+        }
+        this.buffer = (this.buffer.length ? Buffer.concat([this.buffer, chunk]) : chunk);
+        while (this.buffer.length >= alac_1.PCM_PACKET_SIZE) {
+            const frame = this.buffer.subarray(0, alac_1.PCM_PACKET_SIZE);
+            this.buffer = this.buffer.subarray(alac_1.PCM_PACKET_SIZE);
+            const alac = (0, alac_1.encodePcmToAlac)(frame);
+            this.push(alac);
+        }
+        callback();
+    }
+}
+exports.AlacEncoderStream = AlacEncoderStream;

package/dist/utils/circularBuffer.d.ts

@@ -0,0 +1,32 @@
+import { EventEmitter } from 'node:events';
+import { Packet } from './packetPool';
+export type BufferStatus = 'buffering' | 'playing' | 'drain' | 'end';
+/**
+ * Fixed-size circular buffer that smooths incoming PCM/ALAC chunks into fixed packet sizes.
+ * Emits status changes for buffering/playing/drain/end to drive UI + sync.
+ */
+export default class CircularBuffer extends EventEmitter {
+    private readonly packetPool;
+    private readonly maxSize;
+    private readonly packetSize;
+    writable: boolean;
+    muted: boolean;
+    private buffers;
+    private currentSize;
+    private status;
+    private hadUnderrun;
+    constructor(packetsInBuffer: number, packetSize: number);
+    /**
+     * Write a PCM/ALAC chunk into the buffer.
+     * Returns false when the buffer is full so upstream can throttle.
+     */
+    write(chunk: Buffer): boolean;
+    /**
+     * Read the next fixed-size packet, zero-filling gaps to preserve timing.
+     */
+    readPacket(): Packet;
+    /** Mark the buffer as ending; drains then emits `end`. */
+    end(): void;
+    /** Clear internal buffers and state. */
+    reset(): void;
+}