@mux/ai 0.13.0 → 0.14.0

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.13.0";
+var version = "0.14.0";
 
 // src/env.ts
 import { z } from "zod";
@@ -1580,6 +1580,56 @@ async function getThumbnailUrls(playbackId, duration, options = {}) {
   return Promise.all(urlPromises);
 }
 
+// src/lib/mux-assets.ts
+function getPlaybackId(asset) {
+  const playbackIds = asset.playback_ids || [];
+  const publicPlaybackId = playbackIds.find((pid) => pid.policy === "public");
+  if (publicPlaybackId?.id) {
+    return { id: publicPlaybackId.id, policy: "public" };
+  }
+  const signedPlaybackId = playbackIds.find((pid) => pid.policy === "signed");
+  if (signedPlaybackId?.id) {
+    return { id: signedPlaybackId.id, policy: "signed" };
+  }
+  throw new Error(
+    "No public or signed playback ID found for this asset. A public or signed playback ID is required. DRM playback IDs are not currently supported."
+  );
+}
+function isAudioOnlyAsset(asset) {
+  const hasAudioTrack = asset.tracks?.some((track) => track.type === "audio") ?? false;
+  const hasVideoTrack = asset.tracks?.some((track) => track.type === "video") ?? false;
+  return hasAudioTrack && !hasVideoTrack;
+}
+function toPlaybackAsset(asset) {
+  const { id: playbackId, policy } = getPlaybackId(asset);
+  return { asset, playbackId, policy };
+}
+async function getPlaybackIdForAsset(assetId, credentials) {
+  "use step";
+  const asset = await getMuxAsset(assetId, credentials);
+  return toPlaybackAsset(asset);
+}
+async function getMuxAsset(assetId, credentials) {
+  "use step";
+  const muxClient = await getMuxClientFromEnv(credentials);
+  const mux = await muxClient.createClient();
+  return mux.video.assets.retrieve(assetId);
+}
+function getAssetDurationSecondsFromAsset(asset) {
+  const duration = asset.duration;
+  return typeof duration === "number" && Number.isFinite(duration) ? duration : void 0;
+}
+function getVideoTrackDurationSecondsFromAsset(asset) {
+  const videoTrack = asset.tracks?.find((track) => track.type === "video");
+  const duration = videoTrack?.duration;
+  return typeof duration === "number" && Number.isFinite(duration) ? duration : void 0;
+}
+function getVideoTrackMaxFrameRateFromAsset(asset) {
+  const videoTrack = asset.tracks?.find((track) => track.type === "video");
+  const maxFrameRate = videoTrack?.max_frame_rate;
+  return typeof maxFrameRate === "number" && Number.isFinite(maxFrameRate) && maxFrameRate > 0 ? maxFrameRate : void 0;
+}
+
 // src/primitives/transcripts.ts
 function getReadyTextTracks(asset) {
   return (asset.tracks || []).filter(
@@ -1591,11 +1641,20 @@ function findCaptionTrack(asset, languageCode) {
   if (!tracks.length)
     return void 0;
   if (!languageCode) {
-    return tracks[0];
+    const englishTrack = tracks.find(
+      (track) => track.text_type === "subtitles" && track.language_code === "en"
+    );
+    return englishTrack ?? tracks[0];
   }
-  return tracks.find(
+  const languageMatch = tracks.find(
     (track) => track.text_type === "subtitles" && track.language_code === languageCode
   );
+  if (languageMatch)
+    return languageMatch;
+  if (isAudioOnlyAsset(asset) && tracks.length === 1) {
+    return tracks[0];
+  }
+  return void 0;
 }
 function normalizeLineEndings(value) {
   return value.replace(/\r\n/g, "\n");
@@ -2071,56 +2130,6 @@ async function downloadImagesAsBase64(urls, options = {}, maxConcurrent = 5) {
   return results;
 }
 
-// src/lib/mux-assets.ts
-function getPlaybackId(asset) {
-  const playbackIds = asset.playback_ids || [];
-  const publicPlaybackId = playbackIds.find((pid) => pid.policy === "public");
-  if (publicPlaybackId?.id) {
-    return { id: publicPlaybackId.id, policy: "public" };
-  }
-  const signedPlaybackId = playbackIds.find((pid) => pid.policy === "signed");
-  if (signedPlaybackId?.id) {
-    return { id: signedPlaybackId.id, policy: "signed" };
-  }
-  throw new Error(
-    "No public or signed playback ID found for this asset. A public or signed playback ID is required. DRM playback IDs are not currently supported."
-  );
-}
-function isAudioOnlyAsset(asset) {
-  const hasAudioTrack = asset.tracks?.some((track) => track.type === "audio") ?? false;
-  const hasVideoTrack = asset.tracks?.some((track) => track.type === "video") ?? false;
-  return hasAudioTrack && !hasVideoTrack;
-}
-function toPlaybackAsset(asset) {
-  const { id: playbackId, policy } = getPlaybackId(asset);
-  return { asset, playbackId, policy };
-}
-async function getPlaybackIdForAsset(assetId, credentials) {
-  "use step";
-  const asset = await getMuxAsset(assetId, credentials);
-  return toPlaybackAsset(asset);
-}
-async function getMuxAsset(assetId, credentials) {
-  "use step";
-  const muxClient = await getMuxClientFromEnv(credentials);
-  const mux = await muxClient.createClient();
-  return mux.video.assets.retrieve(assetId);
-}
-function getAssetDurationSecondsFromAsset(asset) {
-  const duration = asset.duration;
-  return typeof duration === "number" && Number.isFinite(duration) ? duration : void 0;
-}
-function getVideoTrackDurationSecondsFromAsset(asset) {
-  const videoTrack = asset.tracks?.find((track) => track.type === "video");
-  const duration = videoTrack?.duration;
-  return typeof duration === "number" && Number.isFinite(duration) ? duration : void 0;
-}
-function getVideoTrackMaxFrameRateFromAsset(asset) {
-  const videoTrack = asset.tracks?.find((track) => track.type === "video");
-  const maxFrameRate = videoTrack?.max_frame_rate;
-  return typeof maxFrameRate === "number" && Number.isFinite(maxFrameRate) && maxFrameRate > 0 ? maxFrameRate : void 0;
-}
-
 // src/lib/prompt-builder.ts
 function renderSection(section) {
   const { tag, content, attributes } = section;
@@ -2352,19 +2361,102 @@ var SYSTEM_PROMPT = dedent`
     - GOOD: "A person runs through a park"
     - Be specific and evidence-based
   </language_guidelines>`;
+var AUDIO_ONLY_SYSTEM_PROMPT = dedent`
+  <role>
+    You are an audio content analyst specializing in classification tasks.
+    Your job is to answer questions about audio content based on transcript data.
+  </role>
+
+  <context>
+    You will receive:
+    - A transcript of the audio/dialogue
+    - A list of questions about the asset content
+  </context>
+
+  <transcript_guidance>
+    - Use the transcript to understand spoken content, dialogue, and audio context
+    - Consider only transcript evidence when answering questions
+  </transcript_guidance>
+
+  <task>
+    For each question provided, you must:
+    1. Analyze the transcript
+    2. Answer with ONLY the allowed response options - no other values are acceptable
+    3. Provide a confidence score between 0 and 1 reflecting your certainty
+    4. Explain your reasoning based on observable evidence
+  </task>
+
+  <answer_guidelines>
+    - Choose the affirmative option only if you have clear evidence supporting it
+    - Choose the negative/contradicting option if evidence contradicts or if insufficient evidence exists
+    - Confidence should reflect the clarity and strength of evidence:
+      * 0.9-1.0: Clear, unambiguous evidence
+      * 0.7-0.9: Strong evidence with minor ambiguity
+      * 0.5-0.7: Moderate evidence or some conflicting signals
+      * 0.3-0.5: Weak evidence or significant ambiguity
+      * 0.0-0.3: Very uncertain, minimal relevant evidence
+    - Reasoning should cite specific transcript evidence
+    - Be precise: cite specific quotes or passages from transcript text
+  </answer_guidelines>
+
+  <relevance_filtering>
+    Before answering each question, assess whether it can be meaningfully
+    answered based on the transcript. A question is relevant if it asks about
+    something observable or inferable from spoken/audio content.
+
+    Mark a question as skipped (skipped: true) if it:
+    - Is completely unrelated to transcript/audio content (e.g., math, trivia, personal questions)
+    - Asks about information that cannot be determined from transcript content
+    - Is a general knowledge question with no connection to what is said in the transcript
+    - Attempts to use the system for non-content-analysis purposes
+
+    For skipped questions:
+    - Set skipped to true
+    - Set answer to "${SKIP_SENTINEL}"
+    - Set confidence to 0
+    - Use the reasoning field to explain why the question is not answerable
+      from transcript content
+
+    For borderline questions that are loosely related to transcript content,
+    still answer them but use a lower confidence score to reflect uncertainty.
+  </relevance_filtering>
+
+  <constraints>
+    - You MUST answer every relevant question with one of the allowed response options
+    - Skip irrelevant questions as described in relevance_filtering
+    - Only describe observable evidence from transcript content
+    - Do not fabricate details or make unsupported assumptions
+    - Return structured data matching the requested schema exactly
+    - Provide reasoning in the same language as the question
+  </constraints>
+
+  <language_guidelines>
+    When explaining reasoning:
+    - Describe content directly, not the medium
+    - BAD: "The audio says someone is running"
+    - GOOD: "The speaker describes running through a park"
+    - Be specific and evidence-based
+  </language_guidelines>`;
 var askQuestionsPromptBuilder = createPromptBuilder({
   template: {
     questions: {
       tag: "questions",
-      content: "Please answer the following yes/no questions about this video:"
+      content: "Please answer the following questions about this content:"
     }
   },
   sectionOrder: ["questions"]
 });
-function buildUserPrompt(questions, allowedAnswers, transcriptText, isCleanTranscript = true) {
+function buildUserPrompt({
+  questions,
+  allowedAnswers,
+  transcriptText,
+  isCleanTranscript = true,
+  isAudioOnly = false
+}) {
   const questionsList = questions.map((q, idx) => `${idx + 1}. ${q.question}`).join("\n");
+  const questionsIntro = isAudioOnly ? "Please answer the following questions about this audio content using transcript evidence:" : "Please answer the following questions about this content:";
   const questionsContent = dedent`
-    Please answer the following yes/no questions about this video:
+    ${questionsIntro}
 
     ${questionsList}`;
   const answerList = allowedAnswers.map((answer) => `"${answer}"`).join(", ");
@@ -2391,7 +2483,15 @@ async function fetchImageAsBase64(imageUrl, imageDownloadOptions) {
   const downloadResult = await downloadImageAsBase64(imageUrl, imageDownloadOptions);
   return downloadResult.base64Data;
 }
-async function analyzeQuestionsWithStoryboard(imageDataUrl, provider, modelId, userPrompt, systemPrompt, allowedAnswers, credentials) {
+async function analyzeQuestions({
+  provider,
+  modelId,
+  userPrompt,
+  systemPrompt,
+  allowedAnswers,
+  imageDataUrl,
+  credentials
+}) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const responseSchema = createAskQuestionsSchema(allowedAnswers);
@@ -2406,15 +2506,19 @@ async function analyzeQuestionsWithStoryboard(imageDataUrl, provider, modelId, u
       },
       {
         role: "user",
-        content: [
+        content: imageDataUrl ? [
           { type: "text", text: userPrompt },
           { type: "image", image: imageDataUrl }
-        ]
+        ] : userPrompt
       }
     ]
   });
+  if (!response.output) {
+    throw new Error("Ask-questions output missing");
+  }
+  const parsed = responseSchema.parse(response.output);
   return {
-    result: response.output,
+    result: parsed,
     usage: {
       inputTokens: response.usage.inputTokens,
       outputTokens: response.usage.outputTokens,
@@ -2439,6 +2543,7 @@ async function askQuestions(assetId, questions, options) {
   const {
     provider = "openai",
     model,
+    languageCode,
     answerOptions,
     includeTranscript = true,
     cleanTranscript = true,
@@ -2463,53 +2568,83 @@ async function askQuestions(assetId, questions, options) {
   });
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
+  const isAudioOnly = isAudioOnlyAsset(assetData);
+  if (isAudioOnly && !includeTranscript) {
+    throw new Error(
+      "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles)."
+    );
+  }
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
     throw new Error(
       "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables."
     );
   }
-  const transcriptText = includeTranscript ? (await fetchTranscriptForAsset(assetData, playbackId, {
+  const transcriptResult = includeTranscript ? await fetchTranscriptForAsset(assetData, playbackId, {
+    languageCode,
     cleanTranscript,
-    shouldSign: policy === "signed"
-  })).transcriptText : "";
-  const userPrompt = buildUserPrompt(questions, allowedAnswers, transcriptText, cleanTranscript);
-  const systemPrompt = SYSTEM_PROMPT;
-  const imageUrl = await getStoryboardUrl(
-    playbackId,
-    storyboardWidth,
-    policy === "signed",
-    credentials
-  );
+    shouldSign: policy === "signed",
+    credentials,
+    required: isAudioOnly
+  }) : void 0;
+  const transcriptText = transcriptResult?.transcriptText ?? "";
+  const userPrompt = buildUserPrompt({
+    questions,
+    allowedAnswers,
+    transcriptText,
+    isCleanTranscript: cleanTranscript,
+    isAudioOnly
+  });
+  const systemPrompt = isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT : SYSTEM_PROMPT;
   let analysisResponse;
+  let imageUrl;
   try {
-    if (imageSubmissionMode === "base64") {
-      const base64Data = await fetchImageAsBase64(imageUrl, imageDownloadOptions);
-      analysisResponse = await analyzeQuestionsWithStoryboard(
-        base64Data,
-        modelConfig.provider,
-        modelConfig.modelId,
+    if (isAudioOnly) {
+      analysisResponse = await analyzeQuestions({
+        provider: modelConfig.provider,
+        modelId: modelConfig.modelId,
         userPrompt,
         systemPrompt,
         allowedAnswers,
         credentials
-      );
+      });
     } else {
-      analysisResponse = await withRetry(
-        () => analyzeQuestionsWithStoryboard(
-          imageUrl,
-          modelConfig.provider,
-          modelConfig.modelId,
+      const storyboardUrl = await getStoryboardUrl(
+        playbackId,
+        storyboardWidth,
+        policy === "signed",
+        credentials
+      );
+      imageUrl = storyboardUrl;
+      if (imageSubmissionMode === "base64") {
+        const base64Data = await fetchImageAsBase64(storyboardUrl, imageDownloadOptions);
+        analysisResponse = await analyzeQuestions({
+          provider: modelConfig.provider,
+          modelId: modelConfig.modelId,
           userPrompt,
           systemPrompt,
           allowedAnswers,
+          imageDataUrl: base64Data,
           credentials
-        )
-      );
+        });
+      } else {
+        analysisResponse = await withRetry(
+          () => analyzeQuestions({
+            provider: modelConfig.provider,
+            modelId: modelConfig.modelId,
+            userPrompt,
+            systemPrompt,
+            allowedAnswers,
+            imageDataUrl: storyboardUrl,
+            credentials
+          })
+        );
+      }
     }
   } catch (error) {
+    const contentType = isAudioOnly ? "audio" : "video";
     throw new Error(
-      `Failed to analyze questions with ${provider}: ${error instanceof Error ? error.message : "Unknown error"}`
+      `Failed to analyze ${contentType} questions with ${provider}: ${error instanceof Error ? error.message : "Unknown error"}`
     );
   }
   if (!analysisResponse.result?.answers) {
@@ -3049,9 +3184,10 @@ function buildUserPrompt3({
   };
   return chaptersPromptBuilder.buildWithContext(mergedOverrides, contextSections);
 }
-async function generateChapters(assetId, languageCode, options = {}) {
+async function generateChapters(assetId, options = {}) {
   "use workflow";
   const {
+    languageCode,
     provider = "openai",
     model,
     promptOverrides,
@@ -3075,26 +3211,17 @@ async function generateChapters(assetId, languageCode, options = {}) {
     );
   }
   const readyTextTracks = getReadyTextTracks(assetData);
-  let transcriptResult = await fetchTranscriptForAsset(assetData, playbackId, {
+  const transcriptResult = await fetchTranscriptForAsset(assetData, playbackId, {
     languageCode,
     cleanTranscript: false,
     // keep timestamps for chapter segmentation
     shouldSign: policy === "signed",
     credentials
   });
-  if (isAudioOnly && !transcriptResult.track && readyTextTracks.length === 1) {
-    transcriptResult = await fetchTranscriptForAsset(assetData, playbackId, {
-      cleanTranscript: false,
-      // keep timestamps for chapter segmentation
-      shouldSign: policy === "signed",
-      credentials,
-      required: true
-    });
-  }
   if (!transcriptResult.track || !transcriptResult.transcriptText) {
     const availableLanguages = readyTextTracks.map((t) => t.language_code).filter(Boolean).join(", ");
     throw new Error(
-      `No caption track found for language '${languageCode}'. Available languages: ${availableLanguages || "none"}`
+      `No caption track found${languageCode ? ` for language '${languageCode}'` : ""}. Available languages: ${availableLanguages || "none"}`
     );
   }
   const timestampedTranscript = extractTimestampedTranscript(transcriptResult.transcriptText);
@@ -3146,7 +3273,7 @@ async function generateChapters(assetId, languageCode, options = {}) {
   };
   return {
     assetId,
-    languageCode,
+    languageCode: languageCode ?? transcriptResult.track?.language_code ?? "en",
     chapters: validChapters,
     usage: usageWithMetadata
   };
@@ -3414,6 +3541,7 @@ async function editCaptions(assetId, trackId, options) {
     autoCensorProfanity: autoCensorOption,
     replacements: replacementsOption,
     deleteOriginalTrack,
+    uploadToS3: uploadToS3Option,
     uploadToMux: uploadToMuxOption,
     s3Endpoint: providedS3Endpoint,
     s3Region: providedS3Region,
@@ -3432,14 +3560,15 @@ async function editCaptions(assetId, trackId, options) {
   }
   const deleteOriginal = deleteOriginalTrack !== false;
   const uploadToMux = uploadToMuxOption !== false;
+  const uploadToS3 = uploadToS3Option || uploadToMux;
   const s3Endpoint = providedS3Endpoint ?? env_default.S3_ENDPOINT;
   const s3Region = providedS3Region ?? env_default.S3_REGION ?? "auto";
   const s3Bucket = providedS3Bucket ?? env_default.S3_BUCKET;
   const s3AccessKeyId = env_default.S3_ACCESS_KEY_ID;
   const s3SecretAccessKey = env_default.S3_SECRET_ACCESS_KEY;
-  if (uploadToMux && (!s3Endpoint || !s3Bucket || !storageAdapter && (!s3AccessKeyId || !s3SecretAccessKey))) {
+  if (uploadToS3 && (!s3Endpoint || !s3Bucket || !storageAdapter && (!s3AccessKeyId || !s3SecretAccessKey))) {
     throw new Error(
-      "Storage configuration is required for uploading to Mux. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables."
+      "Storage configuration is required for uploading. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables."
     );
   }
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
@@ -3512,53 +3641,45 @@ async function editCaptions(assetId, trackId, options) {
       assetDurationSeconds
     }
   } : void 0;
-  if (!uploadToMux) {
-    return {
-      assetId,
-      trackId,
-      originalVtt: vttContent,
-      editedVtt,
-      totalReplacementCount,
-      autoCensorProfanity: autoCensorResult,
-      replacements: replacementsResult,
-      usage: usageWithMetadata
-    };
-  }
   let presignedUrl;
-  try {
-    presignedUrl = await uploadEditedVttToS3({
-      editedVtt,
-      assetId,
-      trackId,
-      s3Endpoint,
-      s3Region,
-      s3Bucket,
-      storageAdapter,
-      s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
-    });
-  } catch (error) {
-    throw new Error(`Failed to upload VTT to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
-  }
   let uploadedTrackId;
-  try {
-    const languageCode = sourceTrack.language_code || "en";
-    const suffix = trackNameSuffix ?? "edited";
-    const trackName = `${sourceTrack.name || "Subtitles"} (${suffix})`;
-    uploadedTrackId = await createTextTrackOnMux(
-      assetId,
-      languageCode,
-      trackName,
-      presignedUrl,
-      credentials
-    );
-  } catch (error) {
-    console.warn(`Failed to add track to Mux asset: ${error instanceof Error ? error.message : "Unknown error"}`);
-  }
-  if (deleteOriginal && uploadedTrackId) {
+  if (uploadToS3) {
     try {
-      await deleteTrackOnMux(assetId, trackId, credentials);
+      presignedUrl = await uploadEditedVttToS3({
+        editedVtt,
+        assetId,
+        trackId,
+        s3Endpoint,
+        s3Region,
+        s3Bucket,
+        storageAdapter,
+        s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
+      });
     } catch (error) {
-      console.warn(`Failed to delete original track: ${error instanceof Error ? error.message : "Unknown error"}`);
+      throw new Error(`Failed to upload VTT to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    if (uploadToMux) {
+      try {
+        const languageCode = sourceTrack.language_code || "en";
+        const suffix = trackNameSuffix ?? "edited";
+        const trackName = `${sourceTrack.name || "Subtitles"} (${suffix})`;
+        uploadedTrackId = await createTextTrackOnMux(
+          assetId,
+          languageCode,
+          trackName,
+          presignedUrl,
+          credentials
+        );
+      } catch (error) {
+        console.warn(`Failed to add track to Mux asset: ${error instanceof Error ? error.message : "Unknown error"}`);
+      }
+      if (deleteOriginal && uploadedTrackId) {
+        try {
+          await deleteTrackOnMux(assetId, trackId, credentials);
+        } catch (error) {
+          console.warn(`Failed to delete original track: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+      }
     }
   }
   return {
@@ -3629,43 +3750,21 @@ async function generateEmbeddingsInternal(assetId, options = {}) {
   const embeddingModel = resolveEmbeddingModelConfig({ ...options, provider, model });
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
-  const isAudioOnly = isAudioOnlyAsset(assetData);
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
     throw new Error(
       "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables."
     );
   }
-  const readyTextTracks = getReadyTextTracks(assetData);
   const useVttChunking = chunkingStrategy.type === "vtt";
-  let transcriptResult = await fetchTranscriptForAsset(assetData, playbackId, {
+  const transcriptResult = await fetchTranscriptForAsset(assetData, playbackId, {
     languageCode,
     cleanTranscript: !useVttChunking,
     shouldSign: policy === "signed",
-    credentials
+    credentials,
+    required: true
   });
-  if (isAudioOnly && !transcriptResult.track && readyTextTracks.length === 1) {
-    transcriptResult = await fetchTranscriptForAsset(assetData, playbackId, {
-      cleanTranscript: !useVttChunking,
-      shouldSign: policy === "signed",
-      credentials
-    });
-  }
-  if (!transcriptResult.track || !transcriptResult.transcriptText) {
-    const availableLanguages = readyTextTracks.map((t) => t.language_code).filter(Boolean).join(", ");
-    if (isAudioOnly) {
-      throw new Error(
-        `No transcript track found${languageCode ? ` for language '${languageCode}'` : ""}. Audio-only assets require a transcript. Available languages: ${availableLanguages || "none"}`
-      );
-    }
-    throw new Error(
-      `No caption track found${languageCode ? ` for language '${languageCode}'` : ""}. Available languages: ${availableLanguages || "none"}`
-    );
-  }
   const transcriptText = transcriptResult.transcriptText;
-  if (!transcriptText.trim()) {
-    throw new Error("Transcript is empty");
-  }
   const chunks = useVttChunking ? chunkVTTCues(
     parseVTTCues(transcriptText),
     chunkingStrategy.maxTokens,
@@ -3791,7 +3890,7 @@ var SYSTEM_PROMPT4 = dedent5`
     - Connect engagement data to content features
   </quality_guidelines>
 `;
-var AUDIO_ONLY_SYSTEM_PROMPT = dedent5`
+var AUDIO_ONLY_SYSTEM_PROMPT2 = dedent5`
   <role>
     You are a video engagement analyst specializing in understanding viewer behavior for audio content.
     Your job is to explain why specific moments have high or low engagement based on audio/dialogue and viewer watch patterns.
@@ -4079,9 +4178,14 @@ async function generateEngagementInsights(assetId, options = {}) {
   }
   const { hotspots, heatmap } = engagementResult.value;
   if (hotspots.length === 0) {
-    throw new Error(
-      `No engagement data available for asset ${assetId} in timeframe ${timeframe}. Video may not have been viewed yet or engagement tracking is not enabled.`
-    );
+    return {
+      assetId,
+      momentInsights: [],
+      overallInsight: {
+        summary: `No engagement data available for asset ${assetId} in timeframe ${timeframe}. Video may not have been viewed yet, not contain notable engagement patterns, or engagement tracking is not enabled.`,
+        trends: []
+      }
+    };
   }
   let transcriptText = "";
   if (transcriptResult.status === "fulfilled") {
@@ -4124,7 +4228,7 @@ async function generateEngagementInsights(assetId, options = {}) {
       imageUrls.push(storyboardResult.value);
     }
   }
-  const systemPrompt = audioOnly ? AUDIO_ONLY_SYSTEM_PROMPT : SYSTEM_PROMPT4;
+  const systemPrompt = audioOnly ? AUDIO_ONLY_SYSTEM_PROMPT2 : SYSTEM_PROMPT4;
   const userPrompt = buildUserPrompt4(
     hotspots,
     transcriptSegments,
@@ -4249,6 +4353,12 @@ var DEFAULT_THRESHOLDS = {
   violence: 0.8
 };
 var DEFAULT_PROVIDER2 = "openai";
+var OPENAI_MODERATION_RETRIABLE_STATUS_CODES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var OPENAI_MODERATION_MAX_RETRIES = 2;
+var OPENAI_MODERATION_BASE_DELAY_MS = 750;
+var OPENAI_MODERATION_MAX_DELAY_MS = 3e3;
+var MIN_SAMPLE_COVERAGE_FOR_CONFIDENT_THRESHOLDING = 0.5;
+var MIN_SUCCESSFUL_THUMBNAILS_FOR_CONFIDENT_THRESHOLDING = 3;
 var HIVE_ENDPOINT = "https://api.thehive.ai/api/v2/task/sync";
 var HIVE_SEXUAL_CATEGORIES = [
   "general_nsfw",
@@ -4270,6 +4380,92 @@ var HIVE_VIOLENCE_CATEGORIES = [
   "yes_self_harm",
   "garm_death_injury_or_military_conflict"
 ];
+var OpenAIModerationRequestError = class extends Error {
+  constructor(message, {
+    status,
+    retriable
+  }) {
+    super(message);
+    this.name = "OpenAIModerationRequestError";
+    this.status = status;
+    this.retriable = retriable;
+  }
+};
+function isRetriableOpenAIModerationStatus(status) {
+  return OPENAI_MODERATION_RETRIABLE_STATUS_CODES.has(status);
+}
+function compactBodySnippet(body, maxLength = 180) {
+  const compact = body.replace(/\s+/g, " ").trim();
+  if (!compact) {
+    return "(empty response body)";
+  }
+  return compact.length > maxLength ? `${compact.slice(0, maxLength)}...` : compact;
+}
+function parseOpenAIModerationResponse(bodyText, status, statusText) {
+  if (!bodyText.trim()) {
+    throw new OpenAIModerationRequestError(
+      `OpenAI moderation returned an empty response (${status} ${statusText}).`,
+      { status, retriable: isRetriableOpenAIModerationStatus(status) }
+    );
+  }
+  try {
+    return JSON.parse(bodyText);
+  } catch {
+    throw new OpenAIModerationRequestError(
+      `OpenAI moderation returned non-JSON response (${status} ${statusText}): ${compactBodySnippet(bodyText)}`,
+      { status, retriable: true }
+    );
+  }
+}
+async function callOpenAIModerationApi({
+  model,
+  input,
+  credentials
+}) {
+  "use step";
+  const apiKey = await getApiKeyFromEnv("openai", credentials);
+  return withRetry(
+    async () => {
+      let res;
+      try {
+        res = await fetch("https://api.openai.com/v1/moderations", {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${apiKey}`
+          },
+          body: JSON.stringify({
+            model,
+            input
+          })
+        });
+      } catch (error) {
+        throw new OpenAIModerationRequestError(
+          `OpenAI moderation request failed: ${error instanceof Error ? error.message : String(error)}`,
+          { retriable: true }
+        );
+      }
+      const bodyText = await res.text();
+      const json = parseOpenAIModerationResponse(bodyText, res.status, res.statusText);
+      if (!res.ok) {
+        throw new OpenAIModerationRequestError(
+          `OpenAI moderation error: ${res.status} ${res.statusText} - ${JSON.stringify(json)}`,
+          {
+            status: res.status,
+            retriable: isRetriableOpenAIModerationStatus(res.status)
+          }
+        );
+      }
+      return json;
+    },
+    {
+      maxRetries: OPENAI_MODERATION_MAX_RETRIES,
+      baseDelay: OPENAI_MODERATION_BASE_DELAY_MS,
+      maxDelay: OPENAI_MODERATION_MAX_DELAY_MS,
+      shouldRetry: (error) => error instanceof OpenAIModerationRequestError ? error.retriable : true
+    }
+  );
+}
 async function processConcurrently(items, processor, maxConcurrent = 5) {
   "use step";
   const results = [];
@@ -4283,32 +4479,19 @@ async function processConcurrently(items, processor, maxConcurrent = 5) {
 }
 async function moderateImageWithOpenAI(entry) {
   "use step";
-  const apiKey = await getApiKeyFromEnv("openai", entry.credentials);
   try {
-    const res = await fetch("https://api.openai.com/v1/moderations", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${apiKey}`
-      },
-      body: JSON.stringify({
-        model: entry.model,
-        input: [
-          {
-            type: "image_url",
-            image_url: {
-              url: entry.image
-            }
+    const json = await callOpenAIModerationApi({
+      model: entry.model,
+      input: [
+        {
+          type: "image_url",
+          image_url: {
+            url: entry.image
           }
-        ]
-      })
+        }
+      ],
+      credentials: entry.credentials
     });
-    const json = await res.json();
-    if (!res.ok) {
-      throw new Error(
-        `OpenAI moderation error: ${res.status} ${res.statusText} - ${JSON.stringify(json)}`
-      );
-    }
     const categoryScores = json.results?.[0]?.category_scores || {};
     return {
       url: entry.url,
@@ -4340,25 +4523,12 @@ async function requestOpenAIModeration(images, model, maxConcurrent = 5, submiss
 }
 async function requestOpenAITextModeration(text, model, url, credentials) {
   "use step";
-  const apiKey = await getApiKeyFromEnv("openai", credentials);
   try {
-    const res = await fetch("https://api.openai.com/v1/moderations", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${apiKey}`
-      },
-      body: JSON.stringify({
-        model,
-        input: text
-      })
+    const json = await callOpenAIModerationApi({
+      model,
+      input: text,
+      credentials
     });
-    const json = await res.json();
-    if (!res.ok) {
-      throw new Error(
-        `OpenAI moderation error: ${res.status} ${res.statusText} - ${JSON.stringify(json)}`
-      );
-    }
     const categoryScores = json.results?.[0]?.category_scores || {};
     return {
       url,
@@ -4564,22 +4734,13 @@ async function getModerationScores(assetId, options = {}) {
   let thumbnailCount;
   if (isAudioOnly) {
     mode = "transcript";
-    const readyTextTracks = getReadyTextTracks(asset);
-    let transcriptResult = await fetchTranscriptForAsset(asset, playbackId, {
+    const transcriptResult = await fetchTranscriptForAsset(asset, playbackId, {
       languageCode,
       cleanTranscript: true,
       shouldSign: policy === "signed",
       credentials,
       required: true
     });
-    if (!transcriptResult.track && readyTextTracks.length === 1) {
-      transcriptResult = await fetchTranscriptForAsset(asset, playbackId, {
-        cleanTranscript: true,
-        shouldSign: policy === "signed",
-        credentials,
-        required: true
-      });
-    }
     if (provider === "openai") {
       thumbnailScores = await requestOpenAITranscriptModeration(
         transcriptResult.transcriptText,
@@ -4593,35 +4754,28 @@ async function getModerationScores(assetId, options = {}) {
       throw new Error(`Unsupported moderation provider: ${provider}`);
     }
   } else {
-    const thumbnailUrls = maxSamples === void 0 ? (
-      // Generate thumbnail URLs (signed if needed) using existing interval-based logic.
-      await getThumbnailUrls(playbackId, duration, {
-        interval: thumbnailInterval,
+    const estimatedIntervalCount = duration <= 50 ? 5 : Math.ceil(duration / 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
+      }),
+      {
         width: thumbnailWidth,
         shouldSign: policy === "signed",
         credentials
-      })
-    ) : (
-      // In maxSamples mode, sample valid timestamps over the trimmed usable span.
-      // Use proportional trims (≈ duration/6, capped at 5s) to stay well inside the
-      // renderable range — Mux can't always serve thumbnails at the very edges.
-      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
-        }),
-        {
-          width: thumbnailWidth,
-          shouldSign: policy === "signed",
-          credentials
-        }
-      )
-    );
+      }
+    ) : await getThumbnailUrls(playbackId, duration, {
+      interval: thumbnailInterval,
+      width: thumbnailWidth,
+      shouldSign: policy === "signed",
+      credentials
+    });
     thumbnailCount = thumbnailUrls.length;
     if (provider === "openai") {
       thumbnailScores = await requestOpenAIModeration(
@@ -4645,20 +4799,40 @@ async function getModerationScores(assetId, options = {}) {
     }
   }
   const failed = thumbnailScores.filter((s) => s.error);
-  if (failed.length > 0) {
+  const successful = thumbnailScores.filter((s) => !s.error);
+  if (successful.length === 0) {
     const details = failed.map((s) => `${s.url}: ${s.errorMessage || "Unknown error"}`).join("; ");
     throw new Error(
-      `Moderation failed for ${failed.length}/${thumbnailScores.length} thumbnail(s): ${details}`
+      `Moderation failed for all ${thumbnailScores.length} sample(s): ${details}`
+    );
+  }
+  if (failed.length > 0) {
+    console.warn(
+      `Moderation had partial failures (${failed.length}/${thumbnailScores.length}); continuing with successful samples.`
     );
   }
-  const maxSexual = Math.max(...thumbnailScores.map((s) => s.sexual));
-  const maxViolence = Math.max(...thumbnailScores.map((s) => s.violence));
+  const maxSexual = Math.max(...successful.map((s) => s.sexual));
+  const maxViolence = Math.max(...successful.map((s) => s.violence));
   const finalThresholds = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const requestedSampleCount = thumbnailScores.length;
+  const successfulSampleCount = successful.length;
+  const failedSampleCount = failed.length;
+  const sampleCoverage = successfulSampleCount / requestedSampleCount;
+  const hasEnoughSuccessfulSamples = mode === "transcript" || successfulSampleCount >= MIN_SUCCESSFUL_THUMBNAILS_FOR_CONFIDENT_THRESHOLDING;
+  const isLowConfidence = sampleCoverage < MIN_SAMPLE_COVERAGE_FOR_CONFIDENT_THRESHOLDING || !hasEnoughSuccessfulSamples;
   return {
     assetId,
     mode,
     isAudioOnly,
     thumbnailScores,
+    coverage: {
+      requestedSampleCount,
+      successfulSampleCount,
+      failedSampleCount,
+      sampleCoverage,
+      isPartial: failedSampleCount > 0,
+      isLowConfidence
+    },
     usage: {
       metadata: {
         assetDurationSeconds: duration,
@@ -4886,7 +5060,7 @@ var SYSTEM_PROMPT5 = dedent6`
 
     Write as if describing reality, not describing a recording of reality.
   </language_guidelines>`;
-var AUDIO_ONLY_SYSTEM_PROMPT2 = dedent6`
+var AUDIO_ONLY_SYSTEM_PROMPT3 = dedent6`
   <role>
     You are an audio content analyst specializing in transcript analysis and metadata generation.
   </role>
@@ -5063,6 +5237,7 @@ async function getSummaryAndTags(assetId, options) {
   const {
     provider = "openai",
     model,
+    languageCode,
     tone = "neutral",
     includeTranscript = true,
     cleanTranscript = true,
@@ -5101,6 +5276,7 @@ async function getSummaryAndTags(assetId, options) {
     );
   }
   const transcriptResult = includeTranscript ? await fetchTranscriptForAsset(assetData, playbackId, {
+    languageCode,
     cleanTranscript,
     shouldSign: policy === "signed",
     credentials: workflowCredentials,
@@ -5122,7 +5298,7 @@ async function getSummaryAndTags(assetId, options) {
   });
   let analysisResponse;
   let imageUrl;
-  const systemPrompt = isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT2 : SYSTEM_PROMPT5;
+  const systemPrompt = isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT3 : SYSTEM_PROMPT5;
   try {
     if (isAudioOnly) {
       analysisResponse = await analyzeAudioOnly(
@@ -5419,7 +5595,8 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     fromLanguageCode,
     numSpeakers = 0,
     // 0 = auto-detect
-    uploadToMux = true,
+    uploadToS3: uploadToS3Option,
+    uploadToMux: uploadToMuxOption,
     storageAdapter,
     credentials: providedCredentials
   } = options;
@@ -5428,13 +5605,15 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   }
   const credentials = providedCredentials;
   const effectiveStorageAdapter = storageAdapter;
+  const uploadToMux = uploadToMuxOption !== false;
+  const uploadToS3 = uploadToS3Option || uploadToMux;
   const s3Endpoint = options.s3Endpoint ?? env_default.S3_ENDPOINT;
   const s3Region = options.s3Region ?? env_default.S3_REGION ?? "auto";
   const s3Bucket = options.s3Bucket ?? env_default.S3_BUCKET;
   const s3AccessKeyId = env_default.S3_ACCESS_KEY_ID;
   const s3SecretAccessKey = env_default.S3_SECRET_ACCESS_KEY;
-  if (uploadToMux && (!s3Endpoint || !s3Bucket || !effectiveStorageAdapter && (!s3AccessKeyId || !s3SecretAccessKey))) {
-    throw new Error("Storage configuration is required for uploading to Mux. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables.");
+  if (uploadToS3 && (!s3Endpoint || !s3Bucket || !effectiveStorageAdapter && (!s3AccessKeyId || !s3SecretAccessKey))) {
+    throw new Error("Storage configuration is required for uploading. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables.");
   }
   const { asset: initialAsset, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(initialAsset);
@@ -5511,70 +5690,65 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     throw new Error(`Dubbing job timed out or failed. Final status: ${dubbingStatus}`);
   }
   console.warn("\u2705 Dubbing completed successfully!");
-  if (!uploadToMux) {
-    const targetLanguage2 = getLanguageCodePair(toLanguageCode);
-    return {
-      assetId,
-      targetLanguageCode: targetLanguage2.iso639_1,
-      targetLanguage: targetLanguage2,
-      dubbingId
-    };
-  }
-  console.warn("\u{1F4E5} Downloading dubbed audio from ElevenLabs...");
-  let dubbedAudioBuffer;
-  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({
-      dubbingId,
-      languageCode: downloadLangCode,
-      credentials
-    });
-    console.warn("\u2705 Dubbed audio downloaded successfully!");
-  } catch (error) {
-    throw new Error(`Failed to download dubbed audio: ${error instanceof Error ? error.message : "Unknown error"}`);
-  }
-  console.warn("\u{1F4E4} Uploading dubbed audio to S3-compatible storage...");
   let presignedUrl;
-  try {
-    presignedUrl = await uploadDubbedAudioToS3({
-      dubbedAudioBuffer,
-      assetId,
-      toLanguageCode,
-      s3Endpoint,
-      s3Region,
-      s3Bucket,
-      storageAdapter: effectiveStorageAdapter,
-      s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
-    });
-  } catch (error) {
-    throw new Error(`Failed to upload audio to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
-  }
-  console.warn("\u{1F4F9} Adding dubbed audio track to Mux asset...");
   let uploadedTrackId;
-  const muxLangCode = toISO639_1(toLanguageCode);
-  try {
-    uploadedTrackId = await createAudioTrackOnMux(assetId, muxLangCode, presignedUrl, credentials);
-    const languageName = new Intl.DisplayNames(["en"], { type: "language" }).of(muxLangCode) || muxLangCode.toUpperCase();
-    const trackName = `${languageName} (auto-dubbed)`;
-    console.warn(`\u2705 Track added to Mux asset with ID: ${uploadedTrackId}`);
-    console.warn(`\u{1F4CB} Track name: "${trackName}"`);
-  } catch (error) {
-    console.warn(`\u26A0\uFE0F Failed to add audio track to Mux asset: ${error instanceof Error ? error.message : "Unknown error"}`);
-    console.warn("\u{1F517} You can manually add the track using this presigned URL:");
-    console.warn(presignedUrl);
+  if (uploadToS3) {
+    console.warn("\u{1F4E5} Downloading dubbed audio from ElevenLabs...");
+    let dubbedAudioBuffer;
+    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({
+        dubbingId,
+        languageCode: downloadLangCode,
+        credentials
+      });
+      console.warn("\u2705 Dubbed audio downloaded successfully!");
+    } catch (error) {
+      throw new Error(`Failed to download dubbed audio: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    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
+      });
+    } catch (error) {
+      throw new Error(`Failed to upload audio to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    if (uploadToMux) {
+      console.warn("\u{1F4F9} Adding dubbed audio track to Mux asset...");
+      const muxLangCode = toISO639_1(toLanguageCode);
+      try {
+        uploadedTrackId = await createAudioTrackOnMux(assetId, muxLangCode, presignedUrl, credentials);
+        const languageName = new Intl.DisplayNames(["en"], { type: "language" }).of(muxLangCode) || muxLangCode.toUpperCase();
+        const trackName = `${languageName} (auto-dubbed)`;
+        console.warn(`\u2705 Track added to Mux asset with ID: ${uploadedTrackId}`);
+        console.warn(`\u{1F4CB} Track name: "${trackName}"`);
+      } catch (error) {
+        console.warn(`\u26A0\uFE0F Failed to add audio track to Mux asset: ${error instanceof Error ? error.message : "Unknown error"}`);
+        console.warn("\u{1F517} You can manually add the track using this presigned URL:");
+        console.warn(presignedUrl);
+      }
+    }
   }
   const targetLanguage = getLanguageCodePair(toLanguageCode);
   return {
@@ -6016,7 +6190,7 @@ async function uploadVttToS3({
     expiresInSeconds: s3SignedUrlExpirySeconds ?? 86400
   }, storageAdapter);
 }
-async function translateCaptions(assetId, fromLanguageCode, toLanguageCode, options) {
+async function translateCaptions(assetId, trackId, toLanguageCode, options) {
   "use workflow";
   const {
     provider = "openai",
@@ -6024,6 +6198,7 @@ async function translateCaptions(assetId, fromLanguageCode, toLanguageCode, opti
     s3Endpoint: providedS3Endpoint,
     s3Region: providedS3Region,
     s3Bucket: providedS3Bucket,
+    uploadToS3: uploadToS3Option,
     uploadToMux: uploadToMuxOption,
     storageAdapter,
     credentials: providedCredentials,
@@ -6037,17 +6212,17 @@ async function translateCaptions(assetId, fromLanguageCode, toLanguageCode, opti
   const s3AccessKeyId = env_default.S3_ACCESS_KEY_ID;
   const s3SecretAccessKey = env_default.S3_SECRET_ACCESS_KEY;
   const uploadToMux = uploadToMuxOption !== false;
+  const uploadToS3 = uploadToS3Option || uploadToMux;
   const modelConfig = resolveLanguageModelConfig({
     ...options,
     model,
     provider
   });
-  if (uploadToMux && (!s3Endpoint || !s3Bucket || !effectiveStorageAdapter && (!s3AccessKeyId || !s3SecretAccessKey))) {
-    throw new Error("Storage configuration is required for uploading to Mux. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables.");
+  if (uploadToS3 && (!s3Endpoint || !s3Bucket || !effectiveStorageAdapter && (!s3AccessKeyId || !s3SecretAccessKey))) {
+    throw new Error("Storage configuration is required for uploading. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables.");
   }
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
-  const isAudioOnly = isAudioOnlyAsset(assetData);
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
     throw new Error(
@@ -6055,30 +6230,20 @@ async function translateCaptions(assetId, fromLanguageCode, toLanguageCode, opti
     );
   }
   const readyTextTracks = getReadyTextTracks(assetData);
-  if (!readyTextTracks.length) {
-    throw new Error("No ready text tracks found for this asset");
-  }
-  let sourceTextTrack = readyTextTracks.find(
-    (track) => track.text_type === "subtitles" && track.language_code === fromLanguageCode
-  );
-  if (!sourceTextTrack && isAudioOnly && readyTextTracks.length === 1) {
-    sourceTextTrack = readyTextTracks[0];
-  }
+  const sourceTextTrack = readyTextTracks.find((t) => t.id === trackId);
   if (!sourceTextTrack) {
-    const availableLanguages = readyTextTracks.map((t) => t.language_code).filter(Boolean).join(", ");
-    if (isAudioOnly) {
-      throw new Error(
-        `No transcript track found with language code '${fromLanguageCode}' for this asset. Audio-only assets require a transcript. Available languages: ${availableLanguages || "none"}`
-      );
-    }
+    const availableTrackIds = readyTextTracks.map((t) => t.id).filter(Boolean).join(", ");
     throw new Error(
-      `No ready text track found with language code '${fromLanguageCode}' for this asset. Available languages: ${availableLanguages || "none"}`
+      `Track '${trackId}' not found or not ready on asset '${assetId}'. Available track IDs: ${availableTrackIds || "none"}`
     );
   }
-  if (!sourceTextTrack.id) {
-    throw new Error("Transcript track is missing an id");
+  const fromLanguageCode = sourceTextTrack.language_code;
+  if (!fromLanguageCode) {
+    throw new Error(
+      `Track '${trackId}' is missing language metadata (language_code). Cannot determine source language for translation.`
+    );
   }
-  const vttUrl = await buildTranscriptUrl(playbackId, sourceTextTrack.id, policy === "signed", credentials);
+  const vttUrl = await buildTranscriptUrl(playbackId, trackId, policy === "signed", credentials);
   let vttContent;
   try {
     vttContent = await fetchVttFromMux(vttUrl);
@@ -6111,50 +6276,43 @@ async function translateCaptions(assetId, fromLanguageCode, toLanguageCode, opti
   } : void 0;
   const sourceLanguage = getLanguageCodePair(fromLanguageCode);
   const targetLanguage = getLanguageCodePair(toLanguageCode);
-  if (!uploadToMux) {
-    return {
-      assetId,
-      sourceLanguageCode: fromLanguageCode,
-      targetLanguageCode: toLanguageCode,
-      sourceLanguage,
-      targetLanguage,
-      originalVtt: vttContent,
-      translatedVtt,
-      usage: usageWithMetadata
-    };
-  }
   let presignedUrl;
-  try {
-    presignedUrl = await uploadVttToS3({
-      translatedVtt,
-      assetId,
-      fromLanguageCode,
-      toLanguageCode,
-      s3Endpoint,
-      s3Region,
-      s3Bucket,
-      storageAdapter: effectiveStorageAdapter,
-      s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
-    });
-  } catch (error) {
-    throw new Error(`Failed to upload VTT to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
-  }
   let uploadedTrackId;
-  try {
-    const languageName = getLanguageName(toLanguageCode);
-    const trackName = `${languageName} (auto-translated)`;
-    uploadedTrackId = await createTextTrackOnMux(
-      assetId,
-      toLanguageCode,
-      trackName,
-      presignedUrl,
-      credentials
-    );
-  } catch (error) {
-    console.warn(`Failed to add track to Mux asset: ${error instanceof Error ? error.message : "Unknown error"}`);
+  if (uploadToS3) {
+    try {
+      presignedUrl = await uploadVttToS3({
+        translatedVtt,
+        assetId,
+        fromLanguageCode,
+        toLanguageCode,
+        s3Endpoint,
+        s3Region,
+        s3Bucket,
+        storageAdapter: effectiveStorageAdapter,
+        s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
+      });
+    } catch (error) {
+      throw new Error(`Failed to upload VTT to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+    if (uploadToMux) {
+      try {
+        const languageName = getLanguageName(toLanguageCode);
+        const trackName = `${languageName} (auto-translated)`;
+        uploadedTrackId = await createTextTrackOnMux(
+          assetId,
+          toLanguageCode,
+          trackName,
+          presignedUrl,
+          credentials
+        );
+      } catch (error) {
+        console.warn(`Failed to add track to Mux asset: ${error instanceof Error ? error.message : "Unknown error"}`);
+      }
+    }
   }
   return {
     assetId,
+    trackId,
     sourceLanguageCode: fromLanguageCode,
     targetLanguageCode: toLanguageCode,
     sourceLanguage,