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

package/dist/waveform/live-waveform.js

@@ -0,0 +1,191 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Node2D, node, fillOps, property, } from "@motionscript/core";
+import { declarePaints } from "@motionscript/core/component";
+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
+ *
+ * {@link 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.
+ */
+let LiveWaveform = class LiveWaveform extends Node2D {
+    declareAssets(assets) {
+        super.declareAssets(assets);
+        declarePaints(this, assets);
+    }
+    /**
+     * 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 motion-script's own
+     * `Video` times its picture from, and the same one that makes a node dropped
+     * halfway through a scene start its recording at its entrance rather than
+     * partway in.
+     */
+    get at() {
+        return this.offset + (this.playing ? Math.max(0, this.time.elapsed) : 0);
+    }
+    renderSelf(ctx) {
+        const rect = this.layoutBounds;
+        const width = rect?.width ?? 0;
+        const height = rect?.height ?? 0;
+        if (width <= 0 || height <= 0)
+            return;
+        const count = Math.max(1, Math.round(this.bars));
+        const span = Math.max(0.05, this.window);
+        const at = this.at;
+        const voice = this.speaker < 0 ? null : Math.round(this.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(this.envelope, at - span / 2, at + span / 2, count), voice);
+        const shaped = this.style === "line" ? taper(sampled) : sampled;
+        const boxes = layOutBars(shaped, {
+            width,
+            height,
+            gap: this.style === "blocks" ? 0.12 : this.gap,
+            align: this.align,
+            gain: this.gain,
+            floor: this.floor,
+        });
+        if (boxes.length === 0)
+            return;
+        const groups = groupByPaint(boxes, (i) => livePaintKey(shaped[i].speaker, this.byVoice, voice));
+        for (const [key, run] of groups) {
+            const graphics = paintBars(run, this.paintFor(key), this.radius);
+            if (graphics)
+                ctx.draw(graphics);
+        }
+    }
+    /** See {@link FullWaveform.paintFor} — a voice is a hue, never a gradient. */
+    paintFor(key) {
+        if (key === "all")
+            return this.fill;
+        const voice = Number(key.slice("voice:".length));
+        if (!Number.isFinite(voice) || voice < 0)
+            return this.fill;
+        return this.voiceColors[voice] ?? voiceColor(voice);
+    }
+};
+__decorate([
+    property({ default: EMPTY_ENVELOPE })
+], LiveWaveform.prototype, "envelope", void 0);
+__decorate([
+    property({ default: 48 })
+], LiveWaveform.prototype, "bars", void 0);
+__decorate([
+    property({ default: 0.35 })
+], LiveWaveform.prototype, "gap", void 0);
+__decorate([
+    property({ default: 4 })
+], LiveWaveform.prototype, "radius", void 0);
+__decorate([
+    property({ default: 3 })
+], LiveWaveform.prototype, "window", void 0);
+__decorate([
+    property({ default: 0 })
+], LiveWaveform.prototype, "offset", void 0);
+__decorate([
+    property({ default: true })
+], LiveWaveform.prototype, "playing", void 0);
+__decorate([
+    property({ default: 1.4 })
+], LiveWaveform.prototype, "gain", void 0);
+__decorate([
+    property({ default: 0.04 })
+], LiveWaveform.prototype, "floor", void 0);
+__decorate([
+    property({ default: "center" })
+], LiveWaveform.prototype, "align", void 0);
+__decorate([
+    property({ default: "bars" })
+], LiveWaveform.prototype, "style", void 0);
+__decorate([
+    property({ default: -1 })
+], LiveWaveform.prototype, "speaker", void 0);
+__decorate([
+    property({ default: false })
+], LiveWaveform.prototype, "byVoice", void 0);
+__decorate([
+    property({ default: [] })
+], LiveWaveform.prototype, "voiceColors", void 0);
+__decorate([
+    property({
+        default: "#6366f1",
+        mapper: fillOps.resolve,
+        tween: fillOps.lerp,
+    })
+], LiveWaveform.prototype, "fill", void 0);
+LiveWaveform = __decorate([
+    node({
+        key: "liveWaveform",
+        parentKey: "node",
+        forkable: true,
+        layout: {
+            children: "freeform",
+            defaultWidthMode: "fixed",
+            defaultHeightMode: "fixed",
+            acceptsChildren: true,
+        },
+        seed: {
+            width: 420,
+            height: 220,
+        },
+    })
+], LiveWaveform);
+export { LiveWaveform };
+/**
+ * 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  Node2D,\n  node,\n  fillOps,\n  property,\n  type AssetScope,\n  type Fill,\n  type Node2DProps,\n  type RenderContext2D,\n} from \"@motionscript/core\"\n\nimport { declarePaints } from \"@motionscript/core/component\"\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\nexport interface LiveWaveformProps extends Node2DProps {\n  /** The baked recording. See {@link AudioEnvelope} for why it is baked. */\n  envelope: AudioEnvelope\n  /** How many bars the visualiser is made of. */\n  bars: number\n  /** Space between bars, as a fraction of the pitch. */\n  gap: number\n  radius: number\n  /** How many seconds of audio are on screen at once. */\n  window: number\n  /** Seconds into the file the node's first frame shows. */\n  offset: number\n  /** Advance with the scene clock. Off freezes the picture at {@link offset}. */\n  playing: boolean\n  /** Multiplies every magnitude before it is clamped. */\n  gain: number\n  /** How much of the box a silent bar still occupies, `0`–`1`. */\n  floor: number\n  align: WaveformAlignment\n  style: WaveformStyle\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: number\n  /** Colour each bar by whoever is speaking in it. */\n  byVoice: boolean\n  /** A colour per voice index. Short or empty falls back to the palette. */\n  voiceColors: string[]\n  fill: Fill\n}\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 * {@link 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 */\n@node({\n  key: \"liveWaveform\",\n  parentKey: \"node\",\n  forkable: true,\n  layout: {\n    children: \"freeform\",\n    defaultWidthMode: \"fixed\",\n    defaultHeightMode: \"fixed\",\n    acceptsChildren: true,\n  },\n  seed: {\n    width: 420,\n    height: 220,\n  },\n})\nexport class LiveWaveform extends Node2D<LiveWaveformProps> {\n  @property({ default: EMPTY_ENVELOPE }) declare envelope: AudioEnvelope\n  @property({ default: 48 }) declare bars: number\n  @property({ default: 0.35 }) declare gap: number\n  @property({ default: 4 }) declare radius: number\n  @property({ default: 3 }) declare window: number\n  @property({ default: 0 }) declare offset: number\n  @property({ default: true }) declare playing: boolean\n  @property({ default: 1.4 }) declare gain: number\n  @property({ default: 0.04 }) declare floor: number\n  @property({ default: \"center\" }) declare align: WaveformAlignment\n  @property({ default: \"bars\" }) declare style: WaveformStyle\n  @property({ default: -1 }) declare speaker: number\n  @property({ default: false }) declare byVoice: boolean\n  @property({ default: [] }) declare voiceColors: string[]\n\n  @property({\n    default: \"#6366f1\",\n    mapper: fillOps.resolve,\n    tween: fillOps.lerp,\n  })\n  declare fill: Fill\n\n  override declareAssets(assets: AssetScope): void {\n    super.declareAssets(assets)\n    declarePaints(this, assets)\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 motion-script's own\n   * `Video` times its picture from, and the same one that makes a node dropped\n   * halfway through a scene start its recording at its entrance rather than\n   * partway in.\n   */\n  private get at(): number {\n    return this.offset + (this.playing ? Math.max(0, this.time.elapsed) : 0)\n  }\n\n  protected renderSelf(ctx: RenderContext2D): void {\n    const rect = this.layoutBounds\n    const width = rect?.width ?? 0\n    const height = rect?.height ?? 0\n    if (width <= 0 || height <= 0) return\n\n    const count = Math.max(1, Math.round(this.bars))\n    const span = Math.max(0.05, this.window)\n    const at = this.at\n    const voice = this.speaker < 0 ? null : Math.round(this.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(this.envelope, at - span / 2, at + span / 2, count),\n      voice\n    )\n\n    const shaped = this.style === \"line\" ? taper(sampled) : sampled\n    const boxes = layOutBars(shaped, {\n      width,\n      height,\n      gap: this.style === \"blocks\" ? 0.12 : this.gap,\n      align: this.align,\n      gain: this.gain,\n      floor: this.floor,\n    })\n    if (boxes.length === 0) return\n\n    const groups = groupByPaint(boxes, (i) =>\n      livePaintKey(shaped[i].speaker, this.byVoice, voice)\n    )\n\n    for (const [key, run] of groups) {\n      const graphics = paintBars(run, this.paintFor(key), this.radius)\n      if (graphics) ctx.draw(graphics)\n    }\n  }\n\n  /** See {@link FullWaveform.paintFor} — a voice is a hue, never a gradient. */\n  private paintFor(key: string): Fill {\n    if (key === \"all\") return this.fill\n    const voice = Number(key.slice(\"voice:\".length))\n    if (!Number.isFinite(voice) || voice < 0) return this.fill\n    return this.voiceColors[voice] ?? voiceColor(voice)\n  }\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,96 @@
+import { Graphics2D, type Fill } from "@motionscript/core";
+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.
+ *
+ * The same eight the app's speaker library suggests, in the same order, so a
+ * transcript whose voices are still unnamed already draws in the colours the
+ * transcript panel is showing them in. Duplicated as literals rather than
+ * imported because `scene-core` knows nothing about the app's speaker table —
+ * and must not, since a scene has to build in a headless render with no
+ * database in scope.
+ */
+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. */
+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, exactly as it does on the timeline's clip bars.
+ */
+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,oBAAoB,CAAA;AAE7E,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;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,mGAShB,CAAA;AAEV,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED,mDAAmD;AACnD,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,CA4BV;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,GACb,UAAU,GAAG,IAAI,CAiBnB;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,150 @@
+import { Graphics2D } from "@motionscript/core";
+/**
+ * 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.
+ *
+ * The same eight the app's speaker library suggests, in the same order, so a
+ * transcript whose voices are still unnamed already draws in the colours the
+ * transcript panel is showing them in. Duplicated as literals rather than
+ * imported because `scene-core` knows nothing about the app's speaker table —
+ * and must not, since a scene has to build in a headless render with no
+ * database in scope.
+ */
+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, exactly as it does on the timeline's clip bars.
+ */
+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;
+        out[i] =
+            align === "center"
+                ? { x, y: -reach, width: barWidth, height: Math.max(1, reach * 2) }
+                : {
+                    x,
+                    y: height / 2 - reach,
+                    width: barWidth,
+                    height: Math.max(1, reach),
+                };
+    }
+    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,
+            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/core\"\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 * The same eight the app's speaker library suggests, in the same order, so a\n * transcript whose voices are still unnamed already draws in the colours the\n * transcript panel is showing them in. Duplicated as literals rather than\n * imported because `scene-core` knows nothing about the app's speaker table —\n * and must not, since a scene has to build in a headless render with no\n * database in scope.\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/** Where one bar sits and how tall it came out. */\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, exactly as it does on the timeline's clip bars.\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    out[i] =\n      align === \"center\"\n        ? { x, y: -reach, width: barWidth, height: Math.max(1, reach * 2) }\n        : {\n            x,\n            y: height / 2 - reach,\n            width: barWidth,\n            height: Math.max(1, reach),\n          }\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      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"]}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@motionscript/audio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.0",
+  "type": "module",
+  "description": "Waveform components for Motion Script: a full recording drawn as bars, and a live meter that responds to a signal.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/motionscript-dev/motionscript.git",
+    "directory": "packages/components/audio"
+  },
+  "homepage": "https://motionscript.dev",
+  "bugs": {
+    "url": "https://github.com/motionscript-dev/motionscript/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "registry.json",
+    "CHANGELOG.md",
+    "!dist/**/*.tsbuildinfo",
+    "!src/**/tests/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.fixtures.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./kit": {
+      "types": "./dist/kit.d.ts",
+      "default": "./dist/kit.js"
+    }
+  },
+  "keywords": [
+    "motion-script",
+    "motion script",
+    "audio",
+    "waveform",
+    "animation"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@motionscript/core": "^0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "eslint": "^9.39.4",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import-x": "^4.16.1",
+    "tsc-alias": "^1.8.16",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.48.0",
+    "vitest": "^4.1.5",
+    "@motionscript/core": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths && node ../../../scripts/build-browser.mjs",
+    "dev": "tsc -p tsconfig.build.json --watch & tsc-alias -p tsconfig.build.json --resolve-full-paths -w",
+    "clean": "rimraf --glob dist .turbo *.tsbuildinfo",
+    "test": "vitest --passWithNoTests",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/registry.json

@@ -0,0 +1,28 @@
+{
+  "kit": {
+    "barrel": "src/kit.ts",
+    "specifier": "@motionscript/audio/kit"
+  },
+  "items": [
+    {
+      "name": "full-waveform",
+      "description": "A whole recording drawn as bars, with a played portion that advances.",
+      "root": "src/waveform",
+      "files": [
+        "envelope.ts",
+        "full-waveform.ts",
+        "shared.ts"
+      ]
+    },
+    {
+      "name": "live-waveform",
+      "description": "A visualiser whose bars move with the recording as it plays, coloured by voice.",
+      "root": "src/waveform",
+      "files": [
+        "envelope.ts",
+        "live-waveform.ts",
+        "shared.ts"
+      ]
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./waveform"
+export { NODES } from "./nodes";

package/src/kit.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+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,
+  paintBars,
+  voiceColor,
+} from "./waveform/shared"
+export type { BarBox, WaveformAlignment, WaveformStyle } from "./waveform/shared"

package/src/nodes.ts

@@ -0,0 +1,19 @@
+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 class's `@node()`
+ * key. The decorator only *declares* that key: nothing is registered by the mere
+ * act of importing a module, so a registry holds exactly what its owner asked
+ * for and two engines in one process can differ about it.
+ *
+ * Listing class **values** is also what survives bundling. This package declares
+ * `sideEffects: false`, which licenses a bundler to drop a module nothing
+ * imports a value from, and a document names a node type by string — so
+ * `import "./waveform/full-waveform"` for its side effect is exactly what gets shaken out, where an
+ * array of bindings is a data dependency that cannot be.
+ */
+export const NODES = [FullWaveform, LiveWaveform];