@motionscript/audio 0.1.0 → 0.1.1-alpha.0

package/dist/waveform/shared.js

@@ -1,25 +1,8 @@
-import { Graphics2D } from "@motionscript/sdk";
-/**
- * Geometry and paint shared by the two waveform nodes.
- *
- * They draw the same object — a row of bars whose heights are loudness — and
- * differ only in what decides the heights: the whole file for one, a window
- * around the playhead for the other. Everything about *how a row of bars is
- * laid out and painted* is therefore common, and lives here so the two cannot
- * drift into looking like different components.
- */
+import { Graphics2D, clamp } from "@motionscript/sdk";
 /** How a bar is grown out of its baseline. */
 export const WAVEFORM_ALIGNMENTS = ["center", "bottom"];
-/** What the bars are shaped like. */
 export const WAVEFORM_STYLES = ["bars", "line", "blocks"];
-/**
- * The colours voices are drawn in when nobody has assigned any.
- *
- * Eight hues that can be told apart at a glance, handed out by voice index. They
- * are literals rather than looked up, because a scene has to build in a
- * headless render with no database in scope; a host that names its voices
- * supplies its own colours instead.
- */
+/** Eight distinct hues handed out by voice index. Literals, because a scene builds headless with no database in scope; a host that names its voices supplies its own. */
 export const VOICE_PALETTE = [
     "#6366f1",
     "#14b8a6",
@@ -36,17 +19,10 @@ export function voiceColor(index) {
         VOICE_PALETTE.length];
 }
 /**
- * Lays a row of bars out across a box.
- *
- * The gap is stated as a *fraction of the pitch* rather than in pixels, and
- * that is the one decision here worth stating out loud: the bar count is a
- * control, so a gap in pixels would silently become a solid block at 200 bars
- * and a picket fence at 20. As a fraction, the row keeps the same rhythm at
- * every density — which is what lets the count be a slider anyone can drag.
- *
- * A bar is never thinner than a hairline and never shorter than one either: a
- * silent passage has to read as "audio, and nothing here" rather than as a hole
- * in the drawing.
+ * Lays a row of bars across a box. The gap is a fraction of the pitch, not px:
+ * the bar count is a control, and a px gap would become a solid block at 200
+ * bars and a picket fence at 20. A bar is never thinner or shorter than a
+ * hairline, so a silent passage reads as audio with nothing in it, not a hole.
  */
 export function layOutBars(bars, options) {
     const { width, height, gap, align, gain, floor } = options;
@@ -54,18 +30,15 @@ export function layOutBars(bars, options) {
     if (count === 0 || width <= 0 || height <= 0)
         return [];
     const pitch = width / count;
-    const barWidth = Math.max(1, pitch * (1 - clamp01(gap)));
-    // The tallest a bar may be. Centre-aligned bars grow both ways from the
-    // middle, so the *half* is what a magnitude of 1 fills.
+    const barWidth = Math.max(1, pitch * (1 - clamp(gap, 0, 1)));
+    // Centre-aligned bars grow both ways, so half the height is what a magnitude of 1 fills.
     const full = align === "center" ? height / 2 : height;
     const out = new Array(count);
     for (let i = 0; i < count; i++) {
-        const magnitude = clamp01(bars[i].magnitude * gain);
-        const reach = Math.max(full * clamp01(floor), full * magnitude);
+        const magnitude = clamp(bars[i].magnitude * gain, 0, 1);
+        const reach = Math.max(full * clamp(floor, 0, 1), full * magnitude);
         const x = -width / 2 + pitch * i + (pitch - barWidth) / 2;
-        // A hairline minimum, taken before the position so the bar stays inside the
-        // box: a silent bar 1px tall that kept the position of a zero-height one
-        // would hang half a pixel (centred) or a whole pixel (bottom) outside it.
+        // The hairline minimum is taken before the position, or a 1px bar placed as if zero-height would hang outside the box.
         const h = Math.max(1, align === "center" ? reach * 2 : reach);
         out[i] =
             align === "center"
@@ -75,14 +48,10 @@ export function layOutBars(bars, options) {
     return out;
 }
 /**
- * Draws a run of bars in one paint.
- *
- * Batched by colour by the caller, and this is why: every `Graphics2D` handed to
- * `ctx.draw` is a surface the renderer composites, so a bar apiece would be a
- * thousand surfaces a frame. Chaining the rects of one colour into a single
- * `Graphics2D` before filling makes it one — and, as a bonus, a gradient fill
- * maps across the whole run rather than restarting inside every bar, which is
- * the behaviour anyone reaching for a gradient here actually wants.
+ * Draws a run of bars in one paint. Callers batch by colour: every `Graphics2D`
+ * handed to `ctx.draw` is a surface the renderer composites, so a bar apiece
+ * would be a thousand surfaces a frame. One `Graphics2D` per run also maps a
+ * gradient across the whole run instead of restarting inside every bar.
  */
 export function paintBars(boxes, fill, radius) {
     if (boxes.length === 0)
@@ -93,25 +62,17 @@ export function paintBars(boxes, fill, radius) {
     for (const box of boxes) {
         graphics.rect({
             x: box.x + box.width / 2,
-            // The box is stated y-down and the rect is drawn y-up. A centred bar is
-            // symmetric about the middle, so only a bottom-aligned one shows the flip.
+            // The box is y-down and the rect y-up; only a bottom-aligned bar shows the flip.
             y: -(box.y + box.height / 2),
             width: box.width,
             height: box.height,
-            // Never rounder than the bar is wide, or a thin bar becomes a lozenge
-            // whose ends taper away to nothing.
+            // A thin bar rounder than it is wide becomes a lozenge.
             cornerRadius: Math.min(radius, box.width / 2, box.height / 2),
         });
     }
     return graphics.fill(fill);
 }
-/**
- * Groups bars by the paint they take, preserving order within each group.
- *
- * The seam that makes {@link paintBars} worth batching: a diarized waveform has
- * as many colours as it has voices, not as many as it has bars, so a
- * conversation of two people is two draws however long it runs.
- */
+/** Groups bars by the paint they take, in order within each group: a diarized waveform has as many colours as voices, so two people is two draws however long it runs. */
 export function groupByPaint(boxes, keyOf) {
     const groups = new Map();
     for (let i = 0; i < boxes.length; i++) {
@@ -124,22 +85,23 @@ export function groupByPaint(boxes, keyOf) {
     }
     return groups;
 }
-export function clamp01(value) {
-    return value < 0 ? 0 : value > 1 ? 1 : value;
+/**
+ * The colour of a `voice:N` group key, or `fallback` for a bad index. Always a
+ * colour string, never one of the node's fills: a voice is identified by hue, so
+ * a gradient or image would defeat the point, and it keeps these paints from
+ * declaring assets.
+ */
+export function voiceFill(key, voiceColors, fallback) {
+    const voice = Number(key.slice("voice:".length));
+    if (!Number.isFinite(voice) || voice < 0)
+        return fallback;
+    return voiceColors[voice] ?? voiceColor(voice);
 }
 /**
- * The {@link groupByPaint} key one bar of a live visualiser takes.
- *
- * Filtered to one voice, every bar is that voice regardless of `byVoice` or
- * whose turn the bucket originally belonged to. That second part is the one
- * worth spelling out: {@link forSpeaker} silences a bar by zeroing its
- * magnitude but leaves `speaker` exactly as it was, so a bar sitting in the
- * middle of a *different* voice's turn is still stamped with that voice's
- * index — grouping by `byVoice`'s usual per-bar key would paint those silent
- * stretches in whoever used to be talking there, in flickers too short to
- * read as anything but noise. Forcing every bar under the filtered voice's own
- * key is the true picture instead: the node is drawing exactly one person, on
- * or off, never anyone else's colour.
+ * The {@link groupByPaint} key of one live bar. Filtered to a voice, every bar
+ * takes that voice's key: {@link forSpeaker} zeroes a bar's magnitude but leaves
+ * its `speaker`, so the usual per-bar key would paint the silenced stretches in
+ * whoever used to talk there, in flickers too short to read as anything but noise.
  */
 export function livePaintKey(barSpeaker, byVoice, filteredVoice) {
     if (filteredVoice !== null)

package/dist/waveform/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/waveform/shared.ts"],"names":[],"mappings":"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","sourcesContent":["import { Graphics2D, type Fill, type FillResolved } from \"@motionscript/sdk\"\n\nimport type { EnvelopeBar } from \"./envelope\"\n\n/**\n * Geometry and paint shared by the two waveform nodes.\n *\n * They draw the same object — a row of bars whose heights are loudness — and\n * differ only in what decides the heights: the whole file for one, a window\n * around the playhead for the other. Everything about *how a row of bars is\n * laid out and painted* is therefore common, and lives here so the two cannot\n * drift into looking like different components.\n */\n\n/** How a bar is grown out of its baseline. */\nexport const WAVEFORM_ALIGNMENTS = [\"center\", \"bottom\"] as const\nexport type WaveformAlignment = (typeof WAVEFORM_ALIGNMENTS)[number]\n\n/** What the bars are shaped like. */\nexport const WAVEFORM_STYLES = [\"bars\", \"line\", \"blocks\"] as const\nexport type WaveformStyle = (typeof WAVEFORM_STYLES)[number]\n\n/**\n * The colours voices are drawn in when nobody has assigned any.\n *\n * Eight hues that can be told apart at a glance, handed out by voice index. They\n * are literals rather than looked up, because a scene has to build in a\n * headless render with no database in scope; a host that names its voices\n * supplies its own colours instead.\n */\nexport const VOICE_PALETTE = [\n  \"#6366f1\",\n  \"#14b8a6\",\n  \"#f59e0b\",\n  \"#ec4899\",\n  \"#22c55e\",\n  \"#3b82f6\",\n  \"#f97316\",\n  \"#a855f7\",\n] as const\n\n/** The colour a voice takes, wrapping past the end of the palette. */\nexport function voiceColor(index: number): string {\n  return VOICE_PALETTE[\n    ((index % VOICE_PALETTE.length) + VOICE_PALETTE.length) %\n      VOICE_PALETTE.length\n  ]\n}\n\n/**\n * Where one bar sits and how tall it came out: its top-left corner and size, in\n * the node's own pixels with **y pointing down** from the middle of the box.\n * {@link paintBars} turns that into the centred, y-up rect the renderer draws.\n */\nexport interface BarBox {\n  x: number\n  y: number\n  width: number\n  height: number\n}\n\n/**\n * Lays a row of bars out across a box.\n *\n * The gap is stated as a *fraction of the pitch* rather than in pixels, and\n * that is the one decision here worth stating out loud: the bar count is a\n * control, so a gap in pixels would silently become a solid block at 200 bars\n * and a picket fence at 20. As a fraction, the row keeps the same rhythm at\n * every density — which is what lets the count be a slider anyone can drag.\n *\n * A bar is never thinner than a hairline and never shorter than one either: a\n * silent passage has to read as \"audio, and nothing here\" rather than as a hole\n * in the drawing.\n */\nexport function layOutBars(\n  bars: readonly EnvelopeBar[],\n  options: {\n    width: number\n    height: number\n    gap: number\n    align: WaveformAlignment\n    /** Multiplies every magnitude before it is clamped back into 0…1. */\n    gain: number\n    /** Fraction of the box a silent bar still occupies. */\n    floor: number\n  }\n): BarBox[] {\n  const { width, height, gap, align, gain, floor } = options\n  const count = bars.length\n  if (count === 0 || width <= 0 || height <= 0) return []\n\n  const pitch = width / count\n  const barWidth = Math.max(1, pitch * (1 - clamp01(gap)))\n  // The tallest a bar may be. Centre-aligned bars grow both ways from the\n  // middle, so the *half* is what a magnitude of 1 fills.\n  const full = align === \"center\" ? height / 2 : height\n\n  const out: BarBox[] = new Array(count)\n  for (let i = 0; i < count; i++) {\n    const magnitude = clamp01(bars[i].magnitude * gain)\n    const reach = Math.max(full * clamp01(floor), full * magnitude)\n    const x = -width / 2 + pitch * i + (pitch - barWidth) / 2\n\n    // A hairline minimum, taken before the position so the bar stays inside the\n    // box: a silent bar 1px tall that kept the position of a zero-height one\n    // would hang half a pixel (centred) or a whole pixel (bottom) outside it.\n    const h = Math.max(1, align === \"center\" ? reach * 2 : reach)\n    out[i] =\n      align === \"center\"\n        ? { x, y: -h / 2, width: barWidth, height: h }\n        : { x, y: height / 2 - h, width: barWidth, height: h }\n  }\n  return out\n}\n\n/**\n * Draws a run of bars in one paint.\n *\n * Batched by colour by the caller, and this is why: every `Graphics2D` handed to\n * `ctx.draw` is a surface the renderer composites, so a bar apiece would be a\n * thousand surfaces a frame. Chaining the rects of one colour into a single\n * `Graphics2D` before filling makes it one — and, as a bonus, a gradient fill\n * maps across the whole run rather than restarting inside every bar, which is\n * the behaviour anyone reaching for a gradient here actually wants.\n */\nexport function paintBars(\n  boxes: readonly BarBox[],\n  fill: Fill,\n  radius: number\n): Graphics2D | null {\n  if (boxes.length === 0) return null\n  if ((fill as FillResolved[]).length === 0) return null\n\n  const graphics = new Graphics2D()\n  for (const box of boxes) {\n    graphics.rect({\n      x: box.x + box.width / 2,\n      // The box is stated y-down and the rect is drawn y-up. A centred bar is\n      // symmetric about the middle, so only a bottom-aligned one shows the flip.\n      y: -(box.y + box.height / 2),\n      width: box.width,\n      height: box.height,\n      // Never rounder than the bar is wide, or a thin bar becomes a lozenge\n      // whose ends taper away to nothing.\n      cornerRadius: Math.min(radius, box.width / 2, box.height / 2),\n    })\n  }\n  return graphics.fill(fill)\n}\n\n/**\n * Groups bars by the paint they take, preserving order within each group.\n *\n * The seam that makes {@link paintBars} worth batching: a diarized waveform has\n * as many colours as it has voices, not as many as it has bars, so a\n * conversation of two people is two draws however long it runs.\n */\nexport function groupByPaint<K>(\n  boxes: readonly BarBox[],\n  keyOf: (index: number) => K\n): Map<K, BarBox[]> {\n  const groups = new Map<K, BarBox[]>()\n  for (let i = 0; i < boxes.length; i++) {\n    const key = keyOf(i)\n    const run = groups.get(key)\n    if (run) run.push(boxes[i])\n    else groups.set(key, [boxes[i]])\n  }\n  return groups\n}\n\nexport function clamp01(value: number): number {\n  return value < 0 ? 0 : value > 1 ? 1 : value\n}\n\n/**\n * The {@link groupByPaint} key one bar of a live visualiser takes.\n *\n * Filtered to one voice, every bar is that voice regardless of `byVoice` or\n * whose turn the bucket originally belonged to. That second part is the one\n * worth spelling out: {@link forSpeaker} silences a bar by zeroing its\n * magnitude but leaves `speaker` exactly as it was, so a bar sitting in the\n * middle of a *different* voice's turn is still stamped with that voice's\n * index — grouping by `byVoice`'s usual per-bar key would paint those silent\n * stretches in whoever used to be talking there, in flickers too short to\n * read as anything but noise. Forcing every bar under the filtered voice's own\n * key is the true picture instead: the node is drawing exactly one person, on\n * or off, never anyone else's colour.\n */\nexport function livePaintKey(\n  barSpeaker: number,\n  byVoice: boolean,\n  filteredVoice: number | null\n): string {\n  if (filteredVoice !== null) return `voice:${filteredVoice}`\n  return byVoice ? `voice:${barSpeaker}` : \"all\"\n}\n"]}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/waveform/shared.ts"],"names":[],"mappings":"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","sourcesContent":["import { Graphics2D, clamp, type Fill, type FillResolved } from \"@motionscript/sdk\"\n\nimport type { EnvelopeBar } from \"./envelope\"\n\n/** How a bar is grown out of its baseline. */\nexport const WAVEFORM_ALIGNMENTS = [\"center\", \"bottom\"] as const\nexport type WaveformAlignment = (typeof WAVEFORM_ALIGNMENTS)[number]\n\nexport const WAVEFORM_STYLES = [\"bars\", \"line\", \"blocks\"] as const\nexport type WaveformStyle = (typeof WAVEFORM_STYLES)[number]\n\n/** Eight distinct hues handed out by voice index. Literals, because a scene builds headless with no database in scope; a host that names its voices supplies its own. */\nexport const VOICE_PALETTE = [\n  \"#6366f1\",\n  \"#14b8a6\",\n  \"#f59e0b\",\n  \"#ec4899\",\n  \"#22c55e\",\n  \"#3b82f6\",\n  \"#f97316\",\n  \"#a855f7\",\n] as const\n\n/** The colour a voice takes, wrapping past the end of the palette. */\nexport function voiceColor(index: number): string {\n  return VOICE_PALETTE[\n    ((index % VOICE_PALETTE.length) + VOICE_PALETTE.length) %\n      VOICE_PALETTE.length\n  ]\n}\n\n/** A bar's top-left corner and size in the node's pixels, with y pointing down from the middle of the box; {@link paintBars} turns it into the centred y-up rect. */\nexport interface BarBox {\n  x: number\n  y: number\n  width: number\n  height: number\n}\n\n/**\n * Lays a row of bars across a box. The gap is a fraction of the pitch, not px:\n * the bar count is a control, and a px gap would become a solid block at 200\n * bars and a picket fence at 20. A bar is never thinner or shorter than a\n * hairline, so a silent passage reads as audio with nothing in it, not a hole.\n */\nexport function layOutBars(\n  bars: readonly EnvelopeBar[],\n  options: {\n    width: number\n    height: number\n    gap: number\n    align: WaveformAlignment\n    gain: number\n    /** Fraction of the box a silent bar still occupies. */\n    floor: number\n  }\n): BarBox[] {\n  const { width, height, gap, align, gain, floor } = options\n  const count = bars.length\n  if (count === 0 || width <= 0 || height <= 0) return []\n\n  const pitch = width / count\n  const barWidth = Math.max(1, pitch * (1 - clamp(gap, 0, 1)))\n  // Centre-aligned bars grow both ways, so half the height is what a magnitude of 1 fills.\n  const full = align === \"center\" ? height / 2 : height\n\n  const out: BarBox[] = new Array(count)\n  for (let i = 0; i < count; i++) {\n    const magnitude = clamp(bars[i].magnitude * gain, 0, 1)\n    const reach = Math.max(full * clamp(floor, 0, 1), full * magnitude)\n    const x = -width / 2 + pitch * i + (pitch - barWidth) / 2\n\n    // The hairline minimum is taken before the position, or a 1px bar placed as if zero-height would hang outside the box.\n    const h = Math.max(1, align === \"center\" ? reach * 2 : reach)\n    out[i] =\n      align === \"center\"\n        ? { x, y: -h / 2, width: barWidth, height: h }\n        : { x, y: height / 2 - h, width: barWidth, height: h }\n  }\n  return out\n}\n\n/**\n * Draws a run of bars in one paint. Callers batch by colour: every `Graphics2D`\n * handed to `ctx.draw` is a surface the renderer composites, so a bar apiece\n * would be a thousand surfaces a frame. One `Graphics2D` per run also maps a\n * gradient across the whole run instead of restarting inside every bar.\n */\nexport function paintBars(\n  boxes: readonly BarBox[],\n  fill: Fill,\n  radius: number\n): Graphics2D | null {\n  if (boxes.length === 0) return null\n  if ((fill as FillResolved[]).length === 0) return null\n\n  const graphics = new Graphics2D()\n  for (const box of boxes) {\n    graphics.rect({\n      x: box.x + box.width / 2,\n      // The box is y-down and the rect y-up; only a bottom-aligned bar shows the flip.\n      y: -(box.y + box.height / 2),\n      width: box.width,\n      height: box.height,\n      // A thin bar rounder than it is wide becomes a lozenge.\n      cornerRadius: Math.min(radius, box.width / 2, box.height / 2),\n    })\n  }\n  return graphics.fill(fill)\n}\n\n/** Groups bars by the paint they take, in order within each group: a diarized waveform has as many colours as voices, so two people is two draws however long it runs. */\nexport function groupByPaint<K>(\n  boxes: readonly BarBox[],\n  keyOf: (index: number) => K\n): Map<K, BarBox[]> {\n  const groups = new Map<K, BarBox[]>()\n  for (let i = 0; i < boxes.length; i++) {\n    const key = keyOf(i)\n    const run = groups.get(key)\n    if (run) run.push(boxes[i])\n    else groups.set(key, [boxes[i]])\n  }\n  return groups\n}\n\n/**\n * The colour of a `voice:N` group key, or `fallback` for a bad index. Always a\n * colour string, never one of the node's fills: a voice is identified by hue, so\n * a gradient or image would defeat the point, and it keeps these paints from\n * declaring assets.\n */\nexport function voiceFill(key: string, voiceColors: readonly string[], fallback: Fill): Fill {\n  const voice = Number(key.slice(\"voice:\".length))\n  if (!Number.isFinite(voice) || voice < 0) return fallback\n  return voiceColors[voice] ?? voiceColor(voice)\n}\n\n/**\n * The {@link groupByPaint} key of one live bar. Filtered to a voice, every bar\n * takes that voice's key: {@link forSpeaker} zeroes a bar's magnitude but leaves\n * its `speaker`, so the usual per-bar key would paint the silenced stretches in\n * whoever used to talk there, in flickers too short to read as anything but noise.\n */\nexport function livePaintKey(\n  barSpeaker: number,\n  byVoice: boolean,\n  filteredVoice: number | null\n): string {\n  if (filteredVoice !== null) return `voice:${filteredVoice}`\n  return byVoice ? `voice:${barSpeaker}` : \"all\"\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionscript/audio",
-  "version": "0.1.0",
+  "version": "0.1.1-alpha.0",
   "type": "module",
   "description": "Waveform components for Motion Script: a full recording drawn as bars, and a live meter that moves with playback. Both draw a loudness envelope the host supplies.",
   "repository": {
@@ -50,7 +50,7 @@
   "license": "Apache-2.0",
   "author": "Motionscript",
   "peerDependencies": {
-    "@motionscript/sdk": "^0.1.0"
+    "@motionscript/sdk": "^0.1.1-alpha.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.2",
@@ -61,8 +61,8 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.48.0",
     "vitest": "^4.1.5",
-    "@motionscript/core": "0.1.0",
-    "@motionscript/sdk": "0.1.0"
+    "@motionscript/core": "0.1.1-alpha.0",
+    "@motionscript/sdk": "0.1.1-alpha.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths && node ../../../scripts/build-browser.mjs",

package/src/kit.ts

@@ -1,18 +1,10 @@
-/**
- * What the two waveform nodes share, importable without copying it.
- *
- * A registry item copies `envelope.ts` and `shared.ts` beside its node: they
- * hold no class and no registered state, so a fork owning its own copy splits
- * no identity. This is the same surface for a host that samples envelopes or
- * lays bars out itself, and for a fork that keeps only its node file.
- */
+// A registry item copies `envelope.ts` and `shared.ts` beside its node (no class or registered state, so a copy splits no identity); this is the same surface for a host or a fork that keeps only its node file.
 export { EMPTY_ENVELOPE, forSpeaker, sampleEnvelope } from "./waveform/envelope"
 export type { AudioEnvelope, EnvelopeBar } from "./waveform/envelope"
 export {
   VOICE_PALETTE,
   WAVEFORM_ALIGNMENTS,
   WAVEFORM_STYLES,
-  clamp01,
   groupByPaint,
   layOutBars,
   livePaintKey,

package/src/nodes.ts

@@ -1,17 +1,5 @@
 import { FullWaveform } from "./waveform/full-waveform";
 import { LiveWaveform } from "./waveform/live-waveform";
 
-/**
- * Every node type this package publishes.
- *
- * A host registers these by handing the array to an engine —
- * `new Engine(platform, { nodes: NODES })` — which reads each component's key.
- * Defining a component only *declares* that key: nothing is registered by
- * importing a module, so a registry holds exactly what its owner asked for.
- *
- * Listing the component **values** is also what survives bundling: this package
- * declares `sideEffects: false`, and a document names a node type by string, so
- * an import kept only for its side effect is exactly what gets shaken out.
- */
 // Typed by name, so the declaration names each component rather than spelling out its type through core.
 export const NODES: (typeof FullWaveform | typeof LiveWaveform)[] = [FullWaveform, LiveWaveform];

package/src/waveform/envelope.ts

@@ -1,88 +1,32 @@
 /**
- * The shape of a recording, as the waveform nodes draw it.
- *
- * ## How an envelope reaches a node: the host supplies it
- *
- * Nothing in the engine, and nothing in this kit, decodes audio. A waveform node
- * does not read a `sound` node's `src`, declares no audio asset and is not tied
- * to a clip: it draws the {@link AudioEnvelope} it is handed in its `envelope`
- * prop. Decoding a file into an envelope is the host's job, done once per file
- * before the document is built. Where the recording sits on the audio lane is
- * the author's timing too, which is why `FullWaveform.follow` is opt-in.
- *
- * ### The JSON form
- *
- * A document holds the envelope as plain JSON, because a prop value in a
- * document is JSON. The typed arrays in {@link AudioEnvelope} are one spelling of
- * it; `ArrayLike<number>` also accepts the plain arrays a document stores:
- *
- * ```json
- * {
- *   "magnitude": [0, 0.25, 0.5, 1, 0.5, 0],
- *   "duration": 6,
- *   "speaker": [0, 0, 0, 1, 1, -1],
- *   "speakers": 2
- * }
- * ```
- *
- * `magnitude` is the peak loudness, `0`…`1`, of buckets that divide `duration`
- * seconds evenly. `speaker` is `null` when nobody was identified; otherwise it is parallel to `magnitude`, one voice
- * index per bucket, `-1` for "nobody". `speakers` is the voice count, `0` when
- * `speaker` is `null`. A `Float32Array` or `Int16Array` is not JSON-serialisable
- * (`JSON.stringify` writes an object of indices), so a host that holds the typed
- * form converts with `Array.from` before storing it in a document.
- *
- * ## Why the data is baked rather than listened to
- *
- * A scene has to render identically in the preview and in a headless export,
- * and an export has no audio device, no `AudioContext` and no playback to
- * analyse. So a "live" visualiser cannot read a Web Audio analyser: what it
- * reads is a *pre-computed envelope*, indexed by the scene clock. The picture is
- * then a pure function of time, which is what makes scrubbing backwards, jumping
- * to frame 900, and rendering out of order all produce the same frame.
- *
- * The decode happens in the host, once per file, and arrives here through the
- * build — the same arrangement a chart's rows and a protein's atoms already use,
- * and for the same reason: the build is synchronous and cannot await a fetch.
- *
- * ## Why magnitude rather than min/max
- *
- * An editor's waveform is drawn from per-bucket minima *and* maxima, because an
- * editor is a measuring instrument. These nodes are neither — they are a bar
- * chart of loudness that happens to be shaped like a recording — and audio is
- * near enough symmetric that a mirrored magnitude is indistinguishable at the
- * size a node draws. Half the numbers, and one array to reason about.
+ * The host decodes audio into an {@link AudioEnvelope} once per file, before the
+ * build, and hands it to the node; nothing here decodes or listens. It is baked
+ * because an export has no audio device or analyser, and the picture must be a
+ * pure function of time.
+ *
+ * In a document an envelope is plain JSON, which `ArrayLike<number>` accepts.
+ * A `Float32Array` is not JSON-serialisable (`JSON.stringify` writes an object
+ * of indices), so convert with `Array.from` before storing it.
  */
 
 /**
- * A decoded recording, reduced to a uniform grid of loudness — plus, when the
- * host knows it, who is talking in each bucket.
- *
- * The speaker track is **not** something a decoder can produce; it comes from a
- * diarized transcript and is folded in by the host before the build. It lives
- * here rather than in a parallel structure because every reader of it is also a
- * reader of the magnitudes at the same index, and two arrays that must stay the
- * same length are better as one object than as two arguments.
+ * A recording reduced to a uniform grid of loudness, plus who is talking in each
+ * bucket when the host knows. The speaker track comes from a diarized transcript,
+ * not the decoder; it lives here because every reader of it also reads the
+ * magnitudes at the same index.
  */
 export interface AudioEnvelope {
-  /**
-   * Peak magnitude per bucket, 0…1. Buckets span {@link duration} evenly. A
-   * `Float32Array`, or the plain `number[]` a document stores.
-   */
+  /** Peak magnitude per bucket, 0 to 1; buckets span {@link duration} evenly. */
   magnitude: ArrayLike<number>
-  /** The decoded length in seconds. */
+  /** Seconds. */
   duration: number
-  /**
-   * Which voice is speaking in each bucket, as an index into the recording's
-   * own numbering, or `-1` for "nobody identified". Parallel to
-   * {@link magnitude}, or `null` when the track was never diarized.
-   */
+  /** Voice index per bucket (`-1` for nobody), parallel to {@link magnitude}, or `null` when never diarized. */
   speaker: ArrayLike<number> | null
-  /** How many distinct voices the diarizer found. Zero when it did not run. */
+  /** Zero when the diarizer did not run. */
   speakers: number
 }
 
-/** The envelope of a track that hasn't loaded — or isn't there. */
+/** The envelope of a track that has not loaded or is not there. */
 export const EMPTY_ENVELOPE: AudioEnvelope = {
   magnitude: new Float32Array(0),
   duration: 0,
@@ -90,28 +34,19 @@ export const EMPTY_ENVELOPE: AudioEnvelope = {
   speakers: 0,
 }
 
-/** One drawn bar: how loud, and whose. */
 export interface EnvelopeBar {
-  /** 0…1. */
+  /** 0 to 1. */
   magnitude: number
-  /** The voice index, or -1. */
+  /** Voice index, or -1. */
   speaker: number
 }
 
 /**
- * Resamples `[from, to)` seconds of an envelope down to `bars` columns.
- *
- * Peak-preserving rather than averaging, which is the whole difference between
- * a waveform and a blur: averaging a hundred buckets into one column flattens
- * every transient, and transients are what makes a drawn recording read as
- * speech rather than as noise. The speaker of a column is the speaker of its
- * *loudest* bucket, on the same reasoning — a column straddling a turn belongs
- * to whoever is actually audible in it.
- *
- * A window past either end of the recording yields silent, unattributed
- * columns rather than clamping onto the nearest real one. That matters for the
- * live visualiser, which is handed a window centred on the playhead and would
- * otherwise smear the first bucket across the whole run-up to a track's start.
+ * Resamples `[from, to)` seconds down to `bars` columns, keeping peaks rather
+ * than averaging: averaging flattens the transients that make a drawing read as
+ * speech. A column's speaker is that of its loudest bucket. A window past either
+ * end yields silent, unattributed columns rather than clamping onto the nearest
+ * real one, which would smear the first bucket across a live window's run-up.
  */
 export function sampleEnvelope(
   envelope: AudioEnvelope,
@@ -133,8 +68,7 @@ export function sampleEnvelope(
     const start = (from + span * i) * perSecond
     const end = (from + span * (i + 1)) * perSecond
 
-    // At least one bucket per column, so a window zoomed in past the grid draws
-    // the sample it is standing on rather than an empty band.
+    // At least one bucket per column, so a zoomed-in window draws the sample it stands on.
     const first = Math.floor(start)
     const last = Math.max(first, Math.ceil(end) - 1)
 
@@ -155,15 +89,9 @@ export function sampleEnvelope(
 }
 
 /**
- * The same window, with everything that isn't `voice` silenced.
- *
- * The point of the speaker filter, and the reason it silences rather than
- * *drops*: a podcast visualiser filtered to one host should go quiet while the
- * other one talks, not compress their turn out of existence. Keeping the bars
- * and zeroing them is what makes the picture read as "this person is not
- * speaking right now" instead of as a jump cut.
- *
- * `voice` of `null` returns the bars untouched, which is the unfiltered node.
+ * The same window with everything but `voice` silenced, not dropped, so a
+ * filtered visualiser goes quiet while the other host talks instead of cutting
+ * their turn out. `null` returns the bars untouched.
  */
 export function forSpeaker(
   bars: EnvelopeBar[],

package/src/waveform/full-waveform.ts

@@ -1,5 +1,6 @@
 import {
   Types,
+  clamp,
   component2d,
   easeInOut,
   fillOps,
@@ -14,88 +15,61 @@ import {
 
 import { EMPTY_ENVELOPE, sampleEnvelope, type AudioEnvelope } from "./envelope"
 import {
-  clamp01,
   groupByPaint,
   layOutBars,
   paintBars,
-  voiceColor,
+  voiceFill,
   type WaveformAlignment,
 } from "./shared"
 
-/** A paint entry as the waveforms declare theirs: resolved and tweened like a fill, its kind read off the default. */
+/** A fill entry whose kind is read off the default. */
 const paint = (initial: string) =>
   Types.custom<Fill, FillResolved[]>(initial, { resolve: fillOps.resolve, lerp: fillOps.lerp })
 
 /**
- * A **waveform overview**: the whole recording's shape, drawn at once.
+ * The whole recording's shape drawn at once, with a played portion that
+ * advances: a picture of the file where {@link LiveWaveform} is of the moment.
  *
- * The picture every audio editor opens with, and the one a podcast clip puts
- * under its caption — a static silhouette of the file, with a played portion
- * that advances. It answers "how long is this and where are the loud parts",
- * which is a question about the *file*, not about the moment; its sibling
- * {@link LiveWaveform} answers the other one.
- *
- * ## Progress is authored, not assumed
- *
- * `follow` is off by default, and that default is the considered one. A
- * scene has no idea where the recording it is drawing sits on the video's audio
- * lane — a clip is placed, trimmed and sped up out there, and none of that is
- * visible from in here. So the honest default is that the fill is *animation*:
- * the author sweeps it with a command, the same as any other tween, and it lands
- * wherever they put it. `follow` is the shortcut for the common arrangement
- * where the node appears exactly as the track starts, and it says so by being a
- * switch someone has to turn on rather than a behaviour that quietly disagrees
- * with the mix.
- *
- * ## Voices instead of progress
- *
- * With `byVoice` on, the played/ahead split is replaced by one colour per
- * speaking voice, at a size you can read. For a two-hander it is a map of the conversation: who has the
- * floor, where the turns are, how long each one ran. It replaces the progress
- * colours rather than combining with them, because a bar cannot mean two things
- * at once and "played, and also Grace" is a legend nobody can hold in their
- * head.
+ * `follow` is off by default because a scene cannot see where the recording sits
+ * on the video's audio lane (placed, trimmed, sped up); the author sweeps
+ * `progress` with a command, and `follow` is the opt-in for a node that appears
+ * exactly as the track starts. `byVoice` replaces the played/ahead split with
+ * one colour per voice rather than combining with it: a bar cannot mean two
+ * things at once.
  */
 export const FullWaveform = component2d({
   key: "fullWaveform",
   state: {
-    /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+    /** The baked recording; see {@link AudioEnvelope}. */
     envelope: Types.custom<AudioEnvelope>(EMPTY_ENVELOPE),
-    /** How many columns the whole file is drawn as. */
     bars: 120,
-    /** Space between bars, as a fraction of the pitch. See {@link layOutBars}. */
+    /** Space between bars as a fraction of the pitch; see {@link layOutBars}. */
     gap: 0.3,
-    /** Corner radius of a bar, capped at half its width. */
+    /** Capped at half the bar's width. */
     radius: 2,
-    /** How much of the file reads as played, `0`–`1`. Tweenable. */
+    /** The share of the file that reads as played, `0`-`1`. */
     progress: 0,
-    /** Drive `progress` from the node's own clock instead of the prop. */
+    /** Drive `progress` from the node's own clock instead. */
     follow: false,
-    /** Multiplies every magnitude — a quiet track pulled up to fill its box. */
+    /** Multiplies every magnitude, pulling a quiet track up to fill its box. */
     gain: 1,
-    /** How much of the box a silent bar still occupies, `0`–`1`. */
+    /** The share of the box a silent bar still occupies, `0`-`1`. */
     floor: 0.015,
     align: Types.custom<WaveformAlignment>("center"),
-    /** Colour each voice's turns rather than splitting on played / not played. */
     byVoice: false,
-    /** A colour per voice index. Short or empty falls back to the palette. */
+    /** A colour per voice index; short or empty falls back to the palette. */
     voiceColors: Types.custom<string[]>([]),
     /** The bars ahead of the playhead. */
     fill: paint("#5b5b7a"),
-    /** …and the bars behind it. */
     playedFill: paint("#6366f1"),
   },
-  // Nothing declares a component's paints but itself: `fill` and `playedFill` both.
+  // Nothing declares a component's paints but itself.
   load: (loader, state) => {
     loader.fill(state.fill)
     loader.fill(state.playedFill)
   },
   commands: {
-    /**
-     * Fill the waveform in, left to right — the node's one command, since
-     * everything else about it is expressible as an ordinary `to`. Eased in-out
-     * unless it is given an easing of its own.
-     */
+    /** Fill the waveform in, left to right; eased in-out unless given an easing. */
     sweep: (timeline, state) => {
       const ease = timeline.easing ? null : easeInOut()
       const from = state.progress
@@ -109,7 +83,6 @@ export const FullWaveform = component2d({
 })
 
 export type FullWaveform = NodeOf<typeof FullWaveform>
-export type FullWaveformProps = NonNullable<Parameters<typeof FullWaveform>[0]>
 
 interface FullState {
   readonly envelope: AudioEnvelope
@@ -143,9 +116,7 @@ function drawBars(ctx: RenderContext, s: FullState): void {
   })
   if (boxes.length === 0) return
 
-  // One draw per colour rather than per bar — see {@link paintBars}. The key
-  // is a string because it has to be comparable; the paint it stands for is
-  // resolved after the grouping.
+  // One draw per colour, not per bar (see {@link paintBars}); the key is a string so it is comparable.
   const edge = played(ctx, s) * boxes.length
   const groups = groupByPaint(boxes, (i) =>
     s.byVoice
@@ -161,28 +132,15 @@ function drawBars(ctx: RenderContext, s: FullState): void {
   }
 }
 
-/** Where the fill has reached, from whichever source is in charge. */
 function played(ctx: RenderContext, s: FullState): number {
-  if (!s.follow) return clamp01(s.progress)
+  if (!s.follow) return clamp(s.progress, 0, 1)
   const length = s.envelope.duration
   if (length <= 0) return 0
-  return clamp01(ctx.time.elapsed / length)
+  return clamp(ctx.time.elapsed / length, 0, 1)
 }
 
-/**
- * The paint a group takes.
- *
- * A voice's colour is a **colour string**, never one of the node's two fill
- * props, and that is deliberate: a voice is identified by hue, so a gradient
- * or an image there would defeat the only thing the colour is for. It also
- * means these paints declare no assets, which is why `load` only has to account
- * for the two real fill props.
- */
 function paintFor(s: FullState, key: string): Fill {
   if (key === "played") return s.playedFill
   if (key === "ahead") return s.fill
-
-  const voice = Number(key.slice("voice:".length))
-  if (!Number.isFinite(voice) || voice < 0) return s.fill
-  return s.voiceColors[voice] ?? voiceColor(voice)
+  return voiceFill(key, s.voiceColors, s.fill)
 }

package/src/waveform/index.ts

@@ -1,21 +1,5 @@
-/**
- * The waveform family: one subject, two questions.
- *
- * - {@link FullWaveform} draws the **file** — the whole recording's silhouette,
- *   with a played portion that advances. "How long is this, and where are the
- *   loud parts."
- * - {@link LiveWaveform} draws the **moment** — bars moving with playback, the
- *   visualiser a podcast clip puts beside the artwork. "Is anything happening
- *   right now, and whose voice is it."
- *
- * Both read the same baked {@link AudioEnvelope}, which is why they cannot
- * disagree about a recording, and why neither listens to anything — see that
- * module for why a scene that has to export cannot use a live analyser.
- */
 export { FullWaveform } from "./full-waveform"
-export type { FullWaveformProps } from "./full-waveform"
 export { LiveWaveform } from "./live-waveform"
-export type { LiveWaveformProps } from "./live-waveform"
 export { EMPTY_ENVELOPE, forSpeaker, sampleEnvelope } from "./envelope"
 export type { AudioEnvelope, EnvelopeBar } from "./envelope"
 export {