@mux/ai 0.9.0 → 0.10.0

package/dist/primitives/index.d.ts

@@ -1,3 +1,3 @@
-export { D as DEFAULT_STORYBOARD_WIDTH, H as HeatmapOptions, a as HeatmapResponse, b as Hotspot, c as HotspotOptions, d as HotspotResponse, T as ThumbnailOptions, e as TranscriptFetchOptions, f as TranscriptResult, V as VTTCue, g as buildTranscriptUrl, h as chunkByTokens, j as chunkText, k as chunkVTTCues, l as estimateTokenCount, m as extractTextFromVTT, n as extractTimestampedTranscript, o as fetchTranscriptForAsset, p as findCaptionTrack, q as getHeatmapForAsset, r as getHeatmapForPlaybackId, s as getHeatmapForVideo, t as getHotspotsForAsset, u as getHotspotsForPlaybackId, v as getHotspotsForVideo, w as getReadyTextTracks, x as getStoryboardUrl, y as getThumbnailUrls, z as parseVTTCues, A as secondsToTimestamp, B as vttTimestampToSeconds } from '../index-Nxf6BaBO.js';
+export { D as DEFAULT_STORYBOARD_WIDTH, H as HeatmapOptions, a as HeatmapResponse, b as Hotspot, c as HotspotOptions, d as HotspotResponse, T as ThumbnailOptions, e as TranscriptFetchOptions, f as TranscriptResult, V as VTTCue, g as VTTCueBudgetChunkingOptions, h as VTTDurationChunk, j as VTTDurationChunkingOptions, k as buildTranscriptUrl, l as buildVttFromCueBlocks, m as buildVttFromTranslatedCueBlocks, n as chunkByTokens, o as chunkText, p as chunkVTTCues, q as chunkVTTCuesByBudget, r as chunkVTTCuesByDuration, s as concatenateVttSegments, t as estimateTokenCount, u as extractTextFromVTT, v as extractTimestampedTranscript, w as fetchTranscriptForAsset, x as findCaptionTrack, y as getHeatmapForAsset, z as getHeatmapForPlaybackId, A as getHeatmapForVideo, B as getHotspotsForAsset, C as getHotspotsForPlaybackId, E as getHotspotsForVideo, F as getReadyTextTracks, G as getStoryboardUrl, I as getThumbnailUrls, J as parseVTTCues, K as replaceCueText, L as secondsToTimestamp, M as splitVttPreambleAndCueBlocks, N as vttTimestampToSeconds } from '../index-C8-E3VR9.js';
 import '../types-BRbaGW3t.js';
 import '@mux/mux-node';

package/dist/primitives/index.js

@@ -679,6 +679,14 @@ async function getStoryboardUrl(playbackId, width = DEFAULT_STORYBOARD_WIDTH, sh
 }
 
 // src/primitives/text-chunking.ts
+var DEFAULT_MIN_CHUNK_DURATION_RATIO = 2 / 3;
+var DEFAULT_BOUNDARY_LOOKAHEAD_CUES = 12;
+var DEFAULT_BOUNDARY_PAUSE_SECONDS = 1.25;
+var STRONG_BOUNDARY_SCORE = 4;
+var PREFERRED_BOUNDARY_WINDOW_SECONDS = 5 * 60;
+var SENTENCE_BOUNDARY_REGEX = /[.!?]["')\]]*$/;
+var CLAUSE_BOUNDARY_REGEX = /[,;:]["')\]]*$/;
+var NEXT_SENTENCE_START_REGEX = /^[A-Z0-9"'([{]/;
 function estimateTokenCount(text) {
   const words = text.trim().split(/\s+/).length;
   return Math.ceil(words / 0.75);
@@ -751,6 +759,151 @@ function chunkVTTCues(cues, maxTokens, overlapCues = 2) {
   }
   return chunks;
 }
+function scoreCueBoundary(cues, index, boundaryPauseSeconds) {
+  const cue = cues[index];
+  const nextCue = cues[index + 1];
+  if (!nextCue) {
+    return Number.POSITIVE_INFINITY;
+  }
+  const trimmedText = cue.text.trim();
+  let score = 0;
+  if (SENTENCE_BOUNDARY_REGEX.test(trimmedText)) {
+    score += 4;
+  } else if (CLAUSE_BOUNDARY_REGEX.test(trimmedText)) {
+    score += 2;
+  }
+  if (nextCue.startTime - cue.endTime >= boundaryPauseSeconds) {
+    score += 2;
+  }
+  if (NEXT_SENTENCE_START_REGEX.test(nextCue.text.trim())) {
+    score += 1;
+  }
+  return score;
+}
+function chunkVTTCuesByBudget(cues, options) {
+  if (cues.length === 0) {
+    return [];
+  }
+  const maxCuesPerChunk = Math.max(1, options.maxCuesPerChunk);
+  let maxTextTokensPerChunk = Number.POSITIVE_INFINITY;
+  if (options.maxTextTokensPerChunk) {
+    maxTextTokensPerChunk = Math.max(1, options.maxTextTokensPerChunk);
+  }
+  const chunks = [];
+  let chunkIndex = 0;
+  let cueStartIndex = 0;
+  let currentTokenCount = 0;
+  for (let cueIndex = 0; cueIndex < cues.length; cueIndex++) {
+    const cue = cues[cueIndex];
+    const cueTokenCount = estimateTokenCount(cue.text);
+    const currentCueCount = cueIndex - cueStartIndex;
+    const wouldExceedCueCount = currentCueCount >= maxCuesPerChunk;
+    const wouldExceedTokenCount = currentCueCount > 0 && currentTokenCount + cueTokenCount > maxTextTokensPerChunk;
+    if (wouldExceedCueCount || wouldExceedTokenCount) {
+      chunks.push({
+        id: `chunk-${chunkIndex}`,
+        cueStartIndex,
+        cueEndIndex: cueIndex - 1,
+        cueCount: cueIndex - cueStartIndex,
+        startTime: cues[cueStartIndex].startTime,
+        endTime: cues[cueIndex - 1].endTime
+      });
+      cueStartIndex = cueIndex;
+      currentTokenCount = 0;
+      chunkIndex++;
+    }
+    currentTokenCount += cueTokenCount;
+  }
+  chunks.push({
+    id: `chunk-${chunkIndex}`,
+    cueStartIndex,
+    cueEndIndex: cues.length - 1,
+    cueCount: cues.length - cueStartIndex,
+    startTime: cues[cueStartIndex].startTime,
+    endTime: cues[cues.length - 1].endTime
+  });
+  return chunks;
+}
+function chunkVTTCuesByDuration(cues, options) {
+  if (cues.length === 0) {
+    return [];
+  }
+  const targetChunkDurationSeconds = Math.max(1, options.targetChunkDurationSeconds);
+  const maxChunkDurationSeconds = Math.max(targetChunkDurationSeconds, options.maxChunkDurationSeconds);
+  const minChunkDurationSeconds = Math.min(
+    targetChunkDurationSeconds,
+    Math.max(
+      1,
+      options.minChunkDurationSeconds ?? Math.floor(targetChunkDurationSeconds * DEFAULT_MIN_CHUNK_DURATION_RATIO)
+    )
+  );
+  const boundaryLookaheadCues = Math.max(1, options.boundaryLookaheadCues ?? DEFAULT_BOUNDARY_LOOKAHEAD_CUES);
+  const boundaryPauseSeconds = options.boundaryPauseSeconds ?? DEFAULT_BOUNDARY_PAUSE_SECONDS;
+  const preferredBoundaryStartSeconds = Math.max(
+    minChunkDurationSeconds,
+    targetChunkDurationSeconds - Math.min(PREFERRED_BOUNDARY_WINDOW_SECONDS, targetChunkDurationSeconds / 6)
+  );
+  const chunks = [];
+  let chunkIndex = 0;
+  let cueStartIndex = 0;
+  while (cueStartIndex < cues.length) {
+    const chunkStartTime = cues[cueStartIndex].startTime;
+    let cueEndIndex = cueStartIndex;
+    let bestBoundaryIndex = -1;
+    let bestBoundaryScore = -1;
+    let bestPreferredBoundaryIndex = -1;
+    let bestPreferredBoundaryScore = -1;
+    while (cueEndIndex < cues.length) {
+      const cue = cues[cueEndIndex];
+      const currentDuration = cue.endTime - chunkStartTime;
+      if (currentDuration >= minChunkDurationSeconds) {
+        const boundaryScore = scoreCueBoundary(cues, cueEndIndex, boundaryPauseSeconds);
+        if (boundaryScore >= bestBoundaryScore) {
+          bestBoundaryIndex = cueEndIndex;
+          bestBoundaryScore = boundaryScore;
+        }
+        if (currentDuration >= preferredBoundaryStartSeconds && boundaryScore >= bestPreferredBoundaryScore) {
+          bestPreferredBoundaryIndex = cueEndIndex;
+          bestPreferredBoundaryScore = boundaryScore;
+        }
+      }
+      const nextCue = cues[cueEndIndex + 1];
+      if (!nextCue) {
+        break;
+      }
+      const nextDuration = nextCue.endTime - chunkStartTime;
+      const lookaheadExceeded = cueEndIndex - cueStartIndex >= boundaryLookaheadCues;
+      const preferredBoundaryIndex = bestPreferredBoundaryIndex >= cueStartIndex ? bestPreferredBoundaryIndex : bestBoundaryIndex;
+      const preferredBoundaryScore = bestPreferredBoundaryIndex >= cueStartIndex ? bestPreferredBoundaryScore : bestBoundaryScore;
+      if (currentDuration >= targetChunkDurationSeconds) {
+        if (preferredBoundaryIndex >= cueStartIndex && preferredBoundaryScore >= STRONG_BOUNDARY_SCORE) {
+          cueEndIndex = preferredBoundaryIndex;
+          break;
+        }
+        if (nextDuration > maxChunkDurationSeconds || lookaheadExceeded) {
+          cueEndIndex = preferredBoundaryIndex >= cueStartIndex ? preferredBoundaryIndex : cueEndIndex;
+          break;
+        }
+      }
+      if (nextDuration > maxChunkDurationSeconds) {
+        cueEndIndex = preferredBoundaryIndex >= cueStartIndex ? preferredBoundaryIndex : cueEndIndex;
+        break;
+      }
+      cueEndIndex++;
+    }
+    chunks.push({
+      id: `chunk-${chunkIndex}`,
+      cueStartIndex,
+      cueEndIndex,
+      cueCount: cueEndIndex - cueStartIndex + 1,
+      startTime: cues[cueStartIndex].startTime,
+      endTime: cues[cueEndIndex].endTime
+    });
+    cueStartIndex = cueEndIndex + 1;
+    chunkIndex++;
+  }
+  return chunks;
+}
 function chunkText(text, strategy) {
   switch (strategy.type) {
     case "token": {
@@ -792,10 +945,8 @@ async function getThumbnailUrls(playbackId, duration, options = {}) {
   }
   const baseUrl = getMuxThumbnailBaseUrl(playbackId);
   const urlPromises = timestamps.map(async (time) => {
-    if (shouldSign) {
-      return signUrl(baseUrl, playbackId, "thumbnail", { time, width }, credentials);
-    }
-    return `${baseUrl}?time=${time}&width=${width}`;
+    const url = shouldSign ? await signUrl(baseUrl, playbackId, "thumbnail", { time, width }, credentials) : `${baseUrl}?time=${time}&width=${width}`;
+    return { url, time };
   });
   return Promise.all(urlPromises);
 }
@@ -817,24 +968,82 @@ function findCaptionTrack(asset, languageCode) {
     (track) => track.text_type === "subtitles" && track.language_code === languageCode
   );
 }
+function normalizeLineEndings(value) {
+  return value.replace(/\r\n/g, "\n");
+}
+function isTimingLine(line) {
+  return line.includes("-->");
+}
+function parseNumericCueIdentifier(line) {
+  if (!/^\d+$/.test(line)) {
+    return null;
+  }
+  return Number.parseInt(line, 10);
+}
+function isLikelyTitledCueIdentifier(line) {
+  return /^\d+\s+-\s+\S.*$/.test(line);
+}
+function isLikelyCueIdentifier({
+  line,
+  nextLine,
+  previousCueIdentifier
+}) {
+  if (!line || !nextLine || !isTimingLine(nextLine)) {
+    return false;
+  }
+  const numericIdentifier = parseNumericCueIdentifier(line);
+  if (numericIdentifier !== null) {
+    if (previousCueIdentifier === null || previousCueIdentifier === void 0) {
+      return numericIdentifier === 1;
+    }
+    return numericIdentifier === previousCueIdentifier + 1;
+  }
+  return isLikelyTitledCueIdentifier(line);
+}
+function getCueIdentifierLineIndex(lines, timingLineIndex, previousCueIdentifier) {
+  const identifierIndex = timingLineIndex - 1;
+  if (identifierIndex < 0) {
+    return -1;
+  }
+  const candidate = lines[identifierIndex].trim();
+  if (!candidate || isTimingLine(candidate)) {
+    return -1;
+  }
+  return isLikelyCueIdentifier({
+    line: candidate,
+    nextLine: lines[timingLineIndex]?.trim(),
+    previousCueIdentifier
+  }) ? identifierIndex : -1;
+}
 function extractTextFromVTT(vttContent) {
   if (!vttContent.trim()) {
     return "";
   }
   const lines = vttContent.split("\n");
   const textLines = [];
+  let previousCueIdentifier = null;
+  let isInsideNoteBlock = false;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i].trim();
-    if (!line)
+    const nextLine = lines[i + 1]?.trim();
+    if (!line) {
+      isInsideNoteBlock = false;
+      continue;
+    }
+    if (isInsideNoteBlock)
       continue;
     if (line === "WEBVTT")
       continue;
-    if (line.startsWith("NOTE "))
+    if (line === "NOTE" || line.startsWith("NOTE ")) {
+      isInsideNoteBlock = true;
       continue;
-    if (line.includes("-->"))
+    }
+    if (isTimingLine(line))
       continue;
-    if (/^[\w-]+$/.test(line) && !line.includes(" "))
+    if (isLikelyCueIdentifier({ line, nextLine, previousCueIdentifier })) {
+      previousCueIdentifier = parseNumericCueIdentifier(line);
       continue;
+    }
     if (line.startsWith("STYLE") || line.startsWith("REGION"))
       continue;
     const cleanLine = line.replace(/<[^>]*>/g, "").trim();
@@ -893,20 +1102,34 @@ function parseVTTCues(vttContent) {
     return [];
   const lines = vttContent.split("\n");
   const cues = [];
+  let previousCueIdentifier = null;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i].trim();
-    if (line.includes("-->")) {
+    if (isTimingLine(line)) {
       const [startStr, endStr] = line.split(" --> ").map((s) => s.trim());
       const startTime = vttTimestampToSeconds(startStr);
       const endTime = vttTimestampToSeconds(endStr.split(" ")[0]);
-      const textLines = [];
+      const currentCueIdentifierLine = lines[i - 1]?.trim() ?? "";
+      const currentCueIdentifier = isLikelyCueIdentifier({
+        line: currentCueIdentifierLine,
+        nextLine: line,
+        previousCueIdentifier
+      }) ? parseNumericCueIdentifier(currentCueIdentifierLine) : null;
+      const rawTextLines = [];
       let j = i + 1;
-      while (j < lines.length && lines[j].trim() && !lines[j].includes("-->")) {
-        const cleanLine = lines[j].trim().replace(/<[^>]*>/g, "");
-        if (cleanLine)
-          textLines.push(cleanLine);
+      while (j < lines.length && lines[j].trim() && !isTimingLine(lines[j].trim())) {
+        rawTextLines.push(lines[j].trim());
         j++;
       }
+      const trailingNumericLine = parseNumericCueIdentifier(rawTextLines.at(-1) ?? "");
+      if (trailingNumericLine !== null && isLikelyCueIdentifier({
+        line: rawTextLines.at(-1) ?? "",
+        nextLine: lines[j]?.trim(),
+        previousCueIdentifier: currentCueIdentifier
+      }) && rawTextLines.length > 1) {
+        rawTextLines.pop();
+      }
+      const textLines = rawTextLines.map((textLine) => textLine.replace(/<[^>]*>/g, "")).filter(Boolean);
       if (textLines.length > 0) {
         cues.push({
           startTime,
@@ -914,10 +1137,102 @@ function parseVTTCues(vttContent) {
           text: textLines.join(" ")
         });
       }
+      previousCueIdentifier = currentCueIdentifier;
     }
   }
   return cues;
 }
+function splitVttPreambleAndCueBlocks(vttContent) {
+  const normalizedContent = normalizeLineEndings(vttContent).trim();
+  if (!normalizedContent) {
+    return {
+      preamble: "WEBVTT",
+      cueBlocks: []
+    };
+  }
+  const rawBlocks = normalizedContent.split(/\n{2,}/).map((block) => block.trim()).filter(Boolean);
+  const cueBlockStartIndex = rawBlocks.findIndex((block) => block.includes("-->"));
+  if (cueBlockStartIndex === -1) {
+    return {
+      preamble: normalizedContent.startsWith("WEBVTT") ? normalizedContent : `WEBVTT
+
+${normalizedContent}`,
+      cueBlocks: []
+    };
+  }
+  const hasMergedCueBlocks = rawBlocks.slice(cueBlockStartIndex).some((block) => (block.match(/-->/g) ?? []).length > 1);
+  if (hasMergedCueBlocks) {
+    const lines = normalizedContent.split("\n");
+    const timingLineIndices = lines.map((line, index) => isTimingLine(line.trim()) ? index : -1).filter((index) => index >= 0);
+    let previousCueIdentifier = null;
+    const firstCueStartIndex = getCueIdentifierLineIndex(lines, timingLineIndices[0], previousCueIdentifier);
+    const preambleEndIndex = firstCueStartIndex >= 0 ? firstCueStartIndex : timingLineIndices[0];
+    const preamble2 = lines.slice(0, preambleEndIndex).join("\n").trim() || "WEBVTT";
+    const cueBlocks2 = timingLineIndices.map((timingLineIndex, index) => {
+      const cueIdentifierLineIndex = getCueIdentifierLineIndex(lines, timingLineIndex, previousCueIdentifier);
+      const cueStartIndex = cueIdentifierLineIndex >= 0 ? cueIdentifierLineIndex : timingLineIndex;
+      const currentCueIdentifier = cueIdentifierLineIndex >= 0 ? parseNumericCueIdentifier(lines[cueIdentifierLineIndex].trim()) : null;
+      const nextTimingLineIndex = timingLineIndices[index + 1] ?? lines.length;
+      let cueEndIndex = nextTimingLineIndex - 1;
+      while (cueEndIndex > timingLineIndex && !lines[cueEndIndex].trim()) {
+        cueEndIndex--;
+      }
+      const nextCueIdentifierLineIndex = index < timingLineIndices.length - 1 ? getCueIdentifierLineIndex(lines, nextTimingLineIndex, currentCueIdentifier) : -1;
+      if (nextCueIdentifierLineIndex === cueEndIndex) {
+        cueEndIndex--;
+      }
+      while (cueEndIndex > timingLineIndex && !lines[cueEndIndex].trim()) {
+        cueEndIndex--;
+      }
+      previousCueIdentifier = currentCueIdentifier;
+      return lines.slice(cueStartIndex, cueEndIndex + 1).join("\n").trim();
+    });
+    return {
+      preamble: preamble2,
+      cueBlocks: cueBlocks2
+    };
+  }
+  const preambleBlocks = rawBlocks.slice(0, cueBlockStartIndex);
+  const cueBlocks = rawBlocks.slice(cueBlockStartIndex);
+  const preamble = preambleBlocks.length > 0 ? preambleBlocks.join("\n\n") : "WEBVTT";
+  return {
+    preamble,
+    cueBlocks
+  };
+}
+function buildVttFromCueBlocks(cueBlocks, preamble = "WEBVTT") {
+  if (cueBlocks.length === 0) {
+    return `${preamble.trim()}
+`;
+  }
+  return `${preamble.trim()}
+
+${cueBlocks.map((block) => block.trim()).join("\n\n")}
+`;
+}
+function replaceCueText(cueBlock, translatedText) {
+  const lines = normalizeLineEndings(cueBlock).split("\n").map((line) => line.trim()).filter(Boolean);
+  const timingLineIndex = lines.findIndex((line) => line.includes("-->"));
+  if (timingLineIndex === -1) {
+    throw new Error("Cue block is missing a timestamp line");
+  }
+  const headerLines = lines.slice(0, timingLineIndex + 1);
+  const translatedLines = normalizeLineEndings(translatedText).split("\n").map((line) => line.trim()).filter(Boolean);
+  return [...headerLines, ...translatedLines].join("\n");
+}
+function buildVttFromTranslatedCueBlocks(cueBlocks, translatedTexts, preamble = "WEBVTT") {
+  if (cueBlocks.length !== translatedTexts.length) {
+    throw new Error(`Expected ${cueBlocks.length} translated cues, received ${translatedTexts.length}`);
+  }
+  return buildVttFromCueBlocks(
+    cueBlocks.map((cueBlock, index) => replaceCueText(cueBlock, translatedTexts[index])),
+    preamble
+  );
+}
+function concatenateVttSegments(segments, preamble = "WEBVTT") {
+  const cueBlocks = segments.flatMap((segment) => splitVttPreambleAndCueBlocks(segment).cueBlocks);
+  return buildVttFromCueBlocks(cueBlocks, preamble);
+}
 async function buildTranscriptUrl(playbackId, trackId, shouldSign = false, credentials) {
   "use step";
   const baseUrl = `https://stream.mux.com/${playbackId}/text/${trackId}.vtt`;
@@ -979,9 +1294,14 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
 export {
   DEFAULT_STORYBOARD_WIDTH,
   buildTranscriptUrl,
+  buildVttFromCueBlocks,
+  buildVttFromTranslatedCueBlocks,
   chunkByTokens,
   chunkText,
   chunkVTTCues,
+  chunkVTTCuesByBudget,
+  chunkVTTCuesByDuration,
+  concatenateVttSegments,
   estimateTokenCount,
   extractTextFromVTT,
   extractTimestampedTranscript,
@@ -997,7 +1317,9 @@ export {
   getStoryboardUrl,
   getThumbnailUrls,
   parseVTTCues,
+  replaceCueText,
   secondsToTimestamp,
+  splitVttPreambleAndCueBlocks,
   vttTimestampToSeconds
 };
 //# sourceMappingURL=index.js.map