@sudobility/music_player 0.1.0 → 0.1.2

package/dist/rn/playback/sample-engine.d.ts

@@ -0,0 +1,216 @@
+/**
+ * React Native playback: FluidR3, played from samples.
+ *
+ * The web engine runs libfluidsynth (WebAssembly) inside an `AudioWorklet`.
+ * React Native has neither — `react-native-audio-api` exposes no `addModule`
+ * and Hermes has no WebAssembly — so that engine cannot be ported, only
+ * replaced. See `spikes/rn-sample-playback.md`.
+ *
+ * What it is replaced with is **the same soundfont**, pre-rendered. Benjamin
+ * Gleitzman's packs are per-note recordings taken from `FluidR3_GM.sf2`, the
+ * font the web engine plays as `FluidR3Mono_GM.sf3`. Every one of the 128 GM
+ * programs is covered, at every key from A0 to C8, so a note here is the same
+ * recording the browser plays rather than an approximation of it. That
+ * distinction is the whole reason this engine exists: the RN engine that was
+ * deleted synthesised its own instruments from oscillators and could never
+ * match the web, and a wrong sound is worse than a clear error.
+ *
+ * What is *not* reproduced is SF2's per-zone filtering, LFOs and modulator
+ * envelopes — fluidsynth applies those live and a pre-rendered sample cannot.
+ * In practice that costs some expressive variation, not the instrument's
+ * identity.
+ *
+ * The transport half — flattening a score, the note cursor, the dispatch
+ * window, the master trim — is `shared/playback/`, the same code the web
+ * engine runs. This file is only the part that turns a due note into sound.
+ *
+ * It deliberately does *not* reuse `SoundfontPlaybackEngine`'s pump by
+ * refactoring it behind a synth port. That engine is verified on real devices
+ * and this one cannot be until it runs on a phone; destabilising the working
+ * one to serve the unproven one is the wrong order. Once this is device-tested,
+ * merging the two transports is the obvious follow-up.
+ */
+import type { PlaybackPlan, PlaybackTrack, ScoreRange } from '@sudobility/music_types';
+import type { AuditionVoice, PlaybackEngine, PlaybackObserver } from '../../engine.js';
+export { base64ToBytes } from './pack-library.js';
+import type { AudioApi } from './audio-api.js';
+export type SampleEngineDeps = {
+    /** Overridable so tests can drive the engine with a fake audio graph. */
+    loadAudioApi?: () => Promise<AudioApi>;
+    /** Fetches a pack body. Overridable for tests and for self-hosting. */
+    fetchPack?: (url: string) => Promise<string>;
+    /** Base URL for the melodic packs. An app may host its own copy; they are CC-BY 3.0. */
+    packBase?: string;
+    /**
+     * Base URL for the drum-kit packs.
+     *
+     * No default, because there is nowhere to default *to*: no CDN publishes
+     * pre-rendered GM percussion under a usable licence, so these are rendered
+     * by `scripts/build-percussion-packs.mjs` and hosted by the app alongside
+     * its other audio assets. An app with percussion in its scores must set this.
+     */
+    percussionBase?: string;
+    /** Overridable so tests can step the pump by hand instead of waiting. */
+    startPump?: (tick: () => void, intervalMs: number) => () => void;
+};
+export declare class RNSamplePlaybackEngine implements PlaybackEngine {
+    private readonly deps;
+    private api;
+    private ctx;
+    private master;
+    private plan;
+    private tempo;
+    private readonly queue;
+    private clicks;
+    private clickCursor;
+    private library;
+    private observer;
+    private state;
+    private loadState;
+    private stopPump;
+    private stopPositionTimer;
+    /** Context time corresponding to `originTick`. */
+    private originContextTime;
+    private originTick;
+    private positionTick;
+    private tempoMultiplier;
+    private loop;
+    private masterVolume;
+    private metronomeOn;
+    private headroom;
+    private readonly muted;
+    private readonly soloed;
+    /**
+     * Volume and pan per track, held apart from `plan` because `applyMix` is
+     * allowed to change them without the plan being rebuilt — that is the whole
+     * reason it exists.
+     */
+    private readonly mix;
+    private readonly strips;
+    private readonly voices;
+    /** Clicks already on the graph, so pause and stop can take them back. */
+    private readonly pendingClicks;
+    private readonly auditioned;
+    /**
+     * What is sounding, read off the clock rather than off the voice list.
+     *
+     * Deriving it from the voices lit every note the moment it was *scheduled* —
+     * a lookahead early — and held it lit through the release tail, so the
+     * notation ran ahead of the sound and lagged behind its end. The web engine
+     * has always used this; sharing it is what stops the two drifting.
+     */
+    private readonly sounding;
+    private activeNotes;
+    constructor(deps?: SampleEngineDeps);
+    initialize(): Promise<void>;
+    load(plan: PlaybackPlan): Promise<void>;
+    /** The pack name for a track, honouring the percussion/kit distinction. */
+    private packNameForTrack;
+    /** Loads every pack the score needs, reporting progress across all of them. */
+    private ensureScorePacks;
+    private reportLoad;
+    /**
+     * Reports `playing` only once a note can actually sound.
+     *
+     * The same rule the web engine follows, and for the same reason: the caret
+     * dead-reckons from elapsed real time between position reports, so announcing
+     * `playing` before the packs are decoded would glide it silently through
+     * several bars and snap it back when the music finally started.
+     */
+    play(fromTick?: number): Promise<void>;
+    pause(): void;
+    stop(): void;
+    seek(tick: number): void;
+    private haltPump;
+    private setState;
+    /** Score tick at the context's current time, from the tempo map and speed. */
+    private currentTick;
+    private secondsForTick;
+    private reportPosition;
+    /** The lit set, at the clock's position, and only when it has changed. */
+    private reportSounding;
+    private pump;
+    private drainThrough;
+    private tickAtContextTime;
+    /** Mute/solo, with solo winning: any solo means everything unsoloed is silent. */
+    private audibleTrack;
+    private startNote;
+    /**
+     * The track's gain-and-pan pair, built on first use.
+     *
+     * Lazily, because a plan can be loaded before there is an audio context to
+     * build nodes in — `load` does not await `initialize`.
+     */
+    private stripFor;
+    /** Volume, pan, mute and solo, resolved onto one track's strip. */
+    private applyStrip;
+    /** Pushes the whole mix, for a fader move or a mute that must land at once. */
+    private applyAllStrips;
+    private releaseStrips;
+    private applyMasterGain;
+    /**
+     * One voice: source -> [low-pass] -> gain -> master.
+     *
+     * The filter is only built when this velocity actually calls for one (71 of
+     * the 128 instruments never do), because a node per voice is real cost in a
+     * dense passage.
+     */
+    private buildVoiceFromPlan;
+    /** The flat-envelope form, for the metronome and for auditioning a key. */
+    private buildVoice;
+    /**
+     * Drops voices whose release has finished.
+     *
+     * Nothing about the *lit* set any more — that comes off the clock. A voice
+     * outlives its written note by the instrument's release, which is exactly
+     * the discrepancy that made deriving the lit set from here wrong.
+     */
+    private reapVoices;
+    private setActiveNotes;
+    private stopAllVoices;
+    /**
+     * Takes back clicks already placed on the graph.
+     *
+     * An oscillator started with `start(at)` sounds at that moment whatever the
+     * transport does next, and a click goes nowhere near a voice — so without
+     * this, pausing kept ticking for the length of the lookahead.
+     */
+    private cancelPendingClicks;
+    private scheduleClicks;
+    /**
+     * A short sine blip. Synthesised rather than sampled because the packs are
+     * instruments and carry no click, and a metronome is one of the few sounds
+     * where a plain tone is what is wanted anyway.
+     */
+    private scheduleClick;
+    setTempoMultiplier(multiplier: number): void;
+    setLoop(range: ScoreRange | null): void;
+    setTrackMute(trackId: string, muted: boolean): void;
+    setTrackSolo(trackId: string, solo: boolean): void;
+    /**
+     * Re-reads the mix off the tracks it is handed, scheduling nothing.
+     *
+     * All four properties, as the interface promises. Volume and pan used to be
+     * missing here — the engine had no per-track node to put them on, so a fader
+     * moved during playback moved the fader and not the sound, exactly the bug
+     * `applyMix` exists to fix on the web side. They land on the track's strip,
+     * so they reach notes that are already sounding.
+     *
+     * A track the engine does not know is still recorded: `load` builds its strip
+     * later, reading the level from here.
+     */
+    applyMix(tracks: readonly PlaybackTrack[]): void;
+    setMetronome(enabled: boolean): void;
+    setMasterVolume(volume: number): void;
+    /**
+     * Sounds a pitch now and holds it, touching no transport state — no seek, no
+     * state change, no active-note report. Fire-and-forget: the caller is a
+     * keypress handler and cannot await a pack download.
+     */
+    noteOn(midi: number, auditionVoice: AuditionVoice): void;
+    private auditionNote;
+    noteOff(midi: number): void;
+    setObserver(observer: PlaybackObserver | null): void;
+    dispose(): void;
+}
+//# sourceMappingURL=sample-engine.d.ts.map

package/dist/rn/playback/sample-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample-engine.d.ts","sourceRoot":"","sources":["../../../src/rn/playback/sample-engine.ts"],"names":[],"mappings":"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"}