@torrent-tv/proxy 2.91.0 → 2.92.1

package/services/media/container/mpeg-elementary-index.js

@@ -0,0 +1,196 @@
+import { mpegAudioFrame } from "./mpeg-audio-frame.js";
+import { PacketIndex } from "./PacketIndex.js";
+import { H264ElementaryIndex } from "./h264-elementary-index.js";
+import { HevcElementaryIndex } from "./hevc-elementary-index.js";
+import { LatmFrames } from "./latm-frame.js";
+import { ac3Frame } from "./ac3-frame.js";
+import { dtsFrame } from "./dts-frame.js";
+import { MpegAudioReservoir } from "./mpeg-audio-reservoir.js";
+
+/** Preserve elementary-frame addresses while transport packets are discarded. */
+export class MpegElementaryIndex {
+  index;
+  #states = new Map();
+  #completed = false;
+
+  constructor(tracks, { packetMemory, index = null } = {}) {
+    this.index = index ?? new PacketIndex({ packetMemory, deferMemory: true });
+    for (const track of tracks.filter(track => ["video", "audio"].includes(track.type))) {
+      if (!index) this.index.declareTrack(track.trackNumber, { type: track.type, codecId: track.codecId });
+      const supported = track.type === "video" ? ["mpeg1video", "mpeg2video", "h264", "hevc"].includes(track.codecId)
+        : ["mp1", "mp2", "mp3", "aac", "aac_latm", "ac3", "eac3", "dts"].includes(track.codecId);
+      if (!supported) {
+        this.index.refuse(track.trackNumber, `elementary-index-unavailable:${track.codecId || "unknown"}`);
+        continue;
+      }
+      this.#states.set(track.trackNumber, { track, offset: 0, mappings: [], stamps: [], carry: Buffer.alloc(0),
+        latm: track.codecId === "aac_latm" ? new LatmFrames() : null,
+        nalIndex: track.codecId === "h264" ? new H264ElementaryIndex(track, this.index)
+          : track.codecId === "hevc" ? new HevcElementaryIndex(track, this.index) : null,
+        picture: null, pendingStart: 0, lastPicture: -1, presentationBase: null, lastDts: null, referencePts: null,
+        audioBytes: Buffer.alloc(0), audioStart: 0, audioPts: null, lastTimestamp: null, clockShift: 0,
+        reservoir: new MpegAudioReservoir(), packetCount: 0,
+        lastExtension: -1, requiresStamp: false });
+    }
+  }
+
+  push(id, bytes, sourceStart, { pts = null, dts = null } = {}) {
+    const state = this.#states.get(id);
+    if (!state || bytes.length === 0) return;
+    const position = state.offset;
+    if (!state.nalIndex) state.mappings.push({ from: position, to: position + bytes.length, sourceStart });
+    let normalized = null;
+    if (pts !== null) {
+      const cycle = 2 ** 33 / 90000;
+      const clock = dts ?? pts;
+      if (state.lastTimestamp === null) {
+        if (clock > pts + cycle / 2) state.clockShift -= cycle;
+        else if (clock < pts - cycle / 2) state.clockShift += cycle;
+      } else {
+        if (clock + state.clockShift < state.lastTimestamp - cycle / 2) state.clockShift += cycle;
+        else if (clock + state.clockShift > state.lastTimestamp + cycle / 2) state.clockShift -= cycle;
+      }
+      state.lastTimestamp = clock + state.clockShift;
+      let presentation = pts + state.clockShift;
+      if (presentation < state.lastTimestamp - cycle / 2) presentation += cycle;
+      else if (presentation > state.lastTimestamp + cycle / 2) presentation -= cycle;
+      normalized = { position, pts: presentation, dts: state.lastTimestamp };
+      if (!state.nalIndex) state.stamps.push(normalized);
+    }
+    state.offset += bytes.length;
+    if (state.nalIndex) state.nalIndex.push(bytes, sourceStart, normalized);
+    else if (state.track.type === "video") this.#video(state, bytes, position);
+    else this.#audio(state, bytes);
+  }
+
+  complete() {
+    if (this.#completed) return this.index;
+    for (const state of this.#states.values()) {
+      if (state.nalIndex) { state.nalIndex.complete(); continue; }
+      if (state.track.type === "video" && state.picture) this.#closePicture(state, state.offset);
+      if (state.track.type === "audio" && state.audioBytes.length) throw new Error("MPEG audio ends inside a frame.");
+      this.index.complete(state.track.trackNumber);
+    }
+    this.#completed = true;
+    return this.index;
+  }
+
+  #video(state, chunk, position) {
+    const bytes = Buffer.concat([state.carry, chunk]);
+    const base = position - state.carry.length;
+    for (let at = 0; at + 3 < bytes.length; at++) {
+      if (bytes[at] !== 0 || bytes[at + 1] !== 0 || bytes[at + 2] !== 1) continue;
+      const offset = base + at, code = bytes[at + 3];
+      if (code === 0xb5 && at + 9 <= bytes.length && bytes[at + 4] >> 4 === 8 &&
+        state.picture && offset > state.lastExtension) {
+        if ((bytes[at + 6] & 3) !== 3) throw new Error("MPEG field pictures require field-specific packet timing.");
+        const repeat = (bytes[at + 7] & 2) !== 0;
+        const top = (bytes[at + 7] & 128) !== 0;
+        const progressiveFrame = (bytes[at + 8] & 128) !== 0;
+        if (repeat) {
+          if (!progressiveFrame) throw new Error("MPEG repeated fields require field-specific packet timing.");
+          state.picture.duration *= state.track.progressiveSequence ? top ? 3 : 2 : 1.5;
+          state.requiresStamp = true;
+        }
+        state.lastExtension = offset;
+      }
+      if ((code === 0xb3 || code === 0xb8) && offset > state.lastPicture) {
+        if (state.pendingStart === null) state.pendingStart = offset;
+      }
+      if (code !== 0 || at + 6 > bytes.length || offset <= state.lastPicture) continue;
+      if (!(state.track.fps > 0)) throw new Error("MPEG video cadence is not declared.");
+      const reference = (bytes[at + 4] << 2) | (bytes[at + 5] >> 6);
+      const type = (bytes[at + 5] >> 3) & 7;
+      if (type < 1 || type > 3) throw new Error("MPEG picture type is invalid.");
+      const start = state.pendingStart ?? offset;
+      if (state.picture) this.#closePicture(state, start);
+      const stamp = stampAt(state, offset);
+      if (state.requiresStamp && !stamp) throw new Error("MPEG repeated frames require an explicit following timestamp.");
+      state.requiresStamp = false;
+      if (stamp) state.presentationBase = stamp.pts - reference / state.track.fps;
+      if (state.presentationBase === null) throw new Error("MPEG picture has no presentation timestamp.");
+      const pts = stamp?.pts ?? state.presentationBase + reference / state.track.fps;
+      const dts = stamp?.dts ?? (state.lastDts === null ? pts : state.lastDts + 1 / state.track.fps);
+      state.picture = { start, pts, dts, duration: 1 / state.track.fps, keyframe: type === 1 };
+      state.lastDts = dts;
+      state.lastPicture = offset;
+      state.pendingStart = null;
+      if (type !== 3) {
+        // The next reference picture proves that the preceding reference and
+        // its intervening B pictures have all been read in decode order.
+        if (state.referencePts !== null && pts > state.referencePts) this.index.coverThrough(state.track.trackNumber, Math.max(0, state.referencePts));
+        state.referencePts = pts;
+      }
+    }
+    state.carry = Buffer.from(bytes.subarray(Math.max(0, bytes.length - 9)));
+  }
+
+  #closePicture(state, end) {
+    const { start, ...packet } = state.picture;
+    if (!(end > start)) throw new Error("MPEG picture has no bytes.");
+    this.index.append(state.track.trackNumber, { ...packet, ranges: addresses(state, start, end) });
+    state.mappings = state.mappings.filter(mapping => mapping.to > end);
+  }
+
+  #audio(state, chunk) {
+    state.audioBytes = Buffer.concat([state.audioBytes, chunk]);
+    while (state.audioBytes.length >= (state.track.codecId === "dts" ? 24 : ["aac", "ac3", "eac3"].includes(state.track.codecId) ? 7 : 4)) {
+      const frame = state.latm ? state.latm.read(state.audioBytes) : state.track.codecId === "aac" ? adtsFrame(state.audioBytes)
+        : ["ac3", "eac3"].includes(state.track.codecId) ? ac3Frame(state.audioBytes)
+          : state.track.codecId === "dts" ? dtsFrame(state.audioBytes) : mpegAudioFrame(state.audioBytes);
+      if (state.audioBytes.length < frame.size) break;
+      const stamp = stampAt(state, state.audioStart);
+      if (stamp) state.audioPts = stamp.pts;
+      if (state.audioPts === null) throw new Error("MPEG audio frame has no presentation timestamp.");
+      if (frame.codecPrivateB64) {
+        if (state.track.codecPrivateB64 && state.track.codecPrivateB64 !== frame.codecPrivateB64) throw new Error("AAC configuration changes require packet-specific declarations.");
+        state.track.codecPrivateB64 = frame.codecPrivateB64;
+      }
+      Object.assign(state.track, { codecId: frame.codecId, samplingFrequency: frame.sampleRate, channels: frame.channels });
+      const reservoir = frame.codecId === "mp3" ? state.reservoir.prepare(state.audioBytes, frame.size, state.packetCount) : null;
+      this.index.append(state.track.trackNumber, { pts: state.audioPts, dts: state.audioPts,
+        ...(reservoir ? { decodeFromIndex: reservoir.decodeFromIndex } : {}),
+        ...(frame.bitOffset === undefined ? {} : { bitOffset: frame.bitOffset, bitLength: frame.bitLength }),
+        duration: frame.duration, keyframe: true, ranges: addresses(state, state.audioStart + (frame.headerBytes ?? 0), state.audioStart + frame.size) });
+      reservoir?.commit();
+      state.packetCount++;
+      state.audioPts += frame.duration;
+      this.index.coverThrough(state.track.trackNumber, Math.max(0, state.audioPts));
+      state.audioStart += frame.size;
+      state.audioBytes = state.audioBytes.subarray(frame.size);
+      state.mappings = state.mappings.filter(mapping => mapping.to > state.audioStart);
+    }
+    state.audioBytes = Buffer.from(state.audioBytes);
+  }
+}
+
+function stampAt(state, position) {
+  let latest = null;
+  while (state.stamps[0]?.position <= position) latest = state.stamps.shift();
+  return latest;
+}
+
+function addresses(state, from, to) {
+  const ranges = state.mappings.filter(mapping => mapping.from < to && mapping.to > from).map(mapping => [
+    mapping.sourceStart + Math.max(from, mapping.from) - mapping.from,
+    mapping.sourceStart + Math.min(to, mapping.to) - mapping.from - 1
+  ]);
+  if (ranges.reduce((sum, [a, b]) => sum + b - a + 1, 0) !== to - from) throw new Error("MPEG elementary bytes have missing addresses.");
+  return ranges;
+}
+
+function adtsFrame(bytes) {
+  if (bytes[0] !== 0xff || (bytes[1] & 0xf6) !== 0xf0) throw new Error("AAC ADTS header is invalid.");
+  const objectType = (bytes[2] >> 6) + 1;
+  const frequencyIndex = (bytes[2] >> 2) & 15;
+  const sampleRate = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350][frequencyIndex];
+  const channelConfiguration = ((bytes[2] & 1) << 2) | (bytes[3] >> 6);
+  if (!sampleRate || !channelConfiguration) throw new Error("AAC ADTS requires a declared sample rate and channel configuration.");
+  if (bytes[6] & 3) throw new Error("AAC ADTS multiple raw blocks require block-specific addresses.");
+  const headerBytes = bytes[1] & 1 ? 7 : 9;
+  const size = ((bytes[3] & 3) << 11) | (bytes[4] << 3) | (bytes[5] >> 5);
+  if (size <= headerBytes) throw new Error("AAC ADTS frame excludes its payload.");
+  const configuration = Buffer.from([(objectType << 3) | (frequencyIndex >> 1), ((frequencyIndex & 1) << 7) | (channelConfiguration << 3)]);
+  return { size, headerBytes, sampleRate, channels: channelConfiguration === 7 ? 8 : channelConfiguration,
+    duration: 1024 / sampleRate, codecId: "aac", codecPrivateB64: configuration.toString("base64") };
+}

package/services/media/container/mpeg-sequence-reader.js

@@ -0,0 +1,69 @@
+import { mpegVideoConfiguration } from "./mpeg-video-configuration.js";
+
+/** Retain sequence declarations only; preceding user data is not decoder configuration. */
+export class MpegSequenceReader {
+  #codec;
+  #zeros = 0;
+  #code = null;
+  #expectCode = false;
+  #unit = [];
+  #sequence = null;
+  #facts = null;
+
+  constructor(codec) { this.#codec = codec; }
+
+  push(bytes) {
+    for (const byte of bytes) {
+      if (this.#expectCode) {
+        this.#expectCode = false;
+        this.#code = byte;
+        this.#unit = [0, 0, 1, byte];
+        if (byte === 0xb3) this.#facts = null;
+        continue;
+      }
+      if (byte === 0) { this.#zeros++; continue; }
+      if (byte === 1 && this.#zeros >= 2) {
+        this.#appendZeros(this.#zeros - 2);
+        this.#finishUnit();
+        this.#zeros = 0;
+        this.#expectCode = true;
+        continue;
+      }
+      this.#appendZeros(this.#zeros);
+      this.#zeros = 0;
+      this.#append(byte);
+      this.#update();
+    }
+    return this.#facts;
+  }
+
+  #appendZeros(count) {
+    const remaining = this.#limit() - this.#unit.length;
+    for (let at = 0; at < Math.min(count, remaining); at++) this.#unit.push(0);
+    this.#update();
+  }
+
+  #limit() { return this.#code === 0xb3 ? 140 : this.#code === 0xb5 ? 10 : 0; }
+  #append(byte) { if (this.#unit.length < this.#limit()) this.#unit.push(byte); }
+
+  #finishUnit() {
+    if (this.#code === 0xb3) {
+      this.#sequence = Buffer.from(this.#unit);
+      this.#update();
+    }
+    if (this.#code === 0xb5) this.#update();
+  }
+
+  #update() {
+    const sequence = this.#code === 0xb3 ? Buffer.from(this.#unit) : this.#sequence;
+    if (!sequence) return;
+    const extension = this.#code === 0xb5 && this.#unit[4] >> 4 === 1 ? Buffer.from(this.#unit) : null;
+    if (this.#codec === "mpeg2video" && !extension) return;
+    try {
+      const facts = mpegVideoConfiguration(extension ? Buffer.concat([sequence, extension]) : sequence);
+      if (facts && (this.#codec !== "mpeg2video" || facts.codecId === "mpeg2video")) this.#facts = facts;
+    } catch (error) {
+      if (!error.message.includes("truncated")) throw error;
+    }
+  }
+}

package/services/media/container/mpeg-ts-packets.js

@@ -0,0 +1,93 @@
+import { pesPayload } from "./pes-header.js";
+import { MpegElementaryIndex } from "./mpeg-elementary-index.js";
+
+/** Incremental TS demultiplexing with exact elementary-payload addresses. */
+export async function readMpegTsPackets({ readRange, fileSize, layout, tracks, state, interval, stopWhen, packetMemory }) {
+  state.elementary ??= new MpegElementaryIndex(tracks, { packetMemory });
+  state.pids ??= new Map();
+  state.offset ??= 0;
+  state.elementary.index.flushPending();
+  if (state.complete) return state.elementary.index;
+  if (interval && ready(state.elementary.index, tracks, interval)) return state.elementary.index;
+  const wanted = new Set(tracks.filter(track => ["audio", "video"].includes(track.type)).map(track => track.trackNumber));
+  const { width, sync } = layout;
+  while (state.offset + width <= fileSize) {
+    const sourceStart = state.offset + sync;
+    const packet = await readRange(sourceStart, sourceStart + 187);
+    if (packet[0] !== 0x47 || packet[1] & 0x80) throw new Error("MPEG-TS media packet is damaged.");
+    const pid = ((packet[1] & 31) << 8) | packet[2];
+    const control = (packet[3] >> 4) & 3;
+    if (!control) throw new Error("MPEG-TS adaptation control is invalid.");
+    const offset = control === 3 ? 5 + packet[4] : 4;
+    if (offset > 188 || (control === 2 && packet[4] > 183)) throw new Error("MPEG-TS adaptation field exceeds its packet.");
+    if (wanted.has(pid) && control !== 2 && offset < 188) {
+      if (packet[3] & 0xc0) throw new Error("MPEG-TS media is scrambled.");
+      let pes = state.pids.get(pid);
+      const counter = packet[3] & 15;
+      const duplicate = pes?.counter === counter;
+      const discontinuity = control === 3 && packet[4] > 0 && (packet[5] & 0x80) !== 0;
+      if (!duplicate) {
+        if (pes && !discontinuity && counter !== ((pes.counter + 1) & 15)) throw new Error("MPEG-TS media has missing packets.");
+        if (packet[1] & 0x40) {
+          if (pes?.remaining > 0) throw new Error("MPEG-TS PES ended before its declared length.");
+          pes = { counter, parts: [], header: null, remaining: null, timestampGiven: false };
+          state.pids.set(pid, pes);
+        }
+        if (pes) {
+          pes.counter = counter;
+          feed(state.elementary, pid, pes, packet.subarray(offset), sourceStart + offset);
+        }
+      }
+    }
+    state.offset += width;
+    state.elementary.index.flushPending();
+    if (stopWhen?.(state.elementary.index)) return state.elementary.index;
+    if (interval && ready(state.elementary.index, tracks, interval)) return state.elementary.index;
+  }
+  if (state.offset !== fileSize) throw new Error("MPEG-TS ends inside a transport packet.");
+  for (const pes of state.pids.values()) {
+    if (!pes.header || pes.remaining > 0) throw new Error("MPEG-TS ends inside a PES packet.");
+  }
+  const index = state.elementary.complete();
+  state.complete = true;
+  index.flushPending();
+  return index;
+}
+
+function feed(index, pid, pes, bytes, sourceStart) {
+  if (pes.header) return payload(index, pid, pes, bytes, sourceStart);
+  pes.parts.push({ bytes, sourceStart });
+  const header = Buffer.concat(pes.parts.map(part => part.bytes));
+  if (header.length < 9) return;
+  if (header[0] !== 0 || header[1] !== 0 || header[2] !== 1 || (header[6] & 0xc0) !== 0x80) throw new Error("MPEG-TS PES header is invalid.");
+  const size = 9 + header[8];
+  if (header.length < size) return;
+  const optional = pesPayload(header.subarray(6, size));
+  const declared = header.readUInt16BE(4);
+  if (!declared && (header[3] < 0xe0 || header[3] > 0xef)) throw new Error("Only MPEG-TS video PES may omit its length.");
+  if (declared && declared < size - 6) throw new Error("MPEG-TS PES length excludes its header.");
+  pes.header = optional;
+  pes.remaining = declared ? declared - (size - 6) : null;
+  let skip = size;
+  for (const part of pes.parts) {
+    const count = Math.min(skip, part.bytes.length);
+    skip -= count;
+    if (count < part.bytes.length) payload(index, pid, pes, part.bytes.subarray(count), part.sourceStart + count);
+  }
+  pes.parts = [];
+}
+
+function payload(index, pid, pes, bytes, sourceStart) {
+  const size = pes.remaining === null ? bytes.length : Math.min(pes.remaining, bytes.length);
+  if (!size) return;
+  index.push(pid, bytes.subarray(0, size), sourceStart, pes.timestampGiven ? {} : pes.header);
+  pes.timestampGiven = true;
+  if (pes.remaining !== null) pes.remaining -= size;
+}
+
+export function ready(index, tracks, interval) {
+  const results = tracks.filter(track => ["audio", "video"].includes(track.type) &&
+    (!interval.trackIds || interval.trackIds.includes(track.trackNumber))).map(track =>
+    index.inputFor({ trackId: track.trackNumber, from: interval.from, to: interval.to }));
+  return results.some(result => result.kind === "terminal") || results.every(result => result.kind === "result");
+}

package/services/media/container/mpeg-video-configuration.js

@@ -0,0 +1,50 @@
+const RATES = [null, 24000 / 1001, 24, 25, 30000 / 1001, 30, 50, 60000 / 1001, 60];
+
+/** Read sequence declarations from a bounded elementary-stream prefix. */
+export function mpegVideoConfiguration(bytes) {
+  const sequence = bytes.indexOf(Buffer.from([0, 0, 1, 0xb3]));
+  if (sequence < 0) return null;
+  const bits = reader(bytes.subarray(sequence + 4));
+  let width = bits(12), height = bits(12);
+  const aspect = bits(4), rate = bits(4);
+  if (!width || !height || !aspect || !RATES[rate]) throw new Error("MPEG video sequence dimensions or rate are invalid.");
+  bits(18);
+  if (bits(1) !== 1) throw new Error("MPEG video sequence marker is invalid.");
+  bits(10); bits(1);
+  if (bits(1)) for (let index = 0; index < 64; index++) {
+    if (bits(8) === 0) throw new Error("MPEG video quantization matrix is invalid.");
+  }
+  if (bits(1)) for (let index = 0; index < 64; index++) {
+    if (bits(8) === 0) throw new Error("MPEG video quantization matrix is invalid.");
+  }
+  let fps = RATES[rate], codecId = "mpeg1video", progressiveSequence = true;
+  for (let at = sequence + 12; at + 4 < bytes.length; at++) {
+    if (bytes[at] !== 0 || bytes[at + 1] !== 0 || bytes[at + 2] !== 1) continue;
+    if (bytes[at + 3] === 0 || bytes[at + 3] === 0xb8) break;
+    if (bytes[at + 3] !== 0xb5 || bytes[at + 4] >> 4 !== 1) continue;
+    const extension = reader(bytes.subarray(at + 4));
+    extension(4); extension(8); progressiveSequence = extension(1) === 1;
+    if (extension(2) === 0) throw new Error("MPEG video chroma format is invalid.");
+    width += extension(2) * 4096;
+    height += extension(2) * 4096;
+    extension(12);
+    if (extension(1) !== 1) throw new Error("MPEG video extension marker is invalid.");
+    extension(8); extension(1);
+    fps *= (extension(2) + 1) / (extension(5) + 1);
+    codecId = "mpeg2video";
+    break;
+  }
+  return { width, height, fps, codecId, bitDepth: 8, progressiveSequence };
+}
+
+function reader(bytes) {
+  let offset = 0;
+  return count => {
+    if (offset + count > bytes.length * 8) throw new Error("MPEG video sequence header is truncated.");
+    let value = 0;
+    for (let index = 0; index < count; index++, offset++) {
+      value = value * 2 + ((bytes[offset >> 3] >> (7 - (offset & 7))) & 1);
+    }
+    return value;
+  };
+}

package/services/media/container/mpeg4-picture-timing.js

@@ -0,0 +1,108 @@
+import { Bits } from "./h264-configuration.js";
+import { RetainedBytes } from "./RetainedBytes.js";
+
+/** MPEG-4 Visual VOL/VOP clocks, committed only after packet admission. */
+export class Mpeg4PictureTiming {
+  #state = { resolution: null, seconds: 0, previousSeconds: 0, origin: null, reference: null };
+  #memory;
+
+  constructor(memory) { this.#memory = memory; }
+
+  async read(readRange, start, end, startSeconds) {
+    let length = Math.min(4, end - start + 1);
+    while (true) {
+      const bytes = await readRange(start, start + length - 1);
+      try {
+        const picture = this.prepare(bytes, startSeconds);
+        if (!picture.packed) return { pictures: [{ ...picture, start, end }], packed: false, commit: picture.commit };
+        const allocation = new RetainedBytes(this.#memory);
+        try {
+          const full = await allocation.read(end - start + 1, () => readRange(start, end));
+          const starts = [];
+          for (let at = 0; at + 4 <= full.length; at++) if (!full[at] && !full[at + 1] && full[at + 2] === 1 && full[at + 3] === 0xb6) starts.push(at);
+          let state = this.#state;
+          const pictures = starts.map((at, position) => {
+            const first = position === 0 ? 0 : at, last = starts[position + 1] ?? full.length;
+            const one = this.prepare(full.subarray(first, last), startSeconds, state);
+            state = one.state;
+            return { ...one, start: start + first, end: start + last - 1 };
+          });
+          return { pictures, packed: true, commit: () => { this.#state = state; } };
+        } finally { allocation.dispose(); }
+      }
+      catch (error) {
+        if (length === end - start + 1 || !/bits are truncated|no complete VOP header/.test(error.message)) throw error;
+        length = Math.min(end - start + 1, length * 2);
+      }
+    }
+  }
+
+  prepare(bytes, startSeconds, previous = this.#state) {
+    const state = { ...previous };
+    state.packed ||= /DivX[^\0]*p(?=\0|$)/.test(bytes.toString("latin1"));
+    let picture = null;
+    for (let at = 0; at + 4 <= bytes.length; at++) {
+      if (bytes[at] || bytes[at + 1] || bytes[at + 2] !== 1) continue;
+      const code = bytes[at + 3];
+      if (code >= 0x20 && code <= 0x2f) state.resolution = resolutionOf(bytes.subarray(at + 4));
+      if (code === 0xb3) {
+        const bits = new Bits(bytes.subarray(at + 4), "MPEG-4 Visual");
+        const hours = bits.uint(5), minutes = bits.uint(6);
+        marker(bits);
+        const seconds = bits.uint(6);
+        if (hours > 23 || minutes > 59 || seconds > 59) throw new Error("MPEG-4 group clock is invalid.");
+        state.seconds = hours * 3600 + minutes * 60 + seconds;
+      }
+      if (code !== 0xb6) continue;
+      if (picture) {
+        if (state.packed) break;
+        throw new Error("Multiple MPEG-4 pictures require a packed-stream declaration.");
+      }
+      if (!(state.resolution > 0)) throw new Error("MPEG-4 picture precedes its VOL clock declaration.");
+      const bits = new Bits(bytes.subarray(at + 4), "MPEG-4 Visual");
+      const type = bits.uint(2);
+      let seconds = 0;
+      while (bits.uint(1)) seconds++;
+      marker(bits);
+      const increment = bits.uint(Math.max(1, Math.ceil(Math.log2(state.resolution))));
+      if (increment >= state.resolution) throw new Error("MPEG-4 picture clock exceeds its resolution.");
+      marker(bits);
+      const coded = bits.uint(1) === 1;
+      if (type !== 2) {
+        state.previousSeconds = state.seconds;
+        state.seconds += seconds;
+      }
+      const clock = (type === 2 ? state.previousSeconds + seconds : state.seconds) + increment / state.resolution;
+      state.origin ??= clock - startSeconds;
+      const pts = clock - state.origin;
+      const coveredThrough = type === 2 ? null : state.reference;
+      if (type !== 2) state.reference = pts;
+      picture = { pts, keyframe: type === 0, coded, coveredThrough };
+    }
+    if (!picture) throw new Error("MPEG-4 packet has no complete VOP header.");
+    return { ...picture, packed: state.packed === true, state, commit: () => { this.#state = state; } };
+  }
+}
+
+function resolutionOf(bytes) {
+  const bits = new Bits(bytes, "MPEG-4 Visual");
+  bits.uint(1); bits.uint(8);
+  if (bits.uint(1)) { bits.uint(4); bits.uint(3); }
+  if (bits.uint(4) === 15) { bits.uint(8); bits.uint(8); }
+  if (bits.uint(1)) {
+    bits.uint(2); bits.uint(1);
+    if (bits.uint(1)) {
+      bits.uint(15); marker(bits); bits.uint(15); marker(bits);
+      bits.uint(15); marker(bits); bits.uint(3); bits.uint(11); marker(bits);
+      bits.uint(15); marker(bits);
+    }
+  }
+  if (bits.uint(2) !== 0) throw new Error("MPEG-4 nonrectangular pictures require shape-specific timing.");
+  marker(bits);
+  const resolution = bits.uint(16);
+  marker(bits);
+  if (!resolution) throw new Error("MPEG-4 VOL clock resolution is zero.");
+  return resolution;
+}
+
+function marker(bits) { if (bits.uint(1) !== 1) throw new Error("MPEG-4 picture marker bit is invalid."); }

package/services/media/container/pes-header.js

@@ -0,0 +1,34 @@
+/** PES optional headers from ISO/IEC 13818-1; PTS is a 33-bit 90 kHz counter. */
+export function pesPayload(bytes) {
+  let offset = 0, pts = null, dts = null;
+  if ((bytes[0] & 0xc0) === 0x80) {
+    if (bytes.length < 3 || 3 + bytes[2] > bytes.length) throw new Error("MPEG PES optional header is truncated.");
+    const flags = (bytes[1] >> 6) & 3;
+    if (flags === 1) throw new Error("MPEG PES timestamp flags are invalid.");
+    if (flags >= 2) {
+      if (bytes[2] < (flags === 3 ? 10 : 5)) throw new Error("MPEG PES timestamp is truncated.");
+      pts = pesTime(bytes.subarray(3, 8), flags);
+      dts = flags === 3 ? pesTime(bytes.subarray(8, 13), 1) : pts;
+    }
+    offset = 3 + bytes[2];
+  } else {
+    while (offset < bytes.length && bytes[offset] === 0xff) offset++;
+    if ((bytes[offset] & 0xc0) === 0x40) offset += 2;
+    const flags = bytes[offset] >> 4;
+    if (flags === 2 || flags === 3) {
+      const count = flags === 3 ? 10 : 5;
+      if (offset + count > bytes.length) throw new Error("MPEG-1 PES timestamp is truncated.");
+      pts = pesTime(bytes.subarray(offset, offset + 5), flags);
+      dts = flags === 3 ? pesTime(bytes.subarray(offset + 5, offset + 10), 1) : pts;
+      offset += count;
+    } else if (bytes[offset] === 0x0f) offset++;
+    else throw new Error("MPEG-1 PES optional header is invalid.");
+  }
+  return { offset, pts, dts };
+}
+
+function pesTime(bytes, prefix) {
+  if (bytes.length !== 5 || !(bytes[0] & bytes[2] & bytes[4] & 1)) throw new Error("MPEG PES timestamp markers are invalid.");
+  if ((bytes[0] >> 4) !== prefix) throw new Error("MPEG PES timestamp prefix is invalid.");
+  return ((bytes[0] & 14) * 2 ** 29 + bytes[1] * 2 ** 22 + (bytes[2] >> 1) * 2 ** 15 + bytes[3] * 2 ** 7 + (bytes[4] >> 1)) / 90000;
+}

package/services/media/playback-declarations.js

@@ -0,0 +1,57 @@
+import { AudioTrack } from "./tracks/AudioTrack.js";
+
+const VIDEO_CODECS = new Map([
+  ["V_MPEG4/ISO/AVC", "h264"], ["avc1", "h264"], ["avc3", "h264"],
+  ["V_MPEGH/ISO/HEVC", "hevc"], ["hvc1", "hevc"], ["hev1", "hevc"],
+  ["V_MPEG1", "mpeg1video"], ["V_MPEG2", "mpeg2video"],
+  ["V_MPEG4/ISO/ASP", "mpeg4"], ["V_MPEG4/ISO/SP", "mpeg4"], ["mp4v", "mpeg4"],
+  ["V_VP8", "vp8"], ["V_VP9", "vp9"], ["vp09", "vp9"],
+  ["V_AV1", "av1"], ["av01", "av1"], ["V_MJPEG", "mjpeg"],
+  ["V_FFV1", "ffv1"], ["V_THEORA", "theora"]
+]);
+const SUBTITLE_CODECS = new Map([
+  ["S_TEXT/UTF8", "subrip"], ["S_TEXT/ASS", "ass"], ["S_TEXT/SSA", "ssa"],
+  ["S_TEXT/WEBVTT", "webvtt"], ["wvtt", "webvtt"], ["tx3g", "mov_text"],
+  ["S_HDMV/PGS", "hdmv_pgs_subtitle"], ["S_VOBSUB", "dvd_subtitle"]
+]);
+const FOURCC_CODECS = new Map([
+  ["mjpg", "mjpeg"], ["jpeg", "mjpeg"], ["xvid", "mpeg4"],
+  ["divx", "mpeg4"], ["dx50", "mpeg4"], ["mpg2", "mpeg2video"]
+]);
+
+function videoCodecOf(track) {
+  let id = track.codecId;
+  if (id === "V_MS/VFW/FOURCC" && track.codecPrivateB64) {
+    const header = Buffer.from(track.codecPrivateB64, "base64");
+    if (header.length >= 20) id = header.toString("ascii", 16, 20);
+  }
+  return VIDEO_CODECS.get(id) ?? FOURCC_CODECS.get(id.toLowerCase()) ?? id.toLowerCase();
+}
+
+/** One playback inventory, taken from the same declarations used for input. */
+export function playbackDeclarations({ tracks, media, fileBytes = null }) {
+  const ordered = type => tracks.filter(track => track.type === type)
+    .sort((a, b) => a.declaredIndex - b.declaredIndex);
+  const video = ordered("video")[0];
+  const inventory = type => ordered(type).map((track, index) => ({
+    ...track, index, streamIndex: track.declaredIndex,
+    codec: type === "audio" ? AudioTrack.codecNameOf(track)
+      : SUBTITLE_CODECS.get(track.codecId) ?? track.codecId.toLowerCase(),
+    title: track.name ?? ""
+  }));
+  const audioTracks = inventory("audio"), subtitleTracks = inventory("subtitle");
+  return { tracks, video, audioTracks, subtitleTracks,
+    audioCodec: audioTracks[0]?.codec ?? "",
+    videoCodec: video ? videoCodecOf(video) : "",
+    container: media.format,
+    durationSeconds: media.durationSeconds,
+    startTimeSeconds: media.startTimeSeconds,
+    videoWidth: video?.width ?? 0, videoHeight: video?.height ?? 0,
+    fps: video?.fps ?? null, isHdr: video?.isHdr ?? false, bitDepth: video?.bitDepth ?? null,
+    // The measured whole-file average prices decoding; it never addresses packets.
+    bitrateKbps: Number.isFinite(media.bitrateKbps) ? media.bitrateKbps
+      : Number.isSafeInteger(fileBytes) && fileBytes > 0 && media.durationSeconds > 0
+        ? fileBytes * 8 / media.durationSeconds / 1000 : null,
+    streamCounts: { video: ordered("video").length, audio: audioTracks.length, subtitle: subtitleTracks.length }
+  };
+}