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

package/src/waveform/full-waveform.ts

@@ -1,218 +1,217 @@
-import {
-  Node2D,
-  node,
-  command,
-  easeInOut,
-  fillOps,
-  property,
-  type AssetScope,
-  type CommandArgs,
-  type Fill,
-  type FillResolved,
-  type Node2DProps,
-  type RenderContext2D,
-} from "@motionscript/sdk"
-
-import { declarePaints } from "@motionscript/sdk/component"
-import type { Seekable } from "@motionscript/sdk/component"
-import { EMPTY_ENVELOPE, sampleEnvelope, type AudioEnvelope } from "./envelope"
-import {
-  clamp01,
-  groupByPaint,
-  layOutBars,
-  paintBars,
-  voiceColor,
-  type WaveformAlignment,
-} from "./shared"
-
-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.
- */
-@node({
-  key: "fullWaveform",
-  parentKey: "node",
-  forkable: true,
-  layout: {
-    children: "freeform",
-    defaultWidthMode: "fixed",
-    defaultHeightMode: "fixed",
-    acceptsChildren: true,
-  },
-  seed: {
-    width: 900,
-    height: 160,
-  },
-})
-export class FullWaveform extends Node2D<FullWaveformProps> {
-  @property({ default: EMPTY_ENVELOPE }) declare envelope: AudioEnvelope
-  @property({ default: 120 }) declare bars: number
-  @property({ default: 0.3 }) declare gap: number
-  @property({ default: 2 }) declare radius: number
-  @property({ default: 0 }) declare progress: number
-  @property({ default: false }) declare follow: boolean
-  @property({ default: 1 }) declare gain: number
-  @property({ default: 0.015 }) declare floor: number
-  @property({ default: "center" }) declare align: WaveformAlignment
-  @property({ default: false }) declare byVoice: boolean
-  @property({ default: [] }) declare voiceColors: string[]
-
-  @property({
-    default: "#5b5b7a",
-    mapper: fillOps.resolve,
-    tween: fillOps.lerp,
-  })
-  declare fill: Fill
-
-  @property({
-    default: "#6366f1",
-    mapper: fillOps.resolve,
-    tween: fillOps.lerp,
-  })
-  declare 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`.
-   */
-  @command()
-  sweep(args: CommandArgs<Record<string, never>> & { duration: number }): Seekable {
-    return this.to({
-      data: { progress: 1 } as Partial<FullWaveformProps>,
-      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.
-   */
-  override declareAssets(assets: AssetScope): void {
-    super.declareAssets(assets)
-    declarePaints(this, assets, { fills: [this.playedFill as FillResolved[]] })
-  }
-
-  /** Where the fill has reached, from whichever source is in charge. */
-  private get played(): number {
-    if (!this.follow) return clamp01(this.progress)
-    const length = this.envelope.duration
-    if (length <= 0) return 0
-    return clamp01(this.time.elapsed / length)
-  }
-
-  protected renderSelf(ctx: RenderContext2D): void {
-    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.
-   */
-  private paintFor(key: string): Fill {
-    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)
-  }
-}
+import {
+  Node2D,
+  node,
+  command,
+  easeInOut,
+  fillOps,
+  property,
+  type AssetScope,
+  type CommandArgs,
+  type Fill,
+  type FillResolved,
+  type Node2DProps,
+  type RenderContext2D,
+} from "@motionscript/sdk"
+
+import { declarePaints } from "@motionscript/sdk/component"
+import type { Seekable } from "@motionscript/sdk/component"
+import { EMPTY_ENVELOPE, sampleEnvelope, type AudioEnvelope } from "./envelope"
+import {
+  clamp01,
+  groupByPaint,
+  layOutBars,
+  paintBars,
+  voiceColor,
+  type WaveformAlignment,
+} from "./shared"
+
+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, 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.
+ */
+@node({
+  key: "fullWaveform",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    defaultWidthMode: "fixed",
+    defaultHeightMode: "fixed",
+    acceptsChildren: true,
+  },
+  seed: {
+    width: 900,
+    height: 160,
+  },
+})
+export class FullWaveform extends Node2D<FullWaveformProps> {
+  @property({ default: EMPTY_ENVELOPE }) declare envelope: AudioEnvelope
+  @property({ default: 120 }) declare bars: number
+  @property({ default: 0.3 }) declare gap: number
+  @property({ default: 2 }) declare radius: number
+  @property({ default: 0 }) declare progress: number
+  @property({ default: false }) declare follow: boolean
+  @property({ default: 1 }) declare gain: number
+  @property({ default: 0.015 }) declare floor: number
+  @property({ default: "center" }) declare align: WaveformAlignment
+  @property({ default: false }) declare byVoice: boolean
+  @property({ default: [] }) declare voiceColors: string[]
+
+  @property({
+    default: "#5b5b7a",
+    mapper: fillOps.resolve,
+    tween: fillOps.lerp,
+  })
+  declare fill: Fill
+
+  @property({
+    default: "#6366f1",
+    mapper: fillOps.resolve,
+    tween: fillOps.lerp,
+  })
+  declare 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`.
+   */
+  @command()
+  sweep(args: CommandArgs<Record<string, never>> & { duration: number }): Seekable {
+    return this.to({
+      data: { progress: 1 } as Partial<FullWaveformProps>,
+      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.
+   */
+  override declareAssets(assets: AssetScope): void {
+    super.declareAssets(assets)
+    declarePaints(this, assets, { fills: [this.playedFill as FillResolved[]] })
+  }
+
+  /** Where the fill has reached, from whichever source is in charge. */
+  private get played(): number {
+    if (!this.follow) return clamp01(this.progress)
+    const length = this.envelope.duration
+    if (length <= 0) return 0
+    return clamp01(this.time.elapsed / length)
+  }
+
+  protected renderSelf(ctx: RenderContext2D): void {
+    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.
+   */
+  private paintFor(key: string): Fill {
+    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)
+  }
+}

package/src/waveform/index.ts

@@ -1,30 +1,30 @@
-/**
- * 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"
-export type { FullWaveformProps } from "./full-waveform"
-export { LiveWaveform } from "./live-waveform"
-export type { LiveWaveformProps } from "./live-waveform"
-export { EMPTY_ENVELOPE, forSpeaker, sampleEnvelope } from "./envelope"
-export type { AudioEnvelope, EnvelopeBar } from "./envelope"
-export {
-  VOICE_PALETTE,
-  WAVEFORM_ALIGNMENTS,
-  WAVEFORM_STYLES,
-  groupByPaint,
-  layOutBars,
-  paintBars,
-  voiceColor,
-} from "./shared"
-export type { BarBox, WaveformAlignment, WaveformStyle } from "./shared"
+/**
+ * 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"
+export type { FullWaveformProps } from "./full-waveform"
+export { LiveWaveform } from "./live-waveform"
+export type { LiveWaveformProps } from "./live-waveform"
+export { EMPTY_ENVELOPE, forSpeaker, sampleEnvelope } from "./envelope"
+export type { AudioEnvelope, EnvelopeBar } from "./envelope"
+export {
+  VOICE_PALETTE,
+  WAVEFORM_ALIGNMENTS,
+  WAVEFORM_STYLES,
+  groupByPaint,
+  layOutBars,
+  paintBars,
+  voiceColor,
+} from "./shared"
+export type { BarBox, WaveformAlignment, WaveformStyle } from "./shared"