@mudah-cli/audio 0.5.0

package/dist/backends/native.d.ts

@@ -0,0 +1,15 @@
+import type { AudioBackend, AudioFormat } from '../types.js';
+export declare class NativeBackend implements AudioBackend {
+    readonly kind: 'native';
+    private readonly rt;
+    private closed;
+    private constructor();
+    static tryOpen(options: {
+        sampleRate: number;
+        channels: number;
+        format: AudioFormat;
+        framesPerBuffer: number;
+    }): Promise<NativeBackend | undefined>;
+    write(bytes: Uint8Array): void;
+    dispose(): void;
+}

package/dist/backends/native.js

@@ -0,0 +1,52 @@
+export class NativeBackend {
+    kind = 'native';
+    rt;
+    closed = false;
+    constructor(rt) {
+        this.rt = rt;
+    }
+    static async tryOpen(options) {
+        let mod;
+        try {
+            mod = (await import('audify'));
+        }
+        catch {
+            return undefined;
+        }
+        if (typeof mod.RtAudio !== 'function' || mod.RtAudioFormat === undefined)
+            return undefined;
+        try {
+            const rt = new mod.RtAudio();
+            const format = options.format === 'f32' ? mod.RtAudioFormat.RTAUDIO_FLOAT32 : mod.RtAudioFormat.RTAUDIO_SINT16;
+            rt.openStream({ deviceId: rt.getDefaultOutputDevice(), nChannels: options.channels, firstChannel: 0 }, null, format, options.sampleRate, options.framesPerBuffer, 'mudah-audio');
+            rt.start();
+            return new NativeBackend(rt);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    write(bytes) {
+        if (this.closed)
+            return;
+        this.rt.write(Buffer.from(bytes));
+    }
+    dispose() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.rt.stop();
+        }
+        catch {
+            /* already stopped */
+        }
+        try {
+            this.rt.closeStream();
+        }
+        catch {
+            /* already closed */
+        }
+    }
+}
+//# sourceMappingURL=native.js.map

package/dist/backends/native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.js","sourceRoot":"","sources":["../../src/backends/native.ts"],"names":[],"mappings":"AAuBA,MAAM,OAAO,aAAa;IACf,IAAI,GAAG,QAAiB,CAAC;IACjB,EAAE,CAAc;IACzB,MAAM,GAAG,KAAK,CAAC;IAEvB,YAAoB,EAAe;QACjC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAKpB;QACC,IAAI,GAAiB,CAAC;QACtB,IAAI,CAAC;YACH,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC,CAA4B,CAAC;QAC5D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU,IAAI,GAAG,CAAC,aAAa,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAE3F,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAC7B,MAAM,MAAM,GACV,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,cAAc,CAAC;YAClG,EAAE,CAAC,UAAU,CACX,EAAE,QAAQ,EAAE,EAAE,CAAC,sBAAsB,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,QAAQ,EAAE,YAAY,EAAE,CAAC,EAAE,EACvF,IAAI,EACJ,MAAM,EACN,OAAO,CAAC,UAAU,EAClB,OAAO,CAAC,eAAe,EACvB,aAAa,CACd,CAAC;YACF,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,aAAa,CAAC,EAAE,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAiB;QACrB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACpC,CAAC;IAED,OAAO;QACL,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QACjB,CAAC;QAAC,MAAM,CAAC;YACP,qBAAqB;QACvB,CAAC;QACD,IAAI,CAAC;YACH,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,oBAAoB;QACtB,CAAC;IACH,CAAC;CACF"}

package/dist/backends/silent.d.ts

@@ -0,0 +1,7 @@
+import type { AudioBackend } from '../types.js';
+export declare class SilentBackend implements AudioBackend {
+    readonly kind: 'silent';
+    bytesWritten: number;
+    write(bytes: Uint8Array): void;
+    dispose(): void;
+}

package/dist/backends/silent.js

@@ -0,0 +1,9 @@
+export class SilentBackend {
+    kind = 'silent';
+    bytesWritten = 0;
+    write(bytes) {
+        this.bytesWritten += bytes.byteLength;
+    }
+    dispose() { }
+}
+//# sourceMappingURL=silent.js.map

package/dist/backends/silent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"silent.js","sourceRoot":"","sources":["../../src/backends/silent.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,aAAa;IACf,IAAI,GAAG,QAAiB,CAAC;IAClC,YAAY,GAAG,CAAC,CAAC;IAEjB,KAAK,CAAC,KAAiB;QACrB,IAAI,CAAC,YAAY,IAAI,KAAK,CAAC,UAAU,CAAC;IACxC,CAAC;IAED,OAAO,KAAU,CAAC;CACnB"}

package/dist/backends/spawn-command.d.ts

@@ -0,0 +1,10 @@
+import type { SpawnTool } from '../types.js';
+export interface SpawnTarget {
+    readonly sampleRate: number;
+    readonly channels: number;
+}
+/** argv for a raw s16le stdin player. Tests assert this without opening a device. */
+export declare function spawnCommand(tool: SpawnTool, target: SpawnTarget): {
+    command: string;
+    args: string[];
+};

package/dist/backends/spawn-command.js

@@ -0,0 +1,23 @@
+/** argv for a raw s16le stdin player. Tests assert this without opening a device. */
+export function spawnCommand(tool, target) {
+    const rate = String(target.sampleRate);
+    const channels = String(target.channels);
+    switch (tool) {
+        case 'pw-play':
+            return {
+                command: 'pw-play',
+                args: ['--raw', `--rate=${rate}`, `--channels=${channels}`, '--format=s16', '-'],
+            };
+        case 'paplay':
+            return {
+                command: 'paplay',
+                args: ['--raw', `--rate=${rate}`, `--channels=${channels}`, '--format=s16le', '-'],
+            };
+        case 'aplay':
+            return {
+                command: 'aplay',
+                args: ['-t', 'raw', '-f', 'S16_LE', '-c', channels, '-r', rate, '-'],
+            };
+    }
+}
+//# sourceMappingURL=spawn-command.js.map

package/dist/backends/spawn-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-command.js","sourceRoot":"","sources":["../../src/backends/spawn-command.ts"],"names":[],"mappings":"AAOA,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,IAAe,EAAE,MAAmB;IAC/D,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACzC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,SAAS;YACZ,OAAO;gBACL,OAAO,EAAE,SAAS;gBAClB,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,IAAI,EAAE,EAAE,cAAc,QAAQ,EAAE,EAAE,cAAc,EAAE,GAAG,CAAC;aACjF,CAAC;QACJ,KAAK,QAAQ;YACX,OAAO;gBACL,OAAO,EAAE,QAAQ;gBACjB,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,IAAI,EAAE,EAAE,cAAc,QAAQ,EAAE,EAAE,gBAAgB,EAAE,GAAG,CAAC;aACnF,CAAC;QACJ,KAAK,OAAO;YACV,OAAO;gBACL,OAAO,EAAE,OAAO;gBAChB,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC;aACrE,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/backends/spawn.d.ts

@@ -0,0 +1,14 @@
+import type { AudioBackend, SpawnFn, SpawnTool } from '../types.js';
+export declare class SpawnBackend implements AudioBackend {
+    readonly kind: 'spawn';
+    readonly spawnTool: SpawnTool;
+    private readonly child;
+    private readonly onUnderrun;
+    private dead;
+    constructor(tool: SpawnTool, target: {
+        sampleRate: number;
+        channels: number;
+    }, spawnFn: SpawnFn | undefined, onUnderrun?: () => void);
+    write(bytes: Uint8Array): void;
+    dispose(): void;
+}

package/dist/backends/spawn.js

@@ -0,0 +1,48 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { spawnCommand } from './spawn-command.js';
+export class SpawnBackend {
+    kind = 'spawn';
+    spawnTool;
+    child;
+    onUnderrun;
+    dead = false;
+    constructor(tool, target, spawnFn, onUnderrun) {
+        this.spawnTool = tool;
+        this.onUnderrun = onUnderrun;
+        const { command, args } = spawnCommand(tool, target);
+        const run = spawnFn ?? defaultSpawn;
+        this.child = run(command, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+        this.child.on?.('exit', () => {
+            this.dead = true;
+        });
+        this.child.on?.('error', () => {
+            this.dead = true;
+            this.onUnderrun?.();
+        });
+    }
+    write(bytes) {
+        if (this.dead || this.child.stdin === null) {
+            this.onUnderrun?.();
+            return;
+        }
+        try {
+            this.child.stdin.write(bytes);
+        }
+        catch {
+            this.dead = true;
+            this.onUnderrun?.();
+        }
+    }
+    dispose() {
+        this.dead = true;
+        try {
+            this.child.stdin?.end();
+        }
+        catch {
+            /* already closed */
+        }
+        this.child.kill();
+    }
+}
+const defaultSpawn = (command, args, options) => nodeSpawn(command, [...args], options);
+//# sourceMappingURL=spawn.js.map

package/dist/backends/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["../../src/backends/spawn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,OAAO,YAAY;IACd,IAAI,GAAG,OAAgB,CAAC;IACxB,SAAS,CAAY;IACb,KAAK,CAAgB;IACrB,UAAU,CAA2B;IAC9C,IAAI,GAAG,KAAK,CAAC;IAErB,YACE,IAAe,EACf,MAAgD,EAChD,OAA4B,EAC5B,UAAuB;QAEvB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACrD,MAAM,GAAG,GAAG,OAAO,IAAI,YAAY,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;YACjB,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QACtB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAiB;QACrB,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;YACjB,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,oBAAoB;QACtB,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;CACF;AAED,MAAM,YAAY,GAAY,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CACvD,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,CAAkB,CAAC"}

package/dist/detect.d.ts

@@ -0,0 +1,10 @@
+import type { AudioDetection, SpawnTool } from './types.js';
+export declare function silentRequested(env?: NodeJS.ProcessEnv): boolean;
+export declare function canResolveAudify(): boolean;
+export declare function pathDirsFrom(env?: NodeJS.ProcessEnv, override?: readonly string[]): readonly string[];
+export declare function findSpawnTool(dirs?: readonly string[]): SpawnTool | undefined;
+/**
+ * Probe what `AudioOut.open({ backend: 'auto' })` would pick, without opening a stream.
+ * Native is "audify is resolvable", not "the addon loaded".
+ */
+export declare function detectAudio(env?: NodeJS.ProcessEnv, pathDirs?: readonly string[]): AudioDetection;

package/dist/detect.js

@@ -0,0 +1,52 @@
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const requireFromHere = createRequire(fileURLToPath(import.meta.url));
+const SPAWN_TOOLS = ['pw-play', 'paplay', 'aplay'];
+export function silentRequested(env = process.env) {
+    if (env['MUDAH_NO_AUDIO'] === '1')
+        return true;
+    const ci = env['CI'];
+    return ci !== undefined && ci !== '' && ci !== 'false';
+}
+export function canResolveAudify() {
+    try {
+        requireFromHere.resolve('audify');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function pathDirsFrom(env = process.env, override) {
+    if (override !== undefined)
+        return override;
+    return (env['PATH'] ?? '').split(':').filter(Boolean);
+}
+export function findSpawnTool(dirs = pathDirsFrom()) {
+    for (const tool of SPAWN_TOOLS) {
+        for (const dir of dirs) {
+            if (existsSync(join(dir, tool)))
+                return tool;
+        }
+    }
+    return undefined;
+}
+/**
+ * Probe what `AudioOut.open({ backend: 'auto' })` would pick, without opening a stream.
+ * Native is "audify is resolvable", not "the addon loaded".
+ */
+export function detectAudio(env = process.env, pathDirs) {
+    const spawnTool = findSpawnTool(pathDirsFrom(env, pathDirs));
+    const native = canResolveAudify();
+    if (silentRequested(env)) {
+        return { backend: 'silent', native, spawnTool };
+    }
+    if (native)
+        return { backend: 'native', native, spawnTool };
+    if (spawnTool !== undefined)
+        return { backend: 'spawn', native, spawnTool };
+    return { backend: 'silent', native, spawnTool };
+}
+//# sourceMappingURL=detect.js.map

package/dist/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,eAAe,GAAG,aAAa,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAEtE,MAAM,WAAW,GAAyB,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAEzE,MAAM,UAAU,eAAe,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAClE,IAAI,GAAG,CAAC,gBAAgB,CAAC,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAC/C,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACrB,OAAO,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,OAAO,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,IAAI,CAAC;QACH,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAE,QAA4B;IAC7F,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAI,GAAsB,YAAY,EAAE;IACpE,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,GAAG,GAAsB,OAAO,CAAC,GAAG,EACpC,QAA4B;IAE5B,MAAM,SAAS,GAAG,aAAa,CAAC,YAAY,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;IAElC,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,MAAM;QAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC5D,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC5E,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAClD,CAAC"}

package/dist/device.d.ts

@@ -0,0 +1,35 @@
+import type { AudioBackendKind, AudioFormat, AudioOutOptions, PlaySource, SpawnTool } from './types.js';
+/**
+ * PCM output through the OS mixer. Kitty cannot carry audio; this never
+ * writes to the terminal.
+ *
+ * Apps that never import `@mudah-cli/audio` never load a backend.
+ */
+export declare class AudioOut {
+    readonly sampleRate: number;
+    readonly channels: number;
+    readonly format: AudioFormat;
+    readonly backendKind: Exclude<AudioBackendKind, 'auto'>;
+    readonly spawnTool: SpawnTool | undefined;
+    bytesWritten: number;
+    private readonly backend;
+    private readonly clips;
+    private wroteOnce;
+    private disposed;
+    private constructor();
+    static open(options?: AudioOutOptions): Promise<AudioOut>;
+    /**
+     * Push one interleaved buffer. Caller owns timing. Underrun does not throw.
+     */
+    write(pcm: Int16Array | Float32Array): void;
+    /**
+     * One-shot clip. Mixes into later `write()` calls once the stream is pumping.
+     * Before the first `write()`, the samples go to the device immediately.
+     */
+    play(source: PlaySource): Promise<void>;
+    dispose(): void;
+    private normalize;
+    private toDeviceS16;
+    private mixClips;
+    private push;
+}

package/dist/device.js

@@ -0,0 +1,172 @@
+import { SilentBackend } from './backends/silent.js';
+import { NativeBackend } from './backends/native.js';
+import { SpawnBackend } from './backends/spawn.js';
+import { findSpawnTool, pathDirsFrom, detectAudio, silentRequested } from './detect.js';
+import { decodeWav } from './wav.js';
+/**
+ * PCM output through the OS mixer. Kitty cannot carry audio; this never
+ * writes to the terminal.
+ *
+ * Apps that never import `@mudah-cli/audio` never load a backend.
+ */
+export class AudioOut {
+    sampleRate;
+    channels;
+    format;
+    backendKind;
+    spawnTool;
+    bytesWritten = 0;
+    backend;
+    clips = [];
+    wroteOnce = false;
+    disposed = false;
+    constructor(backend, sampleRate, channels, format) {
+        this.backend = backend;
+        this.sampleRate = sampleRate;
+        this.channels = channels;
+        this.format = format;
+        this.backendKind = backend.kind;
+        this.spawnTool = backend.spawnTool;
+    }
+    static async open(options = {}) {
+        const sampleRate = options.sampleRate ?? 44100;
+        const channels = options.channels ?? 2;
+        const format = options.format ?? 's16';
+        const framesPerBuffer = options.framesPerBuffer ?? 1024;
+        const env = options.env ?? process.env;
+        const requested = options.backend ?? 'auto';
+        const dirs = pathDirsFrom(env, options.pathDirs);
+        if (requested === 'silent' || (requested === 'auto' && silentRequested(env))) {
+            return new AudioOut(new SilentBackend(), sampleRate, channels, format);
+        }
+        const detected = detectAudio(env, options.pathDirs);
+        const tryNative = requested === 'native' || (requested === 'auto' && detected.backend === 'native');
+        if (tryNative) {
+            const native = await NativeBackend.tryOpen({ sampleRate, channels, format, framesPerBuffer });
+            if (native !== undefined)
+                return new AudioOut(native, sampleRate, channels, format);
+            if (requested === 'native') {
+                throw new Error('[audio] Native backend failed to load. Install audify (optional peer) and a C++ toolchain if no prebuild exists for this Node version.');
+            }
+        }
+        const trySpawn = requested === 'spawn' || requested === 'auto';
+        if (trySpawn) {
+            const tool = options.spawnTool ?? findSpawnTool(dirs);
+            if (tool !== undefined) {
+                return new AudioOut(new SpawnBackend(tool, { sampleRate, channels }, options.spawn, options.onUnderrun), sampleRate, channels, format);
+            }
+            if (requested === 'spawn') {
+                throw new Error('[audio] Spawn backend needs pw-play, paplay, or aplay on PATH.');
+            }
+        }
+        if (requested === 'auto') {
+            return new AudioOut(new SilentBackend(), sampleRate, channels, format);
+        }
+        throw new Error(`[audio] Backend ${requested} is not available.`);
+    }
+    /**
+     * Push one interleaved buffer. Caller owns timing. Underrun does not throw.
+     */
+    write(pcm) {
+        if (this.disposed)
+            return;
+        const samples = this.toDeviceS16(pcm);
+        this.mixClips(samples);
+        this.push(samples);
+        this.wroteOnce = true;
+    }
+    /**
+     * One-shot clip. Mixes into later `write()` calls once the stream is pumping.
+     * Before the first `write()`, the samples go to the device immediately.
+     */
+    async play(source) {
+        if (this.disposed)
+            return;
+        const clip = this.normalize(source);
+        if (this.wroteOnce) {
+            this.clips.push({ samples: clip, offset: 0 });
+            return;
+        }
+        this.push(clip);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.clips.length = 0;
+        this.backend.dispose();
+    }
+    normalize(source) {
+        const clip = source instanceof Uint8Array ? decodeWav(source) : source;
+        return remapChannels(clip.samples, clip.channels, this.channels);
+    }
+    toDeviceS16(pcm) {
+        if (pcm instanceof Int16Array)
+            return Int16Array.from(pcm);
+        const out = new Int16Array(pcm.length);
+        for (let i = 0; i < pcm.length; i++) {
+            const x = pcm[i] ?? 0;
+            out[i] = Math.max(-32768, Math.min(32767, Math.round(x * 32767)));
+        }
+        return out;
+    }
+    mixClips(into) {
+        for (const clip of this.clips) {
+            const remaining = clip.samples.length - clip.offset;
+            const n = Math.min(into.length, remaining);
+            for (let i = 0; i < n; i++) {
+                const mixed = (into[i] ?? 0) + (clip.samples[clip.offset + i] ?? 0);
+                into[i] = Math.max(-32768, Math.min(32767, mixed));
+            }
+            clip.offset += n;
+        }
+        for (let i = this.clips.length - 1; i >= 0; i--) {
+            const clip = this.clips[i];
+            if (clip !== undefined && clip.offset >= clip.samples.length)
+                this.clips.splice(i, 1);
+        }
+    }
+    push(samples) {
+        const bytes = this.format === 'f32' && this.backendKind === 'native' ? f32le(samples) : s16le(samples);
+        this.backend.write(bytes);
+        this.bytesWritten += bytes.byteLength;
+    }
+}
+function s16le(samples) {
+    const out = new Uint8Array(samples.length * 2);
+    const view = new DataView(out.buffer);
+    for (let i = 0; i < samples.length; i++)
+        view.setInt16(i * 2, samples[i] ?? 0, true);
+    return out;
+}
+function f32le(samples) {
+    const out = new Uint8Array(samples.length * 4);
+    const view = new DataView(out.buffer);
+    for (let i = 0; i < samples.length; i++)
+        view.setFloat32(i * 4, (samples[i] ?? 0) / 32768, true);
+    return out;
+}
+function remapChannels(samples, from, to) {
+    if (from === to)
+        return Int16Array.from(samples);
+    const frames = Math.floor(samples.length / from);
+    const out = new Int16Array(frames * to);
+    for (let f = 0; f < frames; f++) {
+        if (from === 1 && to === 2) {
+            const s = samples[f] ?? 0;
+            out[f * 2] = s;
+            out[f * 2 + 1] = s;
+        }
+        else if (from === 2 && to === 1) {
+            const l = samples[f * 2] ?? 0;
+            const r = samples[f * 2 + 1] ?? 0;
+            out[f] = (l + r) >> 1;
+        }
+        else {
+            for (let c = 0; c < to; c++)
+                out[f * to + c] = samples[f * from + Math.min(c, from - 1)] ?? 0;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=device.js.map

package/dist/device.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { AudioOut, } from './device.js';
+export { detectAudio, canResolveAudify, findSpawnTool, silentRequested, } from './detect.js';
+export { decodeWav, encodeWav, } from './wav.js';
+export { spawnCommand, } from './backends/spawn-command.js';
+export type { AudioBackendKind, AudioClip, AudioDetection, AudioFormat, AudioOutOptions, PlaySource, SpawnTool, } from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { AudioOut, } from './device.js';
+export { detectAudio, canResolveAudify, findSpawnTool, silentRequested, } from './detect.js';
+export { decodeWav, encodeWav, } from './wav.js';
+export { spawnCommand, } from './backends/spawn-command.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,SAAS,EACT,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,YAAY,GACb,MAAM,6BAA6B,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+export type AudioFormat = 's16' | 'f32';
+export type AudioBackendKind = 'auto' | 'native' | 'spawn' | 'silent';
+export type SpawnTool = 'pw-play' | 'paplay' | 'aplay';
+export interface AudioOutOptions {
+    sampleRate?: number;
+    channels?: number;
+    /** Interleaved little-endian. Default `s16`. Spawn always sends s16. */
+    format?: AudioFormat;
+    /** Hint for native RtAudio and for callers that pump a fixed block. Default 1024. */
+    framesPerBuffer?: number;
+    backend?: AudioBackendKind;
+    /** Called when a write cannot reach the device. Never throws. */
+    onUnderrun?: () => void;
+    /** Environment for `CI` / `MUDAH_NO_AUDIO` (tests pass a map). */
+    env?: NodeJS.ProcessEnv;
+    /** Override PATH lookup (tests). */
+    pathDirs?: readonly string[];
+    /** Inject spawn (tests). */
+    spawn?: SpawnFn;
+    /** Skip PATH lookup (tests). */
+    spawnTool?: SpawnTool;
+}
+export type SpawnFn = (command: string, args: readonly string[], options: {
+    stdio: ['pipe', 'ignore', 'ignore'];
+}) => SpawnedPlayer;
+export interface SpawnedPlayer {
+    stdin: {
+        write(data: Uint8Array): boolean;
+        end(): void;
+    } | null;
+    kill(): void;
+    on?(event: 'error' | 'exit', listener: (...args: unknown[]) => void): unknown;
+}
+export interface AudioClip {
+    readonly samples: Int16Array;
+    readonly sampleRate: number;
+    readonly channels: number;
+}
+export type PlaySource = Uint8Array | AudioClip;
+export interface AudioDetection {
+    readonly backend: Exclude<AudioBackendKind, 'auto'>;
+    readonly native: boolean;
+    readonly spawnTool: SpawnTool | undefined;
+}
+export interface AudioBackend {
+    readonly kind: Exclude<AudioBackendKind, 'auto'>;
+    readonly spawnTool?: SpawnTool;
+    write(bytes: Uint8Array): void;
+    dispose(): void;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/wav.d.ts

@@ -0,0 +1,7 @@
+import type { AudioClip } from './types.js';
+/**
+ * Decode a PCM 16-bit little-endian WAV. Other encodings throw.
+ */
+export declare function decodeWav(bytes: Uint8Array): AudioClip;
+/** Encode PCM 16-bit little-endian WAV. Used by tests and one-shot helpers. */
+export declare function encodeWav(clip: AudioClip): Uint8Array;

package/dist/wav.js

@@ -0,0 +1,76 @@
+const RIFF = 0x46464952;
+const WAVE = 0x45564157;
+const FMT = 0x20746d66;
+const DATA = 0x61746164;
+/**
+ * Decode a PCM 16-bit little-endian WAV. Other encodings throw.
+ */
+export function decodeWav(bytes) {
+    const buf = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    const view = new DataView(buf);
+    if (bytes.byteLength < 12 || view.getUint32(0, true) !== RIFF || view.getUint32(8, true) !== WAVE) {
+        throw new Error('[audio] WAV payload is not a RIFF/WAVE file.');
+    }
+    let offset = 12;
+    let channels = 0;
+    let sampleRate = 0;
+    let bits = 0;
+    let audioFormat = 0;
+    let data;
+    while (offset + 8 <= bytes.byteLength) {
+        const id = view.getUint32(offset, true);
+        const size = view.getUint32(offset + 4, true);
+        const start = offset + 8;
+        const end = start + size;
+        if (end > bytes.byteLength)
+            throw new Error('[audio] WAV chunk overruns the buffer.');
+        if (id === FMT) {
+            audioFormat = view.getUint16(start, true);
+            channels = view.getUint16(start + 2, true);
+            sampleRate = view.getUint32(start + 4, true);
+            bits = view.getUint16(start + 14, true);
+        }
+        else if (id === DATA) {
+            data = new Uint8Array(buf, start, size);
+        }
+        offset = end + (size % 2);
+    }
+    if (audioFormat !== 1)
+        throw new Error('[audio] WAV encoding is not PCM (format 1).');
+    if (bits !== 16)
+        throw new Error(`[audio] WAV bits-per-sample is ${bits}, need 16.`);
+    if (channels < 1)
+        throw new Error('[audio] WAV has no channels.');
+    if (data === undefined)
+        throw new Error('[audio] WAV has no data chunk.');
+    const samples = new Int16Array(data.byteLength / 2);
+    const dataView = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    for (let i = 0; i < samples.length; i++)
+        samples[i] = dataView.getInt16(i * 2, true);
+    return { samples, sampleRate, channels };
+}
+/** Encode PCM 16-bit little-endian WAV. Used by tests and one-shot helpers. */
+export function encodeWav(clip) {
+    const dataBytes = clip.samples.byteLength;
+    const buffer = new ArrayBuffer(44 + dataBytes);
+    const view = new DataView(buffer);
+    const out = new Uint8Array(buffer);
+    const blockAlign = clip.channels * 2;
+    const byteRate = clip.sampleRate * blockAlign;
+    view.setUint32(0, RIFF, true);
+    view.setUint32(4, 36 + dataBytes, true);
+    view.setUint32(8, WAVE, true);
+    view.setUint32(12, FMT, true);
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true);
+    view.setUint16(22, clip.channels, true);
+    view.setUint32(24, clip.sampleRate, true);
+    view.setUint32(28, byteRate, true);
+    view.setUint16(32, blockAlign, true);
+    view.setUint16(34, 16, true);
+    view.setUint32(36, DATA, true);
+    view.setUint32(40, dataBytes, true);
+    out.set(new Uint8Array(clip.samples.buffer, clip.samples.byteOffset, dataBytes), 44);
+    return out;
+}
+//# sourceMappingURL=wav.js.map

package/dist/wav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wav.js","sourceRoot":"","sources":["../src/wav.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@mudah-cli/audio",
+  "version": "0.5.0",
+  "description": "Play PCM through the OS mixer from a Mudah app (streaming output and one-shot WAV). Optional: apps that never import it never load an audio backend.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=26"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "audify": "^1.10.0"
+  },
+  "peerDependenciesMeta": {
+    "audify": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}