@motionscript/audio 0.1.0-alpha.5 → 0.1.0-alpha.6

package/dist/waveform/live-waveform.js

@@ -1,11 +1,4 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-import { Node2D, node, fillOps, property, } from "@motionscript/sdk";
-import { declarePaints } from "@motionscript/sdk/component";
+import { Types, component2d, fillOps, } from "@motionscript/sdk";
 import { EMPTY_ENVELOPE, forSpeaker, sampleEnvelope, } from "./envelope.js";
 import { clamp01, groupByPaint, layOutBars, livePaintKey, paintBars, voiceColor, } from "./shared.js";
 /**
@@ -28,7 +21,7 @@ import { clamp01, groupByPaint, layOutBars, livePaintKey, paintBars, voiceColor,
  *
  * ## The speaker filter
  *
- * {@link speaker} narrows the node to one voice of a diarized recording, and it
+ * `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*
@@ -41,132 +34,97 @@ import { clamp01, groupByPaint, layOutBars, livePaintKey, paintBars, voiceColor,
  * true, where falling back to the unfiltered mix would be a silent lie about
  * whose voice you were watching.
  */
-let LiveWaveform = class LiveWaveform extends Node2D {
-    declareAssets(assets) {
-        super.declareAssets(assets);
-        declarePaints(this, assets);
-    }
-    /**
-     * The second of the recording the visualiser is showing.
-     *
-     * Off the node's own clock rather than the scene's, which is what "from the
-     * moment this node appeared" means — the same clock the engine's own
-     * `Video` times its picture from, and the same one that makes a node dropped
-     * halfway through a clip start its recording at its entrance rather than
-     * partway in.
-     */
-    get at() {
-        return this.offset + (this.playing ? Math.max(0, this.time.elapsed) : 0);
-    }
-    renderSelf(ctx) {
-        const rect = this.layoutBounds;
-        const width = rect?.width ?? 0;
-        const height = rect?.height ?? 0;
-        if (width <= 0 || height <= 0)
-            return;
-        const count = Math.max(1, Math.round(this.bars));
-        const span = Math.max(0.05, this.window);
-        const at = this.at;
-        const voice = this.speaker < 0 ? null : Math.round(this.speaker);
-        // The window is centred on the playhead, so the bars run *toward* the
-        // middle and away again — the arrangement every mixer's meter uses, and the
-        // one that reads as sound arriving rather than as a strip scrolling past.
-        const sampled = forSpeaker(sampleEnvelope(this.envelope, at - span / 2, at + span / 2, count), voice);
-        const shaped = this.style === "line" ? taper(sampled) : sampled;
-        const boxes = layOutBars(shaped, {
-            width,
-            height,
-            gap: this.style === "blocks" ? 0.12 : this.gap,
-            align: this.align,
-            gain: this.gain,
-            floor: this.floor,
-        });
-        if (boxes.length === 0)
-            return;
-        const groups = groupByPaint(boxes, (i) => livePaintKey(shaped[i].speaker, this.byVoice, voice));
-        for (const [key, run] of groups) {
-            const graphics = paintBars(run, this.paintFor(key), this.radius);
-            if (graphics)
-                ctx.draw(graphics);
-        }
-    }
-    /** See {@link FullWaveform.paintFor} — a voice is a hue, never a gradient. */
-    paintFor(key) {
-        if (key === "all")
-            return this.fill;
-        const voice = Number(key.slice("voice:".length));
-        if (!Number.isFinite(voice) || voice < 0)
-            return this.fill;
-        return this.voiceColors[voice] ?? voiceColor(voice);
+export const LiveWaveform = component2d({
+    key: "liveWaveform",
+    state: {
+        /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+        envelope: Types.custom(EMPTY_ENVELOPE),
+        /** How many bars the visualiser is made of. */
+        bars: 48,
+        /** Space between bars, as a fraction of the pitch. */
+        gap: 0.35,
+        radius: 4,
+        /** How many seconds of audio are on screen at once. */
+        window: 3,
+        /** Seconds into the file the node's first frame shows. */
+        offset: 0,
+        /** Advance with the scene clock. Off freezes the picture at `offset`. */
+        playing: true,
+        /** Multiplies every magnitude before it is clamped. */
+        gain: 1.4,
+        /** How much of the box a silent bar still occupies, `0`–`1`. */
+        floor: 0.04,
+        align: Types.custom("center"),
+        style: Types.custom("bars"),
+        /**
+         * Show only this voice's activity, by index into the recording's own
+         * numbering. `-1` — the default — is every voice.
+         */
+        speaker: -1,
+        /** Colour each bar by whoever is speaking in it. */
+        byVoice: false,
+        /** A colour per voice index. Short or empty falls back to the palette. */
+        voiceColors: Types.custom([]),
+        fill: Types.custom("#6366f1", { resolve: fillOps.resolve, lerp: fillOps.lerp }),
+    },
+    // Nothing declares a component's paints but itself.
+    load: (loader, state) => loader.fill(state.fill),
+    render: (ctx, state) => {
+        drawBars(ctx, state);
+        ctx.children();
+    },
+});
+/**
+ * The second of the recording the visualiser is showing.
+ *
+ * Off the node's own clock rather than the scene's, which is what "from the
+ * moment this node appeared" means — the same clock the engine's own
+ * `Video` times its picture from, and the same one that makes a node dropped
+ * halfway through a clip start its recording at its entrance rather than
+ * partway in.
+ */
+function at(ctx, s) {
+    return s.offset + (s.playing ? Math.max(0, ctx.time.elapsed) : 0);
+}
+function drawBars(ctx, s) {
+    const { width, height } = ctx.size;
+    if (width <= 0 || height <= 0)
+        return;
+    const count = Math.max(1, Math.round(s.bars));
+    const span = Math.max(0.05, s.window);
+    const now = at(ctx, s);
+    const voice = s.speaker < 0 ? null : Math.round(s.speaker);
+    // The window is centred on the playhead, so the bars run *toward* the
+    // middle and away again — the arrangement every mixer's meter uses, and the
+    // one that reads as sound arriving rather than as a strip scrolling past.
+    const sampled = forSpeaker(sampleEnvelope(s.envelope, now - span / 2, now + span / 2, count), voice);
+    const shaped = s.style === "line" ? taper(sampled) : sampled;
+    const boxes = layOutBars(shaped, {
+        width,
+        height,
+        gap: s.style === "blocks" ? 0.12 : s.gap,
+        align: s.align,
+        gain: s.gain,
+        floor: s.floor,
+    });
+    if (boxes.length === 0)
+        return;
+    const groups = groupByPaint(boxes, (i) => livePaintKey(shaped[i].speaker, s.byVoice, voice));
+    for (const [key, run] of groups) {
+        const graphics = paintBars(run, paintFor(s, key), s.radius);
+        if (graphics)
+            ctx.draw(graphics);
     }
-};
-__decorate([
-    property({ default: EMPTY_ENVELOPE })
-], LiveWaveform.prototype, "envelope", void 0);
-__decorate([
-    property({ default: 48 })
-], LiveWaveform.prototype, "bars", void 0);
-__decorate([
-    property({ default: 0.35 })
-], LiveWaveform.prototype, "gap", void 0);
-__decorate([
-    property({ default: 4 })
-], LiveWaveform.prototype, "radius", void 0);
-__decorate([
-    property({ default: 3 })
-], LiveWaveform.prototype, "window", void 0);
-__decorate([
-    property({ default: 0 })
-], LiveWaveform.prototype, "offset", void 0);
-__decorate([
-    property({ default: true })
-], LiveWaveform.prototype, "playing", void 0);
-__decorate([
-    property({ default: 1.4 })
-], LiveWaveform.prototype, "gain", void 0);
-__decorate([
-    property({ default: 0.04 })
-], LiveWaveform.prototype, "floor", void 0);
-__decorate([
-    property({ default: "center" })
-], LiveWaveform.prototype, "align", void 0);
-__decorate([
-    property({ default: "bars" })
-], LiveWaveform.prototype, "style", void 0);
-__decorate([
-    property({ default: -1 })
-], LiveWaveform.prototype, "speaker", void 0);
-__decorate([
-    property({ default: false })
-], LiveWaveform.prototype, "byVoice", void 0);
-__decorate([
-    property({ default: [] })
-], LiveWaveform.prototype, "voiceColors", void 0);
-__decorate([
-    property({
-        default: "#6366f1",
-        mapper: fillOps.resolve,
-        tween: fillOps.lerp,
-    })
-], LiveWaveform.prototype, "fill", void 0);
-LiveWaveform = __decorate([
-    node({
-        key: "liveWaveform",
-        parentKey: "node",
-        forkable: true,
-        layout: {
-            children: "freeform",
-            defaultWidthMode: "fixed",
-            defaultHeightMode: "fixed",
-            acceptsChildren: true,
-        },
-        seed: {
-            width: 420,
-            height: 220,
-        },
-    })
-], LiveWaveform);
-export { LiveWaveform };
+}
+/** See `FullWaveform`'s paints — a voice is a hue, never a gradient. */
+function paintFor(s, key) {
+    if (key === "all")
+        return s.fill;
+    const voice = Number(key.slice("voice:".length));
+    if (!Number.isFinite(voice) || voice < 0)
+        return s.fill;
+    return s.voiceColors[voice] ?? voiceColor(voice);
+}
 /**
  * Rolls the ends of a window off toward silence.
  *

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

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

package/package.json

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

package/src/nodes.ts

@@ -5,15 +5,13 @@ import { LiveWaveform } from "./waveform/live-waveform";
  * Every node type this package publishes.
  *
  * A host registers these by handing the array to an engine —
- * `new Engine(platform, { nodes: NODES })` — which reads each class's `@node()`
- * key. The decorator only *declares* that key: nothing is registered by the mere
- * act of importing a module, so a registry holds exactly what its owner asked
- * for and two engines in one process can differ about it.
+ * `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 class **values** is also what survives bundling. This package declares
- * `sideEffects: false`, which licenses a bundler to drop a module nothing
- * imports a value from, and a document names a node type by string — so
- * `import "./waveform/full-waveform"` for its side effect is exactly what gets shaken out, where an
- * array of bindings is a data dependency that cannot be.
+ * 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 const NODES = [FullWaveform, LiveWaveform];
+// Typed by name, so the declaration names each component rather than spelling out its type through core.
+export const NODES: (typeof FullWaveform | typeof LiveWaveform)[] = [FullWaveform, LiveWaveform];