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

package/src/waveform/full-waveform.ts

@@ -1,20 +1,17 @@
 import {
-  Node2D,
-  node,
-  command,
+  Types,
+  component2d,
   easeInOut,
   fillOps,
-  property,
-  type AssetScope,
-  type CommandArgs,
   type Fill,
   type FillResolved,
-  type Node2DProps,
-  type RenderContext2D,
+  type NodeOf,
+  type RenderContext,
+  // Named so the emitted declaration reaches these through the sdk, not core.
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
 } 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,
@@ -25,33 +22,9 @@ import {
   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 paint entry as the waveforms declare theirs: resolved and tweened like a fill, its kind read off the default. */
+const paint = (initial: string) =>
+  Types.custom<Fill, FillResolved[]>(initial, { resolve: fillOps.resolve, lerp: fillOps.lerp })
 
 /**
  * A **waveform overview**: the whole recording's shape, drawn at once.
@@ -64,7 +37,7 @@ export interface FullWaveformProps extends Node2DProps {
  *
  * ## Progress is authored, not assumed
  *
- * {@link follow} is off by default, and that default is the considered one. A
+ * `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*:
@@ -76,142 +49,140 @@ export interface FullWaveformProps extends Node2DProps {
  *
  * ## Voices instead of progress
  *
- * With {@link byVoice} on, the played/ahead split is replaced by one colour per
+ * With `byVoice` on, the played/ahead split is replaced by one colour per
  * speaking voice, at a size you can read. For a two-hander it is a map of the conversation: who has the
  * floor, where the turns are, how long each one ran. It replaces the progress
  * colours rather than combining with them, because a bar cannot mean two things
  * at once and "played, and also Grace" is a legend nobody can hold in their
  * head.
  */
-@node({
+export const FullWaveform = component2d({
   key: "fullWaveform",
-  parentKey: "node",
-  forkable: true,
-  layout: {
-    children: "freeform",
-    defaultWidthMode: "fixed",
-    defaultHeightMode: "fixed",
-    acceptsChildren: true,
+  state: {
+    /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+    envelope: Types.custom<AudioEnvelope>(EMPTY_ENVELOPE),
+    /** How many columns the whole file is drawn as. */
+    bars: 120,
+    /** Space between bars, as a fraction of the pitch. See {@link layOutBars}. */
+    gap: 0.3,
+    /** Corner radius of a bar, capped at half its width. */
+    radius: 2,
+    /** How much of the file reads as played, `0`–`1`. Tweenable. */
+    progress: 0,
+    /** Drive `progress` from the node's own clock instead of the prop. */
+    follow: false,
+    /** Multiplies every magnitude — a quiet track pulled up to fill its box. */
+    gain: 1,
+    /** How much of the box a silent bar still occupies, `0`–`1`. */
+    floor: 0.015,
+    align: Types.custom<WaveformAlignment>("center"),
+    /** Colour each voice's turns rather than splitting on played / not played. */
+    byVoice: false,
+    /** A colour per voice index. Short or empty falls back to the palette. */
+    voiceColors: Types.custom<string[]>([]),
+    /** The bars ahead of the playhead. */
+    fill: paint("#5b5b7a"),
+    /** …and the bars behind it. */
+    playedFill: paint("#6366f1"),
+  },
+  // Nothing declares a component's paints but itself: `fill` and `playedFill` both.
+  load: (loader, state) => {
+    loader.fill(state.fill)
+    loader.fill(state.playedFill)
+  },
+  commands: {
+    /**
+     * Fill the waveform in, left to right — the node's one command, since
+     * everything else about it is expressible as an ordinary `to`. Eased in-out
+     * unless it is given an easing of its own.
+     */
+    sweep: (timeline, state) => {
+      const ease = timeline.easing ? null : easeInOut()
+      const from = state.progress
+      return timeline.animate((t) => ({ progress: from + (1 - from) * (ease ? ease(t) : t) }))
+    },
   },
-  seed: {
-    width: 900,
-    height: 160,
+  render: (ctx, state) => {
+    drawBars(ctx, state)
+    ctx.children()
   },
 })
-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[]] })
-  }
+export type FullWaveform = NodeOf<typeof FullWaveform>
+export type FullWaveformProps = NonNullable<Parameters<typeof FullWaveform>[0]>
 
-  /** 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)
-  }
+interface FullState {
+  readonly envelope: AudioEnvelope
+  readonly bars: number
+  readonly gap: number
+  readonly radius: number
+  readonly progress: number
+  readonly follow: boolean
+  readonly gain: number
+  readonly floor: number
+  readonly align: WaveformAlignment
+  readonly byVoice: boolean
+  readonly voiceColors: string[]
+  readonly fill: FillResolved[]
+  readonly playedFill: FillResolved[]
+}
 
-  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
+function drawBars(ctx: RenderContext, s: FullState): void {
+  const { width, height } = ctx.size
+  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
+  const count = Math.max(1, Math.round(s.bars))
+  const sampled = sampleEnvelope(s.envelope, 0, s.envelope.duration, count)
+  const boxes = layOutBars(sampled, {
+    width,
+    height,
+    gap: s.gap,
+    align: s.align,
+    gain: s.gain,
+    floor: s.floor,
+  })
+  if (boxes.length === 0) return
 
-    // One draw per colour rather than per bar — see {@link paintBars}. The key
-    // is a string because it has to be comparable; the paint it stands for is
-    // resolved after the grouping.
-    const edge = this.played * boxes.length
-    const groups = groupByPaint(boxes, (i) =>
-      this.byVoice
-        ? `voice:${sampled[i].speaker}`
-        : i < edge
-          ? "played"
-          : "ahead"
-    )
+  // One draw per colour rather than per bar — see {@link paintBars}. The key
+  // is a string because it has to be comparable; the paint it stands for is
+  // resolved after the grouping.
+  const edge = played(ctx, s) * boxes.length
+  const groups = groupByPaint(boxes, (i) =>
+    s.byVoice
+      ? `voice:${sampled[i].speaker}`
+      : i < edge
+        ? "played"
+        : "ahead"
+  )
 
-    for (const [key, run] of groups) {
-      const graphics = paintBars(run, this.paintFor(key), this.radius)
-      if (graphics) ctx.draw(graphics)
-    }
+  for (const [key, run] of groups) {
+    const graphics = paintBars(run, paintFor(s, key), s.radius)
+    if (graphics) ctx.draw(graphics)
   }
+}
+
+/** Where the fill has reached, from whichever source is in charge. */
+function played(ctx: RenderContext, s: FullState): number {
+  if (!s.follow) return clamp01(s.progress)
+  const length = s.envelope.duration
+  if (length <= 0) return 0
+  return clamp01(ctx.time.elapsed / length)
+}
 
-  /**
-   * The paint a group takes.
-   *
-   * A voice's colour is a **colour string**, never one of the node's two fill
-   * props, and that is deliberate: a voice is identified by hue, so a gradient
-   * or an image there would defeat the only thing the colour is for. It also
-   * means these paints declare no assets, which is why {@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
+/**
+ * The paint a group takes.
+ *
+ * A voice's colour is a **colour string**, never one of the node's two fill
+ * props, and that is deliberate: a voice is identified by hue, so a gradient
+ * or an image there would defeat the only thing the colour is for. It also
+ * means these paints declare no assets, which is why `load` only has to account
+ * for the two real fill props.
+ */
+function paintFor(s: FullState, key: string): Fill {
+  if (key === "played") return s.playedFill
+  if (key === "ahead") return s.fill
 
-    const voice = Number(key.slice("voice:".length))
-    if (!Number.isFinite(voice) || voice < 0) return this.fill
-    return this.voiceColors[voice] ?? voiceColor(voice)
-  }
+  const voice = Number(key.slice("voice:".length))
+  if (!Number.isFinite(voice) || voice < 0) return s.fill
+  return s.voiceColors[voice] ?? voiceColor(voice)
 }

package/src/waveform/live-waveform.ts

@@ -1,15 +1,16 @@
 import {
-  Node2D,
-  node,
+  Types,
+  component2d,
   fillOps,
-  property,
-  type AssetScope,
   type Fill,
-  type Node2DProps,
-  type RenderContext2D,
+  type FillResolved,
+  type NodeOf,
+  type RenderContext,
+  // Named so the emitted declaration reaches these through the sdk, not core.
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
 } from "@motionscript/sdk"
 
-import { declarePaints } from "@motionscript/sdk/component"
 import {
   EMPTY_ENVELOPE,
   forSpeaker,
@@ -28,38 +29,6 @@ import {
   type WaveformStyle,
 } from "./shared"
 
-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.
  *
@@ -80,7 +49,7 @@ export interface LiveWaveformProps extends Node2DProps {
  *
  * ## 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*
@@ -93,109 +62,125 @@ export interface LiveWaveformProps extends Node2DProps {
  * true, where falling back to the unfiltered mix would be a silent lie about
  * whose voice you were watching.
  */
-@node({
+export const LiveWaveform = component2d({
   key: "liveWaveform",
-  parentKey: "node",
-  forkable: true,
-  layout: {
-    children: "freeform",
-    defaultWidthMode: "fixed",
-    defaultHeightMode: "fixed",
-    acceptsChildren: true,
+  state: {
+    /** The baked recording. See {@link AudioEnvelope} for why it is baked. */
+    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. */
+    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<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.
+     */
+    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<string[]>([]),
+    fill: Types.custom<Fill, FillResolved[]>("#6366f1", { resolve: fillOps.resolve, lerp: fillOps.lerp }),
   },
-  seed: {
-    width: 420,
-    height: 220,
+  // Nothing declares a component's paints but itself.
+  load: (loader, state) => loader.fill(state.fill),
+  render: (ctx, state) => {
+    drawBars(ctx, state)
+    ctx.children()
   },
 })
-export class LiveWaveform extends Node2D<LiveWaveformProps> {
-  @property({ default: EMPTY_ENVELOPE }) declare envelope: AudioEnvelope
-  @property({ default: 48 }) declare bars: number
-  @property({ default: 0.35 }) declare gap: number
-  @property({ default: 4 }) declare radius: number
-  @property({ default: 3 }) declare window: number
-  @property({ default: 0 }) declare offset: number
-  @property({ default: true }) declare playing: boolean
-  @property({ default: 1.4 }) declare gain: number
-  @property({ default: 0.04 }) declare floor: number
-  @property({ default: "center" }) declare align: WaveformAlignment
-  @property({ default: "bars" }) declare style: WaveformStyle
-  @property({ default: -1 }) declare speaker: number
-  @property({ default: false }) declare byVoice: boolean
-  @property({ default: [] }) declare voiceColors: string[]
 
-  @property({
-    default: "#6366f1",
-    mapper: fillOps.resolve,
-    tween: fillOps.lerp,
-  })
-  declare fill: Fill
+export type LiveWaveform = NodeOf<typeof LiveWaveform>
+export type LiveWaveformProps = NonNullable<Parameters<typeof LiveWaveform>[0]>
 
-  override declareAssets(assets: AssetScope): void {
-    super.declareAssets(assets)
-    declarePaints(this, assets)
-  }
+interface LiveState {
+  readonly envelope: AudioEnvelope
+  readonly bars: number
+  readonly gap: number
+  readonly radius: number
+  readonly window: number
+  readonly offset: number
+  readonly playing: boolean
+  readonly gain: number
+  readonly floor: number
+  readonly align: WaveformAlignment
+  readonly style: WaveformStyle
+  readonly speaker: number
+  readonly byVoice: boolean
+  readonly voiceColors: string[]
+  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.
-   */
-  private get at(): number {
-    return this.offset + (this.playing ? Math.max(0, this.time.elapsed) : 0)
-  }
+/**
+ * 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: RenderContext, s: LiveState): number {
+  return s.offset + (s.playing ? Math.max(0, ctx.time.elapsed) : 0)
+}
 
-  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
+function drawBars(ctx: RenderContext, s: LiveState): void {
+  const { width, height } = ctx.size
+  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)
+  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(this.envelope, at - span / 2, at + span / 2, count),
-      voice
-    )
+  // 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 = 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 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, this.byVoice, voice)
-    )
+  const groups = groupByPaint(boxes, (i) =>
+    livePaintKey(shaped[i].speaker, s.byVoice, voice)
+  )
 
-    for (const [key, run] of groups) {
-      const graphics = paintBars(run, this.paintFor(key), this.radius)
-      if (graphics) ctx.draw(graphics)
-    }
+  for (const [key, run] of groups) {
+    const graphics = paintBars(run, paintFor(s, key), s.radius)
+    if (graphics) ctx.draw(graphics)
   }
+}
 
-  /** See {@link FullWaveform.paintFor} — a voice is a hue, never a gradient. */
-  private paintFor(key: string): Fill {
-    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)
-  }
+/** 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)
 }
 
 /**