@hraness/dawg 0.6.1 → 0.8.0

package/tui/clip-row.ts

@@ -0,0 +1,132 @@
+/**
+ * Highway clip-row snapshots (0.7 clips lane): each clip on the focused
+ * track as song beats on the tempo map, its waveform peaks over the clip's
+ * window and whether it continues another clip (a comp seam).
+ *
+ * Peaks (`MEDIA_LIMITS.waveformBuckets` per file) come from a per-file cache filled off the frame path: the first
+ * frame shows flat blocks, and `loadClipPeaks` fills the cache and asks for
+ * a redraw.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { clipEndTick, clipLength, clipSongTick } from "../core/clips.ts";
+import type { TrackScore, Track } from "../core/score.ts";
+import { SCORE_LIMITS } from "../core/score.ts";
+import { waveformPeaks } from "../src/media/dsp.ts";
+import { parseWav } from "../src/media/vendor/wav.ts";
+import type { ClipSnapshot } from "./highway.ts";
+
+type FilePeaks = Readonly<{ seconds: number; peaks: readonly number[] }>;
+
+const cache = new Map<string, FilePeaks | null>();
+const pending = new Set<string>();
+
+/** Cache key: the clip's pin, or its path when not hashed yet. */
+function keyOf(src: string, sha256: string | undefined): string {
+  return sha256 ?? `path:${src}`;
+}
+
+/** Cached peaks for a file, without reading it. */
+export function cachedPeaks(
+  src: string,
+  sha256?: string,
+): FilePeaks | null | undefined {
+  return cache.get(keyOf(src, sha256));
+}
+
+/**
+ * Read and analyse every clip file of `track` not cached yet. Resolves true
+ * when anything new was cached (the caller redraws).
+ */
+export async function loadClipPeaks(
+  root: string,
+  track: Track | undefined,
+): Promise<boolean> {
+  let changed = false;
+  for (const clip of track?.clips ?? []) {
+    const key = keyOf(clip.src, clip.sha256);
+    if (cache.has(key) || pending.has(key) || clip.src.startsWith("pack:"))
+      continue;
+    pending.add(key);
+    try {
+      const wav = parseWav(
+        new Uint8Array(await readFile(join(root, clip.src))),
+        {
+          maximumBytes: SCORE_LIMITS.maxSampleFileBytes,
+          maximumDurationSeconds: SCORE_LIMITS.maxClipSeconds + 1,
+          maximumChannels: 2,
+        },
+      );
+      cache.set(key, {
+        seconds: wav.sampleCount / wav.sampleRate,
+        peaks: waveformPeaks(wav),
+      });
+    } catch {
+      cache.set(key, null);
+    } finally {
+      pending.delete(key);
+    }
+    changed = true;
+  }
+  return changed;
+}
+
+/** The peaks inside a clip's window (`offset .. offset + dur`), reversed for `rev`. */
+function windowPeaks(
+  file: FilePeaks,
+  offset: number,
+  seconds: number,
+  rev: boolean,
+): number[] {
+  const count = file.peaks.length;
+  const from = Math.floor((offset / file.seconds) * count);
+  const to = Math.max(
+    from + 1,
+    Math.ceil(((offset + seconds) / file.seconds) * count),
+  );
+  const slice = file.peaks.slice(Math.max(0, from), Math.min(count, to));
+  return rev ? slice.reverse() : slice;
+}
+
+/** Clip-row snapshots for `trackId`, undefined when it has no clips. */
+export function clipSnapshots(
+  score: TrackScore,
+  trackId: string,
+): ClipSnapshot[] | undefined {
+  const track = score.tracks.find((t) => t.id === trackId);
+  const clips = track?.clips;
+  if (!clips || clips.length === 0) return undefined;
+  const tpb = score.ticksPerBeat;
+  const ends = new Set<number>();
+  const shaped = clips.map((clip) => {
+    const file = cachedPeaks(clip.src, clip.sha256) ?? undefined;
+    const startTick = clipSongTick(clip, track.time);
+    const endTick = clipEndTick(score, clip, file?.seconds);
+    return { clip, file, startTick, endTick };
+  });
+  for (const item of shaped) ends.add(Math.round(item.endTick));
+  return shaped.map(({ clip, file, startTick, endTick }) => ({
+    id: clip.id,
+    startBeat: startTick / tpb,
+    durationBeats: Math.max(0, endTick - startTick) / tpb,
+    ...(file
+      ? {
+          peaks: windowPeaks(
+            file,
+            clip.offset ?? 0,
+            clipLength(clip, file.seconds),
+            clip.rev === true,
+          ),
+        }
+      : {}),
+    ...(clip.take !== undefined ? { take: clip.take } : {}),
+    ...(clip.text !== undefined ? { text: clip.text } : {}),
+    ...(clip.mute || track.muted ? { muted: true } : {}),
+    ...(startTick > 0 && ends.has(Math.round(startTick)) ? { seam: true } : {}),
+  }));
+}
+
+/** Test hook: forget cached peaks. */
+export function clearClipPeaks(): void {
+  cache.clear();
+}

package/tui/delight.ts

@@ -0,0 +1,193 @@
+/**
+ * Small, quiet moments that answer the music: the header ▶ glints on each
+ * downbeat, the first wrap of a new song sweeps once across the hit line,
+ * and a play key that is not recording glows its lane. Every one is a pure
+ * function of the transport clock and a timestamp, so tests pin the clock;
+ * `/motion off` turns them all off. None of them touches the score.
+ */
+
+/** How long the header ▶ stays bright after a bar downbeat. */
+export const GLINT_MS = 120;
+/** How long the first-loop sweep takes to cross the hit line. */
+export const SWEEP_MS = 900;
+/** How long a play key's lane glows. */
+export const GHOST_MS = 150;
+/** The card the first wrap shows, once per song. */
+export const FIRST_LOOP_CARD = "↻ first loop";
+
+export type GlintInput = Readonly<{
+  playing: boolean;
+  /** Transport beat, unwrapped. */
+  beat: number;
+  bpm: number;
+  beatsPerBar: number;
+  /** Bar starts within the loop (meter changes); bars repeat when absent. */
+  barBeats?: readonly number[] | undefined;
+  loopBeats?: number | undefined;
+  reducedMotion: boolean;
+}>;
+
+/** Whether the header ▶ glints now: within `GLINT_MS` after a downbeat. */
+export function downbeatGlint(input: GlintInput): boolean {
+  if (!input.playing || input.reducedMotion) return false;
+  if (!Number.isFinite(input.beat) || input.beat < 0) return false;
+  const bpm = Math.max(1, input.bpm);
+  const loop =
+    input.loopBeats && input.loopBeats > 0 ? input.loopBeats : undefined;
+  const inLoop = loop ? input.beat % loop : input.beat;
+  let since: number;
+  if (input.barBeats && input.barBeats.length > 0) {
+    let start = 0;
+    for (const bar of input.barBeats) if (bar <= inLoop + 1e-9) start = bar;
+    since = inLoop - start;
+  } else {
+    const bar = Math.max(1, input.beatsPerBar);
+    since = inLoop % bar;
+  }
+  return (since * 60_000) / bpm < GLINT_MS;
+}
+
+/**
+ * The first-loop sweep's head, 0..1 across the hit line, or undefined when
+ * it is not running. It plays once, `SWEEP_MS` long, from `startedAtMs`.
+ */
+export function sweepProgress(
+  startedAtMs: number | undefined,
+  nowMs: number,
+  reducedMotion: boolean,
+): number | undefined {
+  if (startedAtMs === undefined || reducedMotion) return undefined;
+  const age = nowMs - startedAtMs;
+  if (age < 0 || age >= SWEEP_MS) return undefined;
+  return age / SWEEP_MS;
+}
+
+/** The TAPE reels, one step per beat (op1-ux §9.1). */
+export const REELS = "◐◓◑◒";
+/** ASCII reels for terminals without unicode. */
+export const ASCII_REELS = "|/-\\";
+/** How long the loop brackets stay bright after each wrap (§9.3). */
+export const LOOP_FLASH_MS = 150;
+
+/**
+ * The TAPE reel glyph: turns one step per transport beat while playing,
+ * stands still when stopped or with `/motion off`. A pure function of the
+ * beat, so two panes on one transport turn together.
+ */
+export function reelGlyph(
+  input: Readonly<{
+    playing: boolean;
+    beat: number;
+    reducedMotion: boolean;
+    unicode: boolean;
+  }>,
+): string {
+  const reels = input.unicode ? REELS : ASCII_REELS;
+  if (!input.playing || input.reducedMotion || !Number.isFinite(input.beat))
+    return reels[0]!;
+  const step = Math.floor(Math.max(0, input.beat));
+  return reels[step % reels.length]!;
+}
+
+/**
+ * Whether the loop brackets flash now: within `LOOP_FLASH_MS` after the
+ * transport wraps the loop (each recording pass closes there). Never on
+ * the very first pass, never stopped, never with `/motion off`.
+ */
+export function loopFlash(
+  input: Readonly<{
+    playing: boolean;
+    /** Transport beat, unwrapped. */
+    beat: number;
+    loopBeats?: number | undefined;
+    bpm: number;
+    reducedMotion: boolean;
+  }>,
+): boolean {
+  const loop = input.loopBeats;
+  if (!input.playing || input.reducedMotion || !loop || loop <= 0) return false;
+  if (!Number.isFinite(input.beat) || input.beat < loop) return false;
+  const since = input.beat % loop;
+  return (since * 60_000) / Math.max(1, input.bpm) < LOOP_FLASH_MS;
+}
+
+/** A glowing lane: its pitch and strength (1 at the press, fading to 0). */
+export type LaneGlow = Readonly<{ pitch: number; strength: number }>;
+
+/**
+ * Session-only delight state. The first loop is remembered per song in the
+ * session's metadata (`heardLoop`), handed in by the host, never the score.
+ */
+export class Delight {
+  /** The song has wrapped before (this window or an earlier session). */
+  heardLoop: boolean;
+  /** When this window's first-loop sweep started. */
+  sweepStartedAtMs: number | undefined;
+  private readonly ghosts = new Map<number, number>();
+  private songId: string | undefined;
+
+  constructor(options: { heardLoop?: boolean } = {}) {
+    this.heardLoop = options.heardLoop ?? false;
+  }
+
+  /**
+   * Watch the transport. Returns true once, on the first wrap of a song
+   * that has not wrapped before; the caller shows the card and records it.
+   */
+  observe(
+    input: Readonly<{
+      playing: boolean;
+      beat: number;
+      loopBeats?: number | undefined;
+      empty: boolean;
+    }>,
+    nowMs: number,
+  ): boolean {
+    if (this.heardLoop || !input.playing || input.empty) return false;
+    const loop = input.loopBeats;
+    if (!loop || loop <= 0 || !(input.beat >= loop)) return false;
+    this.heardLoop = true;
+    this.sweepStartedAtMs = nowMs;
+    return true;
+  }
+
+  /**
+   * Follow the open song: a different session starts fresh from its own
+   * metadata; the same one only ever learns that it has wrapped.
+   */
+  song(id: string, heardLoop: boolean): void {
+    if (id !== this.songId) {
+      this.songId = id;
+      this.heardLoop = heardLoop;
+      this.sweepStartedAtMs = undefined;
+    } else if (heardLoop) this.heardLoop = true;
+  }
+
+  /** A play key sounded without recording. */
+  ghost(pitch: number, nowMs: number): void {
+    this.ghosts.set(pitch, nowMs);
+  }
+
+  /** Lanes glowing now, strongest first; expired ones are dropped. */
+  glows(nowMs: number, reducedMotion: boolean): LaneGlow[] {
+    const glows: LaneGlow[] = [];
+    for (const [pitch, atMs] of this.ghosts) {
+      const age = nowMs - atMs;
+      if (age >= GHOST_MS || age < 0) {
+        if (age >= GHOST_MS) this.ghosts.delete(pitch);
+        continue;
+      }
+      if (!reducedMotion) glows.push({ pitch, strength: 1 - age / GHOST_MS });
+    }
+    return glows.sort((a, b) => b.strength - a.strength);
+  }
+
+  /** Whether anything is animating (the host keeps frames coming). */
+  animating(nowMs: number): boolean {
+    return (
+      this.ghosts.size > 0 ||
+      (this.sweepStartedAtMs !== undefined &&
+        nowMs - this.sweepStartedAtMs < SWEEP_MS)
+    );
+  }
+}