@invintusmedia/tomp4 1.3.0 → 1.4.0

package/src/codecs/h264-transform.js

@@ -0,0 +1,268 @@
+/**
+ * H.264 Integer Transforms and Quantization
+ *
+ * Forward and inverse 4x4/8x8 integer DCT transforms,
+ * quantization, and dequantization as specified in H.264.
+ *
+ * Reference: ITU-T H.264, Section 8.5
+ *
+ * @module codecs/h264-transform
+ */
+
+import { levelScale4x4, quantMF4x4, scanOrder4x4 } from './h264-tables.js';
+
+// ══════════════════════════════════════════════════════════
+// 4x4 Inverse Integer Transform (Section 8.5.12.1)
+// ══════════════════════════════════════════════════════════
+
+/**
+ * Inverse 4x4 integer DCT.
+ * Input: 16-element array in raster order (after dequantization).
+ * Output: 16-element residual array in raster order.
+ */
+export function inverseDCT4x4(coeffs) {
+  const d = new Int32Array(16);
+  const r = new Int32Array(16);
+
+  // Copy input
+  for (let i = 0; i < 16; i++) d[i] = coeffs[i];
+
+  // Horizontal pass (rows)
+  for (let i = 0; i < 4; i++) {
+    const si = i * 4;
+    const e0 = d[si + 0] + d[si + 2];
+    const e1 = d[si + 0] - d[si + 2];
+    const e2 = (d[si + 1] >> 1) - d[si + 3];
+    const e3 = d[si + 1] + (d[si + 3] >> 1);
+
+    r[si + 0] = e0 + e3;
+    r[si + 1] = e1 + e2;
+    r[si + 2] = e1 - e2;
+    r[si + 3] = e0 - e3;
+  }
+
+  // Vertical pass (columns)
+  const out = new Int32Array(16);
+  for (let j = 0; j < 4; j++) {
+    const e0 = r[j] + r[8 + j];
+    const e1 = r[j] - r[8 + j];
+    const e2 = (r[4 + j] >> 1) - r[12 + j];
+    const e3 = r[4 + j] + (r[12 + j] >> 1);
+
+    out[j]      = (e0 + e3 + 32) >> 6;
+    out[4 + j]  = (e1 + e2 + 32) >> 6;
+    out[8 + j]  = (e1 - e2 + 32) >> 6;
+    out[12 + j] = (e0 - e3 + 32) >> 6;
+  }
+
+  return out;
+}
+
+// ══════════════════════════════════════════════════════════
+// 4x4 Forward Integer Transform (Section 8.5 inverse)
+// ══════════════════════════════════════════════════════════
+
+/**
+ * Forward 4x4 integer DCT (for encoder).
+ * Input: 16-element residual array in raster order.
+ * Output: 16-element coefficient array in raster order.
+ */
+export function forwardDCT4x4(residual) {
+  const d = new Int32Array(16);
+  const r = new Int32Array(16);
+
+  for (let i = 0; i < 16; i++) d[i] = residual[i];
+
+  // Horizontal pass (Cf * X)
+  for (let i = 0; i < 4; i++) {
+    const si = i * 4;
+    const p0 = d[si + 0] + d[si + 3];
+    const p1 = d[si + 1] + d[si + 2];
+    const p2 = d[si + 1] - d[si + 2];
+    const p3 = d[si + 0] - d[si + 3];
+
+    r[si + 0] = p0 + p1;
+    r[si + 1] = (p3 << 1) + p2;
+    r[si + 2] = p0 - p1;
+    r[si + 3] = p3 - (p2 << 1);
+  }
+
+  // Vertical pass (result * Cf^T)
+  const out = new Int32Array(16);
+  for (let j = 0; j < 4; j++) {
+    const p0 = r[j] + r[12 + j];
+    const p1 = r[4 + j] + r[8 + j];
+    const p2 = r[4 + j] - r[8 + j];
+    const p3 = r[j] - r[12 + j];
+
+    out[j]      = p0 + p1;
+    out[4 + j]  = (p3 << 1) + p2;
+    out[8 + j]  = p0 - p1;
+    out[12 + j] = p3 - (p2 << 1);
+  }
+
+  return out;
+}
+
+// ══════════════════════════════════════════════════════════
+// 4x4 Hadamard Transform (for DC coefficients of Intra16x16)
+// ══════════════════════════════════════════════════════════
+
+/**
+ * Forward 4x4 Hadamard transform for Intra16x16 luma DC coefficients.
+ * Input: 16 DC values (one per 4x4 block in the 16x16 macroblock).
+ * Output: 16 transformed values.
+ */
+export function forwardHadamard4x4(dc) {
+  const t = new Int32Array(16);
+  const out = new Int32Array(16);
+
+  // Horizontal
+  for (let i = 0; i < 4; i++) {
+    const s = i * 4;
+    const p0 = dc[s] + dc[s + 3];
+    const p1 = dc[s + 1] + dc[s + 2];
+    const p2 = dc[s + 1] - dc[s + 2];
+    const p3 = dc[s] - dc[s + 3];
+    t[s]     = p0 + p1;
+    t[s + 1] = p3 + p2;
+    t[s + 2] = p0 - p1;
+    t[s + 3] = p3 - p2;
+  }
+
+  // Vertical
+  for (let j = 0; j < 4; j++) {
+    const p0 = t[j] + t[12 + j];
+    const p1 = t[4 + j] + t[8 + j];
+    const p2 = t[4 + j] - t[8 + j];
+    const p3 = t[j] - t[12 + j];
+    out[j]      = (p0 + p1) >> 1;
+    out[4 + j]  = (p3 + p2) >> 1;
+    out[8 + j]  = (p0 - p1) >> 1;
+    out[12 + j] = (p3 - p2) >> 1;
+  }
+
+  return out;
+}
+
+/**
+ * Inverse 4x4 Hadamard transform for Intra16x16 luma DC.
+ */
+export function inverseHadamard4x4(dc) {
+  // Same as forward (Hadamard is its own inverse up to scaling)
+  const t = new Int32Array(16);
+  const out = new Int32Array(16);
+
+  for (let i = 0; i < 4; i++) {
+    const s = i * 4;
+    const p0 = dc[s] + dc[s + 3];
+    const p1 = dc[s + 1] + dc[s + 2];
+    const p2 = dc[s + 1] - dc[s + 2];
+    const p3 = dc[s] - dc[s + 3];
+    t[s]     = p0 + p1;
+    t[s + 1] = p3 + p2;
+    t[s + 2] = p0 - p1;
+    t[s + 3] = p3 - p2;
+  }
+
+  for (let j = 0; j < 4; j++) {
+    const p0 = t[j] + t[12 + j];
+    const p1 = t[4 + j] + t[8 + j];
+    const p2 = t[4 + j] - t[8 + j];
+    const p3 = t[j] - t[12 + j];
+    out[j]      = p0 + p1;
+    out[4 + j]  = p3 + p2;
+    out[8 + j]  = p0 - p1;
+    out[12 + j] = p3 - p2;
+  }
+
+  return out;
+}
+
+// ══════════════════════════════════════════════════════════
+// 2x2 Hadamard Transform (for chroma DC)
+// ══════════════════════════════════════════════════════════
+
+export function forwardHadamard2x2(dc) {
+  return new Int32Array([
+    dc[0] + dc[1] + dc[2] + dc[3],
+    dc[0] - dc[1] + dc[2] - dc[3],
+    dc[0] + dc[1] - dc[2] - dc[3],
+    dc[0] - dc[1] - dc[2] + dc[3],
+  ]);
+}
+
+export function inverseHadamard2x2(dc) {
+  // Same structure, no scaling needed for 2x2
+  return forwardHadamard2x2(dc);
+}
+
+// ══════════════════════════════════════════════════════════
+// Inverse Quantization (Dequantization)
+// Section 8.5.12.1
+// ══════════════════════════════════════════════════════════
+
+/**
+ * Dequantize a 4x4 block of transform coefficients.
+ * @param {Int32Array} coeffs - 16 coefficients in scan order
+ * @param {number} qp - Quantization parameter (0-51)
+ * @param {boolean} isIntra - Whether the macroblock is intra
+ * @returns {Int32Array} Dequantized coefficients in raster order
+ */
+export function dequantize4x4(coeffs, qp, isIntra) {
+  const qpMod6 = qp % 6;
+  const qpDiv6 = Math.floor(qp / 6);
+  const scale = levelScale4x4[qpMod6];
+  const out = new Int32Array(16);
+
+  for (let i = 0; i < 16; i++) {
+    const pos = scanOrder4x4[i];
+    if (qpDiv6 >= 4) {
+      out[pos] = (coeffs[i] * scale[i]) << (qpDiv6 - 4);
+    } else {
+      out[pos] = (coeffs[i] * scale[i] + (1 << (3 - qpDiv6))) >> (4 - qpDiv6);
+    }
+  }
+
+  return out;
+}
+
+// ══════════════════════════════════════════════════════════
+// Forward Quantization (for encoder)
+// ══════════════════════════════════════════════════════════
+
+/**
+ * Quantize a 4x4 block of transform coefficients.
+ * @param {Int32Array} coeffs - 16 coefficients in raster order
+ * @param {number} qp - Quantization parameter (0-51)
+ * @returns {Int32Array} Quantized coefficients in scan order
+ */
+export function quantize4x4(coeffs, qp) {
+  const qpMod6 = qp % 6;
+  const qpDiv6 = Math.floor(qp / 6);
+  const mf = quantMF4x4[qpMod6];
+  const qBits = 15 + qpDiv6;
+  const offset = (1 << qBits) / 3; // intra offset = 1/3
+  const out = new Int32Array(16);
+
+  for (let i = 0; i < 16; i++) {
+    const pos = scanOrder4x4[i];
+    const sign = coeffs[pos] < 0 ? -1 : 1;
+    const absVal = Math.abs(coeffs[pos]);
+    out[i] = sign * ((absVal * mf[i] + offset) >> qBits);
+  }
+
+  return out;
+}
+
+// ══════════════════════════════════════════════════════════
+// Clipping utility
+// ══════════════════════════════════════════════════════════
+
+export function clip(val, min, max) {
+  return val < min ? min : val > max ? max : val;
+}
+
+export function clip255(val) {
+  return val < 0 ? 0 : val > 255 ? 255 : val;
+}

package/src/codecs/smart-render.js

@@ -0,0 +1,169 @@
+/**
+ * Smart Rendering
+ *
+ * Re-encodes the boundary GOP of an HLS segment to produce a
+ * frame-accurate cut point. Decodes preroll frames, re-encodes
+ * the target frame as a new keyframe, and re-encodes subsequent
+ * frames until the next original keyframe.
+ *
+ * @module codecs/smart-render
+ */
+
+import { H264Decoder, YUVFrame } from './h264-decoder.js';
+import { H264Encoder } from './h264-encoder.js';
+import { TSParser, getCodecInfo } from '../parsers/mpegts.js';
+
+/**
+ * Smart-render a TS segment to start at a precise frame.
+ *
+ * Takes a TS segment and a target start time (relative to segment start).
+ * Returns an array of NAL units where:
+ * - Frames before targetTime are removed
+ * - The frame at targetTime is re-encoded as an IDR keyframe
+ * - Frames between targetTime and next original keyframe are re-encoded as I-frames
+ * - Frames after the next original keyframe use original compressed data
+ *
+ * @param {TSParser} parser - Parsed TS segment
+ * @param {number} targetStartTime - Start time in seconds (relative to segment)
+ * @param {object} [options]
+ * @param {number} [options.endTime] - End time in seconds (relative to segment)
+ * @param {number} [options.qp=20] - Encoding quality (lower = better, 0-51)
+ * @returns {object} { videoAUs, audioAUs, actualStartTime }
+ */
+export function smartRender(parser, targetStartTime, options = {}) {
+  const { endTime = Infinity, qp = 20 } = options;
+  const PTS = 90000;
+  const targetPts = targetStartTime * PTS;
+  const endPts = endTime * PTS;
+
+  const videoAUs = parser.videoAccessUnits;
+  const audioAUs = parser.audioAccessUnits;
+
+  if (videoAUs.length === 0) {
+    return { videoAUs: [], audioAUs: [], actualStartTime: targetStartTime };
+  }
+
+  // Find the keyframe at or before targetTime
+  let keyframeIdx = 0;
+  for (let i = 0; i < videoAUs.length; i++) {
+    if (videoAUs[i].pts > targetPts) break;
+    if (_isKeyframe(videoAUs[i])) keyframeIdx = i;
+  }
+
+  // Find the target frame (first frame at or after targetTime)
+  let targetIdx = keyframeIdx;
+  for (let i = keyframeIdx; i < videoAUs.length; i++) {
+    if (videoAUs[i].pts >= targetPts) { targetIdx = i; break; }
+  }
+
+  // Find the next keyframe after targetIdx
+  let nextKeyframeIdx = videoAUs.length;
+  for (let i = targetIdx + 1; i < videoAUs.length; i++) {
+    if (_isKeyframe(videoAUs[i])) { nextKeyframeIdx = i; break; }
+  }
+
+  // Find end frame
+  let endIdx = videoAUs.length;
+  for (let i = 0; i < videoAUs.length; i++) {
+    if (videoAUs[i].pts >= endPts) { endIdx = i; break; }
+  }
+
+  // If target is already a keyframe, no smart rendering needed
+  if (targetIdx === keyframeIdx) {
+    const clippedVideo = videoAUs.slice(targetIdx, endIdx);
+    const startPts = clippedVideo.length > 0 ? clippedVideo[0].pts : 0;
+    const clippedAudio = audioAUs.filter(au => au.pts >= startPts && au.pts < (endIdx < videoAUs.length ? videoAUs[endIdx].pts : Infinity));
+    return {
+      videoAUs: clippedVideo,
+      audioAUs: clippedAudio,
+      actualStartTime: startPts / PTS,
+    };
+  }
+
+  // ── Smart rendering: decode preroll, re-encode boundary ──
+
+  // Step 1: Decode preroll frames to get pixel data at targetIdx
+  const decoder = new H264Decoder();
+  let targetFrame = null;
+
+  for (let i = keyframeIdx; i <= targetIdx; i++) {
+    const frame = decoder.decodeAccessUnit(videoAUs[i].nalUnits);
+    if (frame && i === targetIdx) targetFrame = frame;
+  }
+
+  if (!targetFrame) {
+    // Fallback: couldn't decode, start at keyframe instead
+    const clippedVideo = videoAUs.slice(keyframeIdx, endIdx);
+    const startPts = clippedVideo[0].pts;
+    return {
+      videoAUs: clippedVideo,
+      audioAUs: audioAUs.filter(au => au.pts >= startPts),
+      actualStartTime: startPts / PTS,
+    };
+  }
+
+  // Step 2: Re-encode target frame as IDR
+  const encoder = new H264Encoder();
+  const encodedNals = encoder.encode(
+    targetFrame.Y, targetFrame.U, targetFrame.V,
+    targetFrame.width, targetFrame.height, qp
+  );
+
+  // Step 3: Build output access units
+  const outputVideo = [];
+  const targetPtsActual = videoAUs[targetIdx].pts;
+  const targetDts = videoAUs[targetIdx].dts;
+
+  // First AU: the re-encoded IDR frame (with new SPS/PPS)
+  outputVideo.push({
+    nalUnits: encodedNals, // [SPS, PPS, IDR]
+    pts: targetPtsActual,
+    dts: targetDts,
+    _smartRendered: true,
+  });
+
+  // Step 4: Re-encode frames between target and next keyframe as I-frames
+  for (let i = targetIdx + 1; i < Math.min(nextKeyframeIdx, endIdx); i++) {
+    // Decode this frame
+    const frame = decoder.decodeAccessUnit(videoAUs[i].nalUnits);
+    if (frame) {
+      const frameNals = encoder.encode(frame.Y, frame.U, frame.V,
+        frame.width, frame.height, qp);
+      // Use only the IDR NAL (skip SPS/PPS for subsequent frames)
+      const idrOnly = frameNals.filter(n => (n[0] & 0x1F) === 5);
+      outputVideo.push({
+        nalUnits: idrOnly,
+        pts: videoAUs[i].pts,
+        dts: videoAUs[i].dts,
+        _smartRendered: true,
+      });
+    }
+  }
+
+  // Step 5: Original compressed data from next keyframe onward
+  for (let i = nextKeyframeIdx; i < endIdx; i++) {
+    outputVideo.push(videoAUs[i]);
+  }
+
+  // Clip audio to match video range
+  const audioStartPts = targetPtsActual;
+  const audioEndPts = endIdx < videoAUs.length ? videoAUs[endIdx - 1].pts + PTS : Infinity;
+  const outputAudio = audioAUs.filter(au => au.pts >= audioStartPts && au.pts < audioEndPts);
+
+  return {
+    videoAUs: outputVideo,
+    audioAUs: outputAudio,
+    actualStartTime: targetPtsActual / PTS,
+    smartRenderedFrames: Math.min(nextKeyframeIdx, endIdx) - targetIdx,
+    originalFrames: Math.max(0, endIdx - nextKeyframeIdx),
+  };
+}
+
+function _isKeyframe(au) {
+  for (const nal of au.nalUnits) {
+    if ((nal[0] & 0x1F) === 5) return true; // IDR
+  }
+  return false;
+}
+
+export default smartRender;

package/src/hls-clip.js

@@ -23,6 +23,7 @@
 import { parseHls, isHlsUrl, parsePlaylistText, toAbsoluteUrl } from './hls.js';
 import { TSParser, getCodecInfo } from './parsers/mpegts.js';
 import { createInitSegment, createFragment } from './muxers/fmp4.js';
+import { smartRender } from './codecs/smart-render.js';
 
 // ── constants ─────────────────────────────────────────────
 
@@ -78,57 +79,85 @@ function remuxToFragment(parser, sequenceNumber, videoBaseTime, audioBaseTime, a
 }
 
 /**
- * Clip a parsed TS segment at the start (frame-accurate with preroll)
- * and/or at the end. Returns clipped access units + timing metadata.
+ * Clip a parsed TS segment at the start and/or end.
+ *
+ * Uses smart rendering when clipping at the start: re-encodes the
+ * boundary GOP so the segment starts with a new keyframe at the
+ * exact requested time. No preroll, no edit list, frame-accurate.
+ *
+ * @param {TSParser} parser - Parsed TS segment
+ * @param {number} [startTime] - Start time in seconds (relative to segment)
+ * @param {number} [endTime] - End time in seconds (relative to segment)
+ * @param {object} [options]
+ * @param {number} [options.qp=20] - Encoding quality for smart-rendered frames
  */
-function clipSegment(parser, startTime, endTime) {
+function clipSegment(parser, startTime, endTime, options = {}) {
+  const { qp = 20 } = options;
   const startPts = (startTime !== undefined ? startTime : 0) * PTS_PER_SECOND;
   const endPts = (endTime !== undefined ? endTime : Infinity) * PTS_PER_SECOND;
   const videoAUs = parser.videoAccessUnits;
   const audioAUs = parser.audioAccessUnits;
 
-  // Find keyframe at or before startTime
+  if (videoAUs.length === 0) return null;
+
+  // Check if startTime falls between keyframes (needs smart rendering)
   let keyframeIdx = 0;
   for (let i = 0; i < videoAUs.length; i++) {
     if (videoAUs[i].pts > startPts) break;
     if (isKeyframe(videoAUs[i])) keyframeIdx = i;
   }
 
-  // Find end index
-  let endIdx = videoAUs.length;
+  let targetIdx = keyframeIdx;
   for (let i = keyframeIdx; i < videoAUs.length; i++) {
-    if (videoAUs[i].pts >= endPts) { endIdx = i; break; }
+    if (videoAUs[i].pts >= startPts) { targetIdx = i; break; }
   }
 
-  const clippedVideo = videoAUs.slice(keyframeIdx, endIdx);
-  if (clippedVideo.length === 0) return null;
+  const needsSmartRender = startTime !== undefined && targetIdx > keyframeIdx;
+
+  let clippedVideo, clippedAudio, startOffset;
+
+  if (needsSmartRender) {
+    // Smart render: re-encode boundary GOP for frame-accurate start
+    const result = smartRender(parser, startTime, { endTime, qp });
+    clippedVideo = result.videoAUs;
+    startOffset = result.videoAUs.length > 0 ? result.videoAUs[0].pts : 0;
 
-  const keyframePts = clippedVideo[0].pts;
-  const prerollPts = Math.max(0, startPts - keyframePts);
+    // Clip audio to match smart-rendered video
+    const audioEnd = endPts < Infinity ? Math.min(endPts, videoAUs[videoAUs.length - 1].pts + PTS_PER_SECOND) : Infinity;
+    clippedAudio = audioAUs.filter(au => au.pts >= startOffset && au.pts < audioEnd);
+  } else {
+    // Start is at a keyframe — no smart rendering needed
+    let endIdx = videoAUs.length;
+    for (let i = keyframeIdx; i < videoAUs.length; i++) {
+      if (videoAUs[i].pts >= endPts) { endIdx = i; break; }
+    }
+
+    clippedVideo = videoAUs.slice(keyframeIdx, endIdx);
+    if (clippedVideo.length === 0) return null;
+    startOffset = clippedVideo[0].pts;
 
-  // Clip audio from keyframe (for A/V sync, matching the fix in ts-to-mp4.js)
-  const lastVideoPts = clippedVideo[clippedVideo.length - 1].pts;
-  const audioEndPts = Math.min(endPts, lastVideoPts + PTS_PER_SECOND);
-  const clippedAudio = audioAUs.filter(au => au.pts >= keyframePts && au.pts < audioEndPts);
+    const lastVideoPts = clippedVideo[clippedVideo.length - 1].pts;
+    const audioEndPts = Math.min(endPts, lastVideoPts + PTS_PER_SECOND);
+    clippedAudio = audioAUs.filter(au => au.pts >= startOffset && au.pts < audioEndPts);
+  }
+
+  if (clippedVideo.length === 0) return null;
 
   // Normalize timestamps to start at 0
-  const offset = keyframePts;
-  for (const au of clippedVideo) { au.pts -= offset; au.dts -= offset; }
-  for (const au of clippedAudio) { au.pts -= offset; }
+  for (const au of clippedVideo) { au.pts -= startOffset; au.dts -= startOffset; }
+  for (const au of clippedAudio) { au.pts -= startOffset; }
 
-  // Calculate durations
-  const videoDuration = clippedVideo.length > 1
+  // Duration from actual content
+  const duration = clippedVideo.length > 1
     ? clippedVideo[clippedVideo.length - 1].dts - clippedVideo[0].dts +
-      (clippedVideo[1].dts - clippedVideo[0].dts) // add one frame for last
+      (clippedVideo.length > 1 ? clippedVideo[1].dts - clippedVideo[0].dts : 3003)
     : 3003;
-  const playbackDuration = (videoDuration - prerollPts) / PTS_PER_SECOND;
 
   return {
     videoSamples: clippedVideo,
     audioSamples: clippedAudio,
-    prerollPts,
-    playbackDuration: Math.max(0, playbackDuration),
-    mediaDuration: videoDuration / PTS_PER_SECOND,
+    duration: duration / PTS_PER_SECOND,
+    smartRendered: needsSmartRender,
   };
 }
 
@@ -383,13 +412,13 @@ export async function clipHls(source, options = {}) {
     });
 
     clipSegments.push({
-      duration: firstClipped.playbackDuration,
+      duration: firstClipped.duration,
       data: firstFragment, // pre-clipped, in memory
       originalUrl: null,
       timelineOffset: 0,
       isBoundary: true,
     });
-    timelineOffset += firstClipped.mediaDuration;
+    timelineOffset += firstClipped.duration;
 
     // ── Middle segments (pass-through, remuxed on demand) ──
     for (let i = 1; i < overlapping.length - 1; i++) {
@@ -410,6 +439,7 @@ export async function clipHls(source, options = {}) {
       const lastRelEnd = endTime - lastSeg.startTime;
       const lastClipped = clipSegment(lastParser, undefined, lastRelEnd);
       if (lastClipped && lastClipped.videoSamples.length > 0) {
+        const lastDuration = lastClipped.duration;
         const lastSeqNum = overlapping.length;
         const lastVideoBaseTime = Math.round(timelineOffset * PTS_PER_SECOND);
         const lastAudioBaseTime = Math.round(timelineOffset * audioTimescale);
@@ -426,7 +456,7 @@ export async function clipHls(source, options = {}) {
         });
 
         clipSegments.push({
-          duration: lastClipped.playbackDuration,
+          duration: lastClipped.duration,
           data: lastFragment,
           originalUrl: null,
           timelineOffset,

package/src/index.js

@@ -342,7 +342,7 @@ toMp4.TSParser = TSParser;
 toMp4.RemoteMp4 = RemoteMp4;
 
 // Version (injected at build time for dist, read from package.json for ESM)
-toMp4.version = '1.3.0';
+toMp4.version = '1.4.0';
 
 // Export
 export {