@invintusmedia/tomp4 1.0.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@invintusmedia/tomp4",
+  "version": "1.0.0",
+  "description": "Convert MPEG-TS and fMP4 streams to standard MP4 - pure JavaScript, zero dependencies",
+  "main": "dist/tomp4.js",
+  "module": "src/index.js",
+  "type": "module",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "dev": "npx serve . -p 3000",
+    "release": "npm run build && git add -A && git commit -m \"Build v$(node -p \"require('./package.json').version\")\" && git push",
+    "release:patch": "npm version patch --no-git-tag-version && npm run release",
+    "release:minor": "npm version minor --no-git-tag-version && npm run release",
+    "release:major": "npm version major --no-git-tag-version && npm run release",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TVWIT/toMp4.js.git"
+  },
+  "keywords": [
+    "mp4",
+    "mpeg-ts",
+    "mpegts",
+    "fmp4",
+    "video",
+    "converter",
+    "transmux",
+    "hls",
+    "streaming"
+  ],
+  "author": "Invintus Media",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/TVWIT/toMp4.js/issues"
+  },
+  "homepage": "https://tvwit.github.io/toMp4.js/"
+}
+

package/src/fmp4-to-mp4.js

@@ -0,0 +1,375 @@
+/**
+ * Fragmented MP4 to Standard MP4 Converter
+ * Pure JavaScript - no dependencies
+ */
+
+// ============================================
+// Box Utilities
+// ============================================
+function parseBoxes(data, offset = 0, end = data.byteLength) {
+  const boxes = [];
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  while (offset < end) {
+    if (offset + 8 > end) break;
+    const size = view.getUint32(offset);
+    const type = String.fromCharCode(data[offset+4], data[offset+5], data[offset+6], data[offset+7]);
+    if (size === 0 || size < 8) break;
+    boxes.push({ type, offset, size, data: data.subarray(offset, offset + size) });
+    offset += size;
+  }
+  return boxes;
+}
+
+function findBox(boxes, type) {
+  for (const box of boxes) if (box.type === type) return box;
+  return null;
+}
+
+function parseChildBoxes(box, headerSize = 8) {
+  return parseBoxes(box.data, headerSize, box.size);
+}
+
+function createBox(type, ...payloads) {
+  let size = 8;
+  for (const p of payloads) size += p.byteLength;
+  const result = new Uint8Array(size);
+  const view = new DataView(result.buffer);
+  view.setUint32(0, size);
+  result[4] = type.charCodeAt(0); result[5] = type.charCodeAt(1); result[6] = type.charCodeAt(2); result[7] = type.charCodeAt(3);
+  let offset = 8;
+  for (const p of payloads) { result.set(p, offset); offset += p.byteLength; }
+  return result;
+}
+
+// ============================================
+// trun/tfhd Parsing
+// ============================================
+function parseTrunWithOffset(trunData) {
+  const view = new DataView(trunData.buffer, trunData.byteOffset, trunData.byteLength);
+  const version = trunData[8];
+  const flags = (trunData[9] << 16) | (trunData[10] << 8) | trunData[11];
+  const sampleCount = view.getUint32(12);
+  let offset = 16, dataOffset = 0;
+  if (flags & 0x1) { dataOffset = view.getInt32(offset); offset += 4; }
+  if (flags & 0x4) offset += 4;
+  const samples = [];
+  for (let i = 0; i < sampleCount; i++) {
+    const sample = {};
+    if (flags & 0x100) { sample.duration = view.getUint32(offset); offset += 4; }
+    if (flags & 0x200) { sample.size = view.getUint32(offset); offset += 4; }
+    if (flags & 0x400) { sample.flags = view.getUint32(offset); offset += 4; }
+    if (flags & 0x800) { sample.compositionTimeOffset = version === 0 ? view.getUint32(offset) : view.getInt32(offset); offset += 4; }
+    samples.push(sample);
+  }
+  return { samples, dataOffset };
+}
+
+function parseTfhd(tfhdData) {
+  return new DataView(tfhdData.buffer, tfhdData.byteOffset, tfhdData.byteLength).getUint32(12);
+}
+
+// ============================================
+// Moov Rebuilding
+// ============================================
+function rebuildMvhd(mvhdBox, duration) {
+  const data = new Uint8Array(mvhdBox.data);
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const version = data[8];
+  const durationOffset = version === 0 ? 24 : 32;
+  if (version === 0) view.setUint32(durationOffset, duration);
+  else { view.setUint32(durationOffset, 0); view.setUint32(durationOffset + 4, duration); }
+  return data;
+}
+
+function rebuildTkhd(tkhdBox, trackInfo, maxDuration) {
+  const data = new Uint8Array(tkhdBox.data);
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const version = data[8];
+  let trackDuration = maxDuration;
+  if (trackInfo) { trackDuration = 0; for (const s of trackInfo.samples) trackDuration += s.duration || 0; }
+  if (version === 0) view.setUint32(28, trackDuration);
+  else { view.setUint32(36, 0); view.setUint32(40, trackDuration); }
+  return data;
+}
+
+function rebuildMdhd(mdhdBox, trackInfo, maxDuration) {
+  const data = new Uint8Array(mdhdBox.data);
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const version = data[8];
+  let trackDuration = 0;
+  if (trackInfo) for (const s of trackInfo.samples) trackDuration += s.duration || 0;
+  const durationOffset = version === 0 ? 24 : 32;
+  if (version === 0) view.setUint32(durationOffset, trackDuration);
+  else { view.setUint32(durationOffset, 0); view.setUint32(durationOffset + 4, trackDuration); }
+  return data;
+}
+
+function rebuildStbl(stblBox, trackInfo) {
+  const stblChildren = parseChildBoxes(stblBox);
+  const newParts = [];
+  for (const child of stblChildren) if (child.type === 'stsd') { newParts.push(child.data); break; }
+  const samples = trackInfo?.samples || [];
+  const chunkOffsets = trackInfo?.chunkOffsets || [];
+  
+  // stts
+  const sttsEntries = [];
+  let curDur = null, count = 0;
+  for (const s of samples) {
+    const d = s.duration || 0;
+    if (d === curDur) count++;
+    else { if (curDur !== null) sttsEntries.push({ count, duration: curDur }); curDur = d; count = 1; }
+  }
+  if (curDur !== null) sttsEntries.push({ count, duration: curDur });
+  const sttsData = new Uint8Array(8 + sttsEntries.length * 8);
+  const sttsView = new DataView(sttsData.buffer);
+  sttsView.setUint32(4, sttsEntries.length);
+  let off = 8;
+  for (const e of sttsEntries) { sttsView.setUint32(off, e.count); sttsView.setUint32(off + 4, e.duration); off += 8; }
+  newParts.push(createBox('stts', sttsData));
+  
+  // stsc
+  const stscEntries = [];
+  if (chunkOffsets.length > 0) {
+    let currentSampleCount = chunkOffsets[0].sampleCount, firstChunk = 1;
+    for (let i = 1; i <= chunkOffsets.length; i++) {
+      const sampleCount = i < chunkOffsets.length ? chunkOffsets[i].sampleCount : -1;
+      if (sampleCount !== currentSampleCount) {
+        stscEntries.push({ firstChunk, samplesPerChunk: currentSampleCount, sampleDescriptionIndex: 1 });
+        firstChunk = i + 1; currentSampleCount = sampleCount;
+      }
+    }
+  } else stscEntries.push({ firstChunk: 1, samplesPerChunk: samples.length, sampleDescriptionIndex: 1 });
+  const stscData = new Uint8Array(8 + stscEntries.length * 12);
+  const stscView = new DataView(stscData.buffer);
+  stscView.setUint32(4, stscEntries.length);
+  off = 8;
+  for (const e of stscEntries) { stscView.setUint32(off, e.firstChunk); stscView.setUint32(off + 4, e.samplesPerChunk); stscView.setUint32(off + 8, e.sampleDescriptionIndex); off += 12; }
+  newParts.push(createBox('stsc', stscData));
+  
+  // stsz
+  const stszData = new Uint8Array(12 + samples.length * 4);
+  const stszView = new DataView(stszData.buffer);
+  stszView.setUint32(8, samples.length);
+  off = 12;
+  for (const s of samples) { stszView.setUint32(off, s.size || 0); off += 4; }
+  newParts.push(createBox('stsz', stszData));
+  
+  // stco
+  const numChunks = chunkOffsets.length || 1;
+  const stcoData = new Uint8Array(8 + numChunks * 4);
+  const stcoView = new DataView(stcoData.buffer);
+  stcoView.setUint32(4, numChunks);
+  for (let i = 0; i < numChunks; i++) stcoView.setUint32(8 + i * 4, chunkOffsets[i]?.offset || 0);
+  newParts.push(createBox('stco', stcoData));
+  
+  // ctts
+  const hasCtts = samples.some(s => s.compositionTimeOffset);
+  if (hasCtts) {
+    const cttsEntries = [];
+    let curOff = null; count = 0;
+    for (const s of samples) {
+      const o = s.compositionTimeOffset || 0;
+      if (o === curOff) count++;
+      else { if (curOff !== null) cttsEntries.push({ count, offset: curOff }); curOff = o; count = 1; }
+    }
+    if (curOff !== null) cttsEntries.push({ count, offset: curOff });
+    const cttsData = new Uint8Array(8 + cttsEntries.length * 8);
+    const cttsView = new DataView(cttsData.buffer);
+    cttsView.setUint32(4, cttsEntries.length);
+    off = 8;
+    for (const e of cttsEntries) { cttsView.setUint32(off, e.count); cttsView.setInt32(off + 4, e.offset); off += 8; }
+    newParts.push(createBox('ctts', cttsData));
+  }
+  
+  // stss
+  const syncSamples = [];
+  for (let i = 0; i < samples.length; i++) {
+    const flags = samples[i].flags;
+    if (flags !== undefined) { if (!((flags >> 16) & 0x1)) syncSamples.push(i + 1); }
+  }
+  if (syncSamples.length > 0 && syncSamples.length < samples.length) {
+    const stssData = new Uint8Array(8 + syncSamples.length * 4);
+    const stssView = new DataView(stssData.buffer);
+    stssView.setUint32(4, syncSamples.length);
+    off = 8;
+    for (const n of syncSamples) { stssView.setUint32(off, n); off += 4; }
+    newParts.push(createBox('stss', stssData));
+  }
+  
+  return createBox('stbl', ...newParts);
+}
+
+function rebuildMinf(minfBox, trackInfo) {
+  const minfChildren = parseChildBoxes(minfBox);
+  const newParts = [];
+  for (const child of minfChildren) {
+    if (child.type === 'stbl') newParts.push(rebuildStbl(child, trackInfo));
+    else newParts.push(child.data);
+  }
+  return createBox('minf', ...newParts);
+}
+
+function rebuildMdia(mdiaBox, trackInfo, maxDuration) {
+  const mdiaChildren = parseChildBoxes(mdiaBox);
+  const newParts = [];
+  for (const child of mdiaChildren) {
+    if (child.type === 'minf') newParts.push(rebuildMinf(child, trackInfo));
+    else if (child.type === 'mdhd') newParts.push(rebuildMdhd(child, trackInfo, maxDuration));
+    else newParts.push(child.data);
+  }
+  return createBox('mdia', ...newParts);
+}
+
+function rebuildTrak(trakBox, trackIdMap, maxDuration) {
+  const trakChildren = parseChildBoxes(trakBox);
+  let trackId = 1;
+  for (const child of trakChildren) {
+    if (child.type === 'tkhd') {
+      const view = new DataView(child.data.buffer, child.data.byteOffset, child.data.byteLength);
+      trackId = child.data[8] === 0 ? view.getUint32(20) : view.getUint32(28);
+    }
+  }
+  const trackInfo = trackIdMap.get(trackId);
+  const newParts = [];
+  let hasEdts = false;
+  for (const child of trakChildren) {
+    if (child.type === 'edts') { hasEdts = true; newParts.push(child.data); }
+    else if (child.type === 'mdia') newParts.push(rebuildMdia(child, trackInfo, maxDuration));
+    else if (child.type === 'tkhd') newParts.push(rebuildTkhd(child, trackInfo, maxDuration));
+    else newParts.push(child.data);
+  }
+  if (!hasEdts && trackInfo) {
+    let trackDuration = 0;
+    for (const s of trackInfo.samples) trackDuration += s.duration || 0;
+    const elstData = new Uint8Array(20);
+    const elstView = new DataView(elstData.buffer);
+    elstView.setUint32(4, 1); elstView.setUint32(8, maxDuration); elstView.setInt32(12, 0); elstView.setInt16(16, 1);
+    const elst = createBox('elst', elstData);
+    const edts = createBox('edts', elst);
+    const tkhdIndex = newParts.findIndex(p => p.length >= 8 && String.fromCharCode(p[4], p[5], p[6], p[7]) === 'tkhd');
+    if (tkhdIndex >= 0) newParts.splice(tkhdIndex + 1, 0, edts);
+  }
+  return createBox('trak', ...newParts);
+}
+
+function updateStcoOffsets(output, ftypSize, moovSize) {
+  const mdatContentOffset = ftypSize + moovSize + 8;
+  const view = new DataView(output.buffer, output.byteOffset, output.byteLength);
+  function scan(start, end) {
+    let pos = start;
+    while (pos + 8 <= end) {
+      const size = view.getUint32(pos);
+      if (size < 8) break;
+      const type = String.fromCharCode(output[pos+4], output[pos+5], output[pos+6], output[pos+7]);
+      if (type === 'stco') {
+        const entryCount = view.getUint32(pos + 12);
+        for (let i = 0; i < entryCount; i++) {
+          const entryPos = pos + 16 + i * 4;
+          view.setUint32(entryPos, mdatContentOffset + view.getUint32(entryPos));
+        }
+      } else if (['moov', 'trak', 'mdia', 'minf', 'stbl'].includes(type)) scan(pos + 8, pos + size);
+      pos += size;
+    }
+  }
+  scan(0, output.byteLength);
+}
+
+/**
+ * Convert fragmented MP4 to standard MP4
+ * @param {Uint8Array} fmp4Data - fMP4 data
+ * @returns {Uint8Array} Standard MP4 data
+ */
+export function convertFmp4ToMp4(fmp4Data) {
+  const boxes = parseBoxes(fmp4Data);
+  const ftyp = findBox(boxes, 'ftyp');
+  const moov = findBox(boxes, 'moov');
+  if (!ftyp || !moov) throw new Error('Invalid fMP4: missing ftyp or moov');
+  
+  const moovChildren = parseChildBoxes(moov);
+  const originalTrackIds = [];
+  for (const child of moovChildren) {
+    if (child.type === 'trak') {
+      const trakChildren = parseChildBoxes(child);
+      for (const tc of trakChildren) {
+        if (tc.type === 'tkhd') {
+          const view = new DataView(tc.data.buffer, tc.data.byteOffset, tc.data.byteLength);
+          originalTrackIds.push(tc.data[8] === 0 ? view.getUint32(20) : view.getUint32(28));
+        }
+      }
+    }
+  }
+  
+  const tracks = new Map();
+  const mdatChunks = [];
+  let combinedMdatOffset = 0;
+  
+  for (let i = 0; i < boxes.length; i++) {
+    const box = boxes[i];
+    if (box.type === 'moof') {
+      const moofChildren = parseChildBoxes(box);
+      const moofStart = box.offset;
+      let nextMdatOffset = 0;
+      for (let j = i + 1; j < boxes.length; j++) {
+        if (boxes[j].type === 'mdat') { nextMdatOffset = boxes[j].offset; break; }
+        if (boxes[j].type === 'moof') break;
+      }
+      for (const child of moofChildren) {
+        if (child.type === 'traf') {
+          const trafChildren = parseChildBoxes(child);
+          const tfhd = findBox(trafChildren, 'tfhd');
+          const trun = findBox(trafChildren, 'trun');
+          if (tfhd && trun) {
+            const trackId = parseTfhd(tfhd.data);
+            const { samples, dataOffset } = parseTrunWithOffset(trun.data);
+            if (!tracks.has(trackId)) tracks.set(trackId, { samples: [], chunkOffsets: [] });
+            const track = tracks.get(trackId);
+            const chunkOffset = combinedMdatOffset + (moofStart + dataOffset) - (nextMdatOffset + 8);
+            track.chunkOffsets.push({ offset: chunkOffset, sampleCount: samples.length });
+            track.samples.push(...samples);
+          }
+        }
+      }
+    } else if (box.type === 'mdat') {
+      mdatChunks.push({ data: box.data.subarray(8), offset: combinedMdatOffset });
+      combinedMdatOffset += box.data.subarray(8).byteLength;
+    }
+  }
+  
+  const totalMdatSize = mdatChunks.reduce((sum, c) => sum + c.data.byteLength, 0);
+  const combinedMdat = new Uint8Array(totalMdatSize);
+  for (const chunk of mdatChunks) combinedMdat.set(chunk.data, chunk.offset);
+  
+  const trackIdMap = new Map();
+  const fmp4TrackIds = Array.from(tracks.keys()).sort((a, b) => a - b);
+  for (let i = 0; i < fmp4TrackIds.length && i < originalTrackIds.length; i++) {
+    trackIdMap.set(originalTrackIds[i], tracks.get(fmp4TrackIds[i]));
+  }
+  
+  let maxDuration = 0;
+  for (const [, track] of tracks) {
+    let dur = 0;
+    for (const s of track.samples) dur += s.duration || 0;
+    maxDuration = Math.max(maxDuration, dur);
+  }
+  
+  const newMoovParts = [];
+  for (const child of moovChildren) {
+    if (child.type === 'mvex') continue;
+    if (child.type === 'trak') newMoovParts.push(rebuildTrak(child, trackIdMap, maxDuration));
+    else if (child.type === 'mvhd') newMoovParts.push(rebuildMvhd(child, maxDuration));
+    else newMoovParts.push(child.data);
+  }
+  
+  const newMoov = createBox('moov', ...newMoovParts);
+  const newMdat = createBox('mdat', combinedMdat);
+  const output = new Uint8Array(ftyp.size + newMoov.byteLength + newMdat.byteLength);
+  output.set(ftyp.data, 0);
+  output.set(newMoov, ftyp.size);
+  output.set(newMdat, ftyp.size + newMoov.byteLength);
+  updateStcoOffsets(output, ftyp.size, newMoov.byteLength);
+  
+  return output;
+}
+
+export default convertFmp4ToMp4;
+

package/src/hls.js

@@ -0,0 +1,280 @@
+/**
+ * HLS Playlist Parser and Downloader
+ * Handles master playlists, variant selection, and segment downloading
+ */
+
+/**
+ * Represents a quality variant in an HLS stream
+ */
+class HlsVariant {
+  constructor({ bandwidth, resolution, codecs, url, name }) {
+    this.bandwidth = bandwidth;
+    this.resolution = resolution;
+    this.codecs = codecs;
+    this.url = url;
+    this.name = name || this._generateName();
+  }
+
+  _generateName() {
+    if (this.resolution) return this.resolution;
+    if (this.bandwidth) return `${Math.round(this.bandwidth / 1000)}kbps`;
+    return 'unknown';
+  }
+
+  /** Bandwidth in kbps */
+  get kbps() {
+    return Math.round(this.bandwidth / 1000);
+  }
+
+  /** Bandwidth in Mbps */
+  get mbps() {
+    return (this.bandwidth / 1000000).toFixed(2);
+  }
+}
+
+/**
+ * Represents a parsed HLS stream with quality variants
+ */
+class HlsStream {
+  constructor(masterUrl, variants, segments = null) {
+    this.masterUrl = masterUrl;
+    this.variants = variants;
+    this.segments = segments;
+    this._selectedVariant = null;
+  }
+
+  /** Whether this is a master playlist with multiple qualities */
+  get isMaster() {
+    return this.variants.length > 0;
+  }
+
+  /** Get all available qualities sorted by bandwidth (highest first) */
+  get qualities() {
+    return [...this.variants].sort((a, b) => b.bandwidth - a.bandwidth);
+  }
+
+  /** Get the highest quality variant */
+  get highest() {
+    return this.qualities[0] || null;
+  }
+
+  /** Get the lowest quality variant */
+  get lowest() {
+    const q = this.qualities;
+    return q[q.length - 1] || null;
+  }
+
+  /** Currently selected variant */
+  get selected() {
+    return this._selectedVariant || this.highest;
+  }
+
+  /**
+   * Select a quality variant
+   * @param {string|number|HlsVariant} selector - 'highest', 'lowest', bandwidth number, or variant object
+   * @returns {HlsStream} this for chaining
+   */
+  select(selector) {
+    if (selector === 'highest') {
+      this._selectedVariant = this.highest;
+    } else if (selector === 'lowest') {
+      this._selectedVariant = this.lowest;
+    } else if (typeof selector === 'number') {
+      // Find by bandwidth (closest match)
+      this._selectedVariant = this.qualities.reduce((best, v) => 
+        Math.abs(v.bandwidth - selector) < Math.abs(best.bandwidth - selector) ? v : best
+      );
+    } else if (selector instanceof HlsVariant) {
+      this._selectedVariant = selector;
+    } else if (typeof selector === 'string' && selector.includes('x')) {
+      // Match by resolution string like "1920x1080"
+      this._selectedVariant = this.variants.find(v => v.resolution === selector) || this.highest;
+    }
+    return this;
+  }
+}
+
+/**
+ * Convert relative URL to absolute
+ */
+function toAbsoluteUrl(relative, base) {
+  if (relative.startsWith('http://') || relative.startsWith('https://')) {
+    return relative;
+  }
+  return new URL(relative, base).href;
+}
+
+/**
+ * Parse an HLS playlist text
+ * @param {string} text - Playlist content
+ * @param {string} baseUrl - Base URL for resolving relative paths
+ * @returns {{ variants: HlsVariant[], segments: string[] }}
+ */
+function parsePlaylistText(text, baseUrl) {
+  const lines = text.split('\n').map(l => l.trim());
+  const variants = [];
+  const segments = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Parse master playlist variants
+    if (line.startsWith('#EXT-X-STREAM-INF:')) {
+      const attrs = line.substring(18);
+      const bandwidth = parseInt(attrs.match(/BANDWIDTH=(\d+)/)?.[1] || '0');
+      const resolution = attrs.match(/RESOLUTION=(\d+x\d+)/)?.[1] || null;
+      const codecs = attrs.match(/CODECS="([^"]+)"/)?.[1] || null;
+      
+      // Next non-comment line is the URL
+      let urlLine = lines[i + 1];
+      if (urlLine && !urlLine.startsWith('#')) {
+        variants.push(new HlsVariant({
+          bandwidth,
+          resolution,
+          codecs,
+          url: toAbsoluteUrl(urlLine, baseUrl)
+        }));
+      }
+    }
+
+    // Parse media playlist segments
+    if (line && !line.startsWith('#')) {
+      // It's a segment URL
+      if (!lines.some(l => l.startsWith('#EXT-X-STREAM-INF'))) {
+        segments.push(toAbsoluteUrl(line, baseUrl));
+      }
+    }
+  }
+
+  return { variants, segments };
+}
+
+/**
+ * Parse an HLS playlist from URL
+ * If it's a master playlist, returns variants. If media playlist, returns segments.
+ * 
+ * @param {string} url - HLS playlist URL
+ * @param {object} [options] - Options
+ * @param {function} [options.onProgress] - Progress callback
+ * @returns {Promise<HlsStream>}
+ */
+async function parseHls(url, options = {}) {
+  const log = options.onProgress || (() => {});
+  
+  log('Fetching playlist...');
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch playlist: ${response.status} ${response.statusText}`);
+  }
+  
+  const text = await response.text();
+  const { variants, segments } = parsePlaylistText(text, url);
+
+  if (variants.length > 0) {
+    // Master playlist
+    log(`Found ${variants.length} quality variants`);
+    return new HlsStream(url, variants);
+  } else if (segments.length > 0) {
+    // Media playlist (no variants)
+    log(`Found ${segments.length} segments`);
+    return new HlsStream(url, [], segments);
+  } else {
+    throw new Error('Invalid HLS playlist: no variants or segments found');
+  }
+}
+
+/**
+ * Download segments from an HLS stream
+ * 
+ * @param {HlsStream|string} source - HlsStream object or URL
+ * @param {object} [options] - Options
+ * @param {string|number} [options.quality] - 'highest', 'lowest', or bandwidth number
+ * @param {number} [options.maxSegments] - Max segments to download (default: all)
+ * @param {function} [options.onProgress] - Progress callback
+ * @returns {Promise<Uint8Array>} Combined segment data
+ */
+async function downloadHls(source, options = {}) {
+  const log = options.onProgress || (() => {});
+  
+  // Parse if given a URL string
+  let stream = source;
+  if (typeof source === 'string') {
+    stream = await parseHls(source, options);
+  }
+  
+  // Select quality if specified
+  if (options.quality) {
+    stream.select(options.quality);
+  }
+
+  // Get segments
+  let segments = stream.segments;
+  
+  // If master playlist, fetch the selected variant's media playlist
+  if (stream.isMaster && stream.selected) {
+    const variant = stream.selected;
+    log(`Selected: ${variant.name} (${variant.kbps} kbps)`);
+    
+    const mediaResponse = await fetch(variant.url);
+    if (!mediaResponse.ok) {
+      throw new Error(`Failed to fetch media playlist: ${mediaResponse.status}`);
+    }
+    
+    const mediaText = await mediaResponse.text();
+    const { segments: mediaSegments } = parsePlaylistText(mediaText, variant.url);
+    segments = mediaSegments;
+  }
+
+  if (!segments || segments.length === 0) {
+    throw new Error('No segments found in playlist');
+  }
+
+  // Limit segments if specified
+  const toDownload = options.maxSegments ? segments.slice(0, options.maxSegments) : segments;
+  log(`Downloading ${toDownload.length} segment${toDownload.length > 1 ? 's' : ''}...`);
+
+  // Download all segments in parallel
+  const buffers = await Promise.all(
+    toDownload.map(async (url, i) => {
+      const resp = await fetch(url);
+      if (!resp.ok) {
+        throw new Error(`Segment ${i + 1} failed: ${resp.status}`);
+      }
+      return new Uint8Array(await resp.arrayBuffer());
+    })
+  );
+
+  // Combine into single buffer
+  const totalSize = buffers.reduce((sum, buf) => sum + buf.length, 0);
+  const combined = new Uint8Array(totalSize);
+  let offset = 0;
+  for (const buf of buffers) {
+    combined.set(buf, offset);
+    offset += buf.length;
+  }
+
+  log(`Downloaded ${(totalSize / 1024 / 1024).toFixed(2)} MB`);
+  return combined;
+}
+
+/**
+ * Check if a URL looks like an HLS playlist
+ * @param {string} url - URL to check
+ * @returns {boolean}
+ */
+function isHlsUrl(url) {
+  if (typeof url !== 'string') return false;
+  const lower = url.toLowerCase();
+  return lower.includes('.m3u8') || lower.includes('format=m3u8');
+}
+
+export { 
+  HlsStream, 
+  HlsVariant, 
+  parseHls, 
+  downloadHls, 
+  isHlsUrl,
+  parsePlaylistText,
+  toAbsoluteUrl
+};
+