@invintusmedia/tomp4 1.1.0 → 1.2.0

package/dist/tomp4.js

@@ -1,5 +1,5 @@
 /**
- * toMp4.js v1.1.0
+ * toMp4.js v1.2.0
  * Convert MPEG-TS and fMP4 to standard MP4
  * https://github.com/TVWIT/toMp4.js
  * MIT License
@@ -705,7 +705,7 @@
   toMp4.isMpegTs = isMpegTs;
   toMp4.isFmp4 = isFmp4;
   toMp4.isStandardMp4 = isStandardMp4;
-  toMp4.version = '1.1.0';
+  toMp4.version = '1.2.0';
 
   return toMp4;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invintusmedia/tomp4",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Convert MPEG-TS, fMP4, and HLS streams to MP4 with clipping support - pure JavaScript, zero dependencies",
   "main": "src/index.js",
   "module": "src/index.js",
@@ -20,7 +20,9 @@
   "scripts": {
     "build": "node build.js",
     "dev": "npx serve . -p 3000",
-    "test": "npm run test:clip && npm run test:mp4",
+    "test": "npm run test:hls-map && npm run test:thumbnail && npm run test:clip && npm run test:mp4",
+    "test:hls-map": "node tests/hls-map.test.js",
+    "test:thumbnail": "node tests/thumbnail.node.test.js",
     "test:clip": "node tests/clip.test.js",
     "test:mp4": "node tests/mp4-parser.test.js",
     "test:all": "npm run test",

package/src/fmp4/stitcher.js

@@ -47,12 +47,17 @@ function createBox(type, ...payloads) {
 // Fragment Parsing
 // ============================================
 
-function parseTfhd(tfhdData) {
+function parseTfhd(tfhdData, trexDefaults = {}) {
   const view = new DataView(tfhdData.buffer, tfhdData.byteOffset, tfhdData.byteLength);
   const flags = (tfhdData[9] << 16) | (tfhdData[10] << 8) | tfhdData[11];
   const trackId = view.getUint32(12);
   let offset = 16;
-  let baseDataOffset = 0, defaultSampleDuration = 0, defaultSampleSize = 0, defaultSampleFlags = 0;
+
+  // Start with trex defaults, override with tfhd values if present
+  let baseDataOffset = 0;
+  let defaultSampleDuration = trexDefaults.defaultSampleDuration || 0;
+  let defaultSampleSize = trexDefaults.defaultSampleSize || 0;
+  let defaultSampleFlags = trexDefaults.defaultSampleFlags || 0;
 
   if (flags & 0x1) { baseDataOffset = Number(view.getBigUint64(offset)); offset += 8; }
   if (flags & 0x2) offset += 4; // sample description index
@@ -63,6 +68,43 @@ function parseTfhd(tfhdData) {
   return { trackId, flags, baseDataOffset, defaultSampleDuration, defaultSampleSize, defaultSampleFlags };
 }
 
+/**
+ * Parse trex (Track Extends) box from mvex
+ * This contains default sample values for all fragments
+ */
+function parseTrex(trexData) {
+  const view = new DataView(trexData.buffer, trexData.byteOffset, trexData.byteLength);
+  // Skip box header (8) + version/flags (4)
+  const trackId = view.getUint32(12);
+  const defaultSampleDescriptionIndex = view.getUint32(16);
+  const defaultSampleDuration = view.getUint32(20);
+  const defaultSampleSize = view.getUint32(24);
+  const defaultSampleFlags = view.getUint32(28);
+
+  return { trackId, defaultSampleDescriptionIndex, defaultSampleDuration, defaultSampleSize, defaultSampleFlags };
+}
+
+/**
+ * Extract trex defaults from moov's mvex box
+ */
+function extractTrexDefaults(moovBox) {
+  const defaults = new Map(); // trackId -> { defaultSampleDuration, ... }
+  const moovChildren = parseChildBoxes(moovBox);
+  const mvex = findBox(moovChildren, 'mvex');
+
+  if (mvex) {
+    const mvexChildren = parseChildBoxes(mvex);
+    for (const child of mvexChildren) {
+      if (child.type === 'trex') {
+        const trex = parseTrex(child.data);
+        defaults.set(trex.trackId, trex);
+      }
+    }
+  }
+
+  return defaults;
+}
+
 function parseTfdt(tfdtData) {
   const view = new DataView(tfdtData.buffer, tfdtData.byteOffset, tfdtData.byteLength);
   const version = tfdtData[8];
@@ -433,6 +475,7 @@ export function stitchFmp4(segments, options = {}) {
   let ftyp = null;
   let moov = null;
   let originalTrackIds = [];
+  let trexDefaults = new Map(); // trackId -> default sample values from trex
 
   // Process init segment if provided separately
   if (initData) {
@@ -443,6 +486,7 @@ export function stitchFmp4(segments, options = {}) {
       throw new Error('stitchFmp4: Init segment missing ftyp or moov');
     }
     originalTrackIds = extractTrackIds(moov);
+    trexDefaults = extractTrexDefaults(moov);
   }
 
   // Process each segment
@@ -461,6 +505,7 @@ export function stitchFmp4(segments, options = {}) {
     if (!moov && segMoov) {
       moov = segMoov;
       originalTrackIds = extractTrackIds(moov);
+      trexDefaults = extractTrexDefaults(moov);
     }
 
     // Process fragment boxes (moof + mdat pairs)
@@ -492,7 +537,12 @@ export function stitchFmp4(segments, options = {}) {
             const tfdtBox = findBox(trafChildren, 'tfdt');
 
             if (tfhdBox && trunBox) {
-              const tfhd = parseTfhd(tfhdBox.data);
+              // Get trackId first to look up trex defaults
+              const tfhdView = new DataView(tfhdBox.data.buffer, tfhdBox.data.byteOffset, tfhdBox.data.byteLength);
+              const trackId = tfhdView.getUint32(12);
+              const trackTrexDefaults = trexDefaults.get(trackId) || {};
+
+              const tfhd = parseTfhd(tfhdBox.data, trackTrexDefaults);
               const { samples, dataOffset } = parseTrun(trunBox.data, tfhd);
 
               if (!tracks.has(tfhd.trackId)) {

package/src/hls.js

@@ -126,8 +126,10 @@ function parsePlaylistText(text, baseUrl) {
   const lines = text.split('\n').map(l => l.trim());
   const variants = [];
   const segments = [];
+  let initSegmentUrl = null;
   let currentDuration = 0;
   let runningTime = 0;
+  const isMaster = lines.some(l => l.startsWith('#EXT-X-STREAM-INF'));
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -151,6 +153,15 @@ function parsePlaylistText(text, baseUrl) {
       }
     }
 
+    // Parse CMAF init segment for fMP4 playlists
+    // Example: #EXT-X-MAP:URI="init.m4s"
+    if (line.startsWith('#EXT-X-MAP:')) {
+      const match = line.match(/URI="([^"]+)"/);
+      if (match?.[1]) {
+        initSegmentUrl = toAbsoluteUrl(match[1], baseUrl);
+      }
+    }
+
     // Parse segment duration
     if (line.startsWith('#EXTINF:')) {
       const match = line.match(/#EXTINF:([\d.]+)/);
@@ -160,7 +171,7 @@ function parsePlaylistText(text, baseUrl) {
     // Parse media playlist segments
     if (line && !line.startsWith('#')) {
       // It's a segment URL
-      if (!lines.some(l => l.startsWith('#EXT-X-STREAM-INF'))) {
+      if (!isMaster) {
         segments.push(new HlsSegment(
           toAbsoluteUrl(line, baseUrl),
           currentDuration,
@@ -172,7 +183,7 @@ function parsePlaylistText(text, baseUrl) {
     }
   }
 
-  return { variants, segments };
+  return { variants, segments, initSegmentUrl };
 }
 
 /**
@@ -194,7 +205,7 @@ async function parseHls(url, options = {}) {
   }
   
   const text = await response.text();
-  const { variants, segments } = parsePlaylistText(text, url);
+  const { variants, segments, initSegmentUrl } = parsePlaylistText(text, url);
 
   if (variants.length > 0) {
     // Master playlist
@@ -203,7 +214,9 @@ async function parseHls(url, options = {}) {
   } else if (segments.length > 0) {
     // Media playlist (no variants)
     log(`Found ${segments.length} segments`);
-    return new HlsStream(url, [], segments);
+    const stream = new HlsStream(url, [], segments);
+    stream.initSegmentUrl = initSegmentUrl;
+    return stream;
   } else {
     throw new Error('Invalid HLS playlist: no variants or segments found');
   }
@@ -237,6 +250,7 @@ async function downloadHls(source, options = {}) {
 
   // Get segments
   let segments = stream.segments;
+  let initSegmentUrl = stream.initSegmentUrl || null;
   
   // If master playlist, fetch the selected variant's media playlist
   if (stream.isMaster && stream.selected) {
@@ -249,8 +263,9 @@ async function downloadHls(source, options = {}) {
     }
     
     const mediaText = await mediaResponse.text();
-    const { segments: mediaSegments } = parsePlaylistText(mediaText, variant.url);
+    const { segments: mediaSegments, initSegmentUrl: mediaInit } = parsePlaylistText(mediaText, variant.url);
     segments = mediaSegments;
+    initSegmentUrl = mediaInit || null;
   }
 
   if (!segments || segments.length === 0) {
@@ -300,10 +315,26 @@ async function downloadHls(source, options = {}) {
     })
   );
 
+  // If CMAF/fMP4 playlist includes an init segment, prepend it so the combined
+  // buffer starts with ftyp+moov and conversion can succeed.
+  let initBytes = null;
+  if (initSegmentUrl) {
+    log('Downloading init segment...', { phase: 'download', percent: 0 });
+    const initResp = await fetch(initSegmentUrl);
+    if (!initResp.ok) {
+      throw new Error(`Init segment failed: ${initResp.status}`);
+    }
+    initBytes = new Uint8Array(await initResp.arrayBuffer());
+  }
+
   // Combine into single buffer
-  const totalSize = buffers.reduce((sum, buf) => sum + buf.length, 0);
+  const totalSize = buffers.reduce((sum, buf) => sum + buf.length, 0) + (initBytes ? initBytes.length : 0);
   const combined = new Uint8Array(totalSize);
   let offset = 0;
+  if (initBytes) {
+    combined.set(initBytes, offset);
+    offset += initBytes.length;
+  }
   for (const buf of buffers) {
     combined.set(buf, offset);
     offset += buf.length;
@@ -343,4 +374,3 @@ export {
   parsePlaylistText,
   toAbsoluteUrl
 };
-

package/src/index.js

@@ -40,6 +40,7 @@ import { MP4Muxer } from './muxers/mp4.js';
 import { TSParser } from './parsers/mpegts.js';
 import { MP4Parser } from './parsers/mp4.js';
 import { RemoteMp4 } from './remote/index.js';
+import { thumbnail, ImageResult } from './thumbnail.js';
 
 /**
  * Result object returned by toMp4()
@@ -320,6 +321,7 @@ toMp4.analyze = analyzeTsData;
 // Transcoding (browser-only, uses WebCodecs)
 toMp4.transcode = transcode;
 toMp4.isWebCodecsSupported = isWebCodecsSupported;
+toMp4.thumbnail = thumbnail;
 
 // Parsers
 toMp4.MP4Parser = MP4Parser;
@@ -329,7 +331,7 @@ toMp4.TSParser = TSParser;
 toMp4.RemoteMp4 = RemoteMp4;
 
 // Version (injected at build time for dist, read from package.json for ESM)
-toMp4.version = '1.1.0';
+toMp4.version = '1.2.0';
 
 // Export
 export {
@@ -353,6 +355,9 @@ export {
   // Transcoding (browser-only)
   transcode,
   isWebCodecsSupported,
+  // Thumbnails (browser-only)
+  thumbnail,
+  ImageResult,
   // Muxers
   TSMuxer,
   MP4Muxer,

package/src/thumbnail.js

@@ -0,0 +1,269 @@
+/**
+ * Thumbnail extraction (browser-only)
+ *
+ * This is intentionally implemented using `<video>` + `<canvas>` instead of
+ * container-level parsing, because decoding frames is the hard part:
+ * browsers already have hardware decoders and seeking.
+ *
+ * For HLS inputs, we rely on toMp4() to remux a tiny time range into an MP4 clip
+ * (downloads minimal segments). This also handles fMP4 EXT-X-MAP init segments
+ * now that HLS parsing supports it.
+ *
+ * Limitations:
+ * - Requires browser DOM APIs (document, HTMLVideoElement, canvas).
+ * - For cross-origin URLs, the server must send `Access-Control-Allow-Origin`
+ *   or the canvas will be tainted and pixel extraction will fail.
+ */
+
+import toMp4 from './index.js';
+
+export class ImageResult {
+  constructor(blob, filename = 'thumbnail.jpg') {
+    this.blob = blob;
+    this.filename = filename;
+    this._url = null;
+  }
+
+  toBlob() {
+    return this.blob;
+  }
+
+  toURL() {
+    if (!this._url) this._url = URL.createObjectURL(this.blob);
+    return this._url;
+  }
+
+  revokeURL() {
+    if (this._url) URL.revokeObjectURL(this._url);
+    this._url = null;
+  }
+
+  download(filename) {
+    const a = document.createElement('a');
+    a.href = this.toURL();
+    a.download = filename || this.filename;
+    a.click();
+  }
+}
+
+function isBrowser() {
+  return typeof document !== 'undefined' && typeof window !== 'undefined';
+}
+
+function requireBrowser() {
+  if (!isBrowser()) {
+    throw new Error('toMp4.thumbnail() is browser-only (requires document/canvas).');
+  }
+}
+
+function withTimeout(promise, timeoutMs, message) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error(message)), timeoutMs);
+    promise
+      .then(resolve)
+      .catch(reject)
+      .finally(() => clearTimeout(t));
+  });
+}
+
+async function waitOnce(target, eventName) {
+  return new Promise((resolve, reject) => {
+    const onOk = () => {
+      cleanup();
+      resolve();
+    };
+    const onErr = () => {
+      cleanup();
+      reject(new Error('Video failed to load'));
+    };
+    const cleanup = () => {
+      target.removeEventListener(eventName, onOk);
+      target.removeEventListener('error', onErr);
+    };
+    target.addEventListener(eventName, onOk, { once: true });
+    target.addEventListener('error', onErr, { once: true });
+  });
+}
+
+async function seek(video, timeSeconds) {
+  return new Promise((resolve) => {
+    const onSeeked = () => resolve();
+    video.addEventListener('seeked', onSeeked, { once: true });
+    try {
+      video.currentTime = Math.max(0, timeSeconds);
+    } catch {
+      resolve();
+    }
+  });
+}
+
+/**
+ * Extract a single frame as an image.
+ *
+ * @param {string|Uint8Array|ArrayBuffer|Blob|import('./hls.js').HlsStream|{init?:Uint8Array|ArrayBuffer, segments:(Uint8Array|ArrayBuffer)[]}} input
+ * @param {object} [options]
+ * @param {number} [options.time] - Time in seconds for the capture (default 0.15)
+ * @param {number} [options.maxWidth] - Resize output to this width (preserve aspect)
+ * @param {string} [options.mimeType] - 'image/jpeg' | 'image/webp' | 'image/png'
+ * @param {number} [options.quality] - 0..1 (jpeg/webp)
+ * @param {number} [options.timeoutMs] - Overall timeout (default 15000)
+ * @param {string} [options.hlsQuality] - 'lowest' | 'highest' (default 'lowest')
+ * @returns {Promise<ImageResult>}
+ */
+export async function thumbnail(input, options = {}) {
+  requireBrowser();
+
+  const {
+    time = 0.15,
+    maxWidth = 480,
+    mimeType = 'image/jpeg',
+    quality = 0.82,
+    timeoutMs = 15000,
+    hlsQuality = 'lowest',
+  } = options;
+
+  // If input is fragmented-only fMP4, allow caller to provide init+segments.
+  // This addresses the "no ftyp/moov" case: fragments alone are not decodable
+  // without codec init data.
+  let mp4Cleanup = null;
+  let mediaUrl = null;
+  let localSeek = time;
+
+  const isHlsLike =
+    typeof input === 'string' ? toMp4.isHlsUrl(input) : false;
+
+  const buildMp4Clip = async () => {
+    const clipEnd = time + 1.5;
+    const mp4 = await toMp4(input, {
+      startTime: time,
+      endTime: clipEnd,
+      quality: hlsQuality,
+      onProgress: () => {},
+    });
+    mp4Cleanup = () => mp4.revokeURL();
+    mediaUrl = mp4.toURL();
+    // The clip is normalized to start at 0
+    localSeek = 0.1;
+  };
+
+  const isSegmentsObject =
+    input &&
+    typeof input === 'object' &&
+    !ArrayBuffer.isView(input) &&
+    !(input instanceof ArrayBuffer) &&
+    !(input instanceof Blob) &&
+    !('masterUrl' in input) && // HlsStream
+    Array.isArray(input.segments);
+
+  if (isSegmentsObject) {
+    const init = input.init
+      ? (input.init instanceof ArrayBuffer ? new Uint8Array(input.init) : input.init)
+      : null;
+    const segs = input.segments.map((s) =>
+      s instanceof ArrayBuffer ? new Uint8Array(s) : s,
+    );
+    if (!init) {
+      // fMP4 fragments (moof/mdat) are not decodable without the init segment (ftyp/moov).
+      // This commonly comes from HLS playlists via EXT-X-MAP.
+      throw new Error('Fragments-only input requires an init segment (ftyp/moov). Provide `init` (e.g. EXT-X-MAP) along with `segments`.');
+    }
+    const mp4 = toMp4.stitchFmp4(segs, init ? { init } : undefined);
+    mp4Cleanup = () => mp4.revokeURL();
+    mediaUrl = mp4.toURL();
+    localSeek = time;
+  } else if (isHlsLike || (input && typeof input === 'object' && input.masterUrl && input.variants)) {
+    // HLS URL or HlsStream: make a tiny MP4 clip around the time.
+    await buildMp4Clip();
+  } else if (typeof input === 'string') {
+    // Direct MP4 URL
+    mediaUrl = input;
+    localSeek = time;
+  } else {
+    // Raw bytes/blob: remux to an MP4 clip and capture from that.
+    await buildMp4Clip();
+  }
+
+  const run = async () => {
+    const video = document.createElement('video');
+    video.muted = true;
+    video.playsInline = true;
+    video.preload = 'auto';
+    video.crossOrigin = 'anonymous';
+
+    const host = document.createElement('div');
+    host.style.position = 'fixed';
+    host.style.left = '-99999px';
+    host.style.top = '0';
+    host.style.width = '1px';
+    host.style.height = '1px';
+    host.style.overflow = 'hidden';
+    host.appendChild(video);
+    document.body.appendChild(host);
+
+    try {
+      video.src = mediaUrl;
+      await waitOnce(video, 'loadeddata');
+
+      try {
+        await video.play();
+        video.pause();
+      } catch {
+        // ignore autoplay restrictions; muted should pass in most browsers
+      }
+
+      const dur = Number.isFinite(video.duration) ? video.duration : 0;
+      const safeTime = dur > 0 ? Math.min(localSeek, Math.max(0, dur - 0.05)) : localSeek;
+      await seek(video, safeTime);
+
+      const vw = video.videoWidth || 0;
+      const vh = video.videoHeight || 0;
+      if (!vw || !vh) throw new Error('No video frame available');
+
+      const scale = Math.min(1, maxWidth / vw);
+      const outW = Math.max(1, Math.round(vw * scale));
+      const outH = Math.max(1, Math.round(vh * scale));
+
+      const canvas = document.createElement('canvas');
+      canvas.width = outW;
+      canvas.height = outH;
+      const ctx = canvas.getContext('2d');
+      if (!ctx) throw new Error('Canvas not supported');
+
+      ctx.drawImage(video, 0, 0, outW, outH);
+
+      const blob = await new Promise((resolve, reject) => {
+        try {
+          canvas.toBlob(
+            (b) => (b ? resolve(b) : reject(new Error('Failed to encode thumbnail'))),
+            mimeType,
+            quality,
+          );
+        } catch (err) {
+          reject(err);
+        }
+      });
+
+      return new ImageResult(blob, mimeType === 'image/png' ? 'thumbnail.png' : 'thumbnail.jpg');
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      if (msg.toLowerCase().includes('taint') || msg.toLowerCase().includes('security')) {
+        throw new Error('Canvas is tainted by cross-origin media. Ensure the server sets CORS headers (Access-Control-Allow-Origin).');
+      }
+      throw err;
+    } finally {
+      try {
+        video.pause();
+        video.removeAttribute('src');
+        video.load();
+      } catch {}
+      try {
+        host.remove();
+      } catch {}
+      try {
+        mp4Cleanup?.();
+      } catch {}
+    }
+  };
+
+  return await withTimeout(run(), timeoutMs, 'Thumbnail generation timed out');
+}