@motionscript/audio 0.0.0-stage → 0.1.0-alpha.10

package/dist/waveform/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/waveform/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AACvE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC5D,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,UAAU,EACV,SAAS,EACT,UAAU,GACX,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,MAAM,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA"}

package/dist/waveform/index.js

@@ -0,0 +1,19 @@
+/**
+ * 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.js";
+export { LiveWaveform } from "./live-waveform.js";
+export { EMPTY_ENVELOPE, forSpeaker, sampleEnvelope } from "./envelope.js";
+export { VOICE_PALETTE, WAVEFORM_ALIGNMENTS, WAVEFORM_STYLES, groupByPaint, layOutBars, paintBars, voiceColor, } from "./shared.js";
+//# sourceMappingURL=index.js.map

package/dist/waveform/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/waveform/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEvE,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,UAAU,EACV,SAAS,EACT,UAAU,GACX,MAAM,UAAU,CAAA","sourcesContent":["/**\n * The waveform family: one subject, two questions.\n *\n * - {@link FullWaveform} draws the **file** — the whole recording's silhouette,\n *   with a played portion that advances. \"How long is this, and where are the\n *   loud parts.\"\n * - {@link LiveWaveform} draws the **moment** — bars moving with playback, the\n *   visualiser a podcast clip puts beside the artwork. \"Is anything happening\n *   right now, and whose voice is it.\"\n *\n * Both read the same baked {@link AudioEnvelope}, which is why they cannot\n * disagree about a recording, and why neither listens to anything — see that\n * module for why a scene that has to export cannot use a live analyser.\n */\nexport { FullWaveform } from \"./full-waveform\"\nexport type { FullWaveformProps } from \"./full-waveform\"\nexport { LiveWaveform } from \"./live-waveform\"\nexport type { LiveWaveformProps } from \"./live-waveform\"\nexport { EMPTY_ENVELOPE, forSpeaker, sampleEnvelope } from \"./envelope\"\nexport type { AudioEnvelope, EnvelopeBar } from \"./envelope\"\nexport {\n  VOICE_PALETTE,\n  WAVEFORM_ALIGNMENTS,\n  WAVEFORM_STYLES,\n  groupByPaint,\n  layOutBars,\n  paintBars,\n  voiceColor,\n} from \"./shared\"\nexport type { BarBox, WaveformAlignment, WaveformStyle } from \"./shared\"\n"]}

package/dist/waveform/live-waveform.d.ts

@@ -0,0 +1,129 @@
+import { type Fill, type FillResolved, type NodeOf, type Node2D as _Node2D, type Node2DProps as _Node2DProps } from "@motionscript/sdk";
+import { type AudioEnvelope } from "./envelope.js";
+/**
+ * A **live audio visualiser**: bars that move with the recording as it plays.
+ *
+ * The thing every podcast-to-video tool puts beside the artwork. It is not a
+ * picture of the file — that is {@link FullWaveform} — it is a picture of *this
+ * moment*, and what it is for is making a static frame of a talking head feel
+ * like it is playing.
+ *
+ * ## "Live" without listening
+ *
+ * Nothing here reads an audio device. The bars are sampled out of a baked
+ * envelope at the node's own elapsed time, which is what makes the visualiser
+ * survive the thing it exists for: an **export**, where there is no playback to
+ * analyse and frames may be rendered out of order or in parallel. A frame is a
+ * pure function of its time, so scrubbing back and forth over the visualiser
+ * redraws exactly what it drew the first time — which an analyser node, by
+ * construction, cannot promise. See {@link AudioEnvelope}.
+ *
+ * ## The speaker filter
+ *
+ * `speaker` narrows the node to one voice of a diarized recording, and it
+ * is the reason this node knows about transcripts at all. Two visualisers beside
+ * two headshots, each filtered to its own host, is a podcast edit that would
+ * otherwise be done by hand for every turn — and because the filter *silences*
+ * rather than skips (see {@link forSpeaker}), the quiet host visibly stops
+ * talking instead of vanishing. Nothing about that requires the words: only who
+ * is talking when, which is what the diarizer produces.
+ *
+ * A filter naming a voice the recording doesn't have draws a resting row rather
+ * than everything — a picture of "this person never speaks here", which is
+ * true, where falling back to the unfiltered mix would be a silent lie about
+ * whose voice you were watching.
+ */
+export declare const LiveWaveform: import("@motionscript/sdk").Component<"liveWaveform", import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+    readonly envelope: import("@motionscript/sdk").Type<AudioEnvelope, AudioEnvelope, false>;
+    /** How many bars the visualiser is made of. */
+    readonly bars: 48;
+    /** Space between bars, as a fraction of the pitch. */
+    readonly gap: 0.35;
+    readonly radius: 4;
+    /** How many seconds of audio are on screen at once. */
+    readonly window: 3;
+    /** Seconds into the file the node's first frame shows. */
+    readonly offset: 0;
+    /** Advance with the scene clock. Off freezes the picture at `offset`. */
+    readonly playing: true;
+    /** Multiplies every magnitude before it is clamped. */
+    readonly gain: 1.4;
+    /** How much of the box a silent bar still occupies, `0`–`1`. */
+    readonly floor: 0.04;
+    readonly align: import("@motionscript/sdk").Type<"center" | "bottom", "center" | "bottom", false>;
+    readonly style: import("@motionscript/sdk").Type<"bars" | "line" | "blocks", "bars" | "line" | "blocks", false>;
+    /**
+     * Show only this voice's activity, by index into the recording's own
+     * numbering. `-1` — the default — is every voice.
+     */
+    readonly speaker: -1;
+    /** Colour each bar by whoever is speaking in it. */
+    readonly byVoice: false;
+    /** A colour per voice index. Short or empty falls back to the palette. */
+    readonly voiceColors: import("@motionscript/sdk").Type<string[], string[], false>;
+    readonly fill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+}>, {}, null, _Node2D<_Node2DProps>, import("@motionscript/sdk").CallProps<import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+    readonly envelope: import("@motionscript/sdk").Type<AudioEnvelope, AudioEnvelope, false>;
+    /** How many bars the visualiser is made of. */
+    readonly bars: 48;
+    /** Space between bars, as a fraction of the pitch. */
+    readonly gap: 0.35;
+    readonly radius: 4;
+    /** How many seconds of audio are on screen at once. */
+    readonly window: 3;
+    /** Seconds into the file the node's first frame shows. */
+    readonly offset: 0;
+    /** Advance with the scene clock. Off freezes the picture at `offset`. */
+    readonly playing: true;
+    /** Multiplies every magnitude before it is clamped. */
+    readonly gain: 1.4;
+    /** How much of the box a silent bar still occupies, `0`–`1`. */
+    readonly floor: 0.04;
+    readonly align: import("@motionscript/sdk").Type<"center" | "bottom", "center" | "bottom", false>;
+    readonly style: import("@motionscript/sdk").Type<"bars" | "line" | "blocks", "bars" | "line" | "blocks", false>;
+    /**
+     * Show only this voice's activity, by index into the recording's own
+     * numbering. `-1` — the default — is every voice.
+     */
+    readonly speaker: -1;
+    /** Colour each bar by whoever is speaking in it. */
+    readonly byVoice: false;
+    /** A colour per voice index. Short or empty falls back to the palette. */
+    readonly voiceColors: import("@motionscript/sdk").Type<string[], string[], false>;
+    readonly fill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+}>, null, import("@motionscript/sdk").BuiltNode<import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+    readonly envelope: import("@motionscript/sdk").Type<AudioEnvelope, AudioEnvelope, false>;
+    /** How many bars the visualiser is made of. */
+    readonly bars: 48;
+    /** Space between bars, as a fraction of the pitch. */
+    readonly gap: 0.35;
+    readonly radius: 4;
+    /** How many seconds of audio are on screen at once. */
+    readonly window: 3;
+    /** Seconds into the file the node's first frame shows. */
+    readonly offset: 0;
+    /** Advance with the scene clock. Off freezes the picture at `offset`. */
+    readonly playing: true;
+    /** Multiplies every magnitude before it is clamped. */
+    readonly gain: 1.4;
+    /** How much of the box a silent bar still occupies, `0`–`1`. */
+    readonly floor: 0.04;
+    readonly align: import("@motionscript/sdk").Type<"center" | "bottom", "center" | "bottom", false>;
+    readonly style: import("@motionscript/sdk").Type<"bars" | "line" | "blocks", "bars" | "line" | "blocks", false>;
+    /**
+     * Show only this voice's activity, by index into the recording's own
+     * numbering. `-1` — the default — is every voice.
+     */
+    readonly speaker: -1;
+    /** Colour each bar by whoever is speaking in it. */
+    readonly byVoice: false;
+    /** A colour per voice index. Short or empty falls back to the palette. */
+    readonly voiceColors: import("@motionscript/sdk").Type<string[], string[], false>;
+    readonly fill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+}>, {}, _Node2D<_Node2DProps>>>>;
+export type LiveWaveform = NodeOf<typeof LiveWaveform>;
+export type LiveWaveformProps = NonNullable<Parameters<typeof LiveWaveform>[0]>;
+//# sourceMappingURL=live-waveform.d.ts.map

package/dist/waveform/live-waveform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-waveform.d.ts","sourceRoot":"","sources":["../../src/waveform/live-waveform.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,IAAI,EACT,KAAK,YAAY,EACjB,KAAK,MAAM,EAGX,KAAK,MAAM,IAAI,OAAO,EACtB,KAAK,WAAW,IAAI,YAAY,EACjC,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAIL,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAA;AAYnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,YAAY;IAGrB,0EAA0E;;IAE1E,+CAA+C;;IAE/C,sDAAsD;;;IAGtD,uDAAuD;;IAEvD,0DAA0D;;IAE1D,yEAAyE;;IAEzE,uDAAuD;;IAEvD,gEAAgE;;;;IAIhE;;;OAGG;;IAEH,oDAAoD;;IAEpD,0EAA0E;;;;IA1B1E,0EAA0E;;IAE1E,+CAA+C;;IAE/C,sDAAsD;;;IAGtD,uDAAuD;;IAEvD,0DAA0D;;IAE1D,yEAAyE;;IAEzE,uDAAuD;;IAEvD,gEAAgE;;;;IAIhE;;;OAGG;;IAEH,oDAAoD;;IAEpD,0EAA0E;;;;IA1B1E,0EAA0E;;IAE1E,+CAA+C;;IAE/C,sDAAsD;;;IAGtD,uDAAuD;;IAEvD,0DAA0D;;IAE1D,yEAAyE;;IAEzE,uDAAuD;;IAEvD,gEAAgE;;;;IAIhE;;;OAGG;;IAEH,oDAAoD;;IAEpD,0EAA0E;;;gCAU5E,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,YAAY,CAAC,CAAA;AACtD,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA"}

package/dist/waveform/live-waveform.js

@@ -0,0 +1,149 @@
+import { Types, component2d, fillOps, } from "@motionscript/sdk";
+import { EMPTY_ENVELOPE, forSpeaker, sampleEnvelope, } from "./envelope.js";
+import { clamp01, groupByPaint, layOutBars, livePaintKey, paintBars, voiceColor, } from "./shared.js";
+/**
+ * A **live audio visualiser**: bars that move with the recording as it plays.
+ *
+ * The thing every podcast-to-video tool puts beside the artwork. It is not a
+ * picture of the file — that is {@link FullWaveform} — it is a picture of *this
+ * moment*, and what it is for is making a static frame of a talking head feel
+ * like it is playing.
+ *
+ * ## "Live" without listening
+ *
+ * Nothing here reads an audio device. The bars are sampled out of a baked
+ * envelope at the node's own elapsed time, which is what makes the visualiser
+ * survive the thing it exists for: an **export**, where there is no playback to
+ * analyse and frames may be rendered out of order or in parallel. A frame is a
+ * pure function of its time, so scrubbing back and forth over the visualiser
+ * redraws exactly what it drew the first time — which an analyser node, by
+ * construction, cannot promise. See {@link AudioEnvelope}.
+ *
+ * ## The speaker filter
+ *
+ * `speaker` narrows the node to one voice of a diarized recording, and it
+ * is the reason this node knows about transcripts at all. Two visualisers beside
+ * two headshots, each filtered to its own host, is a podcast edit that would
+ * otherwise be done by hand for every turn — and because the filter *silences*
+ * rather than skips (see {@link forSpeaker}), the quiet host visibly stops
+ * talking instead of vanishing. Nothing about that requires the words: only who
+ * is talking when, which is what the diarizer produces.
+ *
+ * A filter naming a voice the recording doesn't have draws a resting row rather
+ * than everything — a picture of "this person never speaks here", which is
+ * true, where falling back to the unfiltered mix would be a silent lie about
+ * whose voice you were watching.
+ */
+export const LiveWaveform = component2d({
+    key: "liveWaveform",
+    state: {
+        /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+        envelope: Types.custom(EMPTY_ENVELOPE),
+        /** How many bars the visualiser is made of. */
+        bars: 48,
+        /** Space between bars, as a fraction of the pitch. */
+        gap: 0.35,
+        radius: 4,
+        /** How many seconds of audio are on screen at once. */
+        window: 3,
+        /** Seconds into the file the node's first frame shows. */
+        offset: 0,
+        /** Advance with the scene clock. Off freezes the picture at `offset`. */
+        playing: true,
+        /** Multiplies every magnitude before it is clamped. */
+        gain: 1.4,
+        /** How much of the box a silent bar still occupies, `0`–`1`. */
+        floor: 0.04,
+        align: Types.custom("center"),
+        style: Types.custom("bars"),
+        /**
+         * Show only this voice's activity, by index into the recording's own
+         * numbering. `-1` — the default — is every voice.
+         */
+        speaker: -1,
+        /** Colour each bar by whoever is speaking in it. */
+        byVoice: false,
+        /** A colour per voice index. Short or empty falls back to the palette. */
+        voiceColors: Types.custom([]),
+        fill: Types.custom("#6366f1", { resolve: fillOps.resolve, lerp: fillOps.lerp }),
+    },
+    // Nothing declares a component's paints but itself.
+    load: (loader, state) => loader.fill(state.fill),
+    render: (ctx, state) => {
+        drawBars(ctx, state);
+        ctx.children();
+    },
+});
+/**
+ * The second of the recording the visualiser is showing.
+ *
+ * Off the node's own clock rather than the scene's, which is what "from the
+ * moment this node appeared" means — the same clock the engine's own
+ * `Video` times its picture from, and the same one that makes a node dropped
+ * halfway through a clip start its recording at its entrance rather than
+ * partway in.
+ */
+function at(ctx, s) {
+    return s.offset + (s.playing ? Math.max(0, ctx.time.elapsed) : 0);
+}
+function drawBars(ctx, s) {
+    const { width, height } = ctx.size;
+    if (width <= 0 || height <= 0)
+        return;
+    const count = Math.max(1, Math.round(s.bars));
+    const span = Math.max(0.05, s.window);
+    const now = at(ctx, s);
+    const voice = s.speaker < 0 ? null : Math.round(s.speaker);
+    // The window is centred on the playhead, so the bars run *toward* the
+    // middle and away again — the arrangement every mixer's meter uses, and the
+    // one that reads as sound arriving rather than as a strip scrolling past.
+    const sampled = forSpeaker(sampleEnvelope(s.envelope, now - span / 2, now + span / 2, count), voice);
+    const shaped = s.style === "line" ? taper(sampled) : sampled;
+    const boxes = layOutBars(shaped, {
+        width,
+        height,
+        gap: s.style === "blocks" ? 0.12 : s.gap,
+        align: s.align,
+        gain: s.gain,
+        floor: s.floor,
+    });
+    if (boxes.length === 0)
+        return;
+    const groups = groupByPaint(boxes, (i) => livePaintKey(shaped[i].speaker, s.byVoice, voice));
+    for (const [key, run] of groups) {
+        const graphics = paintBars(run, paintFor(s, key), s.radius);
+        if (graphics)
+            ctx.draw(graphics);
+    }
+}
+/** See `FullWaveform`'s paints — a voice is a hue, never a gradient. */
+function paintFor(s, key) {
+    if (key === "all")
+        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);
+}
+/**
+ * Rolls the ends of a window off toward silence.
+ *
+ * What separates the `line` style from `bars`: a hard-edged window makes the
+ * loud bar entering at the right edge appear from nothing, which reads as a
+ * glitch rather than as sound arriving. Fading the outer fifth turns the same
+ * data into a shape that grows out of the baseline — the profile a spectrum
+ * display has, and the reason it looks like one object rather than a row of
+ * separate meters.
+ */
+function taper(bars) {
+    const count = bars.length;
+    if (count < 3)
+        return [...bars];
+    const edge = Math.max(1, Math.floor(count / 5));
+    return bars.map((bar, i) => {
+        const fromEnd = Math.min(i, count - 1 - i);
+        const weight = clamp01(fromEnd / edge);
+        return { magnitude: bar.magnitude * weight, speaker: bar.speaker };
+    });
+}
+//# sourceMappingURL=live-waveform.js.map

package/dist/waveform/live-waveform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-waveform.js","sourceRoot":"","sources":["../../src/waveform/live-waveform.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  Types,\n  component2d,\n  fillOps,\n  type Fill,\n  type FillResolved,\n  type NodeOf,\n  type RenderContext,\n  // Named so the emitted declaration reaches these through the sdk, not core.\n  type Node2D as _Node2D,\n  type Node2DProps as _Node2DProps,\n} from \"@motionscript/sdk\"\n\nimport {\n  EMPTY_ENVELOPE,\n  forSpeaker,\n  sampleEnvelope,\n  type AudioEnvelope,\n  type EnvelopeBar,\n} from \"./envelope\"\nimport {\n  clamp01,\n  groupByPaint,\n  layOutBars,\n  livePaintKey,\n  paintBars,\n  voiceColor,\n  type WaveformAlignment,\n  type WaveformStyle,\n} from \"./shared\"\n\n/**\n * A **live audio visualiser**: bars that move with the recording as it plays.\n *\n * The thing every podcast-to-video tool puts beside the artwork. It is not a\n * picture of the file — that is {@link FullWaveform} — it is a picture of *this\n * moment*, and what it is for is making a static frame of a talking head feel\n * like it is playing.\n *\n * ## \"Live\" without listening\n *\n * Nothing here reads an audio device. The bars are sampled out of a baked\n * envelope at the node's own elapsed time, which is what makes the visualiser\n * survive the thing it exists for: an **export**, where there is no playback to\n * analyse and frames may be rendered out of order or in parallel. A frame is a\n * pure function of its time, so scrubbing back and forth over the visualiser\n * redraws exactly what it drew the first time — which an analyser node, by\n * construction, cannot promise. See {@link AudioEnvelope}.\n *\n * ## The speaker filter\n *\n * `speaker` narrows the node to one voice of a diarized recording, and it\n * is the reason this node knows about transcripts at all. Two visualisers beside\n * two headshots, each filtered to its own host, is a podcast edit that would\n * otherwise be done by hand for every turn — and because the filter *silences*\n * rather than skips (see {@link forSpeaker}), the quiet host visibly stops\n * talking instead of vanishing. Nothing about that requires the words: only who\n * is talking when, which is what the diarizer produces.\n *\n * A filter naming a voice the recording doesn't have draws a resting row rather\n * than everything — a picture of \"this person never speaks here\", which is\n * true, where falling back to the unfiltered mix would be a silent lie about\n * whose voice you were watching.\n */\nexport const LiveWaveform = component2d({\n  key: \"liveWaveform\",\n  state: {\n    /** The baked recording. See {@link AudioEnvelope} for why it is baked. */\n    envelope: Types.custom<AudioEnvelope>(EMPTY_ENVELOPE),\n    /** How many bars the visualiser is made of. */\n    bars: 48,\n    /** Space between bars, as a fraction of the pitch. */\n    gap: 0.35,\n    radius: 4,\n    /** How many seconds of audio are on screen at once. */\n    window: 3,\n    /** Seconds into the file the node's first frame shows. */\n    offset: 0,\n    /** Advance with the scene clock. Off freezes the picture at `offset`. */\n    playing: true,\n    /** Multiplies every magnitude before it is clamped. */\n    gain: 1.4,\n    /** How much of the box a silent bar still occupies, `0`–`1`. */\n    floor: 0.04,\n    align: Types.custom<WaveformAlignment>(\"center\"),\n    style: Types.custom<WaveformStyle>(\"bars\"),\n    /**\n     * Show only this voice's activity, by index into the recording's own\n     * numbering. `-1` — the default — is every voice.\n     */\n    speaker: -1,\n    /** Colour each bar by whoever is speaking in it. */\n    byVoice: false,\n    /** A colour per voice index. Short or empty falls back to the palette. */\n    voiceColors: Types.custom<string[]>([]),\n    fill: Types.custom<Fill, FillResolved[]>(\"#6366f1\", { resolve: fillOps.resolve, lerp: fillOps.lerp }),\n  },\n  // Nothing declares a component's paints but itself.\n  load: (loader, state) => loader.fill(state.fill),\n  render: (ctx, state) => {\n    drawBars(ctx, state)\n    ctx.children()\n  },\n})\n\nexport type LiveWaveform = NodeOf<typeof LiveWaveform>\nexport type LiveWaveformProps = NonNullable<Parameters<typeof LiveWaveform>[0]>\n\ninterface LiveState {\n  readonly envelope: AudioEnvelope\n  readonly bars: number\n  readonly gap: number\n  readonly radius: number\n  readonly window: number\n  readonly offset: number\n  readonly playing: boolean\n  readonly gain: number\n  readonly floor: number\n  readonly align: WaveformAlignment\n  readonly style: WaveformStyle\n  readonly speaker: number\n  readonly byVoice: boolean\n  readonly voiceColors: string[]\n  readonly fill: FillResolved[]\n}\n\n/**\n * The second of the recording the visualiser is showing.\n *\n * Off the node's own clock rather than the scene's, which is what \"from the\n * moment this node appeared\" means — the same clock the engine's own\n * `Video` times its picture from, and the same one that makes a node dropped\n * halfway through a clip start its recording at its entrance rather than\n * partway in.\n */\nfunction at(ctx: RenderContext, s: LiveState): number {\n  return s.offset + (s.playing ? Math.max(0, ctx.time.elapsed) : 0)\n}\n\nfunction drawBars(ctx: RenderContext, s: LiveState): void {\n  const { width, height } = ctx.size\n  if (width <= 0 || height <= 0) return\n\n  const count = Math.max(1, Math.round(s.bars))\n  const span = Math.max(0.05, s.window)\n  const now = at(ctx, s)\n  const voice = s.speaker < 0 ? null : Math.round(s.speaker)\n\n  // The window is centred on the playhead, so the bars run *toward* the\n  // middle and away again — the arrangement every mixer's meter uses, and the\n  // one that reads as sound arriving rather than as a strip scrolling past.\n  const sampled = forSpeaker(\n    sampleEnvelope(s.envelope, now - span / 2, now + span / 2, count),\n    voice\n  )\n\n  const shaped = s.style === \"line\" ? taper(sampled) : sampled\n  const boxes = layOutBars(shaped, {\n    width,\n    height,\n    gap: s.style === \"blocks\" ? 0.12 : s.gap,\n    align: s.align,\n    gain: s.gain,\n    floor: s.floor,\n  })\n  if (boxes.length === 0) return\n\n  const groups = groupByPaint(boxes, (i) =>\n    livePaintKey(shaped[i].speaker, s.byVoice, voice)\n  )\n\n  for (const [key, run] of groups) {\n    const graphics = paintBars(run, paintFor(s, key), s.radius)\n    if (graphics) ctx.draw(graphics)\n  }\n}\n\n/** See `FullWaveform`'s paints — a voice is a hue, never a gradient. */\nfunction paintFor(s: LiveState, key: string): Fill {\n  if (key === \"all\") return s.fill\n  const voice = Number(key.slice(\"voice:\".length))\n  if (!Number.isFinite(voice) || voice < 0) return s.fill\n  return s.voiceColors[voice] ?? voiceColor(voice)\n}\n\n/**\n * Rolls the ends of a window off toward silence.\n *\n * What separates the `line` style from `bars`: a hard-edged window makes the\n * loud bar entering at the right edge appear from nothing, which reads as a\n * glitch rather than as sound arriving. Fading the outer fifth turns the same\n * data into a shape that grows out of the baseline — the profile a spectrum\n * display has, and the reason it looks like one object rather than a row of\n * separate meters.\n */\nfunction taper(bars: readonly EnvelopeBar[]): EnvelopeBar[] {\n  const count = bars.length\n  if (count < 3) return [...bars]\n  const edge = Math.max(1, Math.floor(count / 5))\n\n  return bars.map((bar, i) => {\n    const fromEnd = Math.min(i, count - 1 - i)\n    const weight = clamp01(fromEnd / edge)\n    return { magnitude: bar.magnitude * weight, speaker: bar.speaker }\n  })\n}\n"]}

package/dist/waveform/shared.d.ts

@@ -0,0 +1,98 @@
+import { Graphics2D, type Fill } from "@motionscript/sdk";
+import type { EnvelopeBar } from "./envelope.js";
+/**
+ * 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.
+ */
+/** How a bar is grown out of its baseline. */
+export declare const WAVEFORM_ALIGNMENTS: readonly ["center", "bottom"];
+export type WaveformAlignment = (typeof WAVEFORM_ALIGNMENTS)[number];
+/** What the bars are shaped like. */
+export declare const WAVEFORM_STYLES: readonly ["bars", "line", "blocks"];
+export type WaveformStyle = (typeof WAVEFORM_STYLES)[number];
+/**
+ * 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.
+ */
+export declare const VOICE_PALETTE: readonly ["#6366f1", "#14b8a6", "#f59e0b", "#ec4899", "#22c55e", "#3b82f6", "#f97316", "#a855f7"];
+/** The colour a voice takes, wrapping past the end of the palette. */
+export declare function voiceColor(index: number): string;
+/**
+ * Where one bar sits and how tall it came out: its top-left corner and size, in
+ * the node's own pixels with **y pointing down** from the middle of the box.
+ * {@link paintBars} turns that into the centred, y-up rect the renderer draws.
+ */
+export interface BarBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * 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.
+ */
+export declare function layOutBars(bars: readonly EnvelopeBar[], options: {
+    width: number;
+    height: number;
+    gap: number;
+    align: WaveformAlignment;
+    /** Multiplies every magnitude before it is clamped back into 0…1. */
+    gain: number;
+    /** Fraction of the box a silent bar still occupies. */
+    floor: number;
+}): BarBox[];
+/**
+ * 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.
+ */
+export declare function paintBars(boxes: readonly BarBox[], fill: Fill, radius: number): Graphics2D | null;
+/**
+ * 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.
+ */
+export declare function groupByPaint<K>(boxes: readonly BarBox[], keyOf: (index: number) => K): Map<K, BarBox[]>;
+export declare function clamp01(value: number): number;
+/**
+ * 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.
+ */
+export declare function livePaintKey(barSpeaker: number, byVoice: boolean, filteredVoice: number | null): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/waveform/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/waveform/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,IAAI,EAAqB,MAAM,mBAAmB,CAAA;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C;;;;;;;;GAQG;AAEH,8CAA8C;AAC9C,eAAO,MAAM,mBAAmB,+BAAgC,CAAA;AAChE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEpE,qCAAqC;AACrC,eAAO,MAAM,eAAe,qCAAsC,CAAA;AAClE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAE5D;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,mGAShB,CAAA;AAEV,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,iBAAiB,CAAA;IACxB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;CACd,GACA,MAAM,EAAE,CA2BV;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,GACb,UAAU,GAAG,IAAI,CAmBnB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,GAC1B,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CASlB;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,MAAM,GAAG,IAAI,GAC3B,MAAM,CAGR"}

package/dist/waveform/shared.js

@@ -0,0 +1,149 @@
+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.
+ */
+/** 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.
+ */
+export const VOICE_PALETTE = [
+    "#6366f1",
+    "#14b8a6",
+    "#f59e0b",
+    "#ec4899",
+    "#22c55e",
+    "#3b82f6",
+    "#f97316",
+    "#a855f7",
+];
+/** The colour a voice takes, wrapping past the end of the palette. */
+export function voiceColor(index) {
+    return VOICE_PALETTE[((index % VOICE_PALETTE.length) + VOICE_PALETTE.length) %
+        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.
+ */
+export function layOutBars(bars, options) {
+    const { width, height, gap, align, gain, floor } = options;
+    const count = bars.length;
+    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 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 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.
+        const h = Math.max(1, align === "center" ? reach * 2 : reach);
+        out[i] =
+            align === "center"
+                ? { x, y: -h / 2, width: barWidth, height: h }
+                : { x, y: height / 2 - h, width: barWidth, height: h };
+    }
+    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.
+ */
+export function paintBars(boxes, fill, radius) {
+    if (boxes.length === 0)
+        return null;
+    if (fill.length === 0)
+        return null;
+    const graphics = new Graphics2D();
+    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.
+            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.
+            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.
+ */
+export function groupByPaint(boxes, keyOf) {
+    const groups = new Map();
+    for (let i = 0; i < boxes.length; i++) {
+        const key = keyOf(i);
+        const run = groups.get(key);
+        if (run)
+            run.push(boxes[i]);
+        else
+            groups.set(key, [boxes[i]]);
+    }
+    return groups;
+}
+export function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+/**
+ * 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.
+ */
+export function livePaintKey(barSpeaker, byVoice, filteredVoice) {
+    if (filteredVoice !== null)
+        return `voice:${filteredVoice}`;
+    return byVoice ? `voice:${barSpeaker}` : "all";
+}
+//# sourceMappingURL=shared.js.map

package/dist/waveform/shared.js.map

@@ -0,0 +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"]}