@motionscript/audio 0.1.0 → 0.1.1-alpha.0

package/src/waveform/live-waveform.ts

@@ -1,5 +1,6 @@
 import {
   Types,
+  clamp,
   component2d,
   fillOps,
   type Fill,
@@ -19,83 +20,55 @@ import {
   type EnvelopeBar,
 } from "./envelope"
 import {
-  clamp01,
   groupByPaint,
   layOutBars,
   livePaintKey,
   paintBars,
-  voiceColor,
+  voiceFill,
   type WaveformAlignment,
   type WaveformStyle,
 } from "./shared"
 
 /**
- * A **live audio visualiser**: bars that move with the recording as it plays.
+ * A visualiser whose bars move with the recording: a picture of this moment
+ * where {@link FullWaveform} is of the file. The bars are sampled from a baked
+ * envelope at the node's own elapsed time, so a frame is a pure function of time
+ * and an export, which has no playback to analyse and may render out of order,
+ * draws what the preview drew.
  *
- * The thing every podcast-to-video tool puts beside the artwork. It is not a
- * picture of the file — that is {@link FullWaveform} — it is a picture of *this
- * moment*, and what it is for is making a static frame of a talking head feel
- * like it is playing.
- *
- * ## "Live" without listening
- *
- * Nothing here reads an audio device. The bars are sampled out of a baked
- * envelope at the node's own elapsed time, which is what makes the visualiser
- * survive the thing it exists for: an **export**, where there is no playback to
- * analyse and frames may be rendered out of order or in parallel. A frame is a
- * pure function of its time, so scrubbing back and forth over the visualiser
- * redraws exactly what it drew the first time — which an analyser node, by
- * construction, cannot promise. See {@link AudioEnvelope}.
- *
- * ## The speaker filter
- *
- * `speaker` narrows the node to one voice of a diarized recording, and it
- * is the reason this node knows about transcripts at all. Two visualisers beside
- * two headshots, each filtered to its own host, is a podcast edit that would
- * otherwise be done by hand for every turn — and because the filter *silences*
- * rather than skips (see {@link forSpeaker}), the quiet host visibly stops
- * talking instead of vanishing. Nothing about that requires the words: only who
- * is talking when, which is what the diarizer produces.
- *
- * A filter naming a voice the recording doesn't have draws a resting row rather
- * than everything — a picture of "this person never speaks here", which is
- * true, where falling back to the unfiltered mix would be a silent lie about
- * whose voice you were watching.
+ * `speaker` narrows the node to one voice of a diarized recording; it silences
+ * the other voices (see {@link forSpeaker}) so the quiet host visibly stops. A
+ * voice the recording does not have draws a resting row, not the unfiltered mix,
+ * which would be a silent lie about whose voice you are watching.
  */
 export const LiveWaveform = component2d({
   key: "liveWaveform",
   state: {
-    /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+    /** The baked recording; see {@link AudioEnvelope}. */
     envelope: Types.custom<AudioEnvelope>(EMPTY_ENVELOPE),
-    /** How many bars the visualiser is made of. */
     bars: 48,
-    /** Space between bars, as a fraction of the pitch. */
+    /** Space between bars as a fraction of the pitch. */
     gap: 0.35,
     radius: 4,
-    /** How many seconds of audio are on screen at once. */
+    /** Seconds of audio on screen at once. */
     window: 3,
-    /** Seconds into the file the node's first frame shows. */
+    /** Seconds into the file the first frame shows. */
     offset: 0,
-    /** Advance with the scene clock. Off freezes the picture at `offset`. */
+    /** 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`. */
+    /** The share of the box a silent bar still occupies, `0`-`1`. */
     floor: 0.04,
     align: Types.custom<WaveformAlignment>("center"),
     style: Types.custom<WaveformStyle>("bars"),
-    /**
-     * Show only this voice's activity, by index into the recording's own
-     * numbering. `-1` — the default — is every voice.
-     */
+    /** Show only this voice, by index into the recording's own numbering; `-1` 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. */
+    /** A colour per voice index; short or empty falls back to the palette. */
     voiceColors: Types.custom<string[]>([]),
     fill: Types.custom<Fill, FillResolved[]>("#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)
@@ -104,7 +77,6 @@ export const LiveWaveform = component2d({
 })
 
 export type LiveWaveform = NodeOf<typeof LiveWaveform>
-export type LiveWaveformProps = NonNullable<Parameters<typeof LiveWaveform>[0]>
 
 interface LiveState {
   readonly envelope: AudioEnvelope
@@ -124,15 +96,7 @@ interface LiveState {
   readonly fill: FillResolved[]
 }
 
-/**
- * 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.
- */
+/** The second of the recording on show, off the node's own clock (as `Video`'s is), so a node entering halfway through a clip starts its recording at its entrance. */
 function at(ctx: RenderContext, s: LiveState): number {
   return s.offset + (s.playing ? Math.max(0, ctx.time.elapsed) : 0)
 }
@@ -146,9 +110,7 @@ function drawBars(ctx: RenderContext, s: LiveState): void {
   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.
+  // Centred on the playhead, so sound reads as arriving rather than a strip scrolling past.
   const sampled = forSpeaker(
     sampleEnvelope(s.envelope, now - span / 2, now + span / 2, count),
     voice
@@ -175,24 +137,12 @@ function drawBars(ctx: RenderContext, s: LiveState): void {
   }
 }
 
-/** See `FullWaveform`'s paints — a voice is a hue, never a gradient. */
 function paintFor(s: LiveState, key: string): Fill {
   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)
+  return voiceFill(key, s.voiceColors, s.fill)
 }
 
-/**
- * Rolls the ends of a window off toward silence.
- *
- * What separates the `line` style from `bars`: a hard-edged window makes the
- * loud bar entering at the right edge appear from nothing, which reads as a
- * glitch rather than as sound arriving. Fading the outer fifth turns the same
- * data into a shape that grows out of the baseline — the profile a spectrum
- * display has, and the reason it looks like one object rather than a row of
- * separate meters.
- */
+/** Fades the outer fifth of the window to silence, the `line` style: a hard edge makes a loud bar appear from nothing, which reads as a glitch. */
 function taper(bars: readonly EnvelopeBar[]): EnvelopeBar[] {
   const count = bars.length
   if (count < 3) return [...bars]
@@ -200,7 +150,7 @@ function taper(bars: readonly EnvelopeBar[]): EnvelopeBar[] {
 
   return bars.map((bar, i) => {
     const fromEnd = Math.min(i, count - 1 - i)
-    const weight = clamp01(fromEnd / edge)
+    const weight = clamp(fromEnd / edge, 0, 1)
     return { magnitude: bar.magnitude * weight, speaker: bar.speaker }
   })
 }

package/src/waveform/shared.ts

@@ -1,33 +1,15 @@
-import { Graphics2D, type Fill, type FillResolved } from "@motionscript/sdk"
+import { Graphics2D, clamp, type Fill, type FillResolved } from "@motionscript/sdk"
 
 import type { EnvelopeBar } from "./envelope"
 
-/**
- * Geometry and paint shared by the two waveform nodes.
- *
- * They draw the same object — a row of bars whose heights are loudness — and
- * differ only in what decides the heights: the whole file for one, a window
- * around the playhead for the other. Everything about *how a row of bars is
- * laid out and painted* is therefore common, and lives here so the two cannot
- * drift into looking like different components.
- */
-
 /** How a bar is grown out of its baseline. */
 export const WAVEFORM_ALIGNMENTS = ["center", "bottom"] as const
 export type WaveformAlignment = (typeof WAVEFORM_ALIGNMENTS)[number]
 
-/** What the bars are shaped like. */
 export const WAVEFORM_STYLES = ["bars", "line", "blocks"] as const
 export type WaveformStyle = (typeof WAVEFORM_STYLES)[number]
 
-/**
- * The colours voices are drawn in when nobody has assigned any.
- *
- * Eight hues that can be told apart at a glance, handed out by voice index. They
- * are literals rather than looked up, because a scene has to build in a
- * headless render with no database in scope; a host that names its voices
- * supplies its own colours instead.
- */
+/** Eight distinct hues handed out by voice index. Literals, because a scene builds headless with no database in scope; a host that names its voices supplies its own. */
 export const VOICE_PALETTE = [
   "#6366f1",
   "#14b8a6",
@@ -47,11 +29,7 @@ export function voiceColor(index: number): string {
   ]
 }
 
-/**
- * Where one bar sits and how tall it came out: its top-left corner and size, in
- * the node's own pixels with **y pointing down** from the middle of the box.
- * {@link paintBars} turns that into the centred, y-up rect the renderer draws.
- */
+/** A bar's top-left corner and size in the node's pixels, with y pointing down from the middle of the box; {@link paintBars} turns it into the centred y-up rect. */
 export interface BarBox {
   x: number
   y: number
@@ -60,17 +38,10 @@ export interface BarBox {
 }
 
 /**
- * Lays a row of bars out across a box.
- *
- * The gap is stated as a *fraction of the pitch* rather than in pixels, and
- * that is the one decision here worth stating out loud: the bar count is a
- * control, so a gap in pixels would silently become a solid block at 200 bars
- * and a picket fence at 20. As a fraction, the row keeps the same rhythm at
- * every density — which is what lets the count be a slider anyone can drag.
- *
- * A bar is never thinner than a hairline and never shorter than one either: a
- * silent passage has to read as "audio, and nothing here" rather than as a hole
- * in the drawing.
+ * Lays a row of bars across a box. The gap is a fraction of the pitch, not px:
+ * the bar count is a control, and a px gap would become a solid block at 200
+ * bars and a picket fence at 20. A bar is never thinner or shorter than a
+ * hairline, so a silent passage reads as audio with nothing in it, not a hole.
  */
 export function layOutBars(
   bars: readonly EnvelopeBar[],
@@ -79,7 +50,6 @@ export function layOutBars(
     height: number
     gap: number
     align: WaveformAlignment
-    /** Multiplies every magnitude before it is clamped back into 0…1. */
     gain: number
     /** Fraction of the box a silent bar still occupies. */
     floor: number
@@ -90,20 +60,17 @@ export function layOutBars(
   if (count === 0 || width <= 0 || height <= 0) return []
 
   const pitch = width / count
-  const barWidth = Math.max(1, pitch * (1 - clamp01(gap)))
-  // The tallest a bar may be. Centre-aligned bars grow both ways from the
-  // middle, so the *half* is what a magnitude of 1 fills.
+  const barWidth = Math.max(1, pitch * (1 - clamp(gap, 0, 1)))
+  // Centre-aligned bars grow both ways, so half the height is what a magnitude of 1 fills.
   const full = align === "center" ? height / 2 : height
 
   const out: BarBox[] = new Array(count)
   for (let i = 0; i < count; i++) {
-    const magnitude = clamp01(bars[i].magnitude * gain)
-    const reach = Math.max(full * clamp01(floor), full * magnitude)
+    const magnitude = clamp(bars[i].magnitude * gain, 0, 1)
+    const reach = Math.max(full * clamp(floor, 0, 1), full * magnitude)
     const x = -width / 2 + pitch * i + (pitch - barWidth) / 2
 
-    // A hairline minimum, taken before the position so the bar stays inside the
-    // box: a silent bar 1px tall that kept the position of a zero-height one
-    // would hang half a pixel (centred) or a whole pixel (bottom) outside it.
+    // The hairline minimum is taken before the position, or a 1px bar placed as if zero-height would hang outside the box.
     const h = Math.max(1, align === "center" ? reach * 2 : reach)
     out[i] =
       align === "center"
@@ -114,14 +81,10 @@ export function layOutBars(
 }
 
 /**
- * Draws a run of bars in one paint.
- *
- * Batched by colour by the caller, and this is why: every `Graphics2D` handed to
- * `ctx.draw` is a surface the renderer composites, so a bar apiece would be a
- * thousand surfaces a frame. Chaining the rects of one colour into a single
- * `Graphics2D` before filling makes it one — and, as a bonus, a gradient fill
- * maps across the whole run rather than restarting inside every bar, which is
- * the behaviour anyone reaching for a gradient here actually wants.
+ * Draws a run of bars in one paint. Callers batch by colour: every `Graphics2D`
+ * handed to `ctx.draw` is a surface the renderer composites, so a bar apiece
+ * would be a thousand surfaces a frame. One `Graphics2D` per run also maps a
+ * gradient across the whole run instead of restarting inside every bar.
  */
 export function paintBars(
   boxes: readonly BarBox[],
@@ -135,26 +98,18 @@ export function paintBars(
   for (const box of boxes) {
     graphics.rect({
       x: box.x + box.width / 2,
-      // The box is stated y-down and the rect is drawn y-up. A centred bar is
-      // symmetric about the middle, so only a bottom-aligned one shows the flip.
+      // The box is y-down and the rect y-up; only a bottom-aligned bar shows the flip.
       y: -(box.y + box.height / 2),
       width: box.width,
       height: box.height,
-      // Never rounder than the bar is wide, or a thin bar becomes a lozenge
-      // whose ends taper away to nothing.
+      // A thin bar rounder than it is wide becomes a lozenge.
       cornerRadius: Math.min(radius, box.width / 2, box.height / 2),
     })
   }
   return graphics.fill(fill)
 }
 
-/**
- * Groups bars by the paint they take, preserving order within each group.
- *
- * The seam that makes {@link paintBars} worth batching: a diarized waveform has
- * as many colours as it has voices, not as many as it has bars, so a
- * conversation of two people is two draws however long it runs.
- */
+/** Groups bars by the paint they take, in order within each group: a diarized waveform has as many colours as voices, so two people is two draws however long it runs. */
 export function groupByPaint<K>(
   boxes: readonly BarBox[],
   keyOf: (index: number) => K
@@ -169,23 +124,23 @@ export function groupByPaint<K>(
   return groups
 }
 
-export function clamp01(value: number): number {
-  return value < 0 ? 0 : value > 1 ? 1 : value
+/**
+ * The colour of a `voice:N` group key, or `fallback` for a bad index. Always a
+ * colour string, never one of the node's fills: a voice is identified by hue, so
+ * a gradient or image would defeat the point, and it keeps these paints from
+ * declaring assets.
+ */
+export function voiceFill(key: string, voiceColors: readonly string[], fallback: Fill): Fill {
+  const voice = Number(key.slice("voice:".length))
+  if (!Number.isFinite(voice) || voice < 0) return fallback
+  return voiceColors[voice] ?? voiceColor(voice)
 }
 
 /**
- * The {@link groupByPaint} key one bar of a live visualiser takes.
- *
- * Filtered to one voice, every bar is that voice regardless of `byVoice` or
- * whose turn the bucket originally belonged to. That second part is the one
- * worth spelling out: {@link forSpeaker} silences a bar by zeroing its
- * magnitude but leaves `speaker` exactly as it was, so a bar sitting in the
- * middle of a *different* voice's turn is still stamped with that voice's
- * index — grouping by `byVoice`'s usual per-bar key would paint those silent
- * stretches in whoever used to be talking there, in flickers too short to
- * read as anything but noise. Forcing every bar under the filtered voice's own
- * key is the true picture instead: the node is drawing exactly one person, on
- * or off, never anyone else's colour.
+ * The {@link groupByPaint} key of one live bar. Filtered to a voice, every bar
+ * takes that voice's key: {@link forSpeaker} zeroes a bar's magnitude but leaves
+ * its `speaker`, so the usual per-bar key would paint the silenced stretches in
+ * whoever used to talk there, in flickers too short to read as anything but noise.
  */
 export function livePaintKey(
   barSpeaker: number,

package/dist/browser/chunks/chunk-DD3KHRUL.js

@@ -1,2 +0,0 @@
-var E={magnitude:new Float32Array(0),duration:0,speaker:null,speakers:0};function y(t,r,e,o){let n=Math.max(0,Math.floor(o)),a=new Array(n);for(let i=0;i<n;i++)a[i]={magnitude:0,speaker:-1};let l=t.magnitude.length;if(n===0||l===0||t.duration<=0)return a;let m=l/t.duration,s=(e-r)/n;for(let i=0;i<n;i++){let f=(r+s*i)*m,x=(r+s*(i+1))*m,p=Math.floor(f),u=Math.max(p,Math.ceil(x)-1),g=0,d=-1;for(let c=p;c<=u;c++){if(c<0||c>=l)continue;let h=t.magnitude[c];h<g||(g=h,d=t.speaker?t.speaker[c]:-1)}a[i]={magnitude:g,speaker:d}}return a}function A(t,r){return r===null?t:t.map(e=>e.speaker===r?e:{magnitude:0,speaker:e.speaker})}import{Graphics2D as w}from"@motionscript/sdk";var S=["center","bottom"],T=["bars","line","blocks"],M=["#6366f1","#14b8a6","#f59e0b","#ec4899","#22c55e","#3b82f6","#f97316","#a855f7"];function L(t){return M[(t%M.length+M.length)%M.length]}function _(t,r){let{width:e,height:o,gap:n,align:a,gain:l,floor:m}=r,s=t.length;if(s===0||e<=0||o<=0)return[];let i=e/s,f=Math.max(1,i*(1-k(n))),x=a==="center"?o/2:o,p=new Array(s);for(let u=0;u<s;u++){let g=k(t[u].magnitude*l),d=Math.max(x*k(m),x*g),c=-e/2+i*u+(i-f)/2,h=Math.max(1,a==="center"?d*2:d);p[u]=a==="center"?{x:c,y:-h/2,width:f,height:h}:{x:c,y:o/2-h,width:f,height:h}}return p}function b(t,r,e){if(t.length===0||r.length===0)return null;let o=new w;for(let n of t)o.rect({x:n.x+n.width/2,y:-(n.y+n.height/2),width:n.width,height:n.height,cornerRadius:Math.min(e,n.width/2,n.height/2)});return o.fill(r)}function B(t,r){let e=new Map;for(let o=0;o<t.length;o++){let n=r(o),a=e.get(n);a?a.push(t[o]):e.set(n,[t[o]])}return e}function k(t){return t<0?0:t>1?1:t}function F(t,r,e){return e!==null?`voice:${e}`:r?`voice:${t}`:"all"}export{E as a,y as b,A as c,S as d,T as e,M as f,L as g,_ as h,b as i,B as j,k,F as l};
-//# sourceMappingURL=chunk-DD3KHRUL.js.map

package/dist/browser/chunks/chunk-DD3KHRUL.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/waveform/envelope.ts", "../../../src/waveform/shared.ts"],
-  "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", "import { Graphics2D, type Fill, type FillResolved } from \"@motionscript/sdk\"\n\nimport type { EnvelopeBar } from \"./envelope\"\n\n/**\n * Geometry and paint shared by the two waveform nodes.\n *\n * They draw the same object — a row of bars whose heights are loudness — and\n * differ only in what decides the heights: the whole file for one, a window\n * around the playhead for the other. Everything about *how a row of bars is\n * laid out and painted* is therefore common, and lives here so the two cannot\n * drift into looking like different components.\n */\n\n/** How a bar is grown out of its baseline. */\nexport const WAVEFORM_ALIGNMENTS = [\"center\", \"bottom\"] as const\nexport type WaveformAlignment = (typeof WAVEFORM_ALIGNMENTS)[number]\n\n/** What the bars are shaped like. */\nexport const WAVEFORM_STYLES = [\"bars\", \"line\", \"blocks\"] as const\nexport type WaveformStyle = (typeof WAVEFORM_STYLES)[number]\n\n/**\n * The colours voices are drawn in when nobody has assigned any.\n *\n * Eight hues that can be told apart at a glance, handed out by voice index. They\n * are literals rather than looked up, because a scene has to build in a\n * headless render with no database in scope; a host that names its voices\n * supplies its own colours instead.\n */\nexport const VOICE_PALETTE = [\n  \"#6366f1\",\n  \"#14b8a6\",\n  \"#f59e0b\",\n  \"#ec4899\",\n  \"#22c55e\",\n  \"#3b82f6\",\n  \"#f97316\",\n  \"#a855f7\",\n] as const\n\n/** The colour a voice takes, wrapping past the end of the palette. */\nexport function voiceColor(index: number): string {\n  return VOICE_PALETTE[\n    ((index % VOICE_PALETTE.length) + VOICE_PALETTE.length) %\n      VOICE_PALETTE.length\n  ]\n}\n\n/**\n * Where one bar sits and how tall it came out: its top-left corner and size, in\n * the node's own pixels with **y pointing down** from the middle of the box.\n * {@link paintBars} turns that into the centred, y-up rect the renderer draws.\n */\nexport interface BarBox {\n  x: number\n  y: number\n  width: number\n  height: number\n}\n\n/**\n * Lays a row of bars out across a box.\n *\n * The gap is stated as a *fraction of the pitch* rather than in pixels, and\n * that is the one decision here worth stating out loud: the bar count is a\n * control, so a gap in pixels would silently become a solid block at 200 bars\n * and a picket fence at 20. As a fraction, the row keeps the same rhythm at\n * every density — which is what lets the count be a slider anyone can drag.\n *\n * A bar is never thinner than a hairline and never shorter than one either: a\n * silent passage has to read as \"audio, and nothing here\" rather than as a hole\n * in the drawing.\n */\nexport function layOutBars(\n  bars: readonly EnvelopeBar[],\n  options: {\n    width: number\n    height: number\n    gap: number\n    align: WaveformAlignment\n    /** Multiplies every magnitude before it is clamped back into 0…1. */\n    gain: number\n    /** Fraction of the box a silent bar still occupies. */\n    floor: number\n  }\n): BarBox[] {\n  const { width, height, gap, align, gain, floor } = options\n  const count = bars.length\n  if (count === 0 || width <= 0 || height <= 0) return []\n\n  const pitch = width / count\n  const barWidth = Math.max(1, pitch * (1 - clamp01(gap)))\n  // The tallest a bar may be. Centre-aligned bars grow both ways from the\n  // middle, so the *half* is what a magnitude of 1 fills.\n  const full = align === \"center\" ? height / 2 : height\n\n  const out: BarBox[] = new Array(count)\n  for (let i = 0; i < count; i++) {\n    const magnitude = clamp01(bars[i].magnitude * gain)\n    const reach = Math.max(full * clamp01(floor), full * magnitude)\n    const x = -width / 2 + pitch * i + (pitch - barWidth) / 2\n\n    // A hairline minimum, taken before the position so the bar stays inside the\n    // box: a silent bar 1px tall that kept the position of a zero-height one\n    // would hang half a pixel (centred) or a whole pixel (bottom) outside it.\n    const h = Math.max(1, align === \"center\" ? reach * 2 : reach)\n    out[i] =\n      align === \"center\"\n        ? { x, y: -h / 2, width: barWidth, height: h }\n        : { x, y: height / 2 - h, width: barWidth, height: h }\n  }\n  return out\n}\n\n/**\n * Draws a run of bars in one paint.\n *\n * Batched by colour by the caller, and this is why: every `Graphics2D` handed to\n * `ctx.draw` is a surface the renderer composites, so a bar apiece would be a\n * thousand surfaces a frame. Chaining the rects of one colour into a single\n * `Graphics2D` before filling makes it one — and, as a bonus, a gradient fill\n * maps across the whole run rather than restarting inside every bar, which is\n * the behaviour anyone reaching for a gradient here actually wants.\n */\nexport function paintBars(\n  boxes: readonly BarBox[],\n  fill: Fill,\n  radius: number\n): Graphics2D | null {\n  if (boxes.length === 0) return null\n  if ((fill as FillResolved[]).length === 0) return null\n\n  const graphics = new Graphics2D()\n  for (const box of boxes) {\n    graphics.rect({\n      x: box.x + box.width / 2,\n      // The box is stated y-down and the rect is drawn y-up. A centred bar is\n      // symmetric about the middle, so only a bottom-aligned one shows the flip.\n      y: -(box.y + box.height / 2),\n      width: box.width,\n      height: box.height,\n      // Never rounder than the bar is wide, or a thin bar becomes a lozenge\n      // whose ends taper away to nothing.\n      cornerRadius: Math.min(radius, box.width / 2, box.height / 2),\n    })\n  }\n  return graphics.fill(fill)\n}\n\n/**\n * Groups bars by the paint they take, preserving order within each group.\n *\n * The seam that makes {@link paintBars} worth batching: a diarized waveform has\n * as many colours as it has voices, not as many as it has bars, so a\n * conversation of two people is two draws however long it runs.\n */\nexport function groupByPaint<K>(\n  boxes: readonly BarBox[],\n  keyOf: (index: number) => K\n): Map<K, BarBox[]> {\n  const groups = new Map<K, BarBox[]>()\n  for (let i = 0; i < boxes.length; i++) {\n    const key = keyOf(i)\n    const run = groups.get(key)\n    if (run) run.push(boxes[i])\n    else groups.set(key, [boxes[i]])\n  }\n  return groups\n}\n\nexport function clamp01(value: number): number {\n  return value < 0 ? 0 : value > 1 ? 1 : value\n}\n\n/**\n * The {@link groupByPaint} key one bar of a live visualiser takes.\n *\n * Filtered to one voice, every bar is that voice regardless of `byVoice` or\n * whose turn the bucket originally belonged to. That second part is the one\n * worth spelling out: {@link forSpeaker} silences a bar by zeroing its\n * magnitude but leaves `speaker` exactly as it was, so a bar sitting in the\n * middle of a *different* voice's turn is still stamped with that voice's\n * index — grouping by `byVoice`'s usual per-bar key would paint those silent\n * stretches in whoever used to be talking there, in flickers too short to\n * read as anything but noise. Forcing every bar under the filtered voice's own\n * key is the true picture instead: the node is drawing exactly one person, on\n * or off, never anyone else's colour.\n */\nexport function livePaintKey(\n  barSpeaker: number,\n  byVoice: boolean,\n  filteredVoice: number | null\n): string {\n  if (filteredVoice !== null) return `voice:${filteredVoice}`\n  return byVoice ? `voice:${barSpeaker}` : \"all\"\n}\n"],
-  "mappings": "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",
-  "names": ["EMPTY_ENVELOPE", "sampleEnvelope", "envelope", "from", "to", "bars", "count", "out", "buckets", "perSecond", "span", "start", "end", "first", "last", "loudest", "speaker", "b", "value", "forSpeaker", "voice", "bar", "Graphics2D", "WAVEFORM_ALIGNMENTS", "WAVEFORM_STYLES", "VOICE_PALETTE", "voiceColor", "index", "layOutBars", "bars", "options", "width", "height", "gap", "align", "gain", "floor", "count", "pitch", "barWidth", "clamp01", "full", "out", "i", "magnitude", "reach", "x", "paintBars", "boxes", "fill", "radius", "graphics", "box", "groupByPaint", "keyOf", "groups", "key", "run", "value", "livePaintKey", "barSpeaker", "byVoice", "filteredVoice"]
-}