@mux/ai 0.28.1 → 0.29.0

package/dist/{shots-mGJfYGiO.d.ts → shots-BKd7TMFN.d.ts}

@@ -97,6 +97,24 @@ interface MuxAIOptions {
     /** Optional storage adapter for upload and presigning operations. */
     storageAdapter?: StorageAdapter;
 }
+/**
+ * Asset-relative time range used to limit workflow analysis.
+ *
+ * Times are expressed in seconds. The start is inclusive and the end is
+ * exclusive. Either boundary may be omitted to analyze from the beginning or
+ * through the end of the asset, respectively.
+ */
+interface WorkflowScope {
+    /** Inclusive start offset from the beginning of the asset, in seconds. */
+    startTime?: number;
+    /** Exclusive end offset from the beginning of the asset, in seconds. */
+    endTime?: number;
+}
+/** Base options for workflows that can analyze a bounded part of an asset. */
+interface ScopedMuxAIOptions extends MuxAIOptions {
+    /** Optional asset-relative time range to analyze. */
+    scope?: WorkflowScope;
+}
 /**
  * Workflow credentials.
  *
@@ -356,4 +374,4 @@ declare function getShotsForAsset(assetId: string, options?: ShotRequestOptions)
  */
 declare function waitForShotsForAsset(assetId: string, options?: WaitForShotsOptions): Promise<CompletedShotsResult>;
 
-export { type AssetTextTrack as A, getShotsForAsset as B, type ChunkEmbedding as C, requestShotsForAsset as D, type Encrypted as E, waitForShotsForAsset as F, type Hotspot as H, type ImageSubmissionMode as I, type MuxAIOptions as M, type PlaybackAsset as P, type StoragePutObjectInput as S, type TextChunk as T, type UsageMetadata as U, type VTTChunkingConfig as V, type WorkflowCredentials as W, type StoragePresignGetObjectInput as a, type ChunkingStrategy as b, type EncryptedPayload as c, type MuxAsset as d, type PlaybackPolicy as e, type StorageAdapter as f, type TokenChunkingConfig as g, type TokenUsage as h, type ToneType as i, type VideoEmbeddingsResult as j, type WorkflowCredentialsInput as k, type WorkflowMuxClient as l, decryptFromWorkflow as m, encryptForWorkflow as n, type CompletedShotsResult as o, type ErroredShotsResult as p, type HotspotOptions as q, type HotspotResponse as r, type PendingShotsResult as s, type Shot as t, type ShotRequestOptions as u, type ShotsResult as v, type WaitForShotsOptions as w, getHotspotsForAsset as x, getHotspotsForPlaybackId as y, getHotspotsForVideo as z };
+export { type AssetTextTrack as A, getHotspotsForPlaybackId as B, type ChunkEmbedding as C, getHotspotsForVideo as D, type Encrypted as E, getShotsForAsset as F, requestShotsForAsset as G, type Hotspot as H, type ImageSubmissionMode as I, waitForShotsForAsset as J, type MuxAIOptions as M, type PlaybackAsset as P, type StoragePutObjectInput as S, type TextChunk as T, type UsageMetadata as U, type VTTChunkingConfig as V, type WorkflowCredentials as W, type StoragePresignGetObjectInput as a, type ChunkingStrategy as b, type EncryptedPayload as c, type MuxAsset as d, type PlaybackPolicy as e, type ScopedMuxAIOptions as f, type StorageAdapter as g, type TokenChunkingConfig as h, type TokenUsage as i, type ToneType as j, type VideoEmbeddingsResult as k, type WorkflowCredentialsInput as l, type WorkflowMuxClient as m, type WorkflowScope as n, decryptFromWorkflow as o, encryptForWorkflow as p, type CompletedShotsResult as q, type ErroredShotsResult as r, type HotspotOptions as s, type HotspotResponse as t, type PendingShotsResult as u, type Shot as v, type ShotRequestOptions as w, type ShotsResult as x, type WaitForShotsOptions as y, getHotspotsForAsset as z };

package/dist/workflows/index.d.ts

@@ -1,7 +1,7 @@
-export { A as AskQuestionsOptions, j as AskQuestionsResult, k as AskQuestionsType, l as AudioTranslationOptions, m as AudioTranslationResult, n as AutoCensorProfanityOptions, B as BurnedInCaptionsAnalysis, o as BurnedInCaptionsOptions, p as BurnedInCaptionsPromptOverrides, q as BurnedInCaptionsPromptSections, r as BurnedInCaptionsResult, C as CaptionReplacement, s as CensorMode, u as Chapter, v as ChapterSystemPromptSections, w as ChaptersOptions, x as ChaptersPromptOverrides, y as ChaptersPromptSections, z as ChaptersResult, D as ChaptersType, E as DEFAULT_DESCRIPTION_LENGTH, F as DEFAULT_SUMMARY_KEYWORD_LIMIT, G as DEFAULT_TITLE_LENGTH, H as EditCaptionsOptions, J as EditCaptionsResult, K as EmbeddingsOptions, M as EmbeddingsResult, N as EngagementInsightsOptions, O as EngagementInsightsResult, P as GOOGLE_VISION_LIKELIHOOD_TO_SCORE, Q as HIVE_SEXUAL_CATEGORIES, R as HIVE_VIOLENCE_CATEGORIES, T as HiveModerationOutput, U as HiveModerationSource, V as ModerationOptions, W as ModerationProvider, X as ModerationResult, Y as MomentInsight, Z as OverallInsight, _ as ProfanityDetectionPayload, $ as Question, a0 as QuestionAnswer, a1 as QuestionAnswerType, a2 as ReplacementRecord, a3 as SummarizationOptions, a4 as SummarizationPromptOverrides, a5 as SummarizationPromptSections, a6 as SummaryAndTagsResult, a7 as SummaryType, a8 as ThumbnailModerationScore, a9 as TranslationChunkingOptions, aa as TranslationOptions, ab as TranslationPayload, ac as TranslationResult, ad as aggregateTokenUsage, ae as applyOverrideLists, af as applyReplacements, ag as askQuestions, ah as buildReplacementRegex, ai as burnedInCaptionsSchema, aj as censorVttContent, ak as chapterSchema, al as chaptersSchema, am as createReplacer, an as editCaptions, ao as extractTranscriptSegmentsForHotspots, ap as generateChapters, aq as generateEmbeddings, ar as generateEngagementInsights, as as generateVideoEmbeddings, at as getModerationScores, au as getSummaryAndTags, av as hasBurnedInCaptions, aw as mapShotsToHotspots, ax as normalizeTranslatedVtt, ay as profanityDetectionSchema, az as questionAnswerSchema, aA as shouldSplitChunkTranslationError, aB as summarySchema, aC as transformCueText, aD as translateAudio, aE as translateCaptions, aF as translationSchema } from '../index-DUVBpnj5.js';
+export { A as AskQuestionsOptions, j as AskQuestionsResult, k as AskQuestionsType, l as AudioTranslationOptions, m as AudioTranslationResult, n as AutoCensorProfanityOptions, B as BurnedInCaptionsAnalysis, o as BurnedInCaptionsOptions, p as BurnedInCaptionsPromptOverrides, q as BurnedInCaptionsPromptSections, r as BurnedInCaptionsResult, C as CaptionReplacement, s as CensorMode, u as Chapter, v as ChapterSystemPromptSections, w as ChaptersOptions, x as ChaptersPromptOverrides, y as ChaptersPromptSections, z as ChaptersResult, D as ChaptersType, E as DEFAULT_DESCRIPTION_LENGTH, F as DEFAULT_SUMMARY_KEYWORD_LIMIT, G as DEFAULT_TITLE_LENGTH, H as EditCaptionsOptions, J as EditCaptionsResult, K as EmbeddingsOptions, M as EmbeddingsResult, N as EngagementInsightsOptions, O as EngagementInsightsResult, P as GOOGLE_VISION_LIKELIHOOD_TO_SCORE, Q as HIVE_SEXUAL_CATEGORIES, R as HIVE_VIOLENCE_CATEGORIES, T as HiveModerationOutput, U as HiveModerationSource, V as ModerationOptions, W as ModerationProvider, X as ModerationResult, Y as MomentInsight, Z as OverallInsight, _ as ProfanityDetectionPayload, $ as Question, a0 as QuestionAnswer, a1 as QuestionAnswerType, a2 as ReplacementRecord, a3 as SummarizationOptions, a4 as SummarizationPromptOverrides, a5 as SummarizationPromptSections, a6 as SummaryAndTagsResult, a7 as SummaryType, a8 as ThumbnailModerationScore, a9 as TranslationChunkingOptions, aa as TranslationOptions, ab as TranslationPayload, ac as TranslationResult, ad as aggregateTokenUsage, ae as applyOverrideLists, af as applyReplacements, ag as askQuestions, ah as buildReplacementRegex, ai as burnedInCaptionsSchema, aj as censorVttContent, ak as chapterSchema, al as chaptersSchema, am as createReplacer, an as editCaptions, ao as extractTranscriptSegmentsForHotspots, ap as generateChapters, aq as generateEmbeddings, ar as generateEngagementInsights, as as generateVideoEmbeddings, at as getModerationScores, au as getSummaryAndTags, av as hasBurnedInCaptions, aw as mapShotsToHotspots, ax as normalizeTranslatedVtt, ay as profanityDetectionSchema, az as questionAnswerSchema, aA as shouldSplitChunkTranslationError, aB as summarySchema, aC as transformCueText, aD as translateAudio, aE as translateCaptions, aF as translationSchema } from '../index-DJirK4fh.js';
 import 'zod';
 import '@ai-sdk/anthropic';
 import '@ai-sdk/google';
 import '@ai-sdk/openai';
-import '../shots-mGJfYGiO.js';
+import '../shots-BKd7TMFN.js';
 import '@mux/mux-node';

package/dist/workflows/index.js

@@ -1298,6 +1298,68 @@ async function withRetry(fn, {
   throw lastError || new Error("Retry failed with unknown error");
 }
 
+// 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/lib/mux-url.ts
 var DEFAULT_MUX_IMAGE_ORIGIN = "https://image.mux.com";
 var DEFAULT_MUX_STREAM_ORIGIN = "https://stream.mux.com";
@@ -1384,13 +1446,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/lib/language-codes.ts
@@ -1829,6 +1900,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) {
@@ -1933,6 +2021,7 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
   const {
     languageCode,
     cleanTranscript = true,
+    scope,
     shouldSign,
     credentials,
     required = false
@@ -1964,9 +2053,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) {
@@ -2476,7 +2571,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");
@@ -2488,6 +2584,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).",
@@ -2506,7 +2611,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({
@@ -2535,7 +2641,8 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
         playbackId,
         storyboardWidth,
         policy === "signed",
-        credentials
+        credentials,
+        storyboardScope
       );
       imageUrl = storyboardUrl;
       if (imageSubmissionMode === "base64") {
@@ -2818,6 +2925,7 @@ async function hasBurnedInCaptionsInternal(assetId, options, collectedUsage) {
     imageDownloadOptions,
     promptOverrides,
     credentials,
+    scope,
     ...config
   } = options;
   const userPrompt = buildUserPrompt2(promptOverrides);
@@ -2828,7 +2936,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);
@@ -3027,7 +3146,8 @@ function buildUserPrompt3({
   promptOverrides,
   minChaptersPerHour = 3,
   maxChaptersPerHour = 8,
-  languageName
+  languageName,
+  scope
 }) {
   const contextSections = [
     {
@@ -3042,6 +3162,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 = {
@@ -3068,7 +3190,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     minChaptersPerHour,
     maxChaptersPerHour,
     credentials,
-    outputLanguageCode
+    outputLanguageCode,
+    scope
   } = options;
   const modelConfig = resolveLanguageModelConfig({
     ...options,
@@ -3077,6 +3200,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) {
@@ -3091,7 +3216,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(", ");
@@ -3112,7 +3238,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     promptOverrides,
     minChaptersPerHour,
     maxChaptersPerHour,
-    languageName
+    languageName,
+    scope: resolvedScope
   });
   let chaptersData = null;
   try {
@@ -3134,7 +3261,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}.`);
   }
@@ -3160,8 +3289,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,
@@ -4192,11 +4322,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(
@@ -4209,7 +4344,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(
@@ -5048,27 +5184,32 @@ function planSamplingTimestamps(options) {
 // 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;
   }
@@ -5521,12 +5662,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 };
   });
@@ -5545,7 +5698,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);
@@ -5556,7 +5710,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(
@@ -5573,7 +5736,8 @@ async function getModerationScores(assetId, options = {}) {
       cleanTranscript: true,
       shouldSign: policy === "signed",
       credentials,
-      required: true
+      required: true,
+      scope: effectiveScope
     });
     if (provider === "openai") {
       thumbnailScores = await requestOpenAITranscriptModeration(
@@ -5591,17 +5755,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",
@@ -5611,7 +5779,8 @@ async function getModerationScores(assetId, options = {}) {
       interval: thumbnailInterval,
       width: thumbnailWidth,
       shouldSign: policy === "signed",
-      credentials
+      credentials,
+      scope: renderableScope
     });
     thumbnailCount = thumbnailUrls.length;
     if (provider === "openai") {
@@ -6126,7 +6295,8 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     titleLength,
     descriptionLength,
     tagCount,
-    outputLanguageCode
+    outputLanguageCode,
+    scope
   } = options ?? {};
   if (!VALID_TONES.includes(tone)) {
     throw new MuxAiError(
@@ -6143,6 +6313,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).",
@@ -6161,7 +6340,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]);
@@ -6192,7 +6372,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);