@mux/ai 0.41.0 → 0.42.0

package/dist/{index-C3PW73qH.d.ts → index-NkSOF92U.d.ts}

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { SafetyReport, PromptOverrides, SceneContextItemV1 } from './prompts/index.js';
 import { createAnthropic } from '@ai-sdk/anthropic';
 import { createGoogleGenerativeAI } from '@ai-sdk/google';
 import { createOpenAI } from '@ai-sdk/openai';
@@ -314,56 +315,6 @@ interface ImageDownloadOptions {
     exponentialBackoff?: boolean;
 }
 
-/**
- * Which detector fired on a leak, or `null` when the text is clean.
- *
- * - `canary` — the system-prompt canary token appeared in the output.
- *   Near-zero false-positive rate; treat as a confirmed leak.
- * - `prompt_tag` — an XML-like tag taken from our prompt structure
- *   appeared in the output. Low false-positive rate.
- * - `encoded_blob` — a long run of base64- or hex-shaped characters
- *   appeared in a field expected to hold prose. Heuristic; some false
- *   positives on hashes or tokens in tech-content transcripts.
- * - `unexpected_key` — the model emitted a JSON field not declared in
- *   the schema (see {@link detectUnexpectedKeys}). Stripped silently
- *   by zod's default `.strip()` mode; this signal surfaces the
- *   smuggling attempt rather than letting it go unseen.
- */
-type LeakReason = "canary" | "prompt_tag" | "encoded_blob" | "unexpected_key" | null;
-/**
- * Per-field record of a detected leak. Collected across every scrub
- * performed inside a single workflow invocation and returned to the
- * caller in the workflow result's `safety` field.
- */
-interface ScrubbedFieldReport {
-    /**
-     * Identifier for the field that leaked. Format is workflow-specific
-     * (e.g. "reasoning[0]", "moment_insight[2]", "description"). Intended
-     * for debugging and observability; do not parse programmatically.
-     */
-    field: string;
-    /** Which detector fired — see {@link LeakReason}. */
-    reason: Exclude<LeakReason, null>;
-}
-/**
- * Aggregate safety report returned from workflows that perform
- * output-side scrubbing.
- *
- * Operators can use this to alert on suspected prompt-injection traffic
- * without inspecting log warnings. Shape is stable across workflows so a
- * single observer can consume it uniformly.
- */
-interface SafetyReport {
-    /** `true` when at least one field was suppressed by the scrubber. */
-    leaksDetected: boolean;
-    /**
-     * One entry per suppressed field. Empty (but present) when no leaks
-     * were detected. Iteration order matches the order scrubs ran, so
-     * callers can correlate entries with workflow structure if they wish.
-     */
-    scrubbedFields: ScrubbedFieldReport[];
-}
-
 type SupportedProvider = "openai" | "anthropic" | "google" | "baseten" | "openai-compatible";
 type SupportedEmbeddingProvider = "openai" | "google" | "baseten" | "openai-compatible";
 type OpenAIModelId = Parameters<ReturnType<typeof createOpenAI>["chat"]>[0];
@@ -629,28 +580,6 @@ type AskQuestionsType = z.infer<AskQuestionsSchema>;
  */
 declare function askQuestions(assetId: string, questions: Question[], options?: AskQuestionsOptions): Promise<AskQuestionsResult>;
 
-/**
- * A single section of a prompt, rendered as an XML-like tag.
- */
-interface PromptSection {
-    /** The XML tag name for this section */
-    tag: string;
-    /** The content inside the tag */
-    content: string;
-    /** Optional attributes to add to the tag (e.g., { format: "plain text" }) */
-    attributes?: Record<string, string>;
-}
-/**
- * Configuration for building a prompt section.
- * Can be a full PromptSection object, just a string (content only), or undefined to use default.
- */
-type SectionOverride = string | PromptSection | undefined;
-/**
- * User-provided overrides for prompt sections.
- * Each key can override the corresponding section's content or full definition.
- */
-type PromptOverrides<TSections extends string> = Partial<Record<TSections, SectionOverride>>;
-
 /** Structured payload returned from `hasBurnedInCaptions`. */
 interface BurnedInCaptionsResult {
     assetId: string;
@@ -859,6 +788,11 @@ interface ChaptersOptions extends ScopedMuxAIOptions {
      * Falls back to unconstrained (LLM decides) if no language metadata is available.
      */
     outputLanguageCode?: string;
+    /**
+     * Ordered scene context used to align chapter starts with scene boundaries.
+     * When omitted or empty, chapter generation retains its existing behavior.
+     */
+    sceneContext?: readonly SceneContextItemV1[];
 }
 /**
  * Sections of the chaptering system prompt that can be overridden.
@@ -1409,6 +1343,11 @@ interface SummarizationOptions extends ScopedMuxAIOptions {
     imageSubmissionMode?: ImageSubmissionMode;
     /** Fine-tune storyboard downloads when `imageSubmissionMode` === 'base64'. */
     imageDownloadOptions?: ImageDownloadOptions;
+    /**
+     * Ordered, normalized scenes that augment the storyboard and any transcript
+     * with whole-asset progression. Scene context is treated as untrusted evidence.
+     */
+    sceneContext?: readonly SceneContextItemV1[];
     /**
      * Override specific sections of the user prompt.
      * Useful for customizing the AI's output for specific use cases (SEO, social media, etc.)

package/dist/index.d.ts

@@ -1,15 +1,16 @@
-export { I as ISO639_1, a as ISO639_3, L as LanguageCodePair, M as MUX_TRACK_PASSTHROUGH_MAX_CHARS, R as ReplaceAndCreateTextTrackInput, b as ReplaceAndCreateTextTrackResult, c as ReplaceAndCreateTrackInput, d as ReplaceExistingTracksPolicy, e as ReplaceableTrackType, S as SupportedISO639_1, f as SupportedISO639_3, T as TextTrackReplacementPlan, g as TextTrackSummary, h as TextTrackTarget, i as TrackSummary, j as TrackTarget, k as buildMuxAiTrackPassthrough, l as findNameCollisionTextTracks, m as findSameLanguageTextTracks, n as getLanguageCodePair, o as getLanguageName, p as isDuplicateTrackNameError, q as isMuxGeneratedTextTrack, r as isUndeterminedLanguageCode, s as isValidISO639_1, t as isValidISO639_3, u as normalizeTrackLanguageCode, v as normalizeTrackName, w as planTextTrackReplacement, x as replaceAndCreateTextTrack, y as replaceAndCreateTrack, z as summarizeTextTrack, A as toISO639_1, B as toISO639_3, C as validateTrackPassthrough, D as workflows } from './index-C3PW73qH.js';
+export { I as ISO639_1, a as ISO639_3, L as LanguageCodePair, M as MUX_TRACK_PASSTHROUGH_MAX_CHARS, R as ReplaceAndCreateTextTrackInput, b as ReplaceAndCreateTextTrackResult, c as ReplaceAndCreateTrackInput, d as ReplaceExistingTracksPolicy, e as ReplaceableTrackType, S as SupportedISO639_1, f as SupportedISO639_3, T as TextTrackReplacementPlan, g as TextTrackSummary, h as TextTrackTarget, i as TrackSummary, j as TrackTarget, k as buildMuxAiTrackPassthrough, l as findNameCollisionTextTracks, m as findSameLanguageTextTracks, n as getLanguageCodePair, o as getLanguageName, p as isDuplicateTrackNameError, q as isMuxGeneratedTextTrack, r as isUndeterminedLanguageCode, s as isValidISO639_1, t as isValidISO639_3, u as normalizeTrackLanguageCode, v as normalizeTrackName, w as planTextTrackReplacement, x as replaceAndCreateTextTrack, y as replaceAndCreateTrack, z as summarizeTextTrack, A as toISO639_1, B as toISO639_3, C as validateTrackPassthrough, D as workflows } from './index-NkSOF92U.js';
 import { W as WorkflowCredentials, S as StoragePutObjectInput, a as StoragePresignGetObjectInput } from './shots-CUI09Ohe.js';
 export { A as AssetTextTrack, C as ChunkEmbedding, b as ChunkingStrategy, E as Encrypted, c as EncryptedPayload, I as ImageSubmissionMode, M as MuxAIOptions, d as MuxAsset, P as PlaybackAsset, e as PlaybackPolicy, f as ScopedMuxAIOptions, g as StorageAdapter, T as TextChunk, h as TokenChunkingConfig, i as TokenUsage, j as ToneType, U as UsageMetadata, V as VTTChunkingConfig, k as VideoEmbeddingsResult, l as WorkflowCredentialsInput, m as WorkflowMuxClient, n as WorkflowScope, o as decryptFromWorkflow, p as encryptForWorkflow } from './shots-CUI09Ohe.js';
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
 export { i as primitives } from './index-C2Pk7bbF.js';
 import 'zod';
+import './prompts/index.js';
 import '@ai-sdk/anthropic';
 import '@ai-sdk/google';
 import '@ai-sdk/openai';
 import '@mux/mux-node';
 
-var version = "0.41.0";
+var version = "0.42.0";
 
 type MuxAiErrorType = "validation_error" | "processing_error" | "timeout_error" | "content_policy_error";
 /**

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.41.0";
+var version = "0.42.0";
 
 // src/lib/language-codes.ts
 var ISO639_1_TO_3 = {
@@ -446,6 +446,7 @@ var PROMPT_TAG_NAMES = [
   "answer_guidelines",
   "relevance_filtering",
   "transcript_guidance",
+  "scene_guidance",
   "capabilities",
   "language_guidelines",
   "tone_guidance",
@@ -4768,6 +4769,17 @@ var AUDIO_ONLY_SYSTEM_PROMPT_OVERRIDES = {
     You receive a timestamped transcript from audio-only content with lines in the form "[12s] Transcript text".
     Use those timestamps as anchors to determine chapter start times in seconds.`
 };
+var SCENE_CONTEXT_SYSTEM_PROMPT_OVERRIDES = {
+  context: dedent4`
+    You receive a timestamped transcript with lines in the form "[12s] Caption text" and an ordered scene context.
+    Transcript timestamps are in seconds. Scene start and end timestamps are in milliseconds.
+    Use the scene progression to choose logical chapter groupings and scene starts as chapter boundaries.`,
+  constraints: dedent4`
+    - Only use information present in the transcript and scene context
+    - Return structured data that matches the requested JSON schema
+    - Do not add commentary or extra text outside the JSON
+    - When a <language> section is provided, all chapter titles MUST be written in that language`
+};
 var chaptersPromptBuilder = createPromptBuilder({
   template: {
     task: {
@@ -4805,6 +4817,7 @@ var chaptersPromptBuilder = createPromptBuilder({
 });
 function buildUserPrompt3({
   timestampedTranscript,
+  sceneContext,
   promptOverrides,
   minChaptersPerHour = 3,
   maxChaptersPerHour = 8,
@@ -4818,14 +4831,31 @@ function buildUserPrompt3({
       attributes: { format: "seconds" }
     }
   ];
+  if (sceneContext?.length) {
+    contextSections.push({
+      tag: "scene_context",
+      content: JSON.stringify(sceneContext, null, 2),
+      attributes: { timestamps: "milliseconds", trust: "untrusted_evidence" }
+    });
+  }
   if (languageName) {
     contextSections.push(createLanguageSection(languageName));
   }
+  const sceneBoundarySeconds = getSceneBoundarySeconds(sceneContext).filter(
+    (boundary) => scope ? boundary >= scope.startTime && boundary < scope.endTime : true
+  );
+  let firstChapterGuideline = "";
+  if (sceneBoundarySeconds.length > 0) {
+    firstChapterGuideline = `- The first chapter must start at ${sceneBoundarySeconds[0]}s, the first scene boundary inside the analyzed range`;
+  } else if (scope) {
+    firstChapterGuideline = `- The first chapter must start at ${scope.startTime}s`;
+  }
   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` : ""}
+    ${scope ? `- Analyze only the range from ${scope.startTime}s (inclusive) to ${scope.endTime}s (exclusive)` : ""}
+    ${firstChapterGuideline}
+    ${sceneContext?.length ? "- Use the ordered scene context to identify chapter-sized runs of consecutive scenes\n- Every chapter startTime must exactly equal a scene start_ms divided by 1000; never split a scene" : ""}
     - Chapter start times should be non-decreasing
     - Do not include text before or after the JSON`;
   const mergedOverrides = {
@@ -4834,6 +4864,32 @@ function buildUserPrompt3({
   };
   return chaptersPromptBuilder.buildWithContext(mergedOverrides, contextSections);
 }
+function getSceneBoundarySeconds(sceneContext) {
+  if (!sceneContext?.length) {
+    return [];
+  }
+  return [...new Set(sceneContext.map((scene) => scene.start_ms / 1e3))].sort((a, b) => a - b);
+}
+function alignChaptersToSceneBoundaries(chapters, sceneBoundarySeconds) {
+  if (sceneBoundarySeconds.length === 0) {
+    return chapters;
+  }
+  const chapterByBoundary = /* @__PURE__ */ new Map();
+  for (const chapter of chapters) {
+    const startTime = sceneBoundarySeconds.reduce(
+      (closest, boundary) => Math.abs(boundary - chapter.startTime) < Math.abs(closest - chapter.startTime) ? boundary : closest
+    );
+    const distance = Math.abs(startTime - chapter.startTime);
+    const existing = chapterByBoundary.get(startTime);
+    if (!existing || distance === 0 && existing.distance !== 0) {
+      chapterByBoundary.set(startTime, {
+        chapter: { ...chapter, startTime },
+        distance
+      });
+    }
+  }
+  return [...chapterByBoundary.values()].map(({ chapter }) => chapter).sort((a, b) => a.startTime - b.startTime);
+}
 async function generateChapters(assetId, options = {}) {
   "use workflow";
   const collectedUsage = [];
@@ -4853,7 +4909,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     maxChaptersPerHour,
     credentials,
     outputLanguageCode,
-    scope
+    scope,
+    sceneContext
   } = options;
   const modelConfig = resolveLanguageModelConfig({
     ...options,
@@ -4895,8 +4952,18 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
   }
   const resolvedLanguageCode = outputLanguageCode && outputLanguageCode !== "auto" ? outputLanguageCode : getReliableLanguageCode(transcriptResult.track) ?? languageCode;
   const languageName = resolvedLanguageCode ? getLanguageName(resolvedLanguageCode) : void 0;
+  const sceneBoundarySeconds = getSceneBoundarySeconds(sceneContext).filter(
+    (boundary) => resolvedScope ? boundary >= resolvedScope.startTime && boundary < resolvedScope.endTime : true
+  );
+  if (sceneContext?.length && sceneBoundarySeconds.length === 0) {
+    throw new MuxAiError(
+      "Scene context has no chapter boundaries within the requested scope.",
+      { type: "validation_error" }
+    );
+  }
   const userPrompt = buildUserPrompt3({
     timestampedTranscript,
+    sceneContext,
     promptOverrides,
     minChaptersPerHour,
     maxChaptersPerHour,
@@ -4905,7 +4972,11 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
   });
   let chaptersData = null;
   try {
-    const systemPrompt = isAudioOnly ? chapterSystemPromptBuilder.build(AUDIO_ONLY_SYSTEM_PROMPT_OVERRIDES) : chapterSystemPromptBuilder.build();
+    const systemPromptOverrides = {
+      ...isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT_OVERRIDES : {},
+      ...sceneContext?.length ? SCENE_CONTEXT_SYSTEM_PROMPT_OVERRIDES : {}
+    };
+    const systemPrompt = chapterSystemPromptBuilder.build(systemPromptOverrides);
     chaptersData = await generateChaptersWithAI({
       provider: modelConfig.provider,
       modelId: modelConfig.modelId,
@@ -4923,9 +4994,13 @@ 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").filter(
+  const scopedChapters = 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);
+  const validChapters = alignChaptersToSceneBoundaries(
+    scopedChapters,
+    sceneBoundarySeconds
+  );
   if (validChapters.length === 0) {
     throw new MuxAiError(`Failed to generate valid chapters for asset ${assetId}.`);
   }
@@ -4951,9 +5026,11 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
   if (scrubbedChapters.length === 0) {
     throw new MuxAiError(`Failed to generate valid chapters for asset ${assetId}.`);
   }
-  const firstChapterStartTime = resolvedScope?.startTime ?? 0;
-  if (scrubbedChapters[0].startTime !== firstChapterStartTime) {
-    scrubbedChapters[0].startTime = firstChapterStartTime;
+  if (sceneBoundarySeconds.length === 0) {
+    const firstChapterStartTime = resolvedScope?.startTime ?? 0;
+    if (scrubbedChapters[0].startTime !== firstChapterStartTime) {
+      scrubbedChapters[0].startTime = firstChapterStartTime;
+    }
   }
   const usageWithMetadata = {
     ...usage,
@@ -7060,14 +7137,44 @@ function buildDescriptionGuidance(wordCount, contentType) {
     Write in present tense. Be specific about what is discussed or presented rather than making assumptions.
     Focus on the spoken content and any key insights, dialogue, or narrative elements.`;
 }
-function createSummarizationBuilder({ titleLength, descriptionLength, tagCount } = {}) {
+function buildSceneAwareDescriptionGuidance(wordCount) {
+  if (wordCount < DESCRIPTION_LENGTH_THRESHOLD_SMALL) {
+    return dedent6`A brief summary of the video in no more than ${wordCount} words. Shorter is fine.
+      Focus on the single most important subject or action across the ordered scenes.
+      Use the storyboard as direct visual evidence and the scene context to preserve progression.
+      Write in present tense.`;
+  }
+  if (wordCount > DESCRIPTION_LENGTH_THRESHOLD_LARGE) {
+    return dedent6`A detailed summary that describes what happens across the ordered scenes.
+      Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
+      Be thorough: cover subjects, actions, setting, progression, and notable details supported across scenes.
+      Use the storyboard as direct visual evidence and the scene context to preserve progression.
+      Write in present tense. If the transcript provides dialogue or narration, incorporate key points while preserving scene progression.`;
+  }
+  return dedent6`A summary that describes what happens across the ordered scenes.
+    Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
+    Cover the main subjects, actions, setting, and notable progression supported across scenes.
+    Use the storyboard as direct visual evidence and the scene context to preserve progression.
+    Write in present tense. If the transcript provides dialogue or narration, incorporate key points while preserving scene progression.`;
+}
+function createSummarizationBuilder({ titleLength, descriptionLength, tagCount } = {}, { hasSceneContext = false } = {}) {
   const titleLimit = titleLength ?? DEFAULT_TITLE_LENGTH;
   const keywordLimit = tagCount ?? DEFAULT_SUMMARY_KEYWORD_LIMIT;
+  const task = hasSceneContext ? "Analyze the storyboard frames and ordered scene context together, then generate metadata that captures the full progression of the video content." : "Analyze the storyboard frames and generate metadata that captures the essence of the video content.";
+  const qualityGuidelines = hasSceneContext ? dedent6`
+      - Follow scene_index order to understand what begins, develops, and concludes
+      - Use scene narratives and concepts as grounded evidence, preserving consistent terminology across the output
+      - Use the storyboard as direct visual evidence for whole-asset details
+      - Balance brevity with informativeness` : dedent6`
+      - Examine all frames to understand the full context and progression
+      - Be precise: "golden retriever" is better than "dog" when identifiable
+      - Capture the narrative: what begins, develops, and concludes
+      - Balance brevity with informativeness`;
   return createPromptBuilder({
     template: {
       task: {
         tag: "task",
-        content: "Analyze the storyboard frames and generate metadata that captures the essence of the video content."
+        content: task
       },
       title: {
         tag: "title_requirements",
@@ -7080,7 +7187,7 @@ function createSummarizationBuilder({ titleLength, descriptionLength, tagCount }
       },
       description: {
         tag: "description_requirements",
-        content: buildDescriptionGuidance(descriptionLength ?? DEFAULT_DESCRIPTION_LENGTH, "video")
+        content: hasSceneContext ? buildSceneAwareDescriptionGuidance(descriptionLength ?? DEFAULT_DESCRIPTION_LENGTH) : buildDescriptionGuidance(descriptionLength ?? DEFAULT_DESCRIPTION_LENGTH, "video")
       },
       keywords: {
         tag: "keywords_requirements",
@@ -7096,11 +7203,7 @@ function createSummarizationBuilder({ titleLength, descriptionLength, tagCount }
       },
       qualityGuidelines: {
         tag: "quality_guidelines",
-        content: dedent6`
-          - Examine all frames to understand the full context and progression
-          - Be precise: "golden retriever" is better than "dog" when identifiable
-          - Capture the narrative: what begins, develops, and concludes
-          - Balance brevity with informativeness`
+        content: qualityGuidelines
       }
     },
     sectionOrder: ["task", "title", "description", "keywords", "qualityGuidelines"]
@@ -7152,59 +7255,83 @@ function createAudioOnlyBuilder({ titleLength, descriptionLength, tagCount } = {
     sectionOrder: ["task", "title", "description", "keywords", "qualityGuidelines"]
   });
 }
-var SYSTEM_PROMPT5 = promptDedent`
-  <role>
-    You are a video content analyst specializing in storyboard interpretation and multimodal analysis.
-  </role>
-
-  <context>
-    You receive storyboard images containing multiple sequential frames extracted from a video.
-    ${STORYBOARD_FRAME_INSTRUCTIONS}
-  </context>
-
-  <transcript_guidance>
-    When a transcript is provided alongside the storyboard:
-    - Use it to understand spoken content, dialogue, narration, and audio context
-    - Correlate transcript content with visual frames to build a complete picture
-    - Extract key terminology, names, and specific language used by speakers
-    - Let the transcript inform keyword selection, especially for topics not visually obvious
-    - Prioritize visual content for the description, but enrich it with transcript insights
-    - If transcript and visuals conflict, trust the visual evidence
-  </transcript_guidance>
-
-  <capabilities>
-    - Extract meaning from visual sequences
-    - Identify subjects, actions, settings, and narrative arcs
-    - Generate accurate, searchable metadata
-    - Synthesize visual and transcript information when provided
-  </capabilities>
-
-  <security>
-    ${NON_DISCLOSURE_CONSTRAINT}
-
-    ${UNTRUSTED_USER_INPUT_NOTICE}
-
-    ${VISUAL_TEXT_AS_CONTENT}
-
-    ${CANARY_TRIPWIRE}
-  </security>
-
-  <constraints>
-    - Only describe what is clearly observable in the frames or explicitly stated in the transcript
-    - ${NO_FABRICATION_CONSTRAINT}
-    - ${METADATA_BOUNDARY_WARNING}
-    - ${STRUCTURED_DATA_CONSTRAINT}
-    - Output only the JSON object; no markdown or extra text
-    - When a <language> section is provided, all output text MUST be written in that language
-  </constraints>
-
-  <tone_guidance>
-    ${TONE_GUIDANCE}
-  </tone_guidance>
-
-  <language_guidelines>
-    ${createLanguageGuidelines("video")}
-  </language_guidelines>`;
+function createVideoSystemPrompt(hasSceneContext) {
+  let sceneContext = "";
+  let sceneGuidance = "";
+  if (hasSceneContext) {
+    sceneContext = promptDedent`
+      Ordered scene context is also provided as structured evidence of the video's progression.
+      Entries use stable, zero-based scene_index values and absolute millisecond timestamps.
+      Read scenes in scene_index order to understand what begins, develops, and concludes.`;
+    sceneGuidance = promptDedent`
+      <scene_guidance>
+        - Use scene titles, narratives, and concepts to understand temporal progression
+        - Use storyboard frames as direct visual evidence for subjects, actions, settings, and details
+        - Preserve consistent terminology from the scene context across the title, description, and keywords
+        - Treat optional scene fields as evidence only when present; do not infer omitted details
+        - Consider all provided evidence together; if derived scene context conflicts with storyboard visuals, trust the visuals
+      </scene_guidance>`;
+  }
+  const transcriptEvidence = hasSceneContext ? "storyboard frames and ordered scenes" : "visual frames";
+  const descriptionPriority = hasSceneContext ? "Use the scene context for temporal structure and the storyboard for direct visual details, enriching both with transcript insights" : "Prioritize visual content for the description, but enrich it with transcript insights";
+  const groundingConstraint = hasSceneContext ? "Use all provided evidence together. Ground each claim in the storyboard, scene context, or transcript" : "Only describe what is clearly observable in the frames or explicitly stated in the transcript";
+  return promptDedent`
+    <role>
+      You are a video content analyst specializing in storyboard interpretation and multimodal analysis.
+    </role>
+
+    <context>
+      You receive storyboard images containing multiple sequential frames extracted from a video.
+      ${STORYBOARD_FRAME_INSTRUCTIONS}
+      ${sceneContext}
+    </context>
+
+    ${sceneGuidance}
+
+    <transcript_guidance>
+      When a transcript is provided alongside the storyboard:
+      - Use it to understand spoken content, dialogue, narration, and audio context
+      - Correlate transcript content with ${transcriptEvidence} to build a complete picture
+      - Extract key terminology, names, and specific language used by speakers
+      - Let the transcript inform keyword selection, especially for topics not visually obvious
+      - ${descriptionPriority}
+      - If transcript and visuals conflict, trust the visual evidence
+    </transcript_guidance>
+
+    <capabilities>
+      - Extract meaning from visual sequences
+      - Identify subjects, actions, settings, and narrative arcs
+      - Generate accurate, searchable metadata
+      - Synthesize visual and transcript information when provided
+    </capabilities>
+
+    <security>
+      ${NON_DISCLOSURE_CONSTRAINT}
+
+      ${UNTRUSTED_USER_INPUT_NOTICE}
+
+      ${VISUAL_TEXT_AS_CONTENT}
+
+      ${CANARY_TRIPWIRE}
+    </security>
+
+    <constraints>
+      - ${groundingConstraint}
+      - ${NO_FABRICATION_CONSTRAINT}
+      - ${METADATA_BOUNDARY_WARNING}
+      - ${STRUCTURED_DATA_CONSTRAINT}
+      - Output only the JSON object; no markdown or extra text
+      - When a <language> section is provided, all output text MUST be written in that language
+    </constraints>
+
+    <tone_guidance>
+      ${TONE_GUIDANCE}
+    </tone_guidance>
+
+    <language_guidelines>
+      ${createLanguageGuidelines("video")}
+    </language_guidelines>`;
+}
 var AUDIO_ONLY_SYSTEM_PROMPT3 = promptDedent`
   <role>
     You are an audio content analyst specializing in transcript analysis and metadata generation.
@@ -7255,6 +7382,16 @@ var AUDIO_ONLY_SYSTEM_PROMPT3 = promptDedent`
   <language_guidelines>
     ${createLanguageGuidelines("audio")}
   </language_guidelines>`;
+function createSceneContextSection(sceneContext) {
+  return {
+    tag: "scene_context",
+    content: JSON.stringify(sceneContext),
+    attributes: {
+      format: "json",
+      order: "scene_index_ascending"
+    }
+  };
+}
 function buildUserPrompt5({
   tone,
   transcriptText,
@@ -7264,7 +7401,8 @@ function buildUserPrompt5({
   titleLength,
   descriptionLength,
   tagCount,
-  languageName
+  languageName,
+  sceneContext
 }) {
   const contextSections = [createToneSection(TONE_INSTRUCTIONS[tone])];
   if (languageName) {
@@ -7279,11 +7417,15 @@ function buildUserPrompt5({
     const format = isCleanTranscript ? "plain text" : "WebVTT";
     contextSections.push(createTranscriptSection(transcriptText, format));
   }
+  const hasSceneContext = !isAudioOnly && Boolean(sceneContext?.length);
+  if (hasSceneContext && sceneContext) {
+    contextSections.push(createSceneContextSection(sceneContext));
+  }
   const constraints = { titleLength, descriptionLength, tagCount };
-  const promptBuilder = isAudioOnly ? createAudioOnlyBuilder(constraints) : createSummarizationBuilder(constraints);
+  const promptBuilder = isAudioOnly ? createAudioOnlyBuilder(constraints) : createSummarizationBuilder(constraints, { hasSceneContext });
   return promptBuilder.buildWithContext(promptOverrides, contextSections);
 }
-async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, systemPrompt, descriptionLength, credentials) {
+async function analyzeVideo(imageDataUrl, provider, modelId, userPrompt, systemPrompt, descriptionLength, credentials) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const schema = buildSummarySchema(descriptionLength);
@@ -7299,10 +7441,10 @@ async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, s
     messages: [
       {
         role: "user",
-        content: [
+        content: imageDataUrl ? [
           { type: "text", text: userPrompt },
           { type: "image", image: imageDataUrl }
-        ]
+        ] : userPrompt
       }
     ]
   }));
@@ -7412,6 +7554,7 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     cleanTranscript = true,
     imageSubmissionMode = "url",
     imageDownloadOptions,
+    sceneContext,
     promptOverrides,
     credentials,
     titleLength,
@@ -7435,6 +7578,7 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, workflowCredentials, options?.assetSnapshot);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
   const isAudioOnly = isAudioOnlyAsset(assetData);
+  const hasSceneContext = !isAudioOnly && Boolean(sceneContext?.length);
   const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
   const storyboardScope = isAudioOnly ? void 0 : resolveRenderableVideoScope(
     effectiveScope,
@@ -7451,7 +7595,8 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     );
   }
   const signingContext = await resolveMuxSigningContext(workflowCredentials);
-  if (policy === "signed" && !signingContext) {
+  const requiresSignedPlaybackAccess = includeTranscript || !isAudioOnly;
+  if (policy === "signed" && requiresSignedPlaybackAccess && !signingContext) {
     throw new MuxAiError(
       "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
       { type: "validation_error" }
@@ -7477,11 +7622,15 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     titleLength,
     descriptionLength,
     tagCount,
-    languageName
+    languageName,
+    sceneContext: hasSceneContext ? sceneContext : void 0
   });
   let analysisResponse;
   let imageUrl;
-  const systemPrompt = isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT3 : SYSTEM_PROMPT5;
+  let systemPrompt = AUDIO_ONLY_SYSTEM_PROMPT3;
+  if (!isAudioOnly) {
+    systemPrompt = createVideoSystemPrompt(hasSceneContext);
+  }
   const effectiveDescriptionLength = descriptionLength ?? DEFAULT_DESCRIPTION_LENGTH;
   try {
     if (isAudioOnly) {
@@ -7504,7 +7653,7 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
       imageUrl = storyboardUrl;
       if (imageSubmissionMode === "base64") {
         const downloadResult = await downloadImageAsBase64(storyboardUrl, imageDownloadOptions);
-        analysisResponse = await analyzeStoryboard2(
+        analysisResponse = await analyzeVideo(
           downloadResult.base64Data,
           modelConfig.provider,
           modelConfig.modelId,
@@ -7514,7 +7663,7 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
           workflowCredentials
         );
       } else {
-        analysisResponse = await analyzeStoryboard2(
+        analysisResponse = await analyzeVideo(
           storyboardUrl,
           modelConfig.provider,
           modelConfig.modelId,
@@ -8099,7 +8248,7 @@ import { z as z9 } from "zod";
 var translationSchema = z9.object({
   translation: z9.string()
 });
-var SYSTEM_PROMPT6 = promptDedent`
+var SYSTEM_PROMPT5 = promptDedent`
   You are a subtitle translation expert. Translate VTT subtitle files to the target language specified by the user.
   You may receive either a full VTT file or a chunk from a larger VTT.
   Preserve all timestamps, cue ordering, and VTT formatting exactly as they appear.
@@ -8424,7 +8573,7 @@ async function translateVttWithAI({
     model,
     maxRetries: 0,
     output: Output7.object({ schema: translationSchema }),
-    system: SYSTEM_PROMPT6,
+    system: SYSTEM_PROMPT5,
     messages: [
       {
         role: "user",