@modplayjs/playhead 0.0.0-stage → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Playhead } from './playhead.js';
+export type { PlaybackPosition, AudiblePosition, PlayheadOptions, } from './playhead.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// Copyright (c) 2026 Bitti09 — modplayjs contributors
+// Project-original code.
+// @modplayjs/playhead public API.
+export { Playhead } from './playhead.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,sDAAsD;AACtD,yBAAyB;AACzB,kCAAkC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/playhead.d.ts

@@ -0,0 +1,94 @@
+/** Row-resolution snapshot of the player at the moment of a pull. Matches
+ *  the fields of `core.playState` so it can be passed straight through. */
+export interface PlaybackPosition {
+    /** Order index (pattern position in the sequence). */
+    ord: number;
+    /** Row inside the current pattern. */
+    row: number;
+    /** Tick inside the row (0-based). */
+    frame: number;
+    /** Ticks per row (effect Fxx / Axx). */
+    speed: number;
+    /** Beats per minute (effect Fxx). */
+    bpm: number;
+    /** Elapsed playback time in ms as reported by the core. */
+    timeMs: number;
+}
+/** The position that is audible at the query time. */
+export interface AudiblePosition extends PlaybackPosition {
+    /** Frames actually played out at the query time. */
+    consumedFrames: number;
+    /** How far into the row the playhead is, 0..1 (estimated). */
+    rowProgress: number;
+    /** How far render is ahead of the sink, in frames (ring + device). */
+    queuedFrames: number;
+    /** How old (ms) the newest mark was at the query time. */
+    markAgeMs: number;
+}
+export interface PlayheadOptions {
+    /** Output rate in Hz; must match `core.setSampleRate`. Default 44100. */
+    rate?: number;
+    /** History retained for backward lookups, ms. Default 5000. */
+    historyMs?: number;
+    /** Extra offset applied on top of the sink's accounting, in ms.
+     *  Positive makes the view run LATER (use when the sink's counter is
+     *  known to under-report the buffered audio). Default 0. */
+    latencyMs?: number;
+    /** Monotonic clock in ms. Defaults to performance.now(), else Date.now(). */
+    clock?: () => number;
+}
+export declare class Playhead {
+    private marks;
+    private rate;
+    private readonly historyMs;
+    private latencyMs;
+    private readonly clock;
+    private provider;
+    /** Frames per row is derived from the core's binding time model:
+     *  ticksize = (int)(rate × 2.5 / bpm), row = ticksize × speed. */
+    constructor(opts?: PlayheadOptions);
+    /** Set the output rate (call after `core.setSampleRate`). Existing marks
+     *  keep the row timing they were recorded with. */
+    setRate(hz: number): void;
+    /** Extra latency in ms on top of the sink's own accounting. */
+    setLatencyMs(ms: number): void;
+    getLatencyMs(): number;
+    /**
+     * Install the sink's played-frames counter. The callback runs on every
+     * `positionAt()`; it must be cheap (Atomic load / field read) and must
+     * return the count of frames that have LEFT the sink (not the count
+     * still buffered in it).
+     */
+    setConsumedProvider(fn: (() => number) | null): void;
+    /** Drop all history (new module, seek, transport restart). */
+    reset(): void;
+    /** Number of recorded marks (diagnostics). */
+    get markCount(): number;
+    /**
+     * Record the player state reached at the end of one pull.
+     * `frames` is the CUMULATIVE number of frames handed to the sink.
+     * Monotonic frames are the timeline; the wall clock is only used for
+     * history expiry and for the fallback mode.
+     */
+    mark(frames: number, pos: PlaybackPosition, atMs?: number): void;
+    /**
+     * The position audible now (or at `atMs` / at frame `atFrames` when
+     * given). Returns null before the first mark — callers fall back to
+     * `core.playState`, which is correct while nothing has been rendered.
+     *
+     * The lookup is O(log n) and allocates one small object; it is meant to
+     * be called from a 60 fps render loop.
+     */
+    positionAt(atMs?: number): AudiblePosition | null;
+    private consumedFrames;
+    /** frames per row from the core's binding time model. */
+    private rowFrames;
+    /** ticksize (samples per tick) — truncated, like libxmp's (int) cast. */
+    private tickFrames;
+    /** Output frame at which `pos.row` started. `pos.frame` is the index of
+     *  the tick that just finished, so the row began `pos.frame + 1` ticks
+     *  before the reported position. */
+    private rowStart;
+    private trim;
+}
+//# sourceMappingURL=playhead.d.ts.map

package/dist/playhead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playhead.d.ts","sourceRoot":"","sources":["../src/playhead.ts"],"names":[],"mappings":"AAuBA;2EAC2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;gEAE4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAuBD,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAA+B;IAC/C;sEACkE;IAElE,YAAY,IAAI,GAAE,eAAoB,EAKrC;IAED;uDACmD;IACnD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAExB;IAED,+DAA+D;IAC/D,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7B;IAED,YAAY,IAAI,MAAM,CAErB;IAED;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAEnD;IAED,8DAA8D;IAC9D,KAAK,IAAI,IAAI,CAEZ;IAED,8CAA8C;IAC9C,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CA0B/D;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAqEhD;IAED,OAAO,CAAC,cAAc;IAYtB,yDAAyD;IACzD,OAAO,CAAC,SAAS;IAMjB,yEAAyE;IACzE,OAAO,CAAC,UAAU;IAIlB;;wCAEoC;IACpC,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,IAAI;CAQb"}

package/dist/playhead.js

@@ -0,0 +1,235 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// Copyright (c) 2026 Bitti09 — modplayjs contributors
+// Project-original code.
+// @modplayjs/playhead — playback clock for UIs.
+//
+// A tracker player renders AHEAD of the speaker: out-webaudio keeps a ring
+// at its high-water mark (HIGH_WATER_FRAMES = 0.68 s at 48 kHz) and a
+// terminal sink adds its own buffer on top. Reading `core.playState` from a
+// UI therefore shows the row the renderer is working on, not the row the
+// listener hears — several rows early on a fast song.
+//
+// This module records (rendered-frames, position) marks while the output
+// pulls `core.playBuffer`, then answers "which row was audible at time T"
+// by looking up the frame the SINK has consumed. Nothing here knows about
+// AudioWorklet, ALSA or a pipe: the output supplies the consumption counter
+// (a provider), and the UI only asks for a position.
+//
+// Two modes:
+//   - provider mode: consumedFrames comes from the sink (exact; the ring
+//     depth, the device latency and pause/resume are all already in it).
+//   - fallback mode (no provider): consumed ≈ last mark − latency − elapsed,
+//     for sinks that cannot report depth (a plain pipe, a file writer).
+const FALLBACK_CLOCK = () => {
+    // `performance` is not in the ES2022 lib (this package compiles without
+    // DOM/Node types); reach it through globalThis so a browser/Node runtime
+    // gets the monotonic clock and anything else falls back to wall time.
+    const perf = globalThis.performance;
+    if (perf !== undefined && typeof perf.now === 'function')
+        return perf.now();
+    return Date.now();
+};
+export class Playhead {
+    marks = [];
+    rate;
+    historyMs;
+    latencyMs;
+    clock;
+    provider = null;
+    /** Frames per row is derived from the core's binding time model:
+     *  ticksize = (int)(rate × 2.5 / bpm), row = ticksize × speed. */
+    constructor(opts = {}) {
+        this.rate = opts.rate ?? 44100;
+        this.historyMs = opts.historyMs ?? 5000;
+        this.latencyMs = opts.latencyMs ?? 0;
+        this.clock = opts.clock ?? FALLBACK_CLOCK;
+    }
+    /** Set the output rate (call after `core.setSampleRate`). Existing marks
+     *  keep the row timing they were recorded with. */
+    setRate(hz) {
+        if (hz > 0 && hz !== this.rate)
+            this.rate = hz;
+    }
+    /** Extra latency in ms on top of the sink's own accounting. */
+    setLatencyMs(ms) {
+        this.latencyMs = Number.isFinite(ms) ? ms : 0;
+    }
+    getLatencyMs() {
+        return this.latencyMs;
+    }
+    /**
+     * Install the sink's played-frames counter. The callback runs on every
+     * `positionAt()`; it must be cheap (Atomic load / field read) and must
+     * return the count of frames that have LEFT the sink (not the count
+     * still buffered in it).
+     */
+    setConsumedProvider(fn) {
+        this.provider = fn;
+    }
+    /** Drop all history (new module, seek, transport restart). */
+    reset() {
+        this.marks.length = 0;
+    }
+    /** Number of recorded marks (diagnostics). */
+    get markCount() {
+        return this.marks.length;
+    }
+    /**
+     * Record the player state reached at the end of one pull.
+     * `frames` is the CUMULATIVE number of frames handed to the sink.
+     * Monotonic frames are the timeline; the wall clock is only used for
+     * history expiry and for the fallback mode.
+     */
+    mark(frames, pos, atMs) {
+        const at = atMs ?? this.clock();
+        const last = this.marks[this.marks.length - 1];
+        if (last !== undefined) {
+            // A counter that went backwards means the transport restarted (a new
+            // start() resets the ring / the posted-frame counter). Start a new
+            // epoch instead of corrupting the lookup.
+            if (frames < last.frames)
+                this.marks.length = 0;
+            else if (frames === last.frames) {
+                // Same pull reported twice: keep the newer position.
+                last.pos = pos;
+                last.atMs = at;
+                last.rowFrames = this.rowFrames(pos);
+                last.rowStart = this.rowStart(frames, pos, last.rowFrames);
+                return;
+            }
+        }
+        const rowFrames = this.rowFrames(pos);
+        this.marks.push({
+            frames,
+            atMs: at,
+            pos,
+            rowFrames,
+            rowStart: this.rowStart(frames, pos, rowFrames),
+        });
+        this.trim(at);
+    }
+    /**
+     * The position audible now (or at `atMs` / at frame `atFrames` when
+     * given). Returns null before the first mark — callers fall back to
+     * `core.playState`, which is correct while nothing has been rendered.
+     *
+     * The lookup is O(log n) and allocates one small object; it is meant to
+     * be called from a 60 fps render loop.
+     */
+    positionAt(atMs) {
+        const marks = this.marks;
+        const len = marks.length;
+        if (len === 0)
+            return null;
+        const now = atMs ?? this.clock();
+        const last = marks[len - 1];
+        const first = marks[0];
+        let consumed = this.consumedFrames(now, last);
+        consumed -= Math.round((this.latencyMs * this.rate) / 1000);
+        let target = consumed;
+        // Clamp into the recorded window: before the first pull nothing is
+        // audible yet (the sink has not been fed), after the last pull the
+        // renderer has nothing newer to show.
+        if (target < first.frames)
+            target = first.frames;
+        if (target > last.frames)
+            target = last.frames;
+        // First mark whose cumulative frame count reaches the target: the
+        // target frame lies inside (marks[i-1].frames, marks[i].frames].
+        let lo = 0;
+        let hi = len - 1;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (marks[mid].frames < target)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        const m = marks[lo];
+        const prev = lo > 0 ? marks[lo - 1] : null;
+        // Resolve the row from where it STARTED, not from the pull boundary:
+        // a pull spans several ticks, so the last tick's row began mid-pull
+        // and the frames before that belonged to the previous row.
+        let row = m.pos.row;
+        let rowProgress = 1;
+        let timeMs = m.pos.timeMs - ((m.frames - target) / this.rate) * 1000;
+        if (m.rowFrames > 0) {
+            const intoRow = target - m.rowStart;
+            if (intoRow > 0) {
+                // Frames have been played past the row start, so this row sounds.
+                rowProgress = intoRow / m.rowFrames;
+                if (rowProgress > 1)
+                    rowProgress = 1;
+            }
+            else {
+                // Target is at (or before) the row start: the newest played frame
+                // still belongs to the previous row. Step back whole rows at this
+                // tempo/speed; a tempo or speed change inside the pull makes the
+                // earlier rows a different length, so the previous mark bounds it.
+                const back = 1 + Math.floor(-intoRow / m.rowFrames);
+                row = m.pos.row - back;
+                rowProgress = (back * m.rowFrames + intoRow) / m.rowFrames;
+            }
+            if (prev !== null && row < prev.pos.row)
+                row = prev.pos.row;
+            if (row > m.pos.row)
+                row = m.pos.row;
+            if (row < 0)
+                row = 0; // crossed into the previous pattern: clamp
+            if (rowProgress < 0)
+                rowProgress = 0;
+        }
+        return {
+            ord: m.pos.ord,
+            row,
+            frame: m.pos.frame,
+            speed: m.pos.speed,
+            bpm: m.pos.bpm,
+            timeMs: timeMs > 0 ? timeMs : 0,
+            consumedFrames: consumed,
+            rowProgress,
+            queuedFrames: last.frames - consumed,
+            markAgeMs: now - m.atMs,
+        };
+    }
+    consumedFrames(now, last) {
+        if (this.provider !== null) {
+            const v = this.provider();
+            if (Number.isFinite(v))
+                return v;
+        }
+        // Fallback: assume the sink holds `latencyMs` of audio and drains at
+        // the output rate; clamp into the recorded window.
+        const elapsed = ((now - last.atMs) * this.rate) / 1000;
+        const v = last.frames - elapsed;
+        return v < 0 ? 0 : v;
+    }
+    /** frames per row from the core's binding time model. */
+    rowFrames(pos) {
+        if (!(pos.bpm > 0) || !(pos.speed > 0))
+            return 0;
+        const ticks = this.tickFrames(pos.bpm);
+        return ticks * pos.speed;
+    }
+    /** ticksize (samples per tick) — truncated, like libxmp's (int) cast. */
+    tickFrames(bpm) {
+        return Math.trunc((this.rate * 2.5) / bpm);
+    }
+    /** Output frame at which `pos.row` started. `pos.frame` is the index of
+     *  the tick that just finished, so the row began `pos.frame + 1` ticks
+     *  before the reported position. */
+    rowStart(frames, pos, rowFrames) {
+        if (rowFrames <= 0)
+            return frames;
+        return frames - (pos.frame + 1) * this.tickFrames(pos.bpm);
+    }
+    trim(now) {
+        const marks = this.marks;
+        // Keep a short tail even when the render loop stalls, and never drop
+        // below two marks (a lookup needs a bounding interval).
+        while (marks.length > 4 && now - marks[0].atMs > this.historyMs) {
+            marks.shift();
+        }
+    }
+}
+//# sourceMappingURL=playhead.js.map

package/dist/playhead.js.map

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

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@modplayjs/playhead",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Playback clock for modplayjs UIs: maps sink consumption time to the song row that is actually audible (pattern-view sync).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {},
+  "keywords": [
+    "tracker",
+    "mod",
+    "libxmp",
+    "chiptune",
+    "playback-clock",
+    "latency",
+    "subtitles"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modplayjs/modplayjs.git",
+    "directory": "packages/playhead"
+  },
+  "bugs": {
+    "url": "https://github.com/modplayjs/modplayjs/issues"
+  },
+  "homepage": "https://github.com/modplayjs/modplayjs#readme",
+  "license": "BSD-3-Clause",
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.