@real-music-packages/web-core 0.32.0 → 0.34.0

package/dist/waveform-DdSMAbYQ.d.ts

@@ -0,0 +1,202 @@
+import { PromoTheme, SafeBox } from './video.js';
+
+interface ScoreNote {
+    /** MIDI note number (middle C = 60). */
+    pitchMidi: number;
+    /** Diatonic letter name: C D E F G A B. */
+    step: string;
+    /** Chromatic alteration in semitones: -1 flat, +1 sharp, 0 natural, ±2 double. */
+    alter: number;
+    /** Scientific octave (middle C = C4). */
+    octave: number;
+    /** Onset on the linear playback clock, in ms (repeats expanded). */
+    onsetMs: number;
+    /** Sounding duration in ms (tie chains merged). */
+    durMs: number;
+    /** Staff index within the whole sheet (0-based). */
+    staff: number;
+    /** Voice id within the part. */
+    voice: number;
+    /** Performing hand: grand-staff top -> "R", bottom -> "L" (see hand-inference stub). */
+    hand: 'L' | 'R';
+    /** Engraved bar this note sits in, 1-based. Repeat passes keep the printed
+     *  number — a cursor or scrubber points at bars as printed, not as played. */
+    measure: number;
+    /** Lyric syllable attached to this note, if any. */
+    lyric?: string;
+    /** Fingering digit attached to this note, if any. */
+    fingering?: number;
+}
+/**
+ * Tempo map. v1 is a single constant tempo (one segment at t=0). The piecewise
+ * shape is the documented seam for rubato / multiple `<sound tempo>` — see the
+ * tempo-map stub note in scoreFromMusicXML.
+ */
+interface TempoMap {
+    /** Where the tempo came from: the XML's notated tempo, the fallback, or an override. */
+    source: 'xml' | 'fallback' | 'override';
+    /** Piecewise-constant segments, ordered by onset. v1 always has exactly one (at 0). */
+    segments: Array<{
+        atMs: number;
+        bpm: number;
+    }>;
+}
+interface Score {
+    notes: ScoreNote[];
+    tempoMap: TempoMap;
+    /** End of the last sounding note, in ms. */
+    durationMs: number;
+    key?: string;
+    timeSig?: string;
+    title?: string;
+    composer?: string;
+}
+interface ScoreFromMusicXMLOpts {
+    /** bpm to use when the XML has no notated tempo (DefaultStartTempoInBpm === 0). Default 100. */
+    tempoFallback?: number;
+    /** Force this bpm regardless of the XML's notated tempo (per-recipe override). */
+    tempoOverride?: number;
+    /**
+     * Provide the OSMD instance. Defaults to a literal `import('opensheetmusicdisplay')`
+     * + a detached div (works in a browser, or in Node after `setupHeadlessDom()`).
+     * Inject for tests or non-DOM environments.
+     */
+    osmdFactory?: () => any;
+}
+/**
+ * Parse MusicXML into a timed, typed Score via OSMD's source model.
+ *
+ * @param xml  MusicXML document (uncompressed string; unzip .mxl first).
+ * @param opts tempoFallback / tempoOverride / osmdFactory.
+ */
+declare function scoreFromMusicXML(xml: string, opts?: ScoreFromMusicXMLOpts): Promise<Score>;
+
+/**
+ * Audio clock the runner exposes to layers. `nowMs` is the current playback
+ * position in milliseconds (audio-clock-driven, NOT wall-clock). During an
+ * offline/deterministic render the runner supplies the frame time directly, so
+ * `nowMs` and the `tMs` passed to `draw` agree.
+ */
+interface AudioClock {
+    /** Current playback position in ms. */
+    nowMs(): number;
+}
+/**
+ * Everything a layer needs to draw a frame. Constructed once per render and
+ * passed to every `init`/`draw`. World coordinates: layers draw in the frame's
+ * pixel space (0,0 top-left, W×H); the camera primitive (./camera) applies any
+ * pan/zoom transform to `ctx2d` BEFORE the layer's `draw` runs, so a layer never
+ * re-derives the viewport.
+ */
+interface RenderCtx {
+    /** The shared 2D context all layers draw onto. */
+    ctx2d: CanvasRenderingContext2D;
+    /** Frame width in px. */
+    W: number;
+    /** Frame height in px. */
+    H: number;
+    /** The parsed Score (timing/pitch/hands/lyrics). May be undefined for
+     *  non-musical scenes (a pure hook/CTA card). */
+    score?: Score;
+    /** Audio playback clock. */
+    audioClock: AudioClock;
+    /** Per-app theme tokens (colours/fonts/brand). */
+    theme: PromoTheme;
+    /** Phone-safe content rectangle (./video safeBox) — layers anchor to this
+     *  instead of re-deriving insets. */
+    safeBox: SafeBox;
+    /** Capture frame rate. */
+    fps: number;
+}
+/**
+ * A composable, time-synced render component.
+ *
+ * @typeParam P  the layer's prop type (what a SceneSpec passes as `p`).
+ */
+interface Layer<P = unknown> {
+    /** Stable identity, e.g. "notation" | "falling-notes" | "caption". */
+    readonly key: string;
+    /**
+     * One-time setup: load assets, lay out, rasterize an offscreen bitmap, etc.
+     * Runs before the first captured frame. May be async (e.g. font/IR load).
+     */
+    init(ctx: RenderCtx, props: P): void | Promise<void>;
+    /**
+     * Per-frame draw. MUST be cheap and a pure function of `tMs` (no rAF / wall
+     * clock). `tMs` is the absolute playback time in ms.
+     */
+    draw(ctx: RenderCtx, tMs: number): void;
+    /** Optional teardown (free bitmaps / audio nodes). */
+    dispose?(): void;
+}
+/**
+ * A layer factory keyed by name, with a runtime prop validator so the runner /
+ * pre-render gate can reject an unknown prop before capture (spec: "unknown
+ * layer/prop → fail fast"). `validateProps` returns an array of human-readable
+ * errors ([] = valid).
+ */
+interface LayerFactory<P = unknown> {
+    key: string;
+    create(): Layer<P>;
+    /** Validate a SceneSpec's `p` object. Return [] when valid. */
+    validateProps(props: unknown): string[];
+}
+
+/** Host-provided level source attached to RenderCtx by the app/capture harness. */
+interface SpectrumInput {
+    /** Normalized 0..1 magnitudes for `bands` bars at time tMs (preferred). */
+    levels?(tMs: number, bands: number): Float32Array | number[] | null | undefined;
+    /** Raw byte-FFT (0..255), log-binned by the layer (AnalyserNode shape). */
+    byteFreq?(tMs: number): Uint8Array | null | undefined;
+}
+/** Augment RenderCtx with the optional spectrum input (declaration merging). */
+declare module '../layer' {
+    interface RenderCtx {
+        /** Optional audio-reactive level source for the spectrum layer (host-wired). */
+        spectrum?: SpectrumInput;
+    }
+}
+interface SpectrumProps {
+    /** Number of bars. Default 44 (whozart SPEC_BARS). */
+    bars?: number;
+    /** Vertical center as a fraction of H. Default 0.46 (whozart). */
+    centerFrac?: number;
+    /** Max half-height as a fraction of H. Default 0.135 (whozart). */
+    maxHeightFrac?: number;
+    /** Bar fill at low magnitude (wine). Default theme.accent. */
+    colorLow?: string;
+    /** Bar fill at high magnitude (gold). Default theme.gold. */
+    colorHigh?: string;
+    /** Per-frame level provider (overrides ctx.spectrum). Pure fn of t for tests. */
+    levelsFn?: (tMs: number, bands: number) => Float32Array | number[] | null;
+}
+declare const spectrumFactory: LayerFactory<SpectrumProps>;
+
+/** Host-provided time-domain sample source (AnalyserNode shape). */
+interface WaveformInput {
+    /** 0..255 samples centered ~128 (AnalyserNode.getByteTimeDomainData). */
+    byteTime?(tMs: number): Uint8Array | null | undefined;
+}
+declare module '../layer' {
+    interface RenderCtx {
+        /** Optional time-domain source for the waveform layer (host-wired). */
+        waveform?: WaveformInput;
+    }
+}
+interface WaveformProps {
+    /** Number of samples plotted. Default 128. */
+    samples?: number;
+    /** Vertical center as a fraction of H. Default 0.46. */
+    centerFrac?: number;
+    /** Max deflection as a fraction of H. Default 0.10. */
+    amplitudeFrac?: number;
+    /** Line width px. Default 5. */
+    lineWidth?: number;
+    /** Line colour. Default theme.accent. */
+    color?: string;
+    /** Per-frame sample provider returning -1..1 (overrides ctx.waveform). */
+    samplesFn?: (tMs: number, n: number) => Float32Array | number[] | null;
+}
+declare const waveformFactory: LayerFactory<WaveformProps>;
+
+export { type AudioClock as A, type Layer as L, type RenderCtx as R, type Score as S, type TempoMap as T, type WaveformInput as W, type LayerFactory as a, type ScoreFromMusicXMLOpts as b, type ScoreNote as c, type SpectrumInput as d, type SpectrumProps as e, type WaveformProps as f, spectrumFactory as g, scoreFromMusicXML as s, waveformFactory as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-music-packages/web-core",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Shared music-theory + audio primitives for the music-suite web apps",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,6 +31,10 @@
       "types": "./dist/streak.d.ts",
       "import": "./dist/streak.js"
     },
+    "./playback": {
+      "types": "./dist/playback.d.ts",
+      "import": "./dist/playback.js"
+    },
     "./scene": {
       "types": "./dist/scene/index.d.ts",
       "import": "./dist/scene/index.js"