@buffered-audio/nodes 0.16.0 → 0.17.0

package/README.md

@@ -63,13 +63,27 @@ export default chain(read("input.wav"), normalize(), trim({ threshold: -60 }), w
 Render a `.bag` (Buffered Audio Graph) file. BAG files are JSON-serialized graph definitions.
 
 ```bash
-npx @buffered-audio/nodes render --bag pipeline.bag
+npx @buffered-audio/nodes render pipeline.bag
 ```
 
-| Flag                        | Description                         |
-| --------------------------- | ----------------------------------- |
-| `--chunk-size <samples>`    | Chunk size in samples               |
-| `--high-water-mark <count>` | Stream backpressure high water mark |
+| Flag                        | Description                                                  |
+| --------------------------- | ----------------------------------------------------------- |
+| `--chunk-size <samples>`    | Chunk size in samples                                       |
+| `--high-water-mark <count>` | Stream backpressure high water mark                         |
+| `--param <name=value>`      | Bind a `{{name}}` template placeholder (repeatable)         |
+
+#### Template parameters
+
+String values in a bag's node `parameters` may contain `{{name}}` placeholders. Each `--param name=value` binds one for that render; the same bag renders different inputs and outputs without editing the file. Every placeholder must be bound, and every `--param` must match a placeholder, or the render fails before any audio work.
+
+```json
+{ "id": "a", "packageName": "@buffered-audio/nodes", "packageVersion": "0.16.0", "nodeName": "Read",  "parameters": { "path": "{{episode}}/raw.wav" } }
+{ "id": "z", "packageName": "@buffered-audio/nodes", "packageVersion": "0.16.0", "nodeName": "Write", "parameters": { "path": "{{episode}}/master.wav" } }
+```
+
+```bash
+npx @buffered-audio/nodes render master.bag --param episode=./e260
+```
 
 ## Nodes
 
@@ -164,7 +178,7 @@ Remove background noise from speech using DTLN neural network
 
 ### Duplicate Channels
 
-Duplicate a mono signal into multiple identical output channels
+Duplicate a mono signal into multiple identical output channels; requires exactly 1 input channel, throws otherwise
 
 [Source](./src/transforms/duplicate-channels/index.ts)
 
@@ -285,7 +299,7 @@ Add silence to start or end of audio
 
 ### Pan
 
-Position mono signal in stereo field or adjust stereo balance
+Position mono signal in stereo field or adjust stereo balance; throws for inputs with more than 2 channels
 
 [Source](./src/transforms/pan/index.ts)
 
@@ -404,7 +418,6 @@ Host a chain of VST3 effect plugins via Pedalboard (whole-file offline mode)
 | `stages[].pluginPath` | string | — | VST3 plugin file or bundle |
 | `stages[].pluginName` | string, optional | — | Sub-plugin name when pluginPath is a multi-plugin shell (e.g. WaveShell) |
 | `stages[].presetPath` | string, optional | — | Optional .vstpreset state file applied after the plugin loads |
-| `stages[].parameters` | record, optional | — | Optional parameter overrides applied after presetPath. Keys map to Pedalboard parameter names exposed by the plugin. |
 | `bypass` | boolean | `false` | Pass audio through unchanged (no subprocess spawn) |
 
 ### Waveform
@@ -508,9 +521,9 @@ class NormalizeStream extends BufferedTransformStream<NormalizeProperties> {
 }
 
 class NormalizeNode extends TransformNode<NormalizeProperties> {
-	static override readonly moduleName = "Normalize";
+	static override readonly nodeName = "Normalize";
 	static override readonly packageName = "buffered-audio-nodes";
-	static override readonly moduleDescription = "Adjust peak or loudness level to a target ceiling";
+	static override readonly nodeDescription = "Adjust peak or loudness level to a target ceiling";
 	static override readonly schema = schema;
 
 	override readonly type = ["buffered-audio-node", "transform", "normalize"] as const;

package/dist/cli.js

@@ -4,6 +4,88 @@ import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
 import { SourceNode, validateGraphDefinition, renderGraph } from '@buffered-audio/core';
 
+var labelOf = (node) => node.id ? `${node.nodeName}#${node.id}` : node.nodeName;
+var collect = (value, previous) => [...previous, value];
+function parseParams(entries) {
+  const parameters = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const separatorIndex = entry.indexOf("=");
+    if (separatorIndex === -1) {
+      process.stderr.write(`Error: --param must be in name=value form, got "${entry}"
+`);
+      process.exit(1);
+    }
+    const name = entry.slice(0, separatorIndex);
+    const value = entry.slice(separatorIndex + 1);
+    if (name === "") {
+      process.stderr.write(`Error: --param name must not be empty, got "${entry}"
+`);
+      process.exit(1);
+    }
+    if (parameters.has(name)) {
+      process.stderr.write(`Error: --param ${name} given more than once
+`);
+      process.exit(1);
+    }
+    parameters.set(name, value);
+  }
+  return Object.fromEntries(parameters);
+}
+function createEventSink() {
+  const totals = /* @__PURE__ */ new Map();
+  const onEvent = (node, event) => {
+    const label = labelOf(node);
+    switch (event.kind) {
+      case "started":
+        process.stdout.write(`[${label}] started
+`);
+        break;
+      case "progress":
+        if (event.framesTotal !== void 0) {
+          const percent = Math.round(event.framesDone / event.framesTotal * 100);
+          process.stdout.write(`[${label}] ${event.phase} ${percent}%
+`);
+        } else {
+          process.stdout.write(`[${label}] ${event.phase} frames=${event.framesDone}
+`);
+        }
+        break;
+      case "log": {
+        const data = event.data ? Object.entries(event.data).map(([key, value]) => `${key}=${String(value)}`) : [];
+        const parts = [event.message, ...data].join(" ");
+        const prefix = event.level === "warn" ? "warn: " : "";
+        process.stdout.write(`${prefix}[${label}] ${parts}
+`);
+        break;
+      }
+      case "finished":
+        totals.set(node, { framesDone: event.framesDone, processingMs: event.processingMs });
+        process.stdout.write(`[${label}] finished
+`);
+        break;
+    }
+  };
+  const printSummary = (sources) => {
+    for (const [node, { framesDone, processingMs }] of totals) {
+      const label = labelOf(node);
+      if (processingMs !== void 0) {
+        process.stdout.write(`[${label}] processed ${framesDone} frames in ${Math.round(processingMs)}ms
+`);
+      } else {
+        process.stdout.write(`[${label}] processed ${framesDone} frames
+`);
+      }
+    }
+    for (const source of sources) {
+      const timing = source.renderTiming;
+      if (!timing) continue;
+      const label = labelOf({ nodeName: source.constructor.nodeName, id: source.id });
+      process.stdout.write(`[${label}] total ${(timing.totalMs / 1e3).toFixed(1)}s, ${timing.realTimeMultiplier.toFixed(1)}x RT
+`);
+    }
+  };
+  return { onEvent, printSummary };
+}
 var program = new Command();
 program.name("buffered-audio-nodes").description("Process audio through buffered audio node pipelines");
 program.command("process").description("Run an async audio processing pipeline").requiredOption("--pipeline <file>", "TypeScript file with default SourceAsyncModule export").option("--chunk-size <samples>", "Chunk size in samples").option("--high-water-mark <count>", "Stream backpressure high water mark").action(async (options) => {
@@ -34,19 +116,22 @@ program.command("process").description("Run an async audio processing pipeline")
 `);
       process.exit(1);
     }
+    const sink = createEventSink();
     const renderOptions = {
       chunkSize,
-      highWaterMark
+      highWaterMark,
+      onEvent: sink.onEvent
     };
     process.stdout.write(`Processing pipeline: ${pipelinePath}
 `);
     await source.render(renderOptions);
+    sink.printSummary([source]);
     process.stdout.write("Done.\n");
   } finally {
     await unregister();
   }
 });
-program.command("render").description("Render a .bag graph definition file").argument("<file>", "Path to .bag file (JSON)").option("--chunk-size <samples>", "Chunk size in samples").option("--high-water-mark <count>", "Stream backpressure high water mark").action(async (file, options) => {
+program.command("render").description("Render a .bag graph definition file").argument("<file>", "Path to .bag file (JSON)").option("--chunk-size <samples>", "Chunk size in samples").option("--high-water-mark <count>", "Stream backpressure high water mark").option("--param <name=value>", "Bind a {{name}} template placeholder in the bag (repeatable)", collect, []).action(async (file, options) => {
   const bagPath = resolve(file);
   if (!existsSync(bagPath)) {
     process.stderr.write(`Error: file not found: ${bagPath}
@@ -66,18 +151,27 @@ program.command("render").description("Render a .bag graph definition file").arg
         for (const value of Object.values(mod)) {
           if (typeof value !== "function") continue;
           const ctor = value;
-          if (typeof ctor.moduleName !== "string") continue;
-          packageMap.set(ctor.moduleName, ctor);
+          if (typeof ctor.nodeName !== "string") continue;
+          packageMap.set(ctor.nodeName, ctor);
         }
         registry.set(nodeDef.packageName, packageMap);
       }
     }
     const chunkSize = options.chunkSize ? parseInt(options.chunkSize, 10) : void 0;
     const highWaterMark = options.highWaterMark ? parseInt(options.highWaterMark, 10) : void 0;
+    const parameters = parseParams(options.param);
+    const sink = createEventSink();
     process.stdout.write(`Rendering graph: ${definition.name}
 `);
-    await renderGraph(definition, registry, { chunkSize, highWaterMark });
-    process.stdout.write("Done.\n");
+    try {
+      const sources = await renderGraph(definition, registry, { chunkSize, highWaterMark, parameters, onEvent: sink.onEvent });
+      sink.printSummary(sources);
+      process.stdout.write("Done.\n");
+    } catch (error) {
+      process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+      process.exitCode = 1;
+    }
   } finally {
     await unregister();
   }