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

package/dist/waveform/envelope.js

@@ -0,0 +1,96 @@
+/**
+ * The shape of a recording, as the waveform nodes draw it.
+ *
+ * ## 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 app, once per file, and arrives here through the
+ * build (see `SceneAsset.envelope`) — 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 * ## 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 app, once per file, and arrives here through the\n * build (see `SceneAsset.envelope`) — the same arrangement a chart's rows and a\n * protein's atoms already use, and for the same reason: the build is\n * 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 * app 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 app 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  /** Peak magnitude per bucket, 0…1. Buckets span {@link duration} evenly. */\n  magnitude: Float32Array\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: Int16Array | 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,104 @@
+import { Node2D, type AssetScope, type CommandArgs, type Fill, type Node2DProps, type RenderContext2D } from "@motionscript/core";
+import type { Seekable } from "@motionscript/core/component";
+import { type AudioEnvelope } from "./envelope.js";
+import { type WaveformAlignment } from "./shared.js";
+export interface FullWaveformProps extends Node2DProps {
+    /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+    envelope: AudioEnvelope;
+    /** How many columns the whole file is drawn as. */
+    bars: number;
+    /** Space between bars, as a fraction of the pitch. See {@link layOutBars}. */
+    gap: number;
+    /** Corner radius of a bar, capped at half its width. */
+    radius: number;
+    /** How much of the file reads as played, `0`–`1`. Tweenable. */
+    progress: number;
+    /** Drive {@link progress} from the node's own clock instead of the prop. */
+    follow: boolean;
+    /** Multiplies every magnitude — a quiet track pulled up to fill its box. */
+    gain: number;
+    /** How much of the box a silent bar still occupies, `0`–`1`. */
+    floor: number;
+    align: WaveformAlignment;
+    /** Colour each voice's turns rather than splitting on played / not played. */
+    byVoice: boolean;
+    /** A colour per voice index. Short or empty falls back to the palette. */
+    voiceColors: string[];
+    /** The bars ahead of the playhead. */
+    fill: Fill;
+    /** …and the bars behind it. */
+    playedFill: Fill;
+}
+/**
+ * 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
+ *
+ * {@link 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 {@link byVoice} on, the played/ahead split is replaced by one colour per
+ * speaking voice — the drawing the timeline's clip bars already make, 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 class FullWaveform extends Node2D<FullWaveformProps> {
+    envelope: AudioEnvelope;
+    bars: number;
+    gap: number;
+    radius: number;
+    progress: number;
+    follow: boolean;
+    gain: number;
+    floor: number;
+    align: WaveformAlignment;
+    byVoice: boolean;
+    voiceColors: string[];
+    fill: Fill;
+    playedFill: Fill;
+    /**
+     * Fill the waveform in, left to right — the node's one command, since
+     * everything else about it is expressible as an ordinary `to`.
+     */
+    sweep(args: CommandArgs<Record<string, never>> & {
+        duration: number;
+    }): Seekable;
+    /**
+     * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
+     * paint props it carries — see {@link declarePaints}. `playedFill` is named
+     * past the conventional slots, so it is passed explicitly.
+     */
+    declareAssets(assets: AssetScope): void;
+    /** Where the fill has reached, from whichever source is in charge. */
+    private get played();
+    protected renderSelf(ctx: RenderContext2D): void;
+    /**
+     * 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 {@link declareAssets}
+     * only has to account for the two real fill props.
+     */
+    private paintFor;
+}
+//# 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,EACL,MAAM,EAMN,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,IAAI,EAET,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAC5D,OAAO,EAAkC,KAAK,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/E,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,UAAU,CAAA;AAEjB,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,0EAA0E;IAC1E,QAAQ,EAAE,aAAa,CAAA;IACvB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAA;IACX,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAA;IACd,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAA;IACf,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;IACZ,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,iBAAiB,CAAA;IACxB,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAA;IAChB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,sCAAsC;IACtC,IAAI,EAAE,IAAI,CAAA;IACV,+BAA+B;IAC/B,UAAU,EAAE,IAAI,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAea,YAAa,SAAQ,MAAM,CAAC,iBAAiB,CAAC;IACV,QAAQ,EAAE,aAAa,CAAA;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACR,KAAK,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,iBAAiB,CAAA;IAC3B,OAAO,EAAE,OAAO,CAAA;IACnB,WAAW,EAAE,MAAM,EAAE,CAAA;IAOhD,IAAI,EAAE,IAAI,CAAA;IAOV,UAAU,EAAE,IAAI,CAAA;IAExB;;;OAGG;IAEH,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,QAAQ;IAQhF;;;;OAIG;IACM,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAKhD,sEAAsE;IACtE,OAAO,KAAK,MAAM,GAKjB;IAED,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAyChD;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ;CAQjB"}

package/dist/waveform/full-waveform.js

@@ -0,0 +1,193 @@
+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, command, easeInOut, fillOps, property, } from "@motionscript/core";
+import { declarePaints } from "@motionscript/core/component";
+import { EMPTY_ENVELOPE, sampleEnvelope } from "./envelope.js";
+import { clamp01, groupByPaint, layOutBars, paintBars, voiceColor, } from "./shared.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
+ *
+ * {@link 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 {@link byVoice} on, the played/ahead split is replaced by one colour per
+ * speaking voice — the drawing the timeline's clip bars already make, 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.
+ */
+let FullWaveform = class FullWaveform extends Node2D {
+    /**
+     * Fill the waveform in, left to right — the node's one command, since
+     * everything else about it is expressible as an ordinary `to`.
+     */
+    sweep(args) {
+        return this.to({
+            data: { progress: 1 },
+            duration: args.duration,
+            easing: args.easing ?? easeInOut(),
+        });
+    }
+    /**
+     * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the
+     * paint props it carries — see {@link declarePaints}. `playedFill` is named
+     * past the conventional slots, so it is passed explicitly.
+     */
+    declareAssets(assets) {
+        super.declareAssets(assets);
+        declarePaints(this, assets, { fills: [this.playedFill] });
+    }
+    /** Where the fill has reached, from whichever source is in charge. */
+    get played() {
+        if (!this.follow)
+            return clamp01(this.progress);
+        const length = this.envelope.duration;
+        if (length <= 0)
+            return 0;
+        return clamp01(this.time.elapsed / length);
+    }
+    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 sampled = sampleEnvelope(this.envelope, 0, this.envelope.duration, count);
+        const boxes = layOutBars(sampled, {
+            width,
+            height,
+            gap: this.gap,
+            align: this.align,
+            gain: this.gain,
+            floor: this.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 = this.played * boxes.length;
+        const groups = groupByPaint(boxes, (i) => this.byVoice
+            ? `voice:${sampled[i].speaker}`
+            : i < edge
+                ? "played"
+                : "ahead");
+        for (const [key, run] of groups) {
+            const graphics = paintBars(run, this.paintFor(key), this.radius);
+            if (graphics)
+                ctx.draw(graphics);
+        }
+    }
+    /**
+     * 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 {@link declareAssets}
+     * only has to account for the two real fill props.
+     */
+    paintFor(key) {
+        if (key === "played")
+            return this.playedFill;
+        if (key === "ahead")
+            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 })
+], FullWaveform.prototype, "envelope", void 0);
+__decorate([
+    property({ default: 120 })
+], FullWaveform.prototype, "bars", void 0);
+__decorate([
+    property({ default: 0.3 })
+], FullWaveform.prototype, "gap", void 0);
+__decorate([
+    property({ default: 2 })
+], FullWaveform.prototype, "radius", void 0);
+__decorate([
+    property({ default: 0 })
+], FullWaveform.prototype, "progress", void 0);
+__decorate([
+    property({ default: false })
+], FullWaveform.prototype, "follow", void 0);
+__decorate([
+    property({ default: 1 })
+], FullWaveform.prototype, "gain", void 0);
+__decorate([
+    property({ default: 0.015 })
+], FullWaveform.prototype, "floor", void 0);
+__decorate([
+    property({ default: "center" })
+], FullWaveform.prototype, "align", void 0);
+__decorate([
+    property({ default: false })
+], FullWaveform.prototype, "byVoice", void 0);
+__decorate([
+    property({ default: [] })
+], FullWaveform.prototype, "voiceColors", void 0);
+__decorate([
+    property({
+        default: "#5b5b7a",
+        mapper: fillOps.resolve,
+        tween: fillOps.lerp,
+    })
+], FullWaveform.prototype, "fill", void 0);
+__decorate([
+    property({
+        default: "#6366f1",
+        mapper: fillOps.resolve,
+        tween: fillOps.lerp,
+    })
+], FullWaveform.prototype, "playedFill", void 0);
+__decorate([
+    command()
+], FullWaveform.prototype, "sweep", null);
+FullWaveform = __decorate([
+    node({
+        key: "fullWaveform",
+        parentKey: "node",
+        forkable: true,
+        layout: {
+            children: "freeform",
+            defaultWidthMode: "fixed",
+            defaultHeightMode: "fixed",
+            acceptsChildren: true,
+        },
+        seed: {
+            width: 900,
+            height: 160,
+        },
+    })
+], FullWaveform);
+export { FullWaveform };
+//# 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":";;;;;;AAAA,OAAO,EACL,MAAM,EACN,IAAI,EACJ,OAAO,EACP,SAAS,EACT,OAAO,EACP,QAAQ,GAOT,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAE5D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAA;AAC/E,OAAO,EACL,OAAO,EACP,YAAY,EACZ,UAAU,EACV,SAAS,EACT,UAAU,GAEX,MAAM,UAAU,CAAA;AA8BjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAgBI,IAAM,YAAY,GAAlB,MAAM,YAAa,SAAQ,MAAyB;IA2BzD;;;OAGG;IAEH,KAAK,CAAC,IAA+D;QACnE,OAAO,IAAI,CAAC,EAAE,CAAC;YACb,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAgC;YACnD,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE;SACnC,CAAC,CAAA;IACJ,CAAC;IAED;;;;OAIG;IACM,aAAa,CAAC,MAAkB;QACvC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAA;QAC3B,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,UAA4B,CAAC,EAAE,CAAC,CAAA;IAC7E,CAAC;IAED,sEAAsE;IACtE,IAAY,MAAM;QAChB,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAA;QACrC,IAAI,MAAM,IAAI,CAAC;YAAE,OAAO,CAAC,CAAA;QACzB,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,CAAA;IAC5C,CAAC;IAES,UAAU,CAAC,GAAoB;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAA;QAC9B,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,CAAC,CAAA;QAC9B,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,CAAA;QAChC,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC;YAAE,OAAM;QAErC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;QAChD,MAAM,OAAO,GAAG,cAAc,CAC5B,IAAI,CAAC,QAAQ,EACb,CAAC,EACD,IAAI,CAAC,QAAQ,CAAC,QAAQ,EACtB,KAAK,CACN,CAAA;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE;YAChC,KAAK;YACL,MAAM;YACN,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC,CAAA;QACF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAE9B,2EAA2E;QAC3E,0EAA0E;QAC1E,+BAA+B;QAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAA;QACvC,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CACvC,IAAI,CAAC,OAAO;YACV,CAAC,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE;YAC/B,CAAC,CAAC,CAAC,GAAG,IAAI;gBACR,CAAC,CAAC,QAAQ;gBACV,CAAC,CAAC,OAAO,CACd,CAAA;QAED,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,EAAE,CAAC;YAChC,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;YAChE,IAAI,QAAQ;gBAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAClC,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACK,QAAQ,CAAC,GAAW;QAC1B,IAAI,GAAG,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,UAAU,CAAA;QAC5C,IAAI,GAAG,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,IAAI,CAAA;QAErC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAA;QAChD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,IAAI,CAAA;QAC1D,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAA;IACrD,CAAC;CACF,CAAA;AAnHgD;IAA9C,QAAQ,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;8CAAgC;AAClC;IAAnC,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;0CAAqB;AACZ;IAAnC,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;yCAAoB;AACb;IAAjC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;4CAAuB;AACd;IAAjC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;8CAAyB;AACZ;IAArC,QAAQ,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;4CAAwB;AACnB;IAAjC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;0CAAqB;AACR;IAArC,QAAQ,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;2CAAsB;AACV;IAAxC,QAAQ,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;2CAAiC;AAC3B;IAArC,QAAQ,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;6CAAyB;AACnB;IAAlC,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;iDAA8B;AAOhD;IALP,QAAQ,CAAC;QACR,OAAO,EAAE,SAAS;QAClB,MAAM,EAAE,OAAO,CAAC,OAAO;QACvB,KAAK,EAAE,OAAO,CAAC,IAAI;KACpB,CAAC;0CACgB;AAOV;IALP,QAAQ,CAAC;QACR,OAAO,EAAE,SAAS;QAClB,MAAM,EAAE,OAAO,CAAC,OAAO;QACvB,KAAK,EAAE,OAAO,CAAC,IAAI;KACpB,CAAC;gDACsB;AAOxB;IADC,OAAO,EAAE;yCAOT;AAtCU,YAAY;IAfxB,IAAI,CAAC;QACJ,GAAG,EAAE,cAAc;QACnB,SAAS,EAAE,MAAM;QACjB,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE;YACN,QAAQ,EAAE,UAAU;YACpB,gBAAgB,EAAE,OAAO;YACzB,iBAAiB,EAAE,OAAO;YAC1B,eAAe,EAAE,IAAI;SACtB;QACD,IAAI,EAAE;YACJ,KAAK,EAAE,GAAG;YACV,MAAM,EAAE,GAAG;SACZ;KACF,CAAC;GACW,YAAY,CAoHxB","sourcesContent":["import {\n  Node2D,\n  node,\n  command,\n  easeInOut,\n  fillOps,\n  property,\n  type AssetScope,\n  type CommandArgs,\n  type Fill,\n  type FillResolved,\n  type Node2DProps,\n  type RenderContext2D,\n} from \"@motionscript/core\"\n\nimport { declarePaints } from \"@motionscript/core/component\"\nimport type { Seekable } from \"@motionscript/core/component\"\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\nexport interface FullWaveformProps extends Node2DProps {\n  /** The baked recording. See {@link AudioEnvelope} for why it is baked. */\n  envelope: AudioEnvelope\n  /** How many columns the whole file is drawn as. */\n  bars: number\n  /** Space between bars, as a fraction of the pitch. See {@link layOutBars}. */\n  gap: number\n  /** Corner radius of a bar, capped at half its width. */\n  radius: number\n  /** How much of the file reads as played, `0`–`1`. Tweenable. */\n  progress: number\n  /** Drive {@link progress} from the node's own clock instead of the prop. */\n  follow: boolean\n  /** Multiplies every magnitude — a quiet track pulled up to fill its box. */\n  gain: number\n  /** How much of the box a silent bar still occupies, `0`–`1`. */\n  floor: number\n  align: WaveformAlignment\n  /** Colour each voice's turns rather than splitting on played / not played. */\n  byVoice: boolean\n  /** A colour per voice index. Short or empty falls back to the palette. */\n  voiceColors: string[]\n  /** The bars ahead of the playhead. */\n  fill: Fill\n  /** …and the bars behind it. */\n  playedFill: Fill\n}\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 * {@link 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 {@link byVoice} on, the played/ahead split is replaced by one colour per\n * speaking voice — the drawing the timeline's clip bars already make, at a size\n * 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 */\n@node({\n  key: \"fullWaveform\",\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: 900,\n    height: 160,\n  },\n})\nexport class FullWaveform extends Node2D<FullWaveformProps> {\n  @property({ default: EMPTY_ENVELOPE }) declare envelope: AudioEnvelope\n  @property({ default: 120 }) declare bars: number\n  @property({ default: 0.3 }) declare gap: number\n  @property({ default: 2 }) declare radius: number\n  @property({ default: 0 }) declare progress: number\n  @property({ default: false }) declare follow: boolean\n  @property({ default: 1 }) declare gain: number\n  @property({ default: 0.015 }) declare floor: number\n  @property({ default: \"center\" }) declare align: WaveformAlignment\n  @property({ default: false }) declare byVoice: boolean\n  @property({ default: [] }) declare voiceColors: string[]\n\n  @property({\n    default: \"#5b5b7a\",\n    mapper: fillOps.resolve,\n    tween: fillOps.lerp,\n  })\n  declare fill: Fill\n\n  @property({\n    default: \"#6366f1\",\n    mapper: fillOps.resolve,\n    tween: fillOps.lerp,\n  })\n  declare playedFill: Fill\n\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`.\n   */\n  @command()\n  sweep(args: CommandArgs<Record<string, never>> & { duration: number }): Seekable {\n    return this.to({\n      data: { progress: 1 } as Partial<FullWaveformProps>,\n      duration: args.duration,\n      easing: args.easing ?? easeInOut(),\n    })\n  }\n\n  /**\n   * This node extends `Node2D` rather than `ShapeNode`, so nothing declares the\n   * paint props it carries — see {@link declarePaints}. `playedFill` is named\n   * past the conventional slots, so it is passed explicitly.\n   */\n  override declareAssets(assets: AssetScope): void {\n    super.declareAssets(assets)\n    declarePaints(this, assets, { fills: [this.playedFill as FillResolved[]] })\n  }\n\n  /** Where the fill has reached, from whichever source is in charge. */\n  private get played(): number {\n    if (!this.follow) return clamp01(this.progress)\n    const length = this.envelope.duration\n    if (length <= 0) return 0\n    return clamp01(this.time.elapsed / length)\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 sampled = sampleEnvelope(\n      this.envelope,\n      0,\n      this.envelope.duration,\n      count\n    )\n    const boxes = layOutBars(sampled, {\n      width,\n      height,\n      gap: this.gap,\n      align: this.align,\n      gain: this.gain,\n      floor: this.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 = this.played * boxes.length\n    const groups = groupByPaint(boxes, (i) =>\n      this.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, this.paintFor(key), this.radius)\n      if (graphics) ctx.draw(graphics)\n    }\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 {@link declareAssets}\n   * only has to account for the two real fill props.\n   */\n  private paintFor(key: string): Fill {\n    if (key === \"played\") return this.playedFill\n    if (key === \"ahead\") return this.fill\n\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"]}

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

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,99 @@
+import { Node2D, type AssetScope, type Fill, type Node2DProps, type RenderContext2D } from "@motionscript/core";
+import { type AudioEnvelope } from "./envelope.js";
+import { type WaveformAlignment, type WaveformStyle } from "./shared.js";
+export interface LiveWaveformProps extends Node2DProps {
+    /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+    envelope: AudioEnvelope;
+    /** How many bars the visualiser is made of. */
+    bars: number;
+    /** Space between bars, as a fraction of the pitch. */
+    gap: number;
+    radius: number;
+    /** How many seconds of audio are on screen at once. */
+    window: number;
+    /** Seconds into the file the node's first frame shows. */
+    offset: number;
+    /** Advance with the scene clock. Off freezes the picture at {@link offset}. */
+    playing: boolean;
+    /** Multiplies every magnitude before it is clamped. */
+    gain: number;
+    /** How much of the box a silent bar still occupies, `0`–`1`. */
+    floor: number;
+    align: WaveformAlignment;
+    style: WaveformStyle;
+    /**
+     * Show only this voice's activity, by index into the recording's own
+     * numbering. `-1` — the default — is every voice.
+     */
+    speaker: number;
+    /** Colour each bar by whoever is speaking in it. */
+    byVoice: boolean;
+    /** A colour per voice index. Short or empty falls back to the palette. */
+    voiceColors: string[];
+    fill: Fill;
+}
+/**
+ * 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.
+ */
+export declare class LiveWaveform extends Node2D<LiveWaveformProps> {
+    envelope: AudioEnvelope;
+    bars: number;
+    gap: number;
+    radius: number;
+    window: number;
+    offset: number;
+    playing: boolean;
+    gain: number;
+    floor: number;
+    align: WaveformAlignment;
+    style: WaveformStyle;
+    speaker: number;
+    byVoice: boolean;
+    voiceColors: string[];
+    fill: Fill;
+    declareAssets(assets: AssetScope): void;
+    /**
+     * 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.
+     */
+    private get at();
+    protected renderSelf(ctx: RenderContext2D): void;
+    /** See {@link FullWaveform.paintFor} — a voice is a hue, never a gradient. */
+    private paintFor;
+}
+//# 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,EACL,MAAM,EAIN,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EAIL,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAA;AACnB,OAAO,EAOL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,UAAU,CAAA;AAEjB,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,0EAA0E;IAC1E,QAAQ,EAAE,aAAa,CAAA;IACvB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAA;IACd,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAA;IACd,+EAA+E;IAC/E,OAAO,EAAE,OAAO,CAAA;IAChB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAA;IACZ,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,iBAAiB,CAAA;IACxB,KAAK,EAAE,aAAa,CAAA;IACpB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAA;IAChB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,IAAI,EAAE,IAAI,CAAA;CACX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAea,YAAa,SAAQ,MAAM,CAAC,iBAAiB,CAAC;IACV,QAAQ,EAAE,aAAa,CAAA;IACnC,IAAI,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,iBAAiB,CAAA;IAC1B,KAAK,EAAE,aAAa,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IACnB,WAAW,EAAE,MAAM,EAAE,CAAA;IAOhD,IAAI,EAAE,IAAI,CAAA;IAET,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAKhD;;;;;;;;OAQG;IACH,OAAO,KAAK,EAAE,GAEb;IAED,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAwChD,8EAA8E;IAC9E,OAAO,CAAC,QAAQ;CAMjB"}