@torrent-tv/proxy 2.91.0 → 2.92.1

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

@@ -0,0 +1,99 @@
+import { Bits } from "./h264-configuration.js";
+
+const SAMPLE_RATES = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350];
+
+/** LOAS frames retain their original addresses; payload bit positions describe raw AAC. */
+export class LatmFrames {
+  #configuration = null;
+
+  read(bytes) {
+    if (bytes.length < 3 || bytes[0] !== 0x56 || (bytes[1] & 0xe0) !== 0xe0) throw new Error("AAC LOAS synchronization is invalid.");
+    const size = 3 + ((bytes[1] & 31) << 8) + bytes[2];
+    if (bytes.length < size) return { size };
+    const bits = new Bits(bytes.subarray(3, size), "AAC LATM");
+    if (!bits.uint(1)) {
+      const version = bits.uint(1), versionA = version ? bits.uint(1) : 0;
+      if (versionA) throw new Error("AAC LATM version A requires its own payload declarations.");
+      if (version) latmValue(bits);
+      const sameTime = bits.uint(1), subframes = bits.uint(6), programs = bits.uint(4), layers = bits.uint(3);
+      if (!sameTime || subframes || programs || layers) throw new Error("AAC LATM multiplexed layers require separate packet declarations.");
+      const ascLength = version ? latmValue(bits) : null, ascStart = bits.at;
+      const configuration = readAudioConfiguration(bits);
+      let ascEnd = bits.at;
+      if (ascLength !== null) {
+        if (ascEnd - ascStart > ascLength) throw new Error("AAC LATM decoder configuration exceeds its bit length.");
+        skip(bits, ascLength - (ascEnd - ascStart));
+        ascEnd = bits.at;
+      }
+      const lengthType = bits.uint(3);
+      if (lengthType !== 0) throw new Error("AAC LATM fixed or CELP frame length requires its own payload declarations.");
+      bits.uint(8);
+      if (bits.uint(1)) {
+        if (version) latmValue(bits);
+        else {
+          let more;
+          do { more = bits.uint(1); bits.uint(8); } while (more);
+        }
+      }
+      if (bits.uint(1)) bits.uint(8);
+      const privateBytes = Buffer.alloc(Math.ceil((ascEnd - ascStart) / 8));
+      for (let bit = ascStart; bit < ascEnd; bit++) {
+        const value = (bits.bytes[bit >> 3] >> (7 - (bit & 7))) & 1;
+        privateBytes[(bit - ascStart) >> 3] |= value << (7 - ((bit - ascStart) & 7));
+      }
+      this.#configuration = { ...configuration, codecPrivateB64: privateBytes.toString("base64") };
+    }
+    if (!this.#configuration) throw new Error("AAC LATM payload precedes its stream configuration.");
+    let length = 0, part;
+    do { part = bits.uint(8); length += part; } while (part === 255);
+    if (!(length > 0) || bits.at + length * 8 > bits.bytes.length * 8) throw new Error("AAC LATM payload exceeds its LOAS frame.");
+    return { size, ...this.#configuration, codecId: "aac", bitOffset: bits.at + 24, bitLength: length * 8 };
+  }
+}
+
+function readAudioConfiguration(bits) {
+  const start = bits.at;
+  let type = audioType(bits);
+  const coreRate = audioRate(bits);
+  let channels = bits.uint(4), sampleRate = coreRate;
+  const parametricStereo = type === 29;
+  if (type === 5 || parametricStereo) { sampleRate = audioRate(bits); type = audioType(bits); }
+  if (![1, 2, 3, 4].includes(type) || !coreRate || !sampleRate || channels > 7) {
+    throw new Error("AAC LATM requires a supported declared audio configuration.");
+  }
+  const shortFrame = bits.uint(1);
+  if (bits.uint(1)) bits.uint(14);
+  const extension = bits.uint(1);
+  channels = channels ? channels === 7 ? 8 : channels : programChannels(bits, start, coreRate);
+  if (extension && bits.uint(1)) throw new Error("AAC LATM extension version requires its own decoder declaration.");
+  return { sampleRate, channels: parametricStereo && channels === 1 ? 2 : channels,
+    duration: (shortFrame ? 960 : 1024) / coreRate };
+}
+
+function audioType(bits) { const type = bits.uint(5); return type === 31 ? 32 + bits.uint(6) : type; }
+function audioRate(bits) { const index = bits.uint(4); return index === 15 ? bits.uint(24) : SAMPLE_RATES[index]; }
+
+/** Program configuration declares every single, paired and LFE channel. */
+function programChannels(bits, start, sampleRate) {
+  bits.uint(4); bits.uint(2);
+  if (SAMPLE_RATES[bits.uint(4)] !== sampleRate) throw new Error("AAC program sample rate differs from its decoder declaration.");
+  const front = bits.uint(4), side = bits.uint(4), back = bits.uint(4), lfe = bits.uint(2),
+    associated = bits.uint(3), coupled = bits.uint(4);
+  if (bits.uint(1)) bits.uint(4);
+  if (bits.uint(1)) bits.uint(4);
+  if (bits.uint(1)) bits.uint(3);
+  let channels = lfe;
+  for (let index = 0; index < front + side + back; index++) {
+    channels += bits.uint(1) ? 2 : 1;
+    bits.uint(4);
+  }
+  skip(bits, 4 * (lfe + associated));
+  skip(bits, 5 * coupled);
+  skip(bits, (8 - ((bits.at - start) % 8)) % 8);
+  skip(bits, bits.uint(8) * 8);
+  if (!channels) throw new Error("AAC program declares no output channels.");
+  return channels;
+}
+
+function latmValue(bits) { return bits.uint((bits.uint(2) + 1) * 8); }
+function skip(bits, count) { for (let left = count; left > 0; left -= 32) bits.uint(Math.min(left, 32)); }

package/services/media/container/matroska-packets.js

@@ -0,0 +1,207 @@
+import { ElementReader } from "./ebml-stream.js";
+import { readUint, readVint } from "./ebml-reader.js";
+import { readBlockHeader } from "./matroska-clusters.js";
+import { PacketIndex } from "./PacketIndex.js";
+import { PacketRecords } from "./PacketRecords.js";
+import { isMp3Codec } from "./mp3-packet-dependencies.js";
+import { followingPacketTime } from "./following-packet-time.js";
+
+const CLUSTER = 0x1f43b675;
+const LEVEL_ONE = new Set([CLUSTER, 0x1c53bb6b, 0x114d9b74, 0x1549a966, 0x1654ae6b, 0x1043a770, 0x1941a469, 0x1254c367]);
+
+/** Index frame addresses by reading structural headers, never frame bodies. */
+export async function readMatroskaPackets({ readRange, fileSize, portionBytes, layout, tracks, durationSeconds, interval, packetMemory, state = {} }) {
+  const reader = new ElementReader({ read: readRange, fileSize, portionBytes });
+  const declared = new Map(tracks.filter(track => ["video", "audio", "subtitle"].includes(track.type)).map(track => [track.trackNumber, track]));
+  if (!state.packets) {
+    state.packets = new Map([...declared.keys()].map(id => [id, new PacketRecords(packetMemory)]));
+    state.at = layout.firstClusterAt ?? layout.segmentEnd;
+  }
+  const packets = state.packets;
+  if (intervalCovered(declared, packets, interval)) return buildIndex(declared, packets, durationSeconds, false, interval, packetMemory);
+  let at = state.at;
+  while (at < layout.segmentEnd) {
+    const element = state.cluster?.element ?? await validHeader(reader, at, layout.segmentEnd);
+    if (element.id !== CLUSTER) {
+      if (element.end === null) throw new Error("An unknown-sized Matroska element is not a Cluster.");
+      at = element.end;
+      state.at = at;
+      continue;
+    }
+    const limit = element.end ?? layout.segmentEnd;
+    if (!state.cluster) state.cluster = { element, cursor: element.dataOffset, clusterTicks: null };
+    let { cursor, clusterTicks } = state.cluster;
+    while (cursor < limit) {
+      const child = await validHeader(reader, cursor, limit);
+      if (element.end === null && LEVEL_ONE.has(child.id)) break;
+      if (child.end === null) throw new Error("Matroska Cluster child has unknown size.");
+      if (child.id === 0xe7) {
+        clusterTicks = readUint(await reader.bytes(child.dataOffset, child.size), 0, child.size);
+      } else if (child.id === 0xa3 || child.id === 0xa0) {
+        if (clusterTicks === null) throw new Error("Matroska block precedes its Cluster Timestamp.");
+        const block = child.id === 0xa3 ? { element: child, duration: null, referenced: false } : await blockGroup(reader, child);
+        if (block.element) {
+          const first = await reader.bytes(block.element.dataOffset, 1);
+          let trackWidth = 1;
+          while (trackWidth <= 8 && !(first[0] & (1 << (8 - trackWidth)))) trackWidth++;
+          if (trackWidth > 8 || trackWidth + 3 > block.element.size) throw new Error("Matroska block header is truncated.");
+          const head = await reader.bytes(block.element.dataOffset, trackWidth + 3);
+          const header = readBlockHeader(head, 0, head.length);
+          const track = header && declared.get(header.trackNumber);
+          if (!header) throw new Error("Matroska block header is truncated.");
+          if (!track) {
+            if (!tracks.some(track => track.trackNumber === header.trackNumber)) throw new Error("Matroska block names an undeclared media track.");
+            cursor = child.end;
+            state.cluster.cursor = cursor;
+            continue;
+          }
+          const ranges = await frameRanges(reader, block.element, header);
+          const duration = block.duration === null ? track.defaultDurationSeconds ?? 0 : block.duration * layout.secondsPerTick / ranges.length;
+          if (ranges.length > 1 && !(duration > 0)) throw new Error("Matroska laced frames need a declared or codec-derived duration.");
+          const pts = (clusterTicks + header.relativeTicks * (track.timestampScale ?? 1)) * layout.secondsPerTick - (track.codecDelaySeconds ?? 0);
+          const records = packets.get(header.trackNumber);
+          const previousLength = records.length;
+          try {
+          for (let frame = 0; frame < ranges.length; frame++) {
+            const padding = paddingForFrame(block.discardPaddingSeconds ?? 0, duration, ranges.length, frame);
+            records.push({ pts: pts + frame * duration, duration,
+              ...(track.type === "audio" && isMp3Codec(track.codecId)
+                ? { decodeFromIndex: records.length, decodeDependencyUnknown: true } : {}),
+              ...(padding ? { discardPaddingSeconds: padding } : {}),
+              keyframe: child.id === 0xa3 ? !!(header.flags & 0x80) : !block.referenced,
+              ranges: [ranges[frame]] });
+          }
+          } catch (error) {
+            records.length = previousLength;
+            throw error;
+          }
+        }
+      } else if (child.id === 0xaf) throw new Error("Matroska media blocks are encrypted.");
+      cursor = child.end;
+      state.cluster.cursor = cursor;
+      state.cluster.clusterTicks = clusterTicks;
+      if (intervalCovered(declared, packets, interval)) return buildIndex(declared, packets, durationSeconds, false, interval, packetMemory);
+    }
+    if (cursor <= at) throw new Error("Matroska packet walk did not advance.");
+    at = element.end ?? cursor;
+    state.at = at;
+    state.cluster = null;
+  }
+  return buildIndex(declared, packets, durationSeconds, true, undefined, packetMemory);
+}
+
+function paddingForFrame(seconds, duration, count, frame) {
+  if (!seconds || count === 1) return seconds;
+  const padding = Math.round(seconds * 1e9), frameTime = Math.round(duration * 1e9);
+  if (Math.abs(padding) > frameTime * count) throw new Error("Matroska DiscardPadding exceeds its laced block duration.");
+  const preceding = padding < 0 ? frame : count - frame - 1;
+  return Math.sign(padding) * Math.max(0, Math.min(frameTime, Math.abs(padding) - preceding * frameTime)) / 1e9;
+}
+
+function intervalCovered(declared, packets, interval) {
+  if (!interval || !Number.isFinite(interval.to)) return false;
+  const requested = [...declared].filter(([id, track]) => interval.trackIds
+    ? interval.trackIds.includes(id) : ["video", "audio"].includes(track.type));
+  return requested.length > 0 && requested.every(([id, track]) => {
+    const depth = track.type === "video" ? track.reorderDepth : 0;
+    if (!Number.isSafeInteger(depth) || depth < 0) return false;
+    const stream = packets.get(id);
+    return stream.length > depth && stream.slice(-(depth + 1)).every(packet => packet.pts >= interval.to);
+  });
+}
+
+function buildIndex(declared, packets, durationSeconds, complete, interval, packetMemory) {
+  const index = new PacketIndex();
+  for (const [id, track] of declared) {
+    index.declareTrack(id, { type: track.type, codecId: track.codecId, codecRanges: track.codecRanges ?? [], prerollSeconds: track.seekPrerollSeconds ?? 0, reorderDepth: track.reorderDepth ?? 0 });
+    const stream = packets.get(id);
+    let needsFollowing = false;
+    for (let position = 0; position < stream.length; position++) {
+      if (stream.durationAt(position) === 0 || stream.derivedDurationAt(position)) { needsFollowing = true; break; }
+    }
+    if (needsFollowing) {
+      const endFor = followingPacketTime(stream, complete ? durationSeconds : null, packetMemory);
+      try { for (let position = 0; position < stream.length; position++) {
+        if (stream.durationAt(position) !== 0 && !stream.derivedDurationAt(position)) continue;
+        const pts = stream.ptsAt(position), end = endFor(pts);
+        stream.setDuration(position, Number.isFinite(end) && end > pts ? end - pts : 0, true);
+      } } finally { endFor.dispose(); }
+    }
+    index.sharePackets(id, stream);
+    if (complete) index.complete(id);
+    else if (interval.trackIds ? interval.trackIds.includes(id) : ["video", "audio"].includes(track.type)) {
+      index.coverThrough(id, interval.to);
+    }
+  }
+  return index;
+}
+
+async function validHeader(reader, at, limit) {
+  const element = await reader.header(at, limit);
+  if (!element || (element.end !== null && element.end > limit)) throw new Error("Matroska element exceeds its parent.");
+  return element;
+}
+
+async function blockGroup(reader, parent) {
+  const result = { element: null, duration: null, referenced: false };
+  for (let at = parent.dataOffset; at < parent.end;) {
+    const child = await validHeader(reader, at, parent.end);
+    if (child.end === null) throw new Error("Matroska BlockGroup child has unknown size.");
+    if (child.id === 0xa1) {
+      if (result.element) throw new Error("Matroska BlockGroup declares multiple Blocks.");
+      result.element = child;
+    }
+    if (child.id === 0x9b) result.duration = readUint(await reader.bytes(child.dataOffset, child.size), 0, child.size);
+    if (child.id === 0x75a2) {
+      if (child.size < 1 || child.size > 8) throw new Error("Matroska DiscardPadding has an invalid integer size.");
+      const bytes = await reader.bytes(child.dataOffset, child.size);
+      const signed = Buffer.alloc(8, bytes[0] & 128 ? 255 : 0);
+      bytes.copy(signed, 8 - bytes.length);
+      const nanoseconds = Number(signed.readBigInt64BE());
+      if (!Number.isSafeInteger(nanoseconds)) throw new Error("Matroska DiscardPadding exceeds its exact time range.");
+      result.discardPaddingSeconds = nanoseconds / 1e9;
+    }
+    if (child.id === 0xfb) result.referenced = true;
+    if (child.id === 0xa4) throw new Error("Matroska packet changes CodecState; its packet configuration must be indexed.");
+    at = child.end;
+  }
+  return result;
+}
+
+/** Decode all lacing forms without copying a frame to inspect its length. */
+async function frameRanges(reader, element, header) {
+  let at = element.dataOffset + header.dataOffset;
+  const lacing = header.flags & 6;
+  if (!lacing) return [[at, element.end - 1]];
+  const count = (await reader.bytes(at++, 1))[0] + 1;
+  const sizes = [];
+  if (lacing === 2) {
+    for (let frame = 0; frame < count - 1; frame++) {
+      let size = 0, byte;
+      do {
+        if (at >= element.end) throw new Error("Matroska Xiph lace is truncated.");
+        byte = (await reader.bytes(at++, 1))[0];
+        size += byte;
+      } while (byte === 255);
+      sizes.push(size);
+    }
+  } else if (lacing === 6) {
+    for (let frame = 0; frame < count - 1; frame++) {
+      const bytes = await reader.bytes(at, Math.min(8, element.end - at));
+      const size = readVint(bytes, 0, false);
+      if (!size || size.value === null) throw new Error("Matroska EBML lace is truncated.");
+      at += size.length;
+      sizes.push(frame === 0 ? Number(size.value) : sizes.at(-1) + Number(size.value) - (2 ** (7 * size.length - 1) - 1));
+    }
+  } else {
+    if ((element.end - at) % count !== 0) throw new Error("Matroska fixed lace does not divide its payload.");
+    for (let frame = 0; frame < count - 1; frame++) sizes.push((element.end - at) / count);
+  }
+  sizes.push(element.end - at - sizes.reduce((sum, size) => sum + size, 0));
+  return sizes.map(size => {
+    if (!Number.isSafeInteger(size) || size <= 0 || at + size > element.end) throw new Error("Matroska lace exceeds its frame data.");
+    const range = [at, at + size - 1];
+    at += size;
+    return range;
+  });
+}

package/services/media/container/memory-unavailable.js

@@ -0,0 +1,8 @@
+/** A resource shortage is pending work, not evidence of damaged media. */
+export class IndexMemoryUnavailable extends Error {
+  constructor(bytes) {
+    super(`Packet index requires ${bytes} additional allocation bytes.`);
+    this.name = "IndexMemoryUnavailable";
+    this.bytes = bytes;
+  }
+}

package/services/media/container/mp3-packet-dependencies.js

@@ -0,0 +1,41 @@
+import { mpegAudioFrame } from "./mpeg-audio-frame.js";
+
+export function isMp3Codec(codecId) { return ["mp3", "A_MPEG/L3", ".mp3"].includes(codecId); }
+
+/** Inspect frame headers and side information, never their compressed bodies. */
+export async function mp3PacketFacts(packet, readRange) {
+  const size = packet.ranges.reduce((sum, [start, end]) => sum + end - start + 1, 0);
+  let at = 0, capacity = 0, required = 0;
+  while (at < size) {
+    const header = await prefix(packet.ranges, at, 4, readRange);
+    const frame = mpegAudioFrame(header);
+    if (frame.codecId !== "mp3" || at + frame.size > size) throw new Error("MP3 packet frame addresses are inconsistent.");
+    const mpeg1 = ((header[1] >> 3) & 3) === 3, mono = header[3] >> 6 === 3;
+    const headerBytes = 4 + ((header[1] & 1) ? 0 : 2);
+    const sideBytes = mpeg1 ? mono ? 17 : 32 : mono ? 9 : 17;
+    if (frame.size < headerBytes + sideBytes) throw new Error("MP3 frame is smaller than its side information.");
+    const bytes = await prefix(packet.ranges, at + headerBytes, sideBytes, readRange);
+    const before = mpeg1 ? (bytes[0] << 1) | (bytes[1] >> 7) : bytes[0];
+    required = Math.max(required, before - capacity);
+    capacity += frame.size - headerBytes - sideBytes;
+    at += frame.size;
+  }
+  return { required, capacity };
+}
+
+async function prefix(ranges, offset, length, readRange) {
+  const bytes = Buffer.allocUnsafeSlow(length);
+  let copied = 0;
+  for (const [start, end] of ranges) {
+    const size = end - start + 1;
+    if (offset >= size) { offset -= size; continue; }
+    const wanted = Math.min(length - copied, size - offset);
+    const value = await readRange(start + offset, start + offset + wanted - 1);
+    if (!value || value.length !== wanted) throw new Error("MP3 header read is incomplete.");
+    bytes.set(value, copied);
+    copied += wanted;
+    if (copied === length) return bytes;
+    offset = 0;
+  }
+  throw new Error("MP3 packet side information exceeds its byte ranges.");
+}

package/services/media/container/mp4-fragments.js

@@ -0,0 +1,148 @@
+import { PacketIndex } from "./PacketIndex.js";
+import { PacketRecords } from "./PacketRecords.js";
+import { RetainedBytes } from "./RetainedBytes.js";
+import { mpegAudioFrame } from "./mpeg-audio-frame.js";
+import { isMp3Codec } from "./mp3-packet-dependencies.js";
+
+/** Fragment sample tables retain exact payload addresses and declared clocks. */
+export async function readMp4Fragments({ readRange, fileSize, tracks, memory, state, firstTrackIds = null }) {
+  if (!state.frames) {
+    state.frames = new Map(tracks.map(track => [track.id, new PacketRecords(memory)]));
+    state.clocks = new Map();
+    state.at = 0;
+    state.media = [];
+  }
+  while (state.at < fileSize) {
+    const at = state.at;
+    if (fileSize - at < 8) throw new Error("MP4 ends inside a fragment box header.");
+    const header = await readRange(at, at + 7);
+    const type = header.toString("latin1", 4, 8);
+    const width = header.readUInt32BE() === 1 ? 16 : 8;
+    const size = width === 16 ? Number((await readRange(at + 8, at + 15)).readBigUInt64BE()) :
+      header.readUInt32BE() || fileSize - at;
+    if (!Number.isSafeInteger(size) || size < width || size > fileSize - at) throw new Error("MP4 fragment box exceeds the file.");
+    if (type === "mdat") state.media.push([at + width, at + size]);
+    if (type === "moof") {
+      const allocation = new RetainedBytes(memory);
+      const lengths = new Map([...state.frames].map(([id, frames]) => [id, frames.length]));
+      const clocks = new Map(state.clocks);
+      try {
+        const bytes = await allocation.read(size, () => readRange(at, at + size - 1));
+        let precedingEnd = at;
+        const fragments = children(bytes, width, bytes.length, "traf");
+        if (!fragments.length) throw new Error("MP4 fragment has no track runs.");
+        for (const traf of fragments) {
+          const tfhd = child(bytes, traf.dataOffset, traf.end, "tfhd");
+          if (!tfhd || tfhd.dataOffset + 8 > tfhd.end) throw new Error("MP4 fragment has no complete track header.");
+          const flags = bytes.readUIntBE(tfhd.dataOffset + 1, 3);
+          const id = bytes.readUInt32BE(tfhd.dataOffset + 4);
+          const track = tracks.find(track => track.id === id);
+          if (!track) throw new Error("MP4 fragment names an undeclared track.");
+          let cursor = tfhd.dataOffset + 8;
+          const take = width => {
+            if (cursor + width > tfhd.end) throw new Error("MP4 fragment defaults are truncated.");
+            const value = width === 8 ? Number(bytes.readBigUInt64BE(cursor)) : bytes.readUInt32BE(cursor);
+            cursor += width;
+            if (!Number.isSafeInteger(value)) throw new Error("MP4 fragment default exceeds its integer range.");
+            return value;
+          };
+          const base = flags & 1 ? take(8) : flags & 0x20000 ? at : precedingEnd;
+          const description = flags & 2 ? take(4) : track.description;
+          if (description !== 1) throw new Error("MP4 fragment changes its sample description.");
+          const defaultDuration = flags & 8 ? take(4) : track.duration;
+          const defaultSize = flags & 16 ? take(4) : track.size;
+          const defaultFlags = flags & 32 ? take(4) : track.flags;
+          if (cursor !== tfhd.end) throw new Error("MP4 fragment defaults contain undeclared fields.");
+          const tfdt = child(bytes, traf.dataOffset, traf.end, "tfdt");
+          let decode = state.clocks.get(id) ?? 0;
+          if (tfdt) {
+            const wide = bytes[tfdt.dataOffset] === 1;
+            if (bytes[tfdt.dataOffset] > 1 || tfdt.dataOffset + (wide ? 12 : 8) > tfdt.end) throw new Error("MP4 fragment decode clock is truncated.");
+            decode = wide ? Number(bytes.readBigUInt64BE(tfdt.dataOffset + 4)) : bytes.readUInt32BE(tfdt.dataOffset + 4);
+            if (!Number.isSafeInteger(decode)) throw new Error("MP4 fragment decode clock exceeds its integer range.");
+          }
+          let address = base;
+          for (const trun of children(bytes, traf.dataOffset, traf.end, "trun")) {
+            if (trun.dataOffset + 8 > trun.end || bytes[trun.dataOffset] > 1) throw new Error("MP4 fragment run header is invalid.");
+            const runFlags = bytes.readUIntBE(trun.dataOffset + 1, 3);
+            const count = bytes.readUInt32BE(trun.dataOffset + 4);
+            let field = trun.dataOffset + 8;
+            const read = signed => {
+              if (field + 4 > trun.end) throw new Error("MP4 fragment sample field is truncated.");
+              const value = signed ? bytes.readInt32BE(field) : bytes.readUInt32BE(field);
+              field += 4;
+              return value;
+            };
+            if (runFlags & 1) address = base + read(true);
+            const firstFlags = runFlags & 4 ? read(false) : defaultFlags;
+            for (let sample = 0; sample < count; sample++) {
+              const duration = runFlags & 0x100 ? read(false) : defaultDuration;
+              const size = runFlags & 0x200 ? read(false) : defaultSize;
+              const flags = runFlags & 0x400 ? read(false) : sample === 0 ? firstFlags : defaultFlags;
+              const composition = runFlags & 0x800 ? read(bytes[trun.dataOffset] === 1) : 0;
+              if (!(duration > 0) || !(size > 0) || !Number.isSafeInteger(address) || address < 0 ||
+                  address + size > fileSize || !Number.isSafeInteger(decode + duration)) throw new Error("MP4 fragment sample timing or address is invalid.");
+              if (track.track.codecId === "mpeg_audio") {
+                if (size < 4) throw new Error("MP4 MPEG audio first sample header is truncated.");
+                const facts = mpegAudioFrame(await readRange(address, address + 3));
+                track.track.codecId = facts.codecId;
+                track.track.channels = facts.channels;
+                track.track.samplingFrequency = facts.sampleRate;
+              }
+              state.frames.get(id).push({ pts: (decode + composition) / track.scale + track.shift,
+                dts: decode / track.scale + track.shift, duration: duration / track.scale,
+                ...(isMp3Codec(track.track.codecId) ? { decodeFromIndex: state.frames.get(id).length, decodeDependencyUnknown: true } : {}),
+                keyframe: !(flags & 0x10000), ranges: [[address, address + size - 1]] });
+              decode += duration;
+              address += size;
+            }
+            if (field !== trun.end) throw new Error("MP4 fragment sample count differs from its run size.");
+          }
+          state.clocks.set(id, decode);
+          precedingEnd = address;
+        }
+      } catch (error) {
+        for (const [id, length] of lengths) state.frames.get(id).length = length;
+        state.clocks = clocks;
+        throw error;
+      } finally { allocation.dispose(); }
+    }
+    state.at += size;
+    if (firstTrackIds?.every(id => state.frames.get(id)?.length > 0)) return null;
+  }
+  const index = new PacketIndex({ packetMemory: memory });
+  for (const track of tracks) {
+    const frames = state.frames.get(track.id);
+    for (const packet of frames) for (const [start, end] of packet.ranges) {
+      if (!state.media.some(([from, to]) => from <= start && end < to)) throw new Error("MP4 fragment sample is outside its media data boxes.");
+    }
+    index.declareTrack(track.id, { type: track.track.type, codecId: track.track.codecId,
+      prerollSeconds: track.track.seekPrerollSeconds ?? 0, reorderDepth: track.track.reorderDepth ?? 0 });
+    index.sharePackets(track.id, frames);
+    index.complete(track.id);
+  }
+  return index;
+}
+
+function children(bytes, start, end, wanted) {
+  const found = [];
+  for (let at = start; at < end;) {
+    if (end - at < 8) throw new Error("MP4 fragment child header is truncated.");
+    const stated = bytes.readUInt32BE(at);
+    const width = stated === 1 ? 16 : 8;
+    if (end - at < width) throw new Error("MP4 fragment extended child header is truncated.");
+    const size = stated === 1 ? Number(bytes.readBigUInt64BE(at + 8)) : stated || end - at;
+    if (!Number.isSafeInteger(size) || size < width || size > end - at) {
+      throw new Error("MP4 fragment child exceeds its parent.");
+    }
+    if (bytes.toString("latin1", at + 4, at + 8) === wanted) found.push({ dataOffset: at + width, end: at + size });
+    at += size;
+  }
+  return found;
+}
+
+function child(bytes, start, end, wanted) {
+  const found = children(bytes, start, end, wanted);
+  if (found.length > 1) throw new Error(`MP4 fragment repeats ${wanted}.`);
+  return found[0] ?? null;
+}

package/services/media/container/mpeg-audio-frame.js

@@ -0,0 +1,19 @@
+export function mpegAudioFrame(bytes) {
+  if (bytes[0] !== 0xff || (bytes[1] & 0xe0) !== 0xe0) throw new Error("MPEG audio lost frame synchronization.");
+  const version = (bytes[1] >> 3) & 3, layer = (bytes[1] >> 1) & 3;
+  const rateIndex = bytes[2] >> 4, sampleIndex = (bytes[2] >> 2) & 3;
+  if (version === 1 || !layer || !rateIndex || rateIndex === 15 || sampleIndex === 3) throw new Error("MPEG audio frame parameters are invalid.");
+  const mpeg1 = version === 3;
+  const rates = mpeg1 ? layer === 3 ? [0, 32, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 448] :
+    layer === 2 ? [0, 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384] :
+      [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320] :
+    layer === 3 ? [0, 32, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256] :
+      [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160];
+  const sampleRate = [44100, 48000, 32000][sampleIndex] / (mpeg1 ? 1 : version === 2 ? 2 : 4);
+  const bitrate = rates[rateIndex] * 1000, padding = (bytes[2] >> 1) & 1;
+  const samples = layer === 3 ? 384 : layer === 1 && !mpeg1 ? 576 : 1152;
+  const size = layer === 3 ? (Math.floor(12 * bitrate / sampleRate) + padding) * 4 :
+    Math.floor((layer === 1 && !mpeg1 ? 72 : 144) * bitrate / sampleRate) + padding;
+  if (size < 4) throw new Error("MPEG audio frame is smaller than its header.");
+  return { size, sampleRate, codecId: `mp${4 - layer}`, duration: samples / sampleRate, channels: bytes[3] >> 6 === 3 ? 1 : 2 };
+}

package/services/media/container/mpeg-audio-reservoir.js

@@ -0,0 +1,27 @@
+/** Layer III decoder input follows its declared main_data_begin byte references. */
+export class MpegAudioReservoir {
+  #history = [];
+
+  prepare(bytes, frameSize, frameIndex) {
+    const version = (bytes[1] >> 3) & 3, layer = (bytes[1] >> 1) & 3;
+    if (layer !== 1) return null;
+    if (version === 1) throw new Error("MPEG audio version is invalid.");
+    const mono = bytes[3] >> 6 === 3, mpeg1 = version === 3;
+    const header = 4 + ((bytes[1] & 1) ? 0 : 2);
+    const sideBytes = mpeg1 ? mono ? 17 : 32 : mono ? 9 : 17;
+    if (bytes.length < header + sideBytes || frameSize < header + sideBytes) throw new Error("MP3 side information is truncated.");
+    const required = mpeg1 ? (bytes[header] << 1) | (bytes[header + 1] >> 7) : bytes[header];
+    let available = 0, decodeFromIndex = frameIndex;
+    for (let at = this.#history.length - 1; at >= 0 && available < required; at--) {
+      available += this.#history[at].bytes;
+      decodeFromIndex = this.#history[at].index;
+    }
+    if (available < required) throw new Error("MP3 bit reservoir refers to bytes before the available source frames.");
+    const capacity = frameSize - header - sideBytes;
+    const history = capacity ? [...this.#history, { index: frameIndex, bytes: capacity }] : [...this.#history];
+    let total = history.reduce((sum, frame) => sum + frame.bytes, 0);
+    const maximum = mpeg1 ? 511 : 255;
+    while (history.length > 1 && total - history[0].bytes >= maximum) total -= history.shift().bytes;
+    return { decodeFromIndex, commit: () => { this.#history = history; } };
+  }
+}