@torrent-tv/proxy 2.87.17 → 2.87.19

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.87.19
+
+- **Fix**: Return shared source bytes after whole-file assembly and retain the buffer held by concurrent readers instead of replacing it; fail malformed fragments explicitly rather than skipping source bytes.
+- **Fix**: Establish decode timestamp ordering in a private preceding cut before a copied-video restart, preserving leading reordered frames at the requested boundary.
+- **Fix**: Carry variable-rate video presentation across cuts only when decode timestamps prove continuity, and predict unproduced cuts in the measured track clock within the readiness integral.
+
+## 2.87.18
+
+- **Fix**: Interpret variable-rate video sample presentation holds and movie-clock resolution as media coverage; project prepared intervals onto the browser's reported HLS timestamp offsets per track.
+
 ## 2.87.17
 
 - **Fix**: Measure re-encoded HLS fragment intervals against their separate init and served timestamp position, without caching an absent header as empty media.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.87.17",
+  "version": "2.87.19",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/transcode-sessions/net-report/post.js

@@ -110,6 +110,7 @@ export async function handleApiTranscodeSessionNetReportPost(req, reply, { outpu
       linkSampleAt: Number.isFinite(linkSampleAt) && linkSampleAt > 0 ? linkSampleAt : undefined,
       bufferedAheadSec,
       bufferedRanges: body.bufferedRanges,
+      timestampOffsets: body.bufferedRanges?.timestampOffsets,
       bufferLimitSeconds:
         Number.isFinite(bufferLimitSeconds) && bufferLimitSeconds > 0 ? bufferLimitSeconds : undefined,
       consumerId,

package/services/encode/EncodeRuns.js

@@ -832,7 +832,12 @@ export class EncodeRuns {
       // Why this encoder exists, recorded with its argument list. It used to be
       // handed to a separate `start` call; there is no separate call now.
       because,
-      onClosed: (name) => this.#host.segmentFiles.publish(session.outputKey ?? "", name, session.segmentFormat),
+      onClosed: (name) => {
+        const index = session.segmentFormat.segmentIndexFromName(
+          session.segmentFormat.servedNameOf?.(name) ?? name);
+        if (Number.isInteger(index) && index < safeIndex) return null;
+        return this.#host.segmentFiles.publish(session.outputKey ?? "", name, session.segmentFormat);
+      },
       onEnded: (ended) => this.noteRunEnded(session, run, ended)
     });
     // THE ONE FAULT THAT IS OTHERWISE SILENT, asked before this run produces a

package/services/encode/run-command.js

@@ -358,6 +358,11 @@ export function buildRunCommand({
   // the cut points and, when re-encoding, as the keyframes to force — one
   // list, so the two cannot drift apart.
   const explicitTimes = segmentFormat.explicitTimesMuxerArgs?.() ?? null;
+  // Matroska seeks begin without the preceding decode timestamps. Copy one
+  // preceding cut privately so reordered frames have established DTS before
+  // the first requested cut. It is never published over another run's output.
+  const inputIndex = !transcodeVideo && !audioOnly && explicitTimes && safeIndex > 0
+    ? safeIndex - 1 : safeIndex;
   // A COPY is cut by this list whatever grid it ended up on. Even when no
   // keyframe index could be read and the boundaries are a plain grid, saying
   // them outright is what keeps the playlist and the muxer agreeing — ffmpeg
@@ -382,7 +387,7 @@ export function buildRunCommand({
   // playlist and its own cuts agree from the start. What they may not do is
   // move the cuts of a session whose playlist is already being read.
   const gridCutTimes = explicitTimes && (!transcodeVideo || timeline.cutGrid === "keyframe")
-    ? segmentCutTimesFrom(publishedGridFor(timeline), safeIndex)
+    ? segmentCutTimesFrom(publishedGridFor(timeline), inputIndex)
     : null;
   // Cut times are stated on the grid, for both branches.
   //
@@ -443,9 +448,11 @@ export function buildRunCommand({
   // back on to reach it; on the uniform grid it is a plain offset. This
   // follows the GRID, not whether the video is re-encoded — a variant cut on
   // the source's keyframes has to seek to them like the copy it accompanies.
+  const inputStartSeconds = inputIndex === safeIndex ? startSeconds :
+    publishedStartTime(timeline, inputIndex, segmentDurationSec);
   const seekSeconds = timeline.cutGrid === "keyframe"
-    ? startSeconds + sourceStartTime
-    : startSeconds;
+    ? inputStartSeconds + sourceStartTime
+    : inputStartSeconds;
   // Two-step seek when we have a real keyframe map: jump to a KNOWN-valid
   // keyframe (coarse, before -i — safe because WE sourced it from ffprobe,
   // not the container's own on-the-fly seek/index) and trim the short
@@ -477,7 +484,7 @@ export function buildRunCommand({
   // The search stays for a grid restored without its source clock, which is the
   // only case that has nothing to carry.
   const carriedKeyframe = timeline.cutGrid === "keyframe" && typeof timeline.sourceStartOf === "function"
-    ? timeline.sourceStartOf(safeIndex)
+    ? timeline.sourceStartOf(inputIndex)
     : null;
   const snappedKeyframe = Number.isFinite(carriedKeyframe)
     ? carriedKeyframe
@@ -689,7 +696,7 @@ export function buildRunCommand({
       "-segment_time_delta",
       "0.05",
       "-segment_start_number",
-      String(safeIndex),
+      String(inputIndex),
       // THE ENCODER SAYS WHEN A PIECE IS FINISHED, on a channel of its own.
       //
       // Measured on the addon host 2026-09-05: a name appears in this list when

package/services/encode/segment-formats/fmp4.js

@@ -11,6 +11,7 @@
  */
 
 import {
+  continuePresentationRanges,
   rebaseSegmentDecodeTimes,
   neutralizeEmptyEdits,
   readPresentationRanges,
@@ -18,6 +19,7 @@ import {
   readTrackTimescales,
   readVideoSampleSize,
   stampSegmentStartTime,
+  translatePresentationRanges,
   walkBoxes
 } from "./mp4-boxes.js";
 
@@ -285,6 +287,10 @@ export const fmp4Format = {
     const served = this.prepareSegmentBytes(raw, { initBytes, startSeconds, rawBytes: raw });
     return readPresentationRanges(Buffer.concat([initBytes, served]));
   },
+  clientMediaRanges(ranges, context) {
+    return translatePresentationRanges(continuePresentationRanges(ranges, context.nextRanges),
+      context.initBytes, context.timestampOffsetSeconds);
+  },
 
   /**
    * Whether a segment carries every track the init promises.

package/services/encode/segment-formats/index.js

@@ -52,6 +52,10 @@ import { mpegtsFormat } from "./mpegts.js";
  * @property {(bytes: Buffer, context?: Partial<PrepareSegmentContext>) =>
  *   { start: number, end: number }[] | undefined} [readMediaRanges] - Actual
  *   served presentation intervals, or undefined until their header is available.
+ * @property {(ranges: { start: number, end: number }[], context: {
+ *   initBytes: Buffer | null, timestampOffsetSeconds?: number, nextRanges?: Array<{ start: number, end: number }> }) =>
+ *   { start: number, end: number }[]} [clientMediaRanges] - Project parsed
+ *   presentation intervals onto the clock reported by this viewer's player.
  */
 
 /** @type {Readonly<Record<string, SegmentFormat>>} */

package/services/encode/segment-formats/mp4-boxes.js

@@ -16,6 +16,7 @@
  * @type {ReadonlySet<string>}
  */
 const CONTAINER_BOXES = new Set(["moov", "mvex", "trak", "mdia", "minf", "stbl", "edts", "moof", "traf"]);
+const presentationTracks = new WeakMap();
 
 /**
  * Walk the box tree, invoking `visit` for every box encountered.
@@ -175,12 +176,24 @@ export function readPresentationRanges(raw) {
   const scales = readTrackTimescales(raw);
   const edits = readTrackEditOffsets(raw);
   const byTrack = new Map();
+  const decodeRanges = new Map();
   const defaultDurations = new Map();
   let trackId = null;
   let decodeTime = 0;
   let defaultDuration = 0;
+  let movieScale = 0;
+  let declaredTrack = null;
+  const kinds = new Map();
   walkBoxes(raw, (type, start, end) => {
-    if (type === "trex" && start + 20 <= end) {
+    if (type === "mvhd") {
+      const at = start + (raw[start] === 1 ? 20 : 12);
+      if (at + 4 <= end) movieScale = raw.readUInt32BE(at);
+    } else if (type === "tkhd") {
+      const at = start + (raw[start] === 1 ? 20 : 12);
+      if (at + 4 <= end) declaredTrack = raw.readUInt32BE(at);
+    } else if (type === "hdlr" && start + 12 <= end) {
+      kinds.set(declaredTrack, raw.toString("latin1", start + 8, start + 12));
+    } else if (type === "trex" && start + 20 <= end) {
       defaultDurations.set(raw.readUInt32BE(start + 4), raw.readUInt32BE(start + 12));
     } else if (type === "tfhd" && start + 8 <= end) {
       const flags = raw.readUIntBE(start + 1, 3);
@@ -209,26 +222,81 @@ export function readPresentationRanges(raw) {
         if (!(duration > 0)) return;
         const position = (decodeTime + composition) / scale + (edits.get(trackId) ?? 0);
         ranges.push({ start: position, end: position + duration / scale });
+        const decode = decodeRanges.get(trackId) ?? [];
+        decode.push({ start: decodeTime / scale + (edits.get(trackId) ?? 0),
+          end: (decodeTime + duration) / scale + (edits.get(trackId) ?? 0) });
+        decodeRanges.set(trackId, decode);
         decodeTime += duration;
       }
       byTrack.set(trackId, ranges);
     }
   });
   // Merge in presentation order: B frames arrive in decode order.
-  const mergedTracks = [...byTrack.values()].map((samples) => {
+  const mergedTracks = [...byTrack].map(([id, samples]) => {
     const merged = [];
-    for (const sample of samples.sort((left, right) => left.start - right.start)) {
+    // Sample durations are decode durations. A displayed video frame remains
+    // present until the next presentation sample, including variable-rate holds.
+    const ordered = samples.sort((left, right) => left.start - right.start);
+    const precision = 1 / (movieScale || scales.get(id));
+    for (const sample of ordered) {
       const previous = merged.at(-1);
-      if (previous && sample.start - previous.end <= Number.EPSILON * Math.max(1, sample.end) * 8) {
+      if (previous && (kinds.get(id) === "vide" ||
+        sample.start - previous.end <= precision + Number.EPSILON * Math.max(1, sample.end) * 8)) {
         previous.end = Math.max(previous.end, sample.end);
       } else merged.push({ ...sample });
     }
-    return merged;
+    // Movie edits quantize independent pieces to movie ticks. Preserve that
+    // declared resolution at joins; it is not a playback buffer threshold.
+    for (const range of merged) range.end += precision;
+    const decoded = decodeRanges.get(id);
+    return { id, ranges: merged, kind: kinds.get(id), precision,
+      decodeStart: Math.min(...decoded.map(({ start }) => start)),
+      decodeEnd: Math.max(...decoded.map(({ end }) => end)) };
   });
   // A multiplexed segment is playable only where every declared track exists.
-  return mergedTracks.reduce((common, ranges) => common.flatMap((left) => ranges
+  const result = intersectPresentationTracks(mergedTracks);
+  presentationTracks.set(result, mergedTracks);
+  return result;
+}
+
+/** A video frame can cross a file boundary when decoding remains continuous. */
+export function continuePresentationRanges(ranges, nextRanges) {
+  const tracks = presentationTracks.get(ranges);
+  const next = presentationTracks.get(nextRanges);
+  if (!tracks || !next) return ranges;
+  const continued = tracks.map((track) => {
+    const following = next.find(({ id }) => id === track.id);
+    const held = track.ranges.map((range) => ({ ...range }));
+    if (track.kind === "vide" && following && held.length > 0 && following.ranges.length > 0 &&
+      Math.abs(track.decodeEnd - following.decodeStart) <= track.precision + following.precision +
+        Number.EPSILON * Math.max(1, following.decodeStart) * 8) {
+      held.at(-1).end = Math.max(held.at(-1).end, following.ranges[0].start);
+    }
+    return { ...track, ranges: held };
+  });
+  const result = intersectPresentationTracks(continued);
+  presentationTracks.set(result, continued);
+  return result;
+}
+
+function intersectPresentationTracks(tracks) {
+  return tracks.map(({ ranges }) => ranges).reduce((common, ranges) => common.flatMap((left) => ranges
     .map((right) => ({ start: Math.max(left.start, right.start), end: Math.min(left.end, right.end) }))
-    .filter(({ start, end }) => end > start)), mergedTracks[0] ?? []);
+    .filter(({ start, end }) => end > start)), tracks[0]?.ranges ?? []);
+}
+
+/** Project the same parsed samples onto the media player's reported clock. */
+export function translatePresentationRanges(ranges, initBytes, timestampOffsetSeconds) {
+  const tracks = presentationTracks.get(ranges);
+  if (!tracks || !initBytes?.length || !Number.isFinite(timestampOffsetSeconds)) return ranges;
+  const edits = readTrackEditOffsets(initBytes);
+  return intersectPresentationTracks(tracks.map(({ id, ranges: held }) => ({
+    id,
+    ranges: held.map(({ start, end }) => ({
+      start: Math.max(0, start + timestampOffsetSeconds - (edits.get(id) ?? 0)),
+      end: end + timestampOffsetSeconds - (edits.get(id) ?? 0)
+    })).filter(({ start, end }) => end > start)
+  })));
 }
 
 /**

package/services/server/ViewerRequests.js

@@ -565,14 +565,25 @@ export class ViewerRequests {
       const trackProgress = output === session ? progress : this.#host.encodeRuns.progressOf(output);
       const trackRates = this.#trackRateReadings(measurement, output, now);
       const timeline = output.timeline;
-      const segments = Array.from({ length: timeline?.segmentCount ?? 0 }, (_, index) => ({
-        index,
-        startSeconds: timeline.publishedStartOf(index),
-        endSeconds: timeline.publishedStartOf(index + 1),
-        mediaRanges: this.#host.segmentStore.mediaRangesOf(output.outputKey, index, {
+      const trackName = output === session ? "video" : "audio";
+      const nativeRanges = Array.from({ length: timeline?.segmentCount ?? 0 }, (_, index) =>
+        this.#host.segmentStore.mediaRangesOf(output.outputKey, index, {
           startSeconds: timeline.publishedStartOf(index)
-        })
-      }));
+        }));
+      const segments = Array.from({ length: timeline?.segmentCount ?? 0 }, (_, index) => {
+        const ranges = nativeRanges[index];
+        return {
+          index,
+          startSeconds: timeline.publishedStartOf(index),
+          endSeconds: timeline.publishedStartOf(index + 1),
+          mediaRanges: ranges && output.segmentFormat?.clientMediaRanges ?
+            output.segmentFormat.clientMediaRanges(ranges, {
+              initBytes: this.#host.segmentStore.initOf(output.outputKey),
+              nextRanges: nativeRanges[index + 1],
+              timestampOffsetSeconds: viewerReading?.timestampOffsets?.[trackName]
+            }) : ranges
+        };
+      });
       const sourceIndexes = [output.spec.video?.fileIndex, output.spec.audio?.fileIndex]
         .filter((fileIndex) => Number.isInteger(fileIndex) && fileIndex >= 0);
       if (sourceIndexes.length === 0) {

package/services/server/playback-readiness.js

@@ -128,7 +128,7 @@ export function predictPlaybackReadiness(input = {}) {
     curve: rateCurve(track.readings, now),
     bitsPerMediaSecond: averageBitsPerMediaSecond(track, track.segments,
       new Set(Array.isArray(track.readySegmentIndices) ? track.readySegmentIndices : [])),
-    segments: track.segments
+    segments: predictedMediaSegments(track.segments)
       .filter((segment) => Number.isInteger(segment?.index) &&
         Number.isFinite(segment?.startSeconds) && Number.isFinite(segment?.endSeconds) &&
         segment.endSeconds > segment.startSeconds && segment.endSeconds > position)
@@ -388,6 +388,25 @@ export function predictPlaybackReadiness(input = {}) {
     "minimum-safe-delay", preparedSegments, readiness.bufferedAtStart);
 }
 
+/** Predict only unknown cuts in the same clock as the measured track. */
+function predictedMediaSegments(segments) {
+  const anchors = segments.filter(({ mediaRanges }) => mediaRanges?.length > 0);
+  return segments.map((segment) => {
+    if (segment.mediaRanges !== undefined && segment.mediaRanges !== null || anchors.length === 0) return segment;
+    const previous = anchors.findLast(({ index }) => index < segment.index);
+    const next = anchors.find(({ index }) => index > segment.index);
+    const nominalLeft = previous?.endSeconds ?? next.startSeconds;
+    const actualLeft = previous?.mediaRanges.at(-1).end ?? next.mediaRanges[0].start;
+    const nominalRight = next?.startSeconds ?? nominalLeft;
+    const actualRight = next?.mediaRanges[0].start ?? actualLeft;
+    const scale = nominalRight > nominalLeft ? (actualRight - actualLeft) / (nominalRight - nominalLeft) : 1;
+    return { ...segment, mediaRanges: [{
+      start: actualLeft + (segment.startSeconds - nominalLeft) * scale,
+      end: actualLeft + (segment.endSeconds - nominalLeft) * scale
+    }] };
+  });
+}
+
 function rateCurve(readings, now) {
   if (readings && Number.isFinite(readings.count) && readings.count > 0 &&
     Number.isFinite(readings.lastAt) && Number.isFinite(readings.lastValue) &&

package/services/storage/piece-store/shared-piece-store.js

@@ -933,13 +933,19 @@ export class SharedPieceStore {
     // THREE pieces reported 812 MB committed against 68 MB allowed, 739 blocks
     // allocated and 676 still alive, and the process was killed at 4.37 GB.
     const displaced = this.#buffers.get(index);
-    this.#buffers.set(index, buffer);
     if (displaced !== undefined && displaced !== buffer) {
       this.#counters.blocksDisplaced += 1;
-      this.#returnBlock(displaced);
+      // A reader may still hold the existing buffer pinned. Verified bytes for
+      // this index are identical, so retain that buffer and return the duplicate.
+      this.#returnBlock(buffer);
+      this.#lru.touch(index);
+      this.#noteProgress();
+      return displaced;
     }
+    this.#buffers.set(index, buffer);
     this.#lru.touch(index);
     this.#noteProgress();
+    return buffer;
   }
 
   /**
@@ -1394,12 +1400,9 @@ export class SharedPieceStore {
         return null;
       }
       this.#counters.fromWholeFile += 1;
-      const release = await this.#claimSlotOrNull();
-      if (release === null) {
-        // No block to put it in. The caller gets the bytes anyway; what it
-        // loses is only that the next read pays for this one again.
-        return whole;
-      }
+      // Fragment readers require shared memory, including when the bytes now
+      // live in an assembled file. Wait for the same reservation as disk reads.
+      const release = await this.#claimSlot();
       try {
         return this.#registerPiece(index, this.#copyIntoNewBuffer(index, whole));
       } finally {
@@ -1432,11 +1435,11 @@ export class SharedPieceStore {
         this.#returnBlock(target);
         throw error;
       }
-      this.#registerPiece(index, target);
+      const registered = this.#registerPiece(index, target);
       this.#counters.fromDisk += 1;
       this.#counters.revivals += 1;
       this.#noteRevival(index);
-      return target;
+      return registered;
     } finally {
       release?.();
       releaseDisk();

package/services/torrent/worker/client.js

@@ -149,18 +149,18 @@ export class TorrentWorkerClient {
       switch (message?.type) {
         case Event.FRAGMENT: {
           const buffer = message.buffer;
-          if (!buffer) {
-            // No buffer means no way to read the fragment; confirm it so the
-            // worker is not left waiting, and let the read end short.
-            this.#worker.postMessage({ type: Event.FRAGMENT_DONE, id: message.id });
-            break;
-          }
-          if (message.offset + message.length > buffer.byteLength) {
-            logger.warn(
-              `torrent-worker: fragment ${message.offset}+${message.length} lies outside ` +
-              `its buffer of ${buffer.byteLength}B (read ${message.id}) — ending the read short`
-            );
+          if (!buffer || !Number.isInteger(message.offset) || message.offset < 0 ||
+            !Number.isInteger(message.length) || message.length <= 0 ||
+            message.offset + message.length > buffer.byteLength) {
+            const error = new Error(`Invalid source fragment ${message.offset}+${message.length} ` +
+              `in a buffer of ${buffer?.byteLength ?? 0}B (read ${message.id}).`);
+            logger.warn(`torrent-worker: ${error.message}`);
+            this.#fragmentReaders.get(message.id)?.fail(error);
+            this.#fragmentReaders.delete(message.id);
+            this.#reads.get(message.id)?.fail(error);
+            this.#reads.delete(message.id);
             this.#worker.postMessage({ type: Event.FRAGMENT_DONE, id: message.id });
+            void this.#caller.call(Command.CANCEL_READ, { readId: message.id }).catch(() => undefined);
             break;
           }
           // A sequential read walks the file forwards, so each fragment either

package/services/viewer/Viewer.js

@@ -392,6 +392,7 @@ export class Viewer {
       linkSampleAgeMs = null,
       bufferedAheadSec,
       bufferedRanges,
+      timestampOffsets,
       bufferLimitSeconds,
       positionSeconds = null,
       playing,
@@ -435,6 +436,8 @@ export class Viewer {
           : now
         : this.netReport?.linkSampleMeasuredAt ?? null,
       bufferedAheadSec: held,
+      timestampOffsets: Object.fromEntries(["video", "audio"].filter((key) =>
+        Number.isFinite(timestampOffsets?.[key])).map((key) => [key, timestampOffsets[key]])),
       bufferedRanges: bufferedRanges && typeof bufferedRanges === "object" ?
         Object.fromEntries(["video", "audio", "media"].filter((key) => Array.isArray(bufferedRanges[key]))
           .map((key) => [key, bufferedRanges[key].slice(0, 256).filter((range) =>

package/test/fmp4-presentation-clock.test.js

@@ -1,11 +1,12 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { fmp4Format } from "../services/encode/segment-formats/fmp4.js";
-import { readPresentationRanges, walkBoxes } from "../services/encode/segment-formats/mp4-boxes.js";
+import { continuePresentationRanges, readPresentationRanges, walkBoxes } from "../services/encode/segment-formats/mp4-boxes.js";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { SegmentStore } from "../services/storage/segment-store/SegmentStore.js";
+import { Viewer } from "../services/viewer/Viewer.js";
 
 function box(type, body) {
   const header = Buffer.alloc(8);
@@ -14,13 +15,15 @@ function box(type, body) {
   return Buffer.concat([header, body]);
 }
 
-function init(emptyMs, mediaTime) {
+function init(emptyMs, mediaTime, kind = "vide") {
   const mvhd = Buffer.alloc(24);
   mvhd.writeUInt32BE(1000, 12);
   const tkhd = Buffer.alloc(20);
   tkhd.writeUInt32BE(1, 12);
   const mdhd = Buffer.alloc(24);
   mdhd.writeUInt32BE(24000, 12);
+  const hdlr = Buffer.alloc(12);
+  hdlr.write(kind, 8);
   const elst = Buffer.alloc(32);
   elst.writeUInt32BE(2, 4);
   elst.writeUInt32BE(emptyMs, 8);
@@ -28,7 +31,8 @@ function init(emptyMs, mediaTime) {
   elst.writeUInt32BE(1000, 20);
   elst.writeInt32BE(mediaTime, 24);
   return box("moov", Buffer.concat([box("mvhd", mvhd), box("trak", Buffer.concat([
-    box("tkhd", tkhd), box("edts", box("elst", elst)), box("mdia", box("mdhd", mdhd))
+    box("tkhd", tkhd), box("edts", box("elst", elst)),
+    box("mdia", Buffer.concat([box("mdhd", mdhd), box("hdlr", hdlr)]))
   ]))]));
 }
 
@@ -95,3 +99,49 @@ test("HLS fragments use the separate init and the same timeline translation as s
     readPresentationRanges(Buffer.concat([header, served])));
   assert.ok(store.mediaRangesOf(key, 1)[0].start > 4);
 });
+
+test("variable-rate video retains its frame until the next presentation sample", () => {
+  const media = Buffer.concat([fragment(0, 0), fragment(72000, 0)]);
+  const video = readPresentationRanges(Buffer.concat([init(0, 0), media]));
+  assert.equal(video.length, 1);
+  assert.equal(video[0].start, 0);
+  assert.ok(video[0].end > 3);
+  const audio = readPresentationRanges(Buffer.concat([init(0, 0, "soun"), media]));
+  assert.equal(audio.length, 2);
+  assert.ok(audio[0].end < 0.05);
+  assert.equal(audio[1].start, 3);
+});
+
+test("client clock projection accounts for shared edits and audio initPTS", () => {
+  const audioHeader = init(0, 0, "soun");
+  const audio = readPresentationRanges(Buffer.concat([audioHeader, fragment(96000, 0)]));
+  const shifted = fmp4Format.clientMediaRanges(audio, {
+    initBytes: audioHeader, timestampOffsetSeconds: -0.083
+  });
+  assert.equal(shifted[0].start, 4 - 0.083);
+  const videoHeader = fmp4Format.prepareSharedInit(init(83, 2000));
+  const video = readPresentationRanges(Buffer.concat([init(83, 2000), fragment(0, 2000)]));
+  const projected = fmp4Format.clientMediaRanges(video, {
+    initBytes: videoHeader, timestampOffsetSeconds: -2000 / 24000
+  });
+  assert.deepEqual(projected, video);
+});
+
+test("a variable-rate frame crosses a cut only with continuous decode samples", () => {
+  const first = readPresentationRanges(Buffer.concat([init(0, 0), fragment(0, 0)]));
+  const continuous = readPresentationRanges(Buffer.concat([init(0, 0), fragment(1000, 72000)]));
+  assert.equal(continuePresentationRanges(first, continuous)[0].end, continuous[0].start);
+  const missing = readPresentationRanges(Buffer.concat([init(0, 0), fragment(24000, 72000)]));
+  assert.deepEqual(continuePresentationRanges(first, missing), first);
+  const audioFirst = readPresentationRanges(Buffer.concat([init(0, 0, "soun"), fragment(0, 0)]));
+  const audioNext = readPresentationRanges(Buffer.concat([init(0, 0, "soun"), fragment(1000, 72000)]));
+  assert.deepEqual(continuePresentationRanges(audioFirst, audioNext), audioFirst);
+});
+
+test("a viewer retains only finite per-track player clock offsets", () => {
+  const viewer = new Viewer("clock-reading", 1);
+  viewer.report({ timestampOffsets: { video: -0.083, audio: 0, media: 400 } }, 2);
+  assert.deepEqual(viewer.linkReading().timestampOffsets, { video: -0.083, audio: 0 });
+  viewer.report({ timestampOffsets: { video: Number.POSITIVE_INFINITY } }, 3);
+  assert.deepEqual(viewer.linkReading().timestampOffsets, {});
+});

package/test/piece-store-reservations.test.js

@@ -148,6 +148,28 @@ test("a revival holds disk bytes across the asynchronous memory reservation", as
   }
 });
 
+test("an assembled-file revival returns shared bytes and preserves a concurrent pinned reader", async () => {
+  const disk = makeDisk();
+  const store = new SharedPieceStore(CHUNK, {
+    length: CHUNK * 16, memoryBytes: CHUNK * 4, disk,
+    readPieceElsewhere: async ({ index }) => piece(index), name: "whole-file-read"
+  });
+  try {
+    store.pin(0);
+    const [first, second] = await Promise.all([store.reside(0), store.reside(0)]);
+    assert.ok(first.buffer instanceof SharedArrayBuffer);
+    assert.equal(first.buffer, second.buffer);
+    await put(store, 1);
+    await put(store, 2);
+    assert.deepEqual(Buffer.from(first.buffer, first.offset, first.length), piece(0));
+    assert.equal(store.locate(0).buffer, first.buffer);
+    assert.equal(store.stats().outstanding, 0);
+    store.unpin(0);
+  } finally {
+    await new Promise((resolve) => store.destroy(resolve));
+  }
+});
+
 /**
  * Wait until a condition holds, rather than for a chosen interval — a test that
  * sleeps samples, it does not check (roadmap item 54).

package/test/playback-readiness.test.js

@@ -39,6 +39,17 @@ test("finds the first safe start from segments delivered before playback", () =>
   assert.ok(Math.abs(forecast.delaySeconds - 1) < 1e-8);
 });
 
+test("future cuts follow measured track time without inventing a permanent clock gap", () => {
+  const state = input({ bufferedAheadSeconds: 3.9, reserveSeconds: 0 });
+  state.tracks[0].clientRanges = [{ start: 0, end: 3.9 }];
+  state.tracks[0].segments[0].mediaRanges = [{ start: 0, end: 3.9 }];
+  const forecast = predictPlaybackReadiness(state);
+  assert.notEqual(forecast.reason, "no-safe-start-found");
+  state.tracks[0].segments[1].mediaRanges = [{ start: 4, end: 8 }];
+  state.tracks[0].readySegmentIndices = [0, 1];
+  assert.equal(predictPlaybackReadiness(state).reason, "no-safe-start-found");
+});
+
 test("keeps source-stall reserve in the proxy's prepared timeline, not the capped browser buffer", () => {
   const now = 10_000;
   const forecast = predictPlaybackReadiness({

package/test/quality-variants.test.js

@@ -761,8 +761,7 @@ test("a run on the keyframe grid is given no trim to apply", () => {
       videoEncoder: { name: "libx264" },
       segmentDurationSec: SEGMENT_SECONDS
     });
-    // Exactly one `-ss`, and it is the input seek: the trim is not there to be
-    // inherited by the cuts.
+    // One input seek establishes decode order in the preceding private cut.
     assert.equal(
       args.filter((one) => one === "-ss").length,
       1,
@@ -770,9 +769,10 @@ test("a run on the keyframe grid is given no trim to apply", () => {
     );
     const seek = Number(args[args.indexOf("-ss") + 1]);
     assert.ok(
-      Math.abs(seek - grid.sourceTimes[index]) < 0.2,
-      `run at #${index} seeks to ${seek}, not to its own keyframe ${grid.sourceTimes[index]}`
+      Math.abs(seek - grid.sourceTimes[index - 1]) < 0.2,
+      `run at #${index} seeks to ${seek}, not to the preceding keyframe ${grid.sourceTimes[index - 1]}`
     );
+    assert.equal(Number(args[args.indexOf("-segment_start_number") + 1]), index - 1);
   }
 });