@torrent-tv/proxy 2.90.0 → 2.92.0

package/services/media/container/PacketIndex.js

@@ -0,0 +1,270 @@
+import { PacketRecords } from "./PacketRecords.js";
+import { IndexMemoryUnavailable } from "./memory-unavailable.js";
+import { isMp3Codec, mp3PacketFacts } from "./mp3-packet-dependencies.js";
+
+/** Exact packet addresses and decode order, owned by one immutable source file. */
+export class PacketIndex {
+  #tracks = new Map();
+  #packetMemory;
+  #deferMemory;
+  #pending = [];
+  #pendingAt = 0;
+
+  constructor({ packetMemory, deferMemory = false } = {}) {
+    this.#packetMemory = packetMemory;
+    this.#deferMemory = deferMemory;
+  }
+
+  declareTrack(id, { type, codecId = "", codecRanges = [], prerollSeconds = 0, reorderDepth = 0 }) {
+    if (this.#tracks.has(id)) throw new Error(`Packet track ${id} was already declared.`);
+    if (!["video", "audio", "subtitle"].includes(type) ||
+      !Number.isFinite(prerollSeconds) || prerollSeconds < 0 ||
+      !Number.isSafeInteger(reorderDepth) || reorderDepth < 0) {
+      throw new TypeError("Invalid packet track parameters.");
+    }
+    const prerollFrames = isMp3Codec(codecId) || ["aac", "aac_latm", "mp4a"].includes(codecId) || /^A_AAC(?:\/|$)/.test(codecId) ? 1 : 0;
+    this.#tracks.set(id, { type, codecId, codecRanges: normalizeRanges(codecRanges), prerollSeconds, prerollFrames, reorderDepth, packets: new PacketRecords(this.#packetMemory), coveredThrough: 0, complete: false });
+  }
+
+  append(id, packet) {
+    const track = this.#track(id);
+    if (track.complete) throw new Error("Cannot append to a completed packet index.");
+    const ranges = validatePacket(packet);
+    if (packet.decodeFromIndex !== undefined && (!Number.isSafeInteger(packet.decodeFromIndex) || packet.decodeFromIndex < 0 ||
+        packet.decodeFromIndex > track.packets.length + this.#pending.slice(this.#pendingAt).filter(one => one?.id === id).length)) {
+      throw new TypeError("A packet decoder dependency must name an existing or current packet.");
+    }
+    const record = { pts: packet.pts, duration: packet.duration, keyframe: packet.keyframe === true, ranges,
+      ...(packet.expectedHash === undefined ? {} : { expectedHash: packet.expectedHash }),
+      ...(packet.discardPaddingSeconds === undefined ? {} : { discardPaddingSeconds: packet.discardPaddingSeconds }),
+      ...(packet.bitOffset === undefined ? {} : { bitOffset: packet.bitOffset, bitLength: packet.bitLength }),
+      ...(packet.dts === undefined ? {} : { dts: packet.dts }) };
+    if (packet.decodeFromIndex !== undefined) record.decodeFromIndex = packet.decodeFromIndex;
+    if (packet.decodeDependencyUnknown) record.decodeDependencyUnknown = true;
+    if (track.type === "audio" && isMp3Codec(track.codecId) && record.decodeFromIndex === undefined) {
+      record.decodeFromIndex = track.packets.length + this.#pending.slice(this.#pendingAt).filter(one => one?.id === id).length;
+      record.decodeDependencyUnknown = true;
+    }
+    if (this.#pending.length) { this.#pending.push({ id, record }); return; }
+    try { track.packets.push(record); }
+    catch (error) {
+      if (!this.#deferMemory || !(error instanceof IndexMemoryUnavailable)) throw error;
+      this.#pending.push({ id, record });
+    }
+  }
+
+  /** Drain facts from the last transport read before accepting another read. */
+  flushPending() {
+    if (!this.#pending.length) return;
+    while (this.#pendingAt < this.#pending.length) {
+      const { id, record } = this.#pending[this.#pendingAt];
+      this.#track(id).packets.push(record);
+      this.#pending[this.#pendingAt++] = null;
+    }
+    this.#pending = [];
+    this.#pendingAt = 0;
+  }
+
+  /** The progressive parser and its interval views share one packet allocation. */
+  async prepareAudioDependencies(interval, readRange) {
+    this.flushPending();
+    for (const [id, track] of this.#tracks) {
+      if (track.type !== "audio" || !isMp3Codec(track.codecId) ||
+          (interval?.trackIds && !interval.trackIds.includes(id)) || interval?.modes?.[id] === "copy") continue;
+      const records = track.packets;
+      for (let position = 0; position < records.length; position++) {
+        const packet = records.at(position);
+        if (!packet.decodeDependencyUnknown || (interval &&
+            (packet.pts >= interval.to || (packet.pts < interval.from && packet.pts + packet.duration <= interval.from &&
+              (position + track.prerollFrames >= records.length || records.ptsAt(position + track.prerollFrames) + records.durationAt(position + track.prerollFrames) <= interval.from))))) continue;
+        const facts = await mp3PacketFacts(packet, readRange);
+        let required = facts.required, first = position;
+        while (required > 0 && first > 0) {
+          first--;
+          required -= (await mp3PacketFacts(records.at(first), readRange)).capacity;
+        }
+        if (required > 0) throw new Error("MP3 bit reservoir refers to bytes before the indexed source.");
+        records.setDecodeFromIndex(position, first);
+      }
+    }
+  }
+
+  /** The progressive parser and its interval views share one packet allocation. */
+  sharePackets(id, records) {
+    const track = this.#track(id);
+    if (track.complete || track.packets.length || !(records instanceof PacketRecords)) {
+      throw new TypeError("Only an empty unfinished track may adopt packet records.");
+    }
+    for (const packet of records) validatePacket(packet);
+    track.packets.dispose();
+    track.packets = records;
+  }
+
+  dispose() {
+    for (const track of this.#tracks.values()) track.packets.dispose();
+    this.#tracks.clear();
+    this.#pending = [];
+    this.#pendingAt = 0;
+  }
+
+  reservePackets(id, count) {
+    const track = this.#track(id);
+    track.packets.reserveCapacity(count, isMp3Codec(track.codecId) ? 76 : 72);
+  }
+
+  complete(id) {
+    const track = this.#track(id);
+    track.packets.releaseUnusedCapacity();
+    track.complete = true;
+  }
+  extendLastPresentation(id, seconds) {
+    const track = this.#track(id);
+    if (track.complete || track.type !== "video" || !Number.isFinite(seconds) || seconds <= 0) throw new TypeError("Only an unfinished video packet may extend its presentation.");
+    track.packets.extendLastPresentation(seconds);
+  }
+  refuse(id, reason) {
+    if (typeof reason !== "string" || !reason) throw new TypeError("A packet refusal requires a reason.");
+    const track = this.#track(id);
+    track.refusal = reason;
+    track.complete = true;
+  }
+  isComplete() { return [...this.#tracks.values()].every(track => track.complete); }
+
+  allocatedBytes() { return [...this.#tracks.values()].reduce((bytes, track) => bytes + track.packets.allocatedBytes, 0); }
+
+  boundsOf(id) {
+    this.flushPending();
+    const track = this.#track(id);
+    if (track.bounds) return track.bounds;
+    const packets = track.packets;
+    if (!packets.length) return null;
+    let start = Infinity, end = -Infinity;
+    for (let index = 0; index < packets.length; index++) {
+      const pts = packets.ptsAt(index);
+      start = Math.min(start, pts);
+      end = Math.max(end, pts + packets.durationAt(index));
+    }
+    const bounds = { start, end };
+    if (track.complete) track.bounds = bounds;
+    return bounds;
+  }
+
+  keyframesOf(id) {
+    this.flushPending();
+    const packets = this.#track(id).packets, times = [];
+    for (let index = 0; index < packets.length; index++) if (packets.keyframeAt(index)) times.push(packets.ptsAt(index));
+    return times.sort((a, b) => a - b);
+  }
+
+  coverThrough(id, seconds) {
+    const track = this.#track(id);
+    if (!Number.isFinite(seconds) || seconds < track.coveredThrough) throw new TypeError("Index coverage must advance.");
+    track.coveredThrough = seconds;
+  }
+
+  /** The same calculation is used to order source bytes and admit an encode. */
+  inputFor({ trackId, from, to, mode = "transcode" }) {
+    this.flushPending();
+    if (!["copy", "transcode"].includes(mode)) throw new TypeError("Unknown segment input mode.");
+    if (!Number.isFinite(from) || !Number.isFinite(to) || from < 0 || to <= from) {
+      throw new TypeError("A segment requires a finite nonempty presentation interval.");
+    }
+    const track = this.#track(trackId);
+    if (track.refusal) return { kind: "terminal", reason: track.refusal, trackId };
+    const packets = track.packets;
+    const startAt = from - (track.type === "audio" && mode === "transcode" ? track.prerollSeconds : 0);
+    const selected = [];
+    for (let index = 0; index < packets.length; index++) {
+      const pts = packets.ptsAt(index);
+      if (pts < to && (pts >= startAt ||
+        ((mode === "transcode" || track.type === "audio") && pts + packets.durationAt(index) > startAt))) selected.push(index);
+    }
+    if (selected.length === 0) {
+      if (track.type === "subtitle" && (track.complete || track.coveredThrough >= to)) {
+        return { kind: "result", trackId, ranges: [], packets: [], from, to, decodeFrom: from };
+      }
+      return track.complete
+        ? { kind: "terminal", reason: "track-has-no-packets-in-interval" }
+        : { kind: "needs-index", trackId, from: startAt, to };
+    }
+    let first = selected[0];
+    let last = selected[selected.length - 1];
+    if (track.type === "audio" && mode === "transcode") {
+      const firstPlayed = selected.find(index => packets.ptsAt(index) + packets.durationAt(index) > from);
+      if (firstPlayed !== undefined) first = Math.min(first, Math.max(0, firstPlayed - track.prerollFrames));
+      for (let index = first; index <= last; index++) first = Math.min(first, packets.at(index).decodeFromIndex ?? index);
+    }
+    if (track.type === "video") {
+      while (first >= 0 && (!packets.keyframeAt(first) || packets.ptsAt(first) > from)) first--;
+      if (first < 0) return track.complete
+        ? { kind: "terminal", reason: "video-interval-has-no-decode-start" }
+        : { kind: "needs-index", trackId, from: startAt, to };
+      let endsAtKeyframe = false;
+      if (mode === "copy") for (let index = 0; index < packets.length; index++) if (packets.ptsAt(index) === to && packets.keyframeAt(index)) { endsAtKeyframe = true; break; }
+      if (mode === "copy" && (packets.ptsAt(first) !== from ||
+        (!endsAtKeyframe && (!track.complete || to < this.boundsOf(trackId).end)))) {
+        return { kind: "terminal", reason: "video-copy-cut-is-not-a-keyframe" };
+      }
+    }
+    // Coverage is established by the parser after its codec-required lookahead;
+    // packets outside the interval are inspected but are not appended to input.
+    if (!track.complete && track.coveredThrough < to) {
+      return { kind: "needs-index", trackId, from: startAt, to };
+    }
+    last = Math.min(last, packets.length - 1);
+    const input = packets.slice(first, last + 1);
+    return {
+      kind: "result",
+      trackId,
+      ranges: normalizeRanges([...track.codecRanges, ...input.flatMap(packet => packet.ranges)]),
+      decodeFrom: packets.ptsAt(first),
+      from,
+      to,
+      ...(track.complete && to >= this.boundsOf(trackId).end ? { sourceEndSeconds: this.boundsOf(trackId).end } : {}),
+      packets: input
+    };
+  }
+
+  #track(id) {
+    const track = this.#tracks.get(id);
+    if (!track) throw new Error(`Packet track ${id} is not declared.`);
+    return track;
+  }
+}
+
+function validatePacket(packet) {
+  if (!Number.isFinite(packet.pts) || !Number.isFinite(packet.duration) || packet.duration < 0) {
+    throw new TypeError("Packet presentation time and duration are required.");
+  }
+  const ranges = normalizeRanges(packet.ranges);
+  if (ranges.length === 0) throw new TypeError("Packet byte addresses are required.");
+  if (packet.dts !== undefined && !Number.isFinite(packet.dts)) throw new TypeError("Packet decode time must be finite.");
+  if (packet.discardPaddingSeconds !== undefined && !Number.isSafeInteger(Math.round(packet.discardPaddingSeconds * 1e9))) {
+    throw new TypeError("Packet discard padding must have an exact finite duration.");
+  }
+  if (packet.expectedHash !== undefined && !/^[a-f0-9]{64}$/.test(packet.expectedHash)) throw new TypeError("Packet SHA-256 must be hexadecimal.");
+  if ((packet.bitOffset === undefined) !== (packet.bitLength === undefined)) throw new TypeError("Packet bit addresses need both offset and length.");
+  if (packet.bitOffset !== undefined && (!Number.isSafeInteger(packet.bitOffset) || packet.bitOffset < 0 ||
+      !Number.isSafeInteger(packet.bitLength) || packet.bitLength <= 0 || packet.bitLength % 8 !== 0 ||
+      packet.bitOffset + packet.bitLength > ranges.reduce((sum, [start, end]) => sum + end - start + 1, 0) * 8)) {
+    throw new TypeError("Packet payload bit addresses are invalid.");
+  }
+  return ranges;
+}
+
+/** Inclusive byte ranges, merged without filling gaps between separate packets. */
+function normalizeRanges(ranges) {
+  const ordered = ranges.map(([start, end]) => {
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start) {
+      throw new TypeError("Invalid packet byte range.");
+    }
+    return [start, end];
+  }).sort((left, right) => left[0] - right[0]);
+  const result = [];
+  for (const range of ordered) {
+    const previous = result[result.length - 1];
+    if (previous && range[0] <= previous[1] + 1) previous[1] = Math.max(previous[1], range[1]);
+    else result.push(range);
+  }
+  return result;
+}

package/services/media/container/PacketRecords.js

@@ -0,0 +1,237 @@
+// Fixed-width packet facts and exact range addresses, outside the object heap.
+// Allocation size is a storage block size, not an admission allowance.
+import { IndexMemoryUnavailable } from "./memory-unavailable.js";
+
+const BLOCK_BYTES = 65536;
+const ADDRESS_BYTES = 8;
+const HEADER_BYTES = 56;
+
+export class PacketRecords {
+  #blocks = [];
+  #addresses = [];
+  #used = 0;
+  #length = 0;
+  #bytes = 0;
+  #reserve;
+  #release;
+  #onDispose;
+  #disposed = false;
+  #prepaid = 0;
+
+  constructor(memory = {}) {
+    const allocation = memory.forRecord?.(this) ?? memory;
+    this.#reserve = allocation.reserve ?? (() => true);
+    this.#release = allocation.release ?? (() => {});
+    this.#onDispose = allocation.dispose;
+  }
+
+  dispose() {
+    if (this.#disposed) return;
+    this.length = 0;
+    this.releaseUnusedCapacity();
+    this.#disposed = true;
+    this.#onDispose?.();
+  }
+
+  get length() { return this.#length; }
+  get allocatedBytes() { return this.#bytes; }
+
+  /** Admit a declared table's complete allocation before reconstructing it. */
+  reserveCapacity(count, recordBytes) {
+    if (this.#disposed || this.#length || this.#prepaid || !Number.isSafeInteger(count) || count < 0 ||
+        !Number.isSafeInteger(recordBytes) || recordBytes < HEADER_BYTES || recordBytes > BLOCK_BYTES) {
+      throw new TypeError("Invalid declared packet capacity.");
+    }
+    const bytes = Math.ceil(count / Math.floor(BLOCK_BYTES / recordBytes)) * BLOCK_BYTES +
+      Math.ceil(count / (BLOCK_BYTES / ADDRESS_BYTES)) * BLOCK_BYTES;
+    if (!Number.isSafeInteger(bytes)) throw new TypeError("Declared packet capacity exceeds its integer range.");
+    if (bytes && !this.#reserve(bytes)) throw new IndexMemoryUnavailable(bytes);
+    this.#prepaid = bytes;
+  }
+
+  releaseUnusedCapacity() {
+    if (this.#prepaid) this.#release(this.#prepaid);
+    this.#prepaid = 0;
+  }
+
+  set length(value) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > this.#length) {
+      throw new TypeError("Packet records may only be truncated.");
+    }
+    const previousBytes = this.#bytes;
+    if (value === 0) {
+      this.#blocks = [];
+      this.#addresses = [];
+      this.#used = 0;
+      this.#bytes = 0;
+    } else if (value < this.#length) {
+      const addressAt = (value - 1) * ADDRESS_BYTES;
+      const address = this.#addresses[Math.floor(addressAt / BLOCK_BYTES)];
+      const blockIndex = address.readUInt32LE(addressAt % BLOCK_BYTES);
+      const at = address.readUInt32LE(addressAt % BLOCK_BYTES + 4);
+      const block = this.#blocks[blockIndex];
+      this.#blocks.length = blockIndex + 1;
+      this.#addresses.length = Math.ceil(value * ADDRESS_BYTES / BLOCK_BYTES);
+      const flags = block.readUInt32LE(at + 48);
+      this.#used = at + HEADER_BYTES + block.readUInt32LE(at + 52) * 16 + ((flags & 2) ? 32 : 0) + ((flags & 8) ? 4 : 0) + ((flags & 16) ? 4 : 0);
+      this.#bytes = [...this.#blocks, ...this.#addresses].reduce((sum, buffer) => sum + buffer.length, 0);
+    }
+    this.#length = value;
+    if (previousBytes !== this.#bytes) this.#release(previousBytes - this.#bytes);
+  }
+
+  push(packet) {
+    if (this.#disposed) throw new Error("Packet records were released.");
+    if (!Number.isFinite(packet.pts) || !Array.isArray(packet.ranges) ||
+      packet.ranges.some(range => !Array.isArray(range) || range.length !== 2 ||
+        !Number.isSafeInteger(range[0]) || !Number.isSafeInteger(range[1]) || range[0] < 0 || range[1] < range[0]) ||
+      [packet.duration, packet.dts, packet.discardPaddingSeconds, packet.bitOffset, packet.bitLength]
+        .some(value => value != null && !Number.isFinite(value)) ||
+      (packet.expectedHash !== undefined && !/^[\da-f]{64}$/i.test(packet.expectedHash)) ||
+      [packet.streamId, packet.decodeFromIndex].some(value => value !== undefined && (!Number.isInteger(value) || value < 0 || value > 0xffffffff))) {
+      throw new TypeError("Invalid binary packet facts.");
+    }
+    const bytes = HEADER_BYTES + packet.ranges.length * 16 + (packet.expectedHash ? 32 : 0) + (packet.streamId !== undefined ? 4 : 0) + (packet.decodeFromIndex !== undefined ? 4 : 0);
+    let block = this.#blocks.at(-1);
+    const newBlock = !block || block.length - this.#used < bytes;
+    const perAddressBlock = BLOCK_BYTES / ADDRESS_BYTES;
+    const addressBlockIndex = Math.floor(this.#length / perAddressBlock);
+    const newAddresses = !this.#addresses[addressBlockIndex];
+    const growth = (newBlock ? Math.max(BLOCK_BYTES, bytes) : 0) + (newAddresses ? BLOCK_BYTES : 0);
+    const prepaid = Math.min(growth, this.#prepaid);
+    if (growth > prepaid && !this.#reserve(growth - prepaid)) throw new IndexMemoryUnavailable(growth - prepaid);
+    this.#prepaid -= prepaid;
+    let payloadAllocation, addressAllocation;
+    try {
+      if (newBlock) payloadAllocation = Buffer.alloc(Math.max(BLOCK_BYTES, bytes));
+      if (newAddresses) addressAllocation = Buffer.alloc(BLOCK_BYTES);
+    } catch (error) {
+      if (growth) this.#release(growth);
+      throw error;
+    }
+    if (newBlock) {
+      block = payloadAllocation;
+      this.#blocks.push(block);
+      this.#bytes += block.length;
+      this.#used = 0;
+    }
+    if (newAddresses) {
+      this.#addresses.push(addressAllocation);
+      this.#bytes += BLOCK_BYTES;
+    }
+    const address = this.#addresses[addressBlockIndex];
+    const addressAt = (this.#length % perAddressBlock) * ADDRESS_BYTES;
+    address.writeUInt32LE(this.#blocks.length - 1, addressAt);
+    address.writeUInt32LE(this.#used, addressAt + 4);
+    const at = this.#used;
+    const numbers = [packet.pts, packet.duration, packet.dts, packet.discardPaddingSeconds,
+      packet.bitOffset, packet.bitLength];
+    numbers.forEach((value, index) => block.writeDoubleLE(value ?? NaN, at + index * 8));
+    block.writeUInt32LE((packet.keyframe ? 1 : 0) | (packet.expectedHash ? 2 : 0) | (packet.streamId !== undefined ? 8 : 0) | (packet.decodeFromIndex !== undefined ? 16 : 0) | (packet.decodeFromIndex !== undefined && !packet.decodeDependencyUnknown ? 32 : 0), at + 48);
+    block.writeUInt32LE(packet.ranges.length, at + 52);
+    packet.ranges.forEach(([start, end], index) => {
+      block.writeDoubleLE(start, at + HEADER_BYTES + index * 16);
+      block.writeDoubleLE(end, at + HEADER_BYTES + index * 16 + 8);
+    });
+    if (packet.expectedHash) block.write(packet.expectedHash, at + HEADER_BYTES + packet.ranges.length * 16, 32, "hex");
+    if (packet.streamId !== undefined) block.writeUInt32LE(packet.streamId, at + bytes - 4 - (packet.decodeFromIndex !== undefined ? 4 : 0));
+    if (packet.decodeFromIndex !== undefined) block.writeUInt32LE(packet.decodeFromIndex, at + bytes - 4);
+    this.#used += bytes;
+    return ++this.#length;
+  }
+
+  #address(index) {
+    const addressAt = index * ADDRESS_BYTES;
+    const address = this.#addresses[Math.floor(addressAt / BLOCK_BYTES)];
+    const offset = addressAt % BLOCK_BYTES;
+    return [this.#blocks[address.readUInt32LE(offset)], address.readUInt32LE(offset + 4)];
+  }
+
+  ptsAt(index) {
+    const [block, at] = this.#address(index);
+    return block.readDoubleLE(at);
+  }
+
+  durationAt(index) {
+    const [block, at] = this.#address(index);
+    return block.readDoubleLE(at + 8);
+  }
+
+  keyframeAt(index) {
+    const [block, at] = this.#address(index);
+    return !!(block.readUInt32LE(at + 48) & 1);
+  }
+
+  derivedDurationAt(index) {
+    const [block, at] = this.#address(index);
+    return !!(block.readUInt32LE(at + 48) & 4);
+  }
+
+  at(index) {
+    if (index < 0) index += this.#length;
+    if (index < 0 || index >= this.#length) return undefined;
+    const [block, at] = this.#address(index);
+    const flags = block.readUInt32LE(at + 48), count = block.readUInt32LE(at + 52);
+    const packet = { pts: block.readDoubleLE(at), keyframe: !!(flags & 1), ranges: [] };
+    const duration = block.readDoubleLE(at + 8);
+    if (!Number.isNaN(duration)) packet.duration = duration;
+    for (const [number, name] of ["dts", "discardPaddingSeconds", "bitOffset", "bitLength"].entries()) {
+      const value = block.readDoubleLE(at + 16 + number * 8);
+      if (!Number.isNaN(value)) packet[name] = value;
+    }
+    for (let range = 0; range < count; range++) packet.ranges.push([
+      block.readDoubleLE(at + HEADER_BYTES + range * 16), block.readDoubleLE(at + HEADER_BYTES + range * 16 + 8)
+    ]);
+    if (flags & 2) packet.expectedHash = block.subarray(at + HEADER_BYTES + count * 16, at + HEADER_BYTES + count * 16 + 32).toString("hex");
+    if (flags & 8) packet.streamId = block.readUInt32LE(at + HEADER_BYTES + count * 16 + ((flags & 2) ? 32 : 0));
+    if (flags & 16) packet.decodeFromIndex = block.readUInt32LE(at + HEADER_BYTES + count * 16 + ((flags & 2) ? 32 : 0) + ((flags & 8) ? 4 : 0));
+    if ((flags & 16) && !(flags & 32)) packet.decodeDependencyUnknown = true;
+    return packet;
+  }
+
+  setDecodeFromIndex(index, first) {
+    if (!Number.isSafeInteger(index) || index < 0 || index >= this.#length ||
+        !Number.isSafeInteger(first) || first < 0 || first > index || first > 0xffffffff) {
+      throw new TypeError("Invalid decoder dependency address.");
+    }
+    const [block, at] = this.#address(index);
+    const flags = block.readUInt32LE(at + 48), count = block.readUInt32LE(at + 52);
+    if (!(flags & 16)) throw new Error("Decoder dependency storage was not reserved.");
+    block.writeUInt32LE(first, at + HEADER_BYTES + count * 16 + ((flags & 2) ? 32 : 0) + ((flags & 8) ? 4 : 0));
+    block.writeUInt32LE(flags | 32, at + 48);
+  }
+
+  extendLastPresentation(seconds) {
+    if (!this.#length) return;
+    const [block, at] = this.#address(this.#length - 1);
+    block.writeDoubleLE(block.readDoubleLE(at + 8) + seconds, at + 8);
+  }
+
+  setDuration(index, seconds, derived = false) {
+    if (!Number.isSafeInteger(index) || index < 0 || index >= this.#length || !Number.isFinite(seconds) || seconds < 0) {
+      throw new TypeError("A packet duration requires an existing record and a finite nonnegative value.");
+    }
+    const [block, at] = this.#address(index);
+    block.writeDoubleLE(seconds, at + 8);
+    const flags = block.readUInt32LE(at + 48);
+    block.writeUInt32LE(derived ? flags | 4 : flags & ~4, at + 48);
+  }
+
+  *[Symbol.iterator]() { for (let index = 0; index < this.#length; index++) yield this.at(index); }
+  map(callback) { return Array.from(this, callback); }
+  filter(callback) { return Array.from(this).filter(callback); }
+  some(callback) { for (const packet of this) if (callback(packet)) return true; return false; }
+  every(callback) { for (const packet of this) if (!callback(packet)) return false; return true; }
+  reduce(callback, initial) {
+    let value = initial;
+    for (const packet of this) value = callback(value, packet);
+    return value;
+  }
+  slice(start = 0, end = this.#length) {
+    if (start < 0) start = Math.max(0, this.#length + start);
+    if (end < 0) end = Math.max(0, this.#length + end);
+    const records = [];
+    for (let index = start; index < Math.min(end, this.#length); index++) records.push(this.at(index));
+    return records;
+  }
+}

package/services/media/container/RetainedBytes.js

@@ -0,0 +1,39 @@
+import { IndexMemoryUnavailable } from "./memory-unavailable.js";
+
+/** Reserve a retained metadata buffer before requesting its bytes. */
+export class RetainedBytes {
+  #allocation;
+  #held = 0;
+  #closed = false;
+
+  constructor(memory = {}) {
+    this.#allocation = memory.forRecord?.(this, "declarations") ?? memory;
+  }
+
+  async read(bytes, read) {
+    if (this.#closed || this.#held) throw new Error("Metadata allocation is no longer available.");
+    if (this.#allocation.reserve?.(bytes) === false) throw new IndexMemoryUnavailable(bytes);
+    this.#held = bytes;
+    try {
+      const value = await read();
+      if (this.#closed) throw new Error("Metadata source was forgotten during its read.");
+      return value;
+    } catch (error) {
+      this.#release();
+      throw error;
+    }
+  }
+
+  #release() {
+    if (!this.#held) return;
+    this.#allocation.release?.(this.#held);
+    this.#held = 0;
+  }
+
+  dispose() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#release();
+    this.#allocation.dispose?.();
+  }
+}

package/services/media/container/RetainedReads.js

@@ -0,0 +1,51 @@
+import { IndexMemoryUnavailable } from "./memory-unavailable.js";
+
+/** Retained declaration ranges reserve memory before reading and share retries. */
+export class RetainedReads {
+  #allocation;
+  #ranges = new Map();
+  #held = 0;
+  #closed = false;
+
+  constructor(memory = {}) {
+    this.#allocation = memory.forRecord?.(this, "declarations") ?? memory;
+  }
+
+  async read(start, end, read) {
+    if (this.#closed) throw new Error("Metadata source was forgotten.");
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start) {
+      throw new TypeError("Retained metadata requires an exact byte range.");
+    }
+    const key = `${start}:${end}`;
+    if (this.#ranges.has(key)) return this.#ranges.get(key);
+    const bytes = end - start + 1;
+    if (this.#allocation.reserve?.(bytes) === false) throw new IndexMemoryUnavailable(bytes);
+    this.#held += bytes;
+    const pending = Promise.resolve().then(() => read(start, end)).then(value => {
+      if (this.#closed) throw new Error("Metadata source was forgotten during its read.");
+      if (!value || value.length !== bytes) throw new Error("Retained metadata read is incomplete.");
+      if (value.byteOffset === 0 && value.buffer.byteLength === bytes && value.buffer instanceof ArrayBuffer) return value;
+      const owned = Buffer.allocUnsafeSlow(bytes);
+      owned.set(value);
+      return owned;
+    }).catch(error => {
+      this.#ranges.delete(key);
+      if (!this.#closed) {
+        this.#held -= bytes;
+        this.#allocation.release?.(bytes);
+      }
+      throw error;
+    });
+    this.#ranges.set(key, pending);
+    return pending;
+  }
+
+  dispose() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#ranges.clear();
+    this.#allocation.release?.(this.#held);
+    this.#held = 0;
+    this.#allocation.dispose?.();
+  }
+}

package/services/media/container/ac3-frame.js

@@ -0,0 +1,46 @@
+/** ATSC A/52 sync information gives exact frame length and sample count. */
+export function ac3Frame(bytes) {
+  if (bytes.length < 7 || bytes[0] !== 0x0b || bytes[1] !== 0x77) throw new Error("AC-3 frame synchronization is invalid.");
+  const bitstreamId = bytes[5] >> 3;
+  if (bitstreamId > 16) throw new Error("AC-3 bitstream version is invalid.");
+  let position = 16;
+  const read = count => {
+    let value = 0;
+    for (let bit = 0; bit < count; bit++, position++) value = (value << 1) | ((bytes[position >> 3] >> (7 - (position & 7))) & 1);
+    return value;
+  };
+  let sampleRate, size, channelMode, lfe, samples, codecId;
+  const frequencies = [48000, 44100, 32000];
+  if (bitstreamId <= 10) {
+    read(16);
+    const frequency = read(2), sizeCode = read(6);
+    if (frequency === 3 || sizeCode > 37) throw new Error("AC-3 frame parameters are invalid.");
+    const rates = [32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384, 448, 512, 576, 640];
+    const bitrate = rates[sizeCode >> 1] * 1000;
+    size = frequency === 1 ? 2 * (Math.floor(bitrate * 1536 / (44100 * 16)) + (sizeCode & 1))
+      : bitrate * 1536 / (frequencies[frequency] * 8);
+    sampleRate = frequencies[frequency] / 2 ** Math.max(0, bitstreamId - 8);
+    read(5);
+    read(3);
+    channelMode = read(3);
+    if ((channelMode & 1) && channelMode !== 1) read(2);
+    if (channelMode & 4) read(2);
+    if (channelMode === 2) read(2);
+    lfe = read(1);
+    samples = 1536;
+    codecId = "ac3";
+  } else {
+    const streamType = read(2), substream = read(3);
+    if (streamType === 3) throw new Error("E-AC-3 stream type is reserved.");
+    if (streamType === 1 || substream !== 0) throw new Error("E-AC-3 dependent substreams require combined frame-set indexing.");
+    size = 2 * (read(11) + 1);
+    const frequency = read(2), blockCode = read(2);
+    sampleRate = frequency === 3 ? frequencies[blockCode] / 2 : frequencies[frequency];
+    if (!sampleRate || size < 7) throw new Error("E-AC-3 frame parameters are invalid.");
+    samples = 256 * (frequency === 3 ? 6 : [1, 2, 3, 6][blockCode]);
+    channelMode = read(3);
+    lfe = read(1);
+    codecId = "eac3";
+  }
+  return { size, sampleRate, channels: [2, 1, 2, 3, 3, 4, 4, 5][channelMode] + lfe, duration: samples / sampleRate, codecId };
+}