@acpfx/audio-player 0.3.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024-2026 acpfx contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @acpfx/audio-player
+
+Audio mixer with SFX support. Plays speech audio through the system speaker, with optional sound effects for agent thinking and tool use.
+
+## Usage
+
+This package is a pipeline node for [@acpfx/cli](../orchestrator/README.md). See the CLI package for installation and usage.
+
+## Manifest
+
+- **Consumes:** `audio.chunk`, `agent.thinking`, `agent.tool_start`, `agent.tool_done`, `agent.delta`, `agent.complete`, `control.interrupt`
+- **Emits:** `audio.chunk`, `player.status`, `lifecycle.ready`, `lifecycle.done`
+
+## Settings
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `speechSource` | string | | Node name whose `audio.chunk` events are speech |
+| `sampleRate` | number | `16000` | Audio sample rate in Hz |
+| `thinkingClip` | string | | Path to thinking SFX audio clip |
+| `toolClip` | string | | Path to tool-use SFX audio clip |
+| `sfxVolume` | number | `0.3` | SFX volume multiplier (0-1) |
+
+## Pipeline Example
+
+```yaml
+nodes:
+  player:
+    use: "@acpfx/audio-player"
+    settings: { speechSource: tts, sampleRate: 16000 }
+    outputs: [mic]  # reference audio for AEC
+```
+
+## License
+
+ISC

package/dist/index.js

@@ -0,0 +1,337 @@
+// src/index.ts
+import { readFileSync as readFileSync2, existsSync } from "node:fs";
+import { join as join2, dirname as dirname2 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../node-sdk/src/index.ts
+import { createInterface } from "node:readline";
+
+// ../core/src/config.ts
+import { parse as parseYaml } from "yaml";
+
+// ../core/src/manifest.ts
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { z as z2 } from "zod";
+
+// ../core/src/acpfx-flags.ts
+import { z } from "zod";
+var SetupCheckResponseSchema = z.object({
+  needed: z.boolean(),
+  description: z.string().optional()
+});
+var SetupProgressSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("progress"),
+    message: z.string(),
+    pct: z.number().optional()
+  }),
+  z.object({ type: z.literal("complete"), message: z.string() }),
+  z.object({ type: z.literal("error"), message: z.string() })
+]);
+var UnsupportedFlagResponseSchema = z.object({
+  unsupported: z.boolean(),
+  flag: z.string()
+});
+
+// ../core/src/manifest.ts
+var ArgumentTypeSchema = z2.enum(["string", "number", "boolean"]);
+var ManifestArgumentSchema = z2.object({
+  type: ArgumentTypeSchema,
+  default: z2.unknown().optional(),
+  description: z2.string().optional(),
+  required: z2.boolean().optional(),
+  enum: z2.array(z2.unknown()).optional()
+});
+var ManifestEnvFieldSchema = z2.object({
+  required: z2.boolean().optional(),
+  description: z2.string().optional()
+});
+var NodeManifestSchema = z2.object({
+  name: z2.string(),
+  description: z2.string().optional(),
+  consumes: z2.array(z2.string()),
+  emits: z2.array(z2.string()),
+  arguments: z2.record(z2.string(), ManifestArgumentSchema).optional(),
+  additional_arguments: z2.boolean().optional(),
+  env: z2.record(z2.string(), ManifestEnvFieldSchema).optional()
+});
+function handleAcpfxFlags(manifestPath) {
+  const acpfxFlag = process.argv.find((a) => a.startsWith("--acpfx-"));
+  const legacyManifest = process.argv.includes("--manifest");
+  if (!acpfxFlag && !legacyManifest) return;
+  const flag = acpfxFlag ?? "--acpfx-manifest";
+  switch (flag) {
+    case "--acpfx-manifest":
+      printManifest(manifestPath);
+      break;
+    case "--acpfx-setup-check":
+      process.stdout.write(JSON.stringify({ needed: false }) + "\n");
+      process.exit(0);
+      break;
+    default:
+      process.stdout.write(
+        JSON.stringify({ unsupported: true, flag }) + "\n"
+      );
+      process.exit(0);
+  }
+}
+function handleManifestFlag(manifestPath) {
+  handleAcpfxFlags(manifestPath);
+}
+function printManifest(manifestPath) {
+  if (!manifestPath) {
+    const script = process.argv[1];
+    const scriptDir = dirname(script);
+    const scriptBase = script.replace(/\.[^.]+$/, "");
+    const colocated = `${scriptBase}.manifest.json`;
+    try {
+      readFileSync(colocated);
+      manifestPath = colocated;
+    } catch {
+      manifestPath = join(scriptDir, "manifest.json");
+    }
+  }
+  try {
+    const content = readFileSync(manifestPath, "utf8");
+    process.stdout.write(content.trim() + "\n");
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`Failed to read manifest: ${err}
+`);
+    process.exit(1);
+  }
+}
+
+// ../node-sdk/src/index.ts
+var NODE_NAME = process.env.ACPFX_NODE_NAME ?? "unknown";
+function emit(event) {
+  process.stdout.write(JSON.stringify(event) + "\n");
+}
+function log(level, message) {
+  emit({ type: "log", level, component: NODE_NAME, message });
+}
+log.info = (message) => log("info", message);
+log.warn = (message) => log("warn", message);
+log.error = (message) => log("error", message);
+log.debug = (message) => log("debug", message);
+function onEvent(handler) {
+  const rl = createInterface({ input: process.stdin });
+  rl.on("line", (line) => {
+    if (!line.trim()) return;
+    try {
+      const event = JSON.parse(line);
+      handler(event);
+    } catch {
+    }
+  });
+  return rl;
+}
+
+// src/index.ts
+var __dirname = dirname2(fileURLToPath(import.meta.url));
+handleManifestFlag();
+var settings = JSON.parse(process.env.ACPFX_SETTINGS || "{}");
+var SPEECH_SOURCE = settings.speechSource ?? "tts";
+var SAMPLE_RATE = settings.sampleRate ?? 16e3;
+var SFX_VOLUME = settings.sfxVolume ?? 0.3;
+var BYTES_PER_SAMPLE = 2;
+function findBundledSound(filename) {
+  const candidates = [
+    join2(__dirname, "..", "sounds", filename),
+    // dev: src/../sounds/
+    join2(__dirname, "sounds", filename),
+    // dist: next to bundled .js
+    join2(__dirname, "..", "..", "sounds", filename)
+    // npm package layout
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+function applyGain(pcm, gain) {
+  if (gain === 1) return pcm;
+  const out = Buffer.alloc(pcm.length);
+  for (let i = 0; i < pcm.length; i += 2) {
+    const sample = Math.max(-32768, Math.min(32767, Math.round(pcm.readInt16LE(i) * gain)));
+    out.writeInt16LE(sample, i);
+  }
+  return out;
+}
+function loadWavPcm(filePath) {
+  try {
+    const raw = readFileSync2(filePath);
+    return raw.subarray(44);
+  } catch (err) {
+    log.error(`Failed to load WAV: ${filePath}: ${err instanceof Error ? err.message : err}`);
+    return null;
+  }
+}
+var agentState = "idle";
+var playingKind = null;
+var thinkingPcm = null;
+var toolPcm = null;
+var sfxLoopTimer = null;
+var sfxActive = false;
+var sfxClipOffset = 0;
+var sfxCurrentClip = null;
+var SFX_CHUNK_MS = 100;
+var SFX_CHUNK_BYTES = Math.floor(SAMPLE_RATE * BYTES_PER_SAMPLE * SFX_CHUNK_MS / 1e3);
+function emitStatus() {
+  emit({
+    type: "player.status",
+    playing: playingKind,
+    agentState,
+    sfxActive
+  });
+}
+function emitChunk(pcm, kind) {
+  const durationMs = Math.round(pcm.length / (SAMPLE_RATE * BYTES_PER_SAMPLE) * 1e3);
+  emit({
+    type: "audio.chunk",
+    trackId: "player",
+    format: "pcm_s16le",
+    sampleRate: SAMPLE_RATE,
+    channels: 1,
+    data: pcm.toString("base64"),
+    durationMs,
+    kind
+  });
+}
+function startSfxLoop() {
+  if (sfxActive) return;
+  const clip = agentState === "thinking" ? thinkingPcm : agentState === "tool" ? toolPcm : null;
+  if (!clip) return;
+  sfxActive = true;
+  playingKind = "sfx";
+  sfxCurrentClip = applyGain(clip, SFX_VOLUME);
+  sfxClipOffset = 0;
+  log.info(`Starting SFX loop (${agentState})`);
+  writeSfxChunk();
+  sfxLoopTimer = setInterval(writeSfxChunk, SFX_CHUNK_MS);
+}
+function writeSfxChunk() {
+  if (!sfxActive || !sfxCurrentClip) return;
+  const remaining = sfxCurrentClip.length - sfxClipOffset;
+  if (remaining <= 0) {
+    sfxClipOffset = 0;
+  }
+  const bytesToWrite = Math.min(SFX_CHUNK_BYTES, sfxCurrentClip.length - sfxClipOffset);
+  const chunk = sfxCurrentClip.subarray(sfxClipOffset, sfxClipOffset + bytesToWrite);
+  sfxClipOffset += bytesToWrite;
+  emitChunk(chunk, "sfx");
+}
+function stopSfxLoop() {
+  if (sfxLoopTimer) {
+    clearInterval(sfxLoopTimer);
+    sfxLoopTimer = null;
+  }
+  if (sfxActive) {
+    sfxActive = false;
+    log.info("Stopped SFX loop");
+  }
+  if (playingKind === "sfx") {
+    playingKind = null;
+  }
+}
+var THINKING_DELAY_MS = 500;
+var sfxDelayTimer = null;
+function cancelSfxDelay() {
+  if (sfxDelayTimer) {
+    clearTimeout(sfxDelayTimer);
+    sfxDelayTimer = null;
+  }
+}
+function flushSfxForSpeech() {
+  stopSfxLoop();
+}
+function handleEvent(event) {
+  const type = event.type;
+  const from = event._from;
+  if (type === "audio.chunk") {
+    if (from !== SPEECH_SOURCE) {
+      log.debug(`Ignoring audio.chunk from "${from}" (expected "${SPEECH_SOURCE}")`);
+      return;
+    }
+    cancelSfxDelay();
+    if (sfxActive) {
+      flushSfxForSpeech();
+    }
+    playingKind = "speech";
+    const pcm = Buffer.from(event.data, "base64");
+    emitChunk(pcm, "speech");
+    return;
+  }
+  if (type === "agent.thinking") {
+    agentState = "thinking";
+    cancelSfxDelay();
+    sfxDelayTimer = setTimeout(() => {
+      sfxDelayTimer = null;
+      if (agentState === "thinking") startSfxLoop();
+    }, THINKING_DELAY_MS);
+    emitStatus();
+    return;
+  }
+  if (type === "agent.tool_start") {
+    agentState = "tool";
+    cancelSfxDelay();
+    stopSfxLoop();
+    startSfxLoop();
+    emitStatus();
+    return;
+  }
+  if (type === "agent.tool_done") {
+    agentState = "idle";
+    cancelSfxDelay();
+    stopSfxLoop();
+    emitStatus();
+    return;
+  }
+  if (type === "agent.delta") {
+    if (agentState !== "idle") {
+      agentState = "idle";
+      cancelSfxDelay();
+      emitStatus();
+    }
+    return;
+  }
+  if (type === "agent.complete") {
+    agentState = "idle";
+    cancelSfxDelay();
+    stopSfxLoop();
+    emitStatus();
+    return;
+  }
+  if (type === "control.interrupt") {
+    agentState = "idle";
+    cancelSfxDelay();
+    stopSfxLoop();
+    playingKind = null;
+    return;
+  }
+}
+function main() {
+  const thinkingPath = settings.thinkingClip ?? findBundledSound("thinking.wav");
+  const toolPath = settings.toolClip ?? findBundledSound("typing.wav");
+  if (thinkingPath) {
+    thinkingPcm = loadWavPcm(thinkingPath);
+    if (thinkingPcm) log.info(`Loaded thinking clip: ${thinkingPath} (${thinkingPcm.length} bytes)`);
+  }
+  if (toolPath) {
+    toolPcm = loadWavPcm(toolPath);
+    if (toolPcm) log.info(`Loaded tool clip: ${toolPath} (${toolPcm.length} bytes)`);
+  }
+  emit({ type: "lifecycle.ready", component: "audio-player" });
+  const rl = onEvent(handleEvent);
+  rl.on("close", () => {
+    stopSfxLoop();
+    emit({ type: "lifecycle.done", component: "audio-player" });
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    stopSfxLoop();
+    process.exit(0);
+  });
+}
+main();

package/dist/manifest.json

@@ -0,0 +1 @@
+{"name":"audio-player","description":"Audio mixer with SFX — emits audio.chunk for downstream playback","consumes":["audio.chunk","agent.thinking","agent.tool_start","agent.tool_done","agent.delta","agent.complete","control.interrupt"],"emits":["audio.chunk","player.status","lifecycle.ready","lifecycle.done"],"arguments":{"speechSource":{"type":"string","description":"Node name whose audio.chunk events are speech (for filtering)"},"sampleRate":{"type":"number","default":16000,"description":"Audio sample rate in Hz"},"thinkingClip":{"type":"string","description":"Path to thinking SFX audio clip"},"toolClip":{"type":"string","description":"Path to tool-use SFX audio clip"},"sfxVolume":{"type":"number","default":0.3,"description":"SFX volume multiplier (0-1)"}}}

package/manifest.yaml

@@ -0,0 +1,33 @@
+name: audio-player
+description: Audio mixer with SFX — emits audio.chunk for downstream playback
+consumes:
+  - audio.chunk
+  - agent.thinking
+  - agent.tool_start
+  - agent.tool_done
+  - agent.delta
+  - agent.complete
+  - control.interrupt
+emits:
+  - audio.chunk
+  - player.status
+  - lifecycle.ready
+  - lifecycle.done
+arguments:
+  speechSource:
+    type: string
+    description: "Node name whose audio.chunk events are speech (for filtering)"
+  sampleRate:
+    type: number
+    default: 16000
+    description: "Audio sample rate in Hz"
+  thinkingClip:
+    type: string
+    description: "Path to thinking SFX audio clip"
+  toolClip:
+    type: string
+    description: "Path to tool-use SFX audio clip"
+  sfxVolume:
+    type: number
+    default: 0.3
+    description: "SFX volume multiplier (0-1)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acpfx/audio-player",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "bin": {
     "acpfx-audio-player": "./dist/index.js"
@@ -8,6 +8,7 @@
   "main": "./dist/index.js",
   "files": [
     "dist",
+    "manifest.yaml",
     "sounds"
   ],
   "dependencies": {
@@ -16,6 +17,6 @@
     "@acpfx/node-sdk": "0.3.0"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external"
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external && node ../../scripts/copy-manifest.js"
   }
 }