@mux/ai 0.28.0 → 0.29.0

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.28.0";
+var version = "0.29.0";
 
 // src/lib/language-codes.ts
 var ISO639_1_TO_3 = {
@@ -1372,6 +1372,7 @@ __export(primitives_exports, {
   extractTextFromVTT: () => extractTextFromVTT,
   extractTimestampedTranscript: () => extractTimestampedTranscript,
   fetchTranscriptForAsset: () => fetchTranscriptForAsset,
+  filterVttByScope: () => filterVttByScope,
   findCaptionTrack: () => findCaptionTrack,
   getHeatmapForAsset: () => getHeatmapForAsset,
   getHeatmapForPlaybackId: () => getHeatmapForPlaybackId,
@@ -1908,13 +1909,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
@@ -2155,30 +2165,97 @@ 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 resolveRenderableVideoScope(scope, assetDurationSeconds, videoTrackDurationSeconds) {
+  if (!hasWorkflowScopeBoundaries(scope)) {
+    return void 0;
+  }
+  const resolvedScope = resolveWorkflowScope(scope, assetDurationSeconds);
+  let renderableEndTime = resolvedScope.endTime;
+  if (videoTrackDurationSeconds !== void 0 && Number.isFinite(videoTrackDurationSeconds) && videoTrackDurationSeconds >= 0) {
+    renderableEndTime = Math.min(videoTrackDurationSeconds, resolvedScope.endTime);
+  }
+  const renderableScope = {
+    startTime: Math.min(resolvedScope.startTime, renderableEndTime),
+    endTime: renderableEndTime
+  };
+  if (renderableScope.startTime >= renderableScope.endTime) {
+    throw new MuxAiError("The requested scope does not include any renderable video.", {
+      type: "validation_error"
+    });
+  }
+  return renderableScope;
+}
+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;
   }
@@ -2512,6 +2589,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) {
@@ -2616,6 +2710,7 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
   const {
     languageCode,
     cleanTranscript = true,
+    scope,
     shouldSign,
     credentials,
     required = false
@@ -2647,9 +2742,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) {
@@ -3431,7 +3532,8 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
     imageSubmissionMode = "url",
     imageDownloadOptions,
     storyboardWidth = 640,
-    credentials
+    credentials,
+    scope
   } = options ?? {};
   const normalizedQuestions = questions.map((q, idx) => normalizeQuestion(q, idx));
   const hasFreeForm = normalizedQuestions.some((q) => q.mode.kind === "freeForm");
@@ -3443,6 +3545,15 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
   const isAudioOnly = isAudioOnlyAsset(assetData);
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  const storyboardScope = isAudioOnly ? void 0 : resolveRenderableVideoScope(
+    effectiveScope,
+    assetDurationSeconds,
+    getVideoTrackDurationSecondsFromAsset(assetData)
+  );
+  if (isAudioOnly && effectiveScope) {
+    resolveWorkflowScope(effectiveScope, assetDurationSeconds);
+  }
   if (isAudioOnly && !includeTranscript) {
     throw new MuxAiError(
       "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles).",
@@ -3461,7 +3572,8 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
     cleanTranscript,
     shouldSign: policy === "signed",
     credentials,
-    required: isAudioOnly
+    required: isAudioOnly,
+    scope: effectiveScope
   }) : void 0;
   const transcriptText = transcriptResult?.transcriptText ?? "";
   const userPrompt = buildUserPrompt({
@@ -3490,7 +3602,8 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
         playbackId,
         storyboardWidth,
         policy === "signed",
-        credentials
+        credentials,
+        storyboardScope
       );
       imageUrl = storyboardUrl;
       if (imageSubmissionMode === "base64") {
@@ -3773,6 +3886,7 @@ async function hasBurnedInCaptionsInternal(assetId, options, collectedUsage) {
     imageDownloadOptions,
     promptOverrides,
     credentials,
+    scope,
     ...config
   } = options;
   const userPrompt = buildUserPrompt2(promptOverrides);
@@ -3783,7 +3897,18 @@ async function hasBurnedInCaptionsInternal(assetId, options, collectedUsage) {
   });
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
-  const imageUrl = await getStoryboardUrl(playbackId, 640, policy === "signed", credentials);
+  const storyboardScope = resolveRenderableVideoScope(
+    scope,
+    assetDurationSeconds,
+    getVideoTrackDurationSecondsFromAsset(assetData)
+  );
+  const imageUrl = await getStoryboardUrl(
+    playbackId,
+    640,
+    policy === "signed",
+    credentials,
+    storyboardScope
+  );
   let analysisResponse;
   if (imageSubmissionMode === "base64") {
     const base64Data = await fetchImageAsBase642(imageUrl, imageDownloadOptions);
@@ -3982,7 +4107,8 @@ function buildUserPrompt3({
   promptOverrides,
   minChaptersPerHour = 3,
   maxChaptersPerHour = 8,
-  languageName
+  languageName,
+  scope
 }) {
   const contextSections = [
     {
@@ -3997,6 +4123,8 @@ function buildUserPrompt3({
   const dynamicChapterGuidelines = dedent4`
     - Create at least ${minChaptersPerHour} and at most ${maxChaptersPerHour} chapters per hour of content
     - Use start times in seconds (not HH:MM:SS)
+    ${scope ? `- Analyze only the range from ${scope.startTime}s (inclusive) to ${scope.endTime}s (exclusive)
+- The first chapter must start at ${scope.startTime}s` : ""}
     - Chapter start times should be non-decreasing
     - Do not include text before or after the JSON`;
   const mergedOverrides = {
@@ -4023,7 +4151,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     minChaptersPerHour,
     maxChaptersPerHour,
     credentials,
-    outputLanguageCode
+    outputLanguageCode,
+    scope
   } = options;
   const modelConfig = resolveLanguageModelConfig({
     ...options,
@@ -4032,6 +4161,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
   });
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  const resolvedScope = effectiveScope ? resolveWorkflowScope(effectiveScope, assetDurationSeconds) : void 0;
   const isAudioOnly = isAudioOnlyAsset(assetData);
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
@@ -4046,7 +4177,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     cleanTranscript: false,
     // keep timestamps for chapter segmentation
     shouldSign: policy === "signed",
-    credentials
+    credentials,
+    scope: effectiveScope
   });
   if (!transcriptResult.track || !transcriptResult.transcriptText) {
     const availableLanguages = readyTextTracks.map((t) => t.language_code).filter(Boolean).join(", ");
@@ -4067,7 +4199,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     promptOverrides,
     minChaptersPerHour,
     maxChaptersPerHour,
-    languageName
+    languageName,
+    scope: resolvedScope
   });
   let chaptersData = null;
   try {
@@ -4089,7 +4222,9 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     throw new MuxAiError(`Failed to generate chapters for asset ${assetId}.`);
   }
   const { chapters: chaptersPayload, usage } = chaptersData;
-  const validChapters = chaptersPayload.chapters.filter((chapter) => typeof chapter.startTime === "number" && typeof chapter.title === "string").sort((a, b) => a.startTime - b.startTime);
+  const validChapters = chaptersPayload.chapters.filter((chapter) => typeof chapter.startTime === "number" && typeof chapter.title === "string").filter(
+    (chapter) => resolvedScope ? chapter.startTime >= resolvedScope.startTime && chapter.startTime < resolvedScope.endTime : true
+  ).sort((a, b) => a.startTime - b.startTime);
   if (validChapters.length === 0) {
     throw new MuxAiError(`Failed to generate valid chapters for asset ${assetId}.`);
   }
@@ -4115,8 +4250,9 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
   if (scrubbedChapters.length === 0) {
     throw new MuxAiError(`Failed to generate valid chapters for asset ${assetId}.`);
   }
-  if (scrubbedChapters[0].startTime !== 0) {
-    scrubbedChapters[0].startTime = 0;
+  const firstChapterStartTime = resolvedScope?.startTime ?? 0;
+  if (scrubbedChapters[0].startTime !== firstChapterStartTime) {
+    scrubbedChapters[0].startTime = firstChapterStartTime;
   }
   const usageWithMetadata = {
     ...usage,
@@ -4695,11 +4831,16 @@ async function generateEmbeddingsInternal(assetId, options, collectedUsage) {
     languageCode,
     chunkingStrategy = { type: "token", maxTokens: 500, overlap: 100 },
     batchSize = 5,
-    credentials
+    credentials,
+    scope
   } = options;
   const embeddingModel = resolveEmbeddingModelConfig({ ...options, provider, model });
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  if (effectiveScope) {
+    resolveWorkflowScope(effectiveScope, assetDurationSeconds);
+  }
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
     throw new Error(
@@ -4712,7 +4853,8 @@ async function generateEmbeddingsInternal(assetId, options, collectedUsage) {
     cleanTranscript: !useVttChunking,
     shouldSign: policy === "signed",
     credentials,
-    required: true
+    required: true,
+    scope: effectiveScope
   });
   const transcriptText = transcriptResult.transcriptText;
   const chunks = useVttChunking ? chunkVTTCues(
@@ -5843,12 +5985,24 @@ async function requestGoogleVisionModeration(images, maxConcurrent = 5, submissi
   }));
   return processConcurrently(targets, moderateImageWithGoogleVision, maxConcurrent);
 }
+function toThumbnailTimeSeconds(timestampMs) {
+  return Number((timestampMs / 1e3).toFixed(2));
+}
+function filterTimestampsWithinExclusiveScope(timestampsMs, scope) {
+  if (!scope) {
+    return timestampsMs;
+  }
+  return timestampsMs.filter((timestampMs) => {
+    const time = toThumbnailTimeSeconds(timestampMs);
+    return time >= scope.startTime && time < scope.endTime;
+  });
+}
 async function getThumbnailUrlsFromTimestamps(playbackId, timestampsMs, options) {
   "use step";
   const { width, shouldSign, credentials } = options;
   const baseUrl = getMuxThumbnailBaseUrl(playbackId);
   const urlPromises = timestampsMs.map(async (tsMs) => {
-    const time = Number((tsMs / 1e3).toFixed(2));
+    const time = toThumbnailTimeSeconds(tsMs);
     const url = shouldSign ? await signUrl(baseUrl, playbackId, "thumbnail", { time, width }, credentials) : `${baseUrl}?time=${time}&width=${width}`;
     return { url, time };
   });
@@ -5867,7 +6021,8 @@ async function getModerationScores(assetId, options = {}) {
     maxConcurrent = 5,
     imageSubmissionMode = "url",
     imageDownloadOptions,
-    credentials: providedCredentials
+    credentials: providedCredentials,
+    scope
   } = options;
   const credentials = providedCredentials;
   const { asset, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
@@ -5878,7 +6033,16 @@ async function getModerationScores(assetId, options = {}) {
     (d) => d != null
   );
   const duration = candidateDurations.length > 0 ? Math.min(...candidateDurations) : 0;
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  const resolvedScope = effectiveScope ? resolveWorkflowScope(effectiveScope, assetDurationSeconds) : void 0;
   const isAudioOnly = isAudioOnlyAsset(asset);
+  const renderableScope = resolvedScope ? {
+    startTime: Math.min(resolvedScope.startTime, duration),
+    endTime: Math.min(resolvedScope.endTime, duration)
+  } : void 0;
+  if (!isAudioOnly && renderableScope && renderableScope.startTime >= renderableScope.endTime) {
+    throw new Error("The requested scope does not include any renderable video.");
+  }
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
     throw new Error(
@@ -5895,7 +6059,8 @@ async function getModerationScores(assetId, options = {}) {
       cleanTranscript: true,
       shouldSign: policy === "signed",
       credentials,
-      required: true
+      required: true,
+      scope: effectiveScope
     });
     if (provider === "openai") {
       thumbnailScores = await requestOpenAITranscriptModeration(
@@ -5913,17 +6078,21 @@ async function getModerationScores(assetId, options = {}) {
       throw new Error(`Unsupported moderation provider: ${exhaustiveCheck}`);
     }
   } else {
-    const estimatedIntervalCount = duration <= 50 ? 5 : Math.ceil(duration / thumbnailInterval);
+    const scopedDuration = renderableScope ? renderableScope.endTime - renderableScope.startTime : duration;
+    const estimatedIntervalCount = scopedDuration <= 50 ? 5 : Math.ceil(scopedDuration / thumbnailInterval);
     const thumbnailUrls = maxSamples !== void 0 && estimatedIntervalCount > maxSamples ? await getThumbnailUrlsFromTimestamps(
       playbackId,
-      planSamplingTimestamps({
-        duration_sec: duration,
-        max_candidates: maxSamples,
-        trim_start_sec: duration > 2 ? Math.min(5, Math.max(1, duration / 6)) : 0,
-        trim_end_sec: duration > 2 ? Math.min(5, Math.max(1, duration / 6)) : 0,
-        fps: videoTrackFps,
-        base_cadence_hz: thumbnailInterval > 0 ? 1 / thumbnailInterval : void 0
-      }),
+      filterTimestampsWithinExclusiveScope(
+        planSamplingTimestamps({
+          duration_sec: duration,
+          max_candidates: maxSamples,
+          trim_start_sec: renderableScope?.startTime ?? (duration > 2 ? Math.min(5, Math.max(1, duration / 6)) : 0),
+          trim_end_sec: renderableScope ? duration - renderableScope.endTime : duration > 2 ? Math.min(5, Math.max(1, duration / 6)) : 0,
+          fps: videoTrackFps,
+          base_cadence_hz: thumbnailInterval > 0 ? 1 / thumbnailInterval : void 0
+        }),
+        renderableScope
+      ),
       {
         width: thumbnailWidth,
         shouldSign: policy === "signed",
@@ -5933,7 +6102,8 @@ async function getModerationScores(assetId, options = {}) {
       interval: thumbnailInterval,
       width: thumbnailWidth,
       shouldSign: policy === "signed",
-      credentials
+      credentials,
+      scope: renderableScope
     });
     thumbnailCount = thumbnailUrls.length;
     if (provider === "openai") {
@@ -6448,7 +6618,8 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     titleLength,
     descriptionLength,
     tagCount,
-    outputLanguageCode
+    outputLanguageCode,
+    scope
   } = options ?? {};
   if (!VALID_TONES.includes(tone)) {
     throw new MuxAiError(
@@ -6465,6 +6636,15 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, workflowCredentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
   const isAudioOnly = isAudioOnlyAsset(assetData);
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  const storyboardScope = isAudioOnly ? void 0 : resolveRenderableVideoScope(
+    effectiveScope,
+    assetDurationSeconds,
+    getVideoTrackDurationSecondsFromAsset(assetData)
+  );
+  if (isAudioOnly && effectiveScope) {
+    resolveWorkflowScope(effectiveScope, assetDurationSeconds);
+  }
   if (isAudioOnly && !includeTranscript) {
     throw new MuxAiError(
       "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles).",
@@ -6483,7 +6663,8 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     cleanTranscript,
     shouldSign: policy === "signed",
     credentials: workflowCredentials,
-    required: isAudioOnly
+    required: isAudioOnly,
+    scope: effectiveScope
   }) : void 0;
   const transcriptText = transcriptResult?.transcriptText ?? "";
   const resolvedLanguageCode = outputLanguageCode && outputLanguageCode !== "auto" ? outputLanguageCode : getReliableLanguageCode(transcriptResult?.track) ?? getReliableLanguageCode(getReadyTextTracks(assetData)[0]);
@@ -6514,7 +6695,13 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
         workflowCredentials
       );
     } else {
-      const storyboardUrl = await getStoryboardUrl(playbackId, 640, policy === "signed", workflowCredentials);
+      const storyboardUrl = await getStoryboardUrl(
+        playbackId,
+        640,
+        policy === "signed",
+        workflowCredentials,
+        storyboardScope
+      );
       imageUrl = storyboardUrl;
       if (imageSubmissionMode === "base64") {
         const downloadResult = await downloadImageAsBase64(storyboardUrl, imageDownloadOptions);
@@ -6729,9 +6916,16 @@ async function checkElevenLabsDubbingStatus({
     targetLanguages: statusData.target_languages ?? []
   };
 }
-async function downloadDubbedAudioFromElevenLabs({
+async function downloadAndUploadDubbedAudio({
   dubbingId,
   languageCode,
+  assetId,
+  toLanguageCode,
+  s3Endpoint,
+  s3Region,
+  s3Bucket,
+  storageAdapter,
+  s3SignedUrlExpirySeconds,
   credentials
 }) {
   "use step";
@@ -6745,19 +6939,7 @@ async function downloadDubbedAudioFromElevenLabs({
   if (!audioResponse.ok) {
     throw new Error(`Failed to fetch dubbed audio: ${audioResponse.statusText}`);
   }
-  return audioResponse.arrayBuffer();
-}
-async function uploadDubbedAudioToS3({
-  dubbedAudioBuffer,
-  assetId,
-  toLanguageCode,
-  s3Endpoint,
-  s3Region,
-  s3Bucket,
-  storageAdapter,
-  s3SignedUrlExpirySeconds
-}) {
-  "use step";
+  const dubbedAudio = new Uint8Array(await audioResponse.arrayBuffer());
   const s3AccessKeyId = env_default.S3_ACCESS_KEY_ID;
   const s3SecretAccessKey = env_default.S3_SECRET_ACCESS_KEY;
   const audioKey = `audio-translations/${assetId}/auto-to-${toLanguageCode}-${Date.now()}.m4a`;
@@ -6768,7 +6950,7 @@ async function uploadDubbedAudioToS3({
     region: s3Region,
     bucket: s3Bucket,
     key: audioKey,
-    body: new Uint8Array(dubbedAudioBuffer),
+    body: dubbedAudio,
     contentType: "audio/mp4"
   }, storageAdapter);
   const presignedUrl = await createPresignedGetUrlWithStorageAdapter({
@@ -6902,46 +7084,24 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   let presignedUrl;
   let uploadedTrackId;
   if (uploadToS3) {
-    console.warn("\u{1F4E5} Downloading dubbed audio from ElevenLabs...");
-    let dubbedAudioBuffer;
+    console.warn("\u{1F4E5} Downloading dubbed audio from ElevenLabs and staging to S3...");
     try {
-      const requestedLangCode = toISO639_3(toLanguageCode);
-      let downloadLangCode = targetLanguages.find(
-        (lang) => lang === requestedLangCode
-      ) ?? targetLanguages.find(
-        (lang) => lang.toLowerCase() === requestedLangCode.toLowerCase()
-      );
-      if (!downloadLangCode && targetLanguages.length > 0) {
-        downloadLangCode = targetLanguages[0];
-        console.warn(`\u26A0\uFE0F Requested language "${requestedLangCode}" not found in target_languages. Using "${downloadLangCode}" instead.`);
-      }
-      if (!downloadLangCode) {
-        downloadLangCode = requestedLangCode;
-        console.warn(`\u26A0\uFE0F No target_languages available from ElevenLabs status. Using requested language code: ${requestedLangCode}`);
-      }
-      dubbedAudioBuffer = await downloadDubbedAudioFromElevenLabs({
+      const downloadLangCode = targetLanguages[0] ?? toISO639_1(toLanguageCode);
+      presignedUrl = await downloadAndUploadDubbedAudio({
         dubbingId,
         languageCode: downloadLangCode,
-        credentials
-      });
-      console.warn("\u2705 Dubbed audio downloaded successfully!");
-    } catch (error) {
-      wrapError(error, "Failed to download dubbed audio");
-    }
-    console.warn("\u{1F4E4} Uploading dubbed audio to S3-compatible storage...");
-    try {
-      presignedUrl = await uploadDubbedAudioToS3({
-        dubbedAudioBuffer,
         assetId,
         toLanguageCode,
         s3Endpoint,
         s3Region,
         s3Bucket,
         storageAdapter: effectiveStorageAdapter,
-        s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
+        s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds,
+        credentials
       });
+      console.warn("\u2705 Dubbed audio staged to S3 successfully!");
     } catch (error) {
-      wrapError(error, "Failed to upload audio to S3");
+      wrapError(error, "Failed to download and upload dubbed audio");
     }
     if (uploadToMux) {
       console.warn("\u{1F4F9} Adding dubbed audio track to Mux asset...");