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

package/dist/kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kit.js","sourceRoot":"","sources":["../src/kit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEhF,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,OAAO,EACP,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,SAAS,EACT,UAAU,GACX,MAAM,mBAAmB,CAAA","sourcesContent":["/**\n * What the two waveform nodes share, importable without copying it.\n *\n * A registry item copies `envelope.ts` and `shared.ts` beside its node: they\n * hold no class and no registered state, so a fork owning its own copy splits\n * no identity. This is the same surface for a host that samples envelopes or\n * lays bars out itself, and for a fork that keeps only its node file.\n */\nexport { EMPTY_ENVELOPE, forSpeaker, sampleEnvelope } from \"./waveform/envelope\"\nexport type { AudioEnvelope, EnvelopeBar } from \"./waveform/envelope\"\nexport {\n  VOICE_PALETTE,\n  WAVEFORM_ALIGNMENTS,\n  WAVEFORM_STYLES,\n  clamp01,\n  groupByPaint,\n  layOutBars,\n  livePaintKey,\n  paintBars,\n  voiceColor,\n} from \"./waveform/shared\"\nexport type { BarBox, WaveformAlignment, WaveformStyle } from \"./waveform/shared\"\n"]}

package/dist/nodes.d.ts

@@ -0,0 +1,16 @@
+import { FullWaveform } from "./waveform/full-waveform.js";
+import { LiveWaveform } from "./waveform/live-waveform.js";
+/**
+ * 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.
+ */
+export declare const NODES: (typeof FullWaveform | typeof LiveWaveform)[];
+//# sourceMappingURL=nodes.d.ts.map

package/dist/nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../src/nodes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,KAAK,EAAE,CAAC,OAAO,YAAY,GAAG,OAAO,YAAY,CAAC,EAAiC,CAAC"}

package/dist/nodes.js

@@ -0,0 +1,17 @@
+import { FullWaveform } from "./waveform/full-waveform.js";
+import { LiveWaveform } from "./waveform/live-waveform.js";
+/**
+ * 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 = [FullWaveform, LiveWaveform];
+//# sourceMappingURL=nodes.js.map

package/dist/nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.js","sourceRoot":"","sources":["../src/nodes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,yGAAyG;AACzG,MAAM,CAAC,MAAM,KAAK,GAAkD,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC","sourcesContent":["import { FullWaveform } from \"./waveform/full-waveform\";\nimport { LiveWaveform } from \"./waveform/live-waveform\";\n\n/**\n * Every node type this package publishes.\n *\n * A host registers these by handing the array to an engine —\n * `new Engine(platform, { nodes: NODES })` — which reads each component's key.\n * Defining a component only *declares* that key: nothing is registered by\n * importing a module, so a registry holds exactly what its owner asked for.\n *\n * Listing the component **values** is also what survives bundling: this package\n * declares `sideEffects: false`, and a document names a node type by string, so\n * an import kept only for its side effect is exactly what gets shaken out.\n */\n// Typed by name, so the declaration names each component rather than spelling out its type through core.\nexport const NODES: (typeof FullWaveform | typeof LiveWaveform)[] = [FullWaveform, LiveWaveform];\n"]}

package/dist/waveform/envelope.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+export interface AudioEnvelope {
+    /**
+     * Peak magnitude per bucket, 0…1. Buckets span {@link duration} evenly. A
+     * `Float32Array`, or the plain `number[]` a document stores.
+     */
+    magnitude: ArrayLike<number>;
+    /** The decoded length in 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.
+     */
+    speaker: ArrayLike<number> | null;
+    /** How many distinct voices the diarizer found. Zero when it did not run. */
+    speakers: number;
+}
+/** The envelope of a track that hasn't loaded — or isn't there. */
+export declare const EMPTY_ENVELOPE: AudioEnvelope;
+/** One drawn bar: how loud, and whose. */
+export interface EnvelopeBar {
+    /** 0…1. */
+    magnitude: number;
+    /** The 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.
+ */
+export declare function sampleEnvelope(envelope: AudioEnvelope, from: number, to: number, bars: number): EnvelopeBar[];
+/**
+ * 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.
+ */
+export declare function forSpeaker(bars: EnvelopeBar[], voice: number | null): EnvelopeBar[];
+//# sourceMappingURL=envelope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/waveform/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;IAC5B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;IACjC,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAA;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,WAAW;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX,WAAW,EAAE,CAkCf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,WAAW,EAAE,EACnB,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB,WAAW,EAAE,CAKf"}

package/dist/waveform/envelope.js

@@ -0,0 +1,126 @@
+/**
+ * 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 envelope of a track that hasn't loaded — or isn't there. */
+export const EMPTY_ENVELOPE = {
+    magnitude: new Float32Array(0),
+    duration: 0,
+    speaker: null,
+    speakers: 0,
+};
+/**
+ * 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.
+ */
+export function sampleEnvelope(envelope, from, to, bars) {
+    const count = Math.max(0, Math.floor(bars));
+    const out = new Array(count);
+    for (let i = 0; i < count; i++)
+        out[i] = { magnitude: 0, speaker: -1 };
+    const buckets = envelope.magnitude.length;
+    if (count === 0 || buckets === 0 || envelope.duration <= 0)
+        return out;
+    const perSecond = buckets / envelope.duration;
+    const span = (to - from) / count;
+    for (let i = 0; i < count; i++) {
+        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.
+        const first = Math.floor(start);
+        const last = Math.max(first, Math.ceil(end) - 1);
+        let loudest = 0;
+        let speaker = -1;
+        for (let b = first; b <= last; b++) {
+            if (b < 0 || b >= buckets)
+                continue;
+            const value = envelope.magnitude[b];
+            if (value < loudest)
+                continue;
+            loudest = value;
+            speaker = envelope.speaker ? envelope.speaker[b] : -1;
+        }
+        out[i] = { magnitude: loudest, speaker };
+    }
+    return out;
+}
+/**
+ * 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.
+ */
+export function forSpeaker(bars, voice) {
+    if (voice === null)
+        return bars;
+    return bars.map((bar) => bar.speaker === voice ? bar : { magnitude: 0, speaker: bar.speaker });
+}
+//# sourceMappingURL=envelope.js.map

package/dist/waveform/envelope.js.map

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

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

@@ -0,0 +1,118 @@
+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 **waveform overview**: the whole recording's shape, drawn at once.
+ *
+ * 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.
+ */
+export declare const FullWaveform: import("@motionscript/sdk").Component<"fullWaveform", 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 columns the whole file is drawn as. */
+    readonly bars: 120;
+    /** Space between bars, as a fraction of the pitch. See {@link layOutBars}. */
+    readonly gap: 0.3;
+    /** Corner radius of a bar, capped at half its width. */
+    readonly radius: 2;
+    /** How much of the file reads as played, `0`–`1`. Tweenable. */
+    readonly progress: 0;
+    /** Drive `progress` from the node's own clock instead of the prop. */
+    readonly follow: false;
+    /** Multiplies every magnitude — a quiet track pulled up to fill its box. */
+    readonly gain: 1;
+    /** How much of the box a silent bar still occupies, `0`–`1`. */
+    readonly floor: 0.015;
+    readonly align: import("@motionscript/sdk").Type<"center" | "bottom", "center" | "bottom", false>;
+    /** Colour each voice's turns rather than splitting on played / not played. */
+    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>;
+    /** The bars ahead of the playhead. */
+    readonly fill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+    /** …and the bars behind it. */
+    readonly playedFill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+}>, {
+    readonly sweep: unknown;
+}, 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 columns the whole file is drawn as. */
+    readonly bars: 120;
+    /** Space between bars, as a fraction of the pitch. See {@link layOutBars}. */
+    readonly gap: 0.3;
+    /** Corner radius of a bar, capped at half its width. */
+    readonly radius: 2;
+    /** How much of the file reads as played, `0`–`1`. Tweenable. */
+    readonly progress: 0;
+    /** Drive `progress` from the node's own clock instead of the prop. */
+    readonly follow: false;
+    /** Multiplies every magnitude — a quiet track pulled up to fill its box. */
+    readonly gain: 1;
+    /** How much of the box a silent bar still occupies, `0`–`1`. */
+    readonly floor: 0.015;
+    readonly align: import("@motionscript/sdk").Type<"center" | "bottom", "center" | "bottom", false>;
+    /** Colour each voice's turns rather than splitting on played / not played. */
+    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>;
+    /** The bars ahead of the playhead. */
+    readonly fill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+    /** …and the bars behind it. */
+    readonly playedFill: 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 columns the whole file is drawn as. */
+    readonly bars: 120;
+    /** Space between bars, as a fraction of the pitch. See {@link layOutBars}. */
+    readonly gap: 0.3;
+    /** Corner radius of a bar, capped at half its width. */
+    readonly radius: 2;
+    /** How much of the file reads as played, `0`–`1`. Tweenable. */
+    readonly progress: 0;
+    /** Drive `progress` from the node's own clock instead of the prop. */
+    readonly follow: false;
+    /** Multiplies every magnitude — a quiet track pulled up to fill its box. */
+    readonly gain: 1;
+    /** How much of the box a silent bar still occupies, `0`–`1`. */
+    readonly floor: 0.015;
+    readonly align: import("@motionscript/sdk").Type<"center" | "bottom", "center" | "bottom", false>;
+    /** Colour each voice's turns rather than splitting on played / not played. */
+    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>;
+    /** The bars ahead of the playhead. */
+    readonly fill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+    /** …and the bars behind it. */
+    readonly playedFill: import("@motionscript/sdk").Type<Fill, FillResolved[], false>;
+}>, {
+    readonly sweep: unknown;
+}, _Node2D<_Node2DProps>>>>;
+export type FullWaveform = NodeOf<typeof FullWaveform>;
+export type FullWaveformProps = NonNullable<Parameters<typeof FullWaveform>[0]>;
+//# sourceMappingURL=full-waveform.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"full-waveform.d.ts","sourceRoot":"","sources":["../../src/waveform/full-waveform.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,IAAI,EACT,KAAK,YAAY,EACjB,KAAK,MAAM,EAGX,KAAK,MAAM,IAAI,OAAO,EACtB,KAAK,WAAW,IAAI,YAAY,EACjC,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAkC,KAAK,aAAa,EAAE,MAAM,YAAY,CAAA;AAc/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,YAAY;IAGrB,0EAA0E;;IAE1E,mDAAmD;;IAEnD,8EAA8E;;IAE9E,wDAAwD;;IAExD,gEAAgE;;IAEhE,sEAAsE;;IAEtE,4EAA4E;;IAE5E,gEAAgE;;;IAGhE,8EAA8E;;IAE9E,0EAA0E;;IAE1E,sCAAsC;;IAEtC,+BAA+B;;;;;IAvB/B,0EAA0E;;IAE1E,mDAAmD;;IAEnD,8EAA8E;;IAE9E,wDAAwD;;IAExD,gEAAgE;;IAEhE,sEAAsE;;IAEtE,4EAA4E;;IAE5E,gEAAgE;;;IAGhE,8EAA8E;;IAE9E,0EAA0E;;IAE1E,sCAAsC;;IAEtC,+BAA+B;;;IAvB/B,0EAA0E;;IAE1E,mDAAmD;;IAEnD,8EAA8E;;IAE9E,wDAAwD;;IAExD,gEAAgE;;IAEhE,sEAAsE;;IAEtE,4EAA4E;;IAE5E,gEAAgE;;;IAGhE,8EAA8E;;IAE9E,0EAA0E;;IAE1E,sCAAsC;;IAEtC,+BAA+B;;;;2BAwBjC,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/full-waveform.js

@@ -0,0 +1,146 @@
+import { Types, component2d, easeInOut, fillOps, } from "@motionscript/sdk";
+import { EMPTY_ENVELOPE, sampleEnvelope } from "./envelope.js";
+import { clamp01, groupByPaint, layOutBars, paintBars, voiceColor, } from "./shared.js";
+/** A paint entry as the waveforms declare theirs: resolved and tweened like a fill, its kind read off the default. */
+const paint = (initial) => Types.custom(initial, { resolve: fillOps.resolve, lerp: fillOps.lerp });
+/**
+ * A **waveform overview**: the whole recording's shape, drawn at once.
+ *
+ * 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.
+ */
+export const FullWaveform = component2d({
+    key: "fullWaveform",
+    state: {
+        /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+        envelope: Types.custom(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}. */
+        gap: 0.3,
+        /** Corner radius of a bar, capped at half its width. */
+        radius: 2,
+        /** How much of the file reads as played, `0`–`1`. Tweenable. */
+        progress: 0,
+        /** Drive `progress` from the node's own clock instead of the prop. */
+        follow: false,
+        /** Multiplies every magnitude — a quiet track pulled up to fill its box. */
+        gain: 1,
+        /** How much of the box a silent bar still occupies, `0`–`1`. */
+        floor: 0.015,
+        align: Types.custom("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. */
+        voiceColors: Types.custom([]),
+        /** 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.
+    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.
+         */
+        sweep: (timeline, state) => {
+            const ease = timeline.easing ? null : easeInOut();
+            const from = state.progress;
+            return timeline.animate((t) => ({ progress: from + (1 - from) * (ease ? ease(t) : t) }));
+        },
+    },
+    render: (ctx, state) => {
+        drawBars(ctx, state);
+        ctx.children();
+    },
+});
+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 sampled = sampleEnvelope(s.envelope, 0, s.envelope.duration, count);
+    const boxes = layOutBars(sampled, {
+        width,
+        height,
+        gap: s.gap,
+        align: s.align,
+        gain: s.gain,
+        floor: s.floor,
+    });
+    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.
+    const edge = played(ctx, s) * boxes.length;
+    const groups = groupByPaint(boxes, (i) => s.byVoice
+        ? `voice:${sampled[i].speaker}`
+        : i < edge
+            ? "played"
+            : "ahead");
+    for (const [key, run] of groups) {
+        const graphics = paintBars(run, paintFor(s, key), s.radius);
+        if (graphics)
+            ctx.draw(graphics);
+    }
+}
+/** Where the fill has reached, from whichever source is in charge. */
+function played(ctx, s) {
+    if (!s.follow)
+        return clamp01(s.progress);
+    const length = s.envelope.duration;
+    if (length <= 0)
+        return 0;
+    return clamp01(ctx.time.elapsed / length);
+}
+/**
+ * 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, key) {
+    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);
+}
+//# sourceMappingURL=full-waveform.js.map

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

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

package/dist/waveform/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 type { FullWaveformProps } from "./full-waveform.js";
+export { LiveWaveform } from "./live-waveform.js";
+export type { LiveWaveformProps } from "./live-waveform.js";
+export { EMPTY_ENVELOPE, forSpeaker, sampleEnvelope } from "./envelope.js";
+export type { AudioEnvelope, EnvelopeBar } from "./envelope.js";
+export { VOICE_PALETTE, WAVEFORM_ALIGNMENTS, WAVEFORM_STYLES, groupByPaint, layOutBars, paintBars, voiceColor, } from "./shared.js";
+export type { BarBox, WaveformAlignment, WaveformStyle } from "./shared.js";
+//# sourceMappingURL=index.d.ts.map