@mux/ai 0.28.1 → 0.29.0

package/dist/primitives/index.d.ts

@@ -1,3 +1,3 @@
-export { D as DEFAULT_STORYBOARD_WIDTH, H as HeatmapOptions, a as HeatmapResponse, L as LOW_CONFIDENCE_THRESHOLD, M as MAX_CUE_TEXT_CHARS, T as ThumbnailOptions, b as TranscriptFetchOptions, c as TranscriptResult, V as VTTCue, d as VTTCueBudgetChunkingOptions, e as VTTDurationChunk, f as VTTDurationChunkingOptions, g as buildTranscriptUrl, h as buildVttFromCueBlocks, j as buildVttFromTranslatedCueBlocks, k as chunkByTokens, l as chunkText, m as chunkVTTCues, n as chunkVTTCuesByBudget, o as chunkVTTCuesByDuration, p as concatenateVttSegments, q as estimateTokenCount, r as extractTextFromVTT, s as extractTimestampedTranscript, t as fetchTranscriptForAsset, u as findCaptionTrack, v as getHeatmapForAsset, w as getHeatmapForPlaybackId, x as getHeatmapForVideo, y as getReadyTextTracks, z as getReliableLanguageCode, A as getStoryboardUrl, B as getThumbnailUrls, C as parseVTTCues, E as replaceCueText, F as sanitizeUntrustedText, G as secondsToTimestamp, I as splitVttPreambleAndCueBlocks, J as stripVttMetadataBlocks, K as vttTimestampToSeconds } from '../index-bjQi1ZCj.js';
-export { o as CompletedShotsResult, p as ErroredShotsResult, H as Hotspot, q as HotspotOptions, r as HotspotResponse, s as PendingShotsResult, t as Shot, u as ShotRequestOptions, v as ShotsResult, w as WaitForShotsOptions, x as getHotspotsForAsset, y as getHotspotsForPlaybackId, z as getHotspotsForVideo, B as getShotsForAsset, D as requestShotsForAsset, F as waitForShotsForAsset } from '../shots-mGJfYGiO.js';
+export { D as DEFAULT_STORYBOARD_WIDTH, H as HeatmapOptions, a as HeatmapResponse, L as LOW_CONFIDENCE_THRESHOLD, M as MAX_CUE_TEXT_CHARS, T as ThumbnailOptions, b as TranscriptFetchOptions, c as TranscriptResult, V as VTTCue, d as VTTCueBudgetChunkingOptions, e as VTTDurationChunk, f as VTTDurationChunkingOptions, g as buildTranscriptUrl, h as buildVttFromCueBlocks, j as buildVttFromTranslatedCueBlocks, k as chunkByTokens, l as chunkText, m as chunkVTTCues, n as chunkVTTCuesByBudget, o as chunkVTTCuesByDuration, p as concatenateVttSegments, q as estimateTokenCount, r as extractTextFromVTT, s as extractTimestampedTranscript, t as fetchTranscriptForAsset, u as filterVttByScope, v as findCaptionTrack, w as getHeatmapForAsset, x as getHeatmapForPlaybackId, y as getHeatmapForVideo, z as getReadyTextTracks, A as getReliableLanguageCode, B as getStoryboardUrl, C as getThumbnailUrls, E as parseVTTCues, F as replaceCueText, G as sanitizeUntrustedText, I as secondsToTimestamp, J as splitVttPreambleAndCueBlocks, K as stripVttMetadataBlocks, N as vttTimestampToSeconds } from '../index-CXwsu679.js';
+export { q as CompletedShotsResult, r as ErroredShotsResult, H as Hotspot, s as HotspotOptions, t as HotspotResponse, u as PendingShotsResult, v as Shot, w as ShotRequestOptions, x as ShotsResult, y as WaitForShotsOptions, z as getHotspotsForAsset, B as getHotspotsForPlaybackId, D as getHotspotsForVideo, F as getShotsForAsset, G as requestShotsForAsset, J as waitForShotsForAsset } from '../shots-BKd7TMFN.js';
 import '@mux/mux-node';

package/dist/primitives/index.js

@@ -1111,13 +1111,22 @@ async function signUrl(url, playbackId, type = "video", params, credentials) {
 
 // src/primitives/storyboards.ts
 var DEFAULT_STORYBOARD_WIDTH = 640;
-async function getStoryboardUrl(playbackId, width = DEFAULT_STORYBOARD_WIDTH, shouldSign = false, credentials) {
+async function getStoryboardUrl(playbackId, width = DEFAULT_STORYBOARD_WIDTH, shouldSign = false, credentials, scope) {
   "use step";
   const baseUrl = getMuxStoryboardBaseUrl(playbackId);
+  const params = { width };
+  if (scope?.startTime !== void 0) {
+    params.asset_start_time = scope.startTime;
+  }
+  if (scope?.endTime !== void 0) {
+    params.asset_end_time = scope.endTime;
+  }
   if (shouldSign) {
-    return signUrl(baseUrl, playbackId, "storyboard", { width }, credentials);
+    return signUrl(baseUrl, playbackId, "storyboard", params, credentials);
   }
-  return `${baseUrl}?width=${width}`;
+  return `${baseUrl}?${new URLSearchParams(
+    Object.entries(params).map(([key, value]) => [key, String(value)])
+  ).toString()}`;
 }
 
 // src/primitives/text-chunking.ts
@@ -1358,30 +1367,77 @@ function chunkText(text, strategy) {
   }
 }
 
+// src/lib/workflow-scope.ts
+function hasWorkflowScopeBoundaries(scope) {
+  return scope?.startTime !== void 0 || scope?.endTime !== void 0;
+}
+function resolveWorkflowScope(scope, assetDurationSeconds) {
+  if (assetDurationSeconds === void 0 || !Number.isFinite(assetDurationSeconds) || assetDurationSeconds <= 0) {
+    throw new MuxAiError("Asset has no valid duration.", { type: "validation_error" });
+  }
+  const startTime = scope?.startTime ?? 0;
+  const endTime = scope?.endTime ?? assetDurationSeconds;
+  if (!Number.isFinite(startTime) || startTime < 0) {
+    throw new MuxAiError(
+      `scope.startTime must be a finite, non-negative number (received ${startTime}).`,
+      { type: "validation_error" }
+    );
+  }
+  if (!Number.isFinite(endTime) || endTime < 0) {
+    throw new MuxAiError(
+      `scope.endTime must be a finite, non-negative number (received ${endTime}).`,
+      { type: "validation_error" }
+    );
+  }
+  if (endTime > assetDurationSeconds) {
+    throw new MuxAiError(
+      `scope.endTime (${endTime}) cannot exceed the asset duration (${assetDurationSeconds}).`,
+      { type: "validation_error" }
+    );
+  }
+  if (startTime >= endTime) {
+    throw new MuxAiError(
+      `scope.startTime (${startTime}) must be less than scope.endTime (${endTime}).`,
+      { type: "validation_error" }
+    );
+  }
+  return { startTime, endTime };
+}
+function timeRangesOverlap(firstStart, firstEnd, second) {
+  const secondStart = second.startTime ?? 0;
+  const secondEnd = second.endTime ?? Number.POSITIVE_INFINITY;
+  return firstStart < secondEnd && firstEnd > secondStart;
+}
+
 // src/primitives/thumbnails.ts
 async function getThumbnailUrls(playbackId, duration, options = {}) {
   "use step";
-  const { interval = 10, width = 640, shouldSign = false, maxSamples, credentials } = options;
+  const { interval = 10, width = 640, shouldSign = false, maxSamples, credentials, scope } = options;
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  const resolvedScope = effectiveScope ? resolveWorkflowScope(effectiveScope, duration) : { startTime: 0, endTime: duration };
+  const rangeDuration = resolvedScope.endTime - resolvedScope.startTime;
   let timestamps = [];
-  if (duration <= 50) {
-    const spacing = duration / 6;
+  if (rangeDuration <= 50) {
+    const spacing = rangeDuration / 6;
     for (let i = 1; i <= 5; i++) {
-      timestamps.push(Math.round(i * spacing));
+      const time = resolvedScope.startTime + i * spacing;
+      timestamps.push(effectiveScope ? Number(time.toFixed(3)) : Math.round(time));
     }
   } else {
-    for (let time = 0; time < duration; time += interval) {
+    for (let time = resolvedScope.startTime; time < resolvedScope.endTime; time += interval) {
       timestamps.push(time);
     }
   }
   if (maxSamples !== void 0 && timestamps.length > maxSamples) {
     const newTimestamps = [];
-    newTimestamps.push(0);
+    newTimestamps.push(resolvedScope.startTime);
     if (maxSamples >= 2) {
-      const spacing = duration / (maxSamples - 1);
+      const lastTime = effectiveScope ? Math.max(resolvedScope.startTime, resolvedScope.endTime - 1e-3) : resolvedScope.endTime;
+      const spacing = (lastTime - resolvedScope.startTime) / (maxSamples - 1);
       for (let i = 1; i < maxSamples - 1; i++) {
-        newTimestamps.push(spacing * i);
+        newTimestamps.push(resolvedScope.startTime + spacing * i);
       }
-      newTimestamps.push(duration);
+      newTimestamps.push(lastTime);
     }
     timestamps = newTimestamps;
   }
@@ -1792,6 +1848,23 @@ function parseVTTCues(vttContent) {
   }
   return cues;
 }
+function filterVttByScope(vttContent, scope) {
+  if (!scope || scope.startTime === void 0 && scope.endTime === void 0) {
+    return vttContent;
+  }
+  const { preamble, cueBlocks } = splitVttPreambleAndCueBlocks(vttContent);
+  const scopedCueBlocks = cueBlocks.filter((cueBlock) => {
+    const cue = parseVTTCues(cueBlock)[0];
+    return cue ? timeRangesOverlap(cue.startTime, cue.endTime, scope) : false;
+  }).map((cueBlock, index) => {
+    const lines = cueBlock.split("\n");
+    if (/^\d+$/.test(lines[0]?.trim()) && lines[1]?.includes("-->")) {
+      lines[0] = String(index + 1);
+    }
+    return lines.join("\n");
+  });
+  return buildVttFromCueBlocks(scopedCueBlocks, preamble);
+}
 function splitVttPreambleAndCueBlocks(vttContent) {
   const normalizedContent = normalizeLineEndings(vttContent).trim();
   if (!normalizedContent) {
@@ -1896,6 +1969,7 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
   const {
     languageCode,
     cleanTranscript = true,
+    scope,
     shouldSign,
     credentials,
     required = false
@@ -1927,9 +2001,15 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
       return { transcriptText: "", transcriptUrl, track };
     }
     const rawVtt = await response.text();
-    const transcriptText = cleanTranscript ? extractTextFromVTT(rawVtt) : rawVtt;
-    if (required && !transcriptText.trim()) {
-      throw new MuxAiError("Transcript is empty.", { type: "validation_error" });
+    const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+    const scopedVtt = filterVttByScope(rawVtt, effectiveScope);
+    const transcriptText = cleanTranscript ? extractTextFromVTT(scopedVtt) : scopedVtt;
+    const hasScopedCues = !effectiveScope || parseVTTCues(scopedVtt).length > 0;
+    if (required && (!transcriptText.trim() || !hasScopedCues)) {
+      throw new MuxAiError(
+        effectiveScope ? "Transcript has no cues in the requested scope." : "Transcript is empty.",
+        { type: "validation_error" }
+      );
     }
     return { transcriptText, transcriptUrl, track };
   } catch (error) {
@@ -1957,6 +2037,7 @@ export {
   extractTextFromVTT,
   extractTimestampedTranscript,
   fetchTranscriptForAsset,
+  filterVttByScope,
   findCaptionTrack,
   getHeatmapForAsset,
   getHeatmapForPlaybackId,