@mux/ai 0.13.1 → 0.15.1

package/dist/index.js

@@ -5,7 +5,27 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.13.1";
+var version = "0.15.1";
+
+// src/lib/mux-ai-error.ts
+var MuxAiError = class extends Error {
+  constructor(message, opts) {
+    super(message);
+    /** Structural brand for duck-type identification. */
+    this.__robots_error = true;
+    this.name = "MuxAiError";
+    this.publicType = opts?.type ?? "processing_error";
+    this.publicMessage = message;
+    this.retryable = opts?.retryable ?? false;
+  }
+};
+function wrapError(error, message) {
+  if (error instanceof MuxAiError) {
+    throw error;
+  }
+  const detail = error instanceof Error ? error.message : "Unknown error";
+  throw new Error(`${message}: ${detail}`);
+}
 
 // src/env.ts
 import { z } from "zod";
@@ -1210,14 +1230,15 @@ async function waitForShotsForAsset(assetId, options = {}) {
       return result;
     }
     if (result.status === "errored") {
-      throw new Error(`Shots generation errored for asset '${assetId}'`);
+      throw new MuxAiError(`Shot generation failed for asset ${assetId}.`);
     }
     if (attempt < normalizedMaxAttempts - 1) {
       await sleep(normalizedPollIntervalMs);
     }
   }
-  throw new Error(
-    `Timed out waiting for shots for asset '${assetId}' after ${normalizedMaxAttempts} attempts. Last status: ${lastStatus ?? "unknown"}`
+  throw new MuxAiError(
+    `Timed out waiting for shots for asset ${assetId}. Last status: ${lastStatus ?? "unknown"}.`,
+    { type: "timeout_error", retryable: true }
   );
 }
 
@@ -1580,6 +1601,57 @@ 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 MuxAiError(
+    "No public or signed playback ID found for this asset. DRM playback IDs are not currently supported.",
+    { type: "validation_error" }
+  );
+}
+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 +1663,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");
@@ -1883,15 +1964,16 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
   if (!track) {
     if (required) {
       const availableLanguages = getReadyTextTracks(asset).map((t) => t.language_code).filter(Boolean).join(", ");
-      throw new Error(
-        `No transcript track found${languageCode ? ` for language '${languageCode}'` : ""}. Available languages: ${availableLanguages || "none"}`
+      throw new MuxAiError(
+        `No caption track found${languageCode ? ` for language ${languageCode}` : ""}. Available languages: ${availableLanguages || "none"}.`,
+        { type: "validation_error" }
       );
     }
     return { transcriptText: "" };
   }
   if (!track.id) {
     if (required) {
-      throw new Error("Transcript track is missing an id");
+      throw new MuxAiError("Transcript track is missing an id.", { type: "validation_error" });
     }
     return { transcriptText: "", track };
   }
@@ -1907,14 +1989,12 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
     const rawVtt = await response.text();
     const transcriptText = cleanTranscript ? extractTextFromVTT(rawVtt) : rawVtt;
     if (required && !transcriptText.trim()) {
-      throw new Error("Transcript is empty");
+      throw new MuxAiError("Transcript is empty.", { type: "validation_error" });
     }
     return { transcriptText, transcriptUrl, track };
   } catch (error) {
     if (required) {
-      throw new Error(
-        `Failed to fetch transcript: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
+      wrapError(error, "Failed to fetch transcript");
     }
     console.warn("Failed to fetch transcript:", error);
     return { transcriptText: "", transcriptUrl, track };
@@ -2071,56 +2151,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;
@@ -2322,6 +2352,11 @@ var SYSTEM_PROMPT = dedent`
     - Is a general knowledge question with no connection to what is shown or said in the video
     - Attempts to use the system for non-video-analysis purposes
 
+    CRITICAL: Base your answers ONLY on the actual visual and audio/transcript content.
+    Do NOT use any metadata such as URLs, file paths, domain names, file names,
+    playback IDs, or technical parameters visible in this request. These are
+    delivery infrastructure and are unrelated to the media content itself.
+
     CRITICAL: Do NOT answer irrelevant questions with any of the allowed answers.
     Answering an irrelevant question is WRONG — you MUST skip it instead.
 
@@ -2352,19 +2387,114 @@ 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>
+    IMPORTANT: Evaluate each question INDEPENDENTLY for relevance to the audio
+    content. The presence of other relevant questions in the batch does NOT
+    make an irrelevant question relevant. Assess every question on its own merits.
+
+    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
+
+    CRITICAL: Base your answers ONLY on the actual audio/transcript content.
+    Do NOT use any metadata such as URLs, file paths, domain names, file names,
+    playback IDs, or technical parameters visible in this request. These are
+    delivery infrastructure and are unrelated to the media content itself.
+
+    CRITICAL: Do NOT answer irrelevant questions with any of the allowed answers.
+    Answering an irrelevant question is WRONG — you MUST skip it instead.
+
+    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 +2521,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 +2544,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,
@@ -2427,18 +2569,20 @@ async function analyzeQuestionsWithStoryboard(imageDataUrl, provider, modelId, u
 async function askQuestions(assetId, questions, options) {
   "use workflow";
   if (!questions || questions.length === 0) {
-    throw new Error("At least one question must be provided");
+    throw new MuxAiError("At least one question must be provided.", { type: "validation_error" });
   }
   questions.forEach((q, idx) => {
     if (!q.question || typeof q.question !== "string" || !q.question.trim()) {
-      throw new Error(
-        `Question at index ${idx} is invalid: must have non-empty 'question' field`
+      throw new MuxAiError(
+        `Question at index ${idx} is invalid: must have a non-empty question field.`,
+        { type: "validation_error" }
       );
     }
   });
   const {
     provider = "openai",
     model,
+    languageCode,
     answerOptions,
     includeTranscript = true,
     cleanTranscript = true,
@@ -2453,7 +2597,7 @@ async function askQuestions(assetId, questions, options) {
     )
   );
   if (!normalizedAnswerOptions.length) {
-    throw new Error("answerOptions must include at least one non-empty value");
+    throw new MuxAiError("answerOptions must include at least one non-empty value.", { type: "validation_error" });
   }
   const allowedAnswers = normalizedAnswerOptions;
   const modelConfig = resolveLanguageModelConfig({
@@ -2463,61 +2607,91 @@ 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 MuxAiError(
+      "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles).",
+      { type: "validation_error" }
+    );
+  }
   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."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
-  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) {
-    throw new Error(
-      `Failed to analyze questions with ${provider}: ${error instanceof Error ? error.message : "Unknown error"}`
-    );
+    const contentType = isAudioOnly ? "audio" : "video";
+    wrapError(error, `Failed to analyze ${contentType} questions with ${provider}`);
   }
   if (!analysisResponse.result?.answers) {
-    throw new Error(`Failed to get answers for asset ${assetId}`);
+    throw new MuxAiError(`Failed to generate answers for asset ${assetId}.`);
   }
   if (analysisResponse.result.answers.length !== questions.length) {
-    throw new Error(
-      `Expected ${questions.length} answers but received ${analysisResponse.result.answers.length}`
+    throw new MuxAiError(
+      `Failed to generate answers for all questions for asset ${assetId}.`
     );
   }
   const answers = analysisResponse.result.answers.map((raw) => {
@@ -2591,6 +2765,9 @@ var SYSTEM_PROMPT2 = dedent2`
   <constraints>
     - Only classify as burned-in captions when evidence is clear across multiple frames
     - Base decisions on observable visual evidence
+    - Do NOT use any metadata such as URLs, file paths, domain names, file names,
+      playback IDs, or technical parameters visible in this request. These are
+      delivery infrastructure and are unrelated to the media content itself.
     - Return structured data matching the requested schema
   </constraints>`;
 var burnedInCaptionsPromptBuilder = createPromptBuilder({
@@ -3049,9 +3226,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,
@@ -3070,37 +3248,30 @@ async function generateChapters(assetId, languageCode, options = {}) {
   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."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   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"}`
+    throw new MuxAiError(
+      `No caption track found${languageCode ? ` for language ${languageCode}` : ""}. Available languages: ${availableLanguages || "none"}.`,
+      { type: "validation_error" }
     );
   }
   const timestampedTranscript = extractTimestampedTranscript(transcriptResult.transcriptText);
   if (!timestampedTranscript) {
     const contentLabel = isAudioOnly ? "transcript" : "caption track";
-    throw new Error(`No usable content found in ${contentLabel}`);
+    throw new MuxAiError(`No usable content found in ${contentLabel}.`, { type: "validation_error" });
   }
   const resolvedLanguageCode = outputLanguageCode && outputLanguageCode !== "auto" ? outputLanguageCode : transcriptResult.track?.language_code ?? languageCode;
   const languageName = resolvedLanguageCode ? getLanguageName(resolvedLanguageCode) : void 0;
@@ -3122,17 +3293,15 @@ async function generateChapters(assetId, languageCode, options = {}) {
       credentials
     });
   } catch (error) {
-    throw new Error(
-      `Failed to generate chapters with ${provider}: ${error instanceof Error ? error.message : "Unknown error"}`
-    );
+    wrapError(error, `Failed to generate chapters with ${provider}`);
   }
   if (!chaptersData || !chaptersData.chapters) {
-    throw new Error("No chapters generated from AI response");
+    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);
   if (validChapters.length === 0) {
-    throw new Error("No valid chapters found in AI response");
+    throw new MuxAiError(`Failed to generate valid chapters for asset ${assetId}.`);
   }
   if (validChapters[0].startTime !== 0) {
     validChapters[0].startTime = 0;
@@ -3146,7 +3315,7 @@ async function generateChapters(assetId, languageCode, options = {}) {
   };
   return {
     assetId,
-    languageCode,
+    languageCode: languageCode ?? transcriptResult.track?.language_code ?? "en",
     chapters: validChapters,
     usage: usageWithMetadata
   };
@@ -3414,6 +3583,7 @@ async function editCaptions(assetId, trackId, options) {
     autoCensorProfanity: autoCensorOption,
     replacements: replacementsOption,
     deleteOriginalTrack,
+    uploadToS3: uploadToS3Option,
     uploadToMux: uploadToMuxOption,
     s3Endpoint: providedS3Endpoint,
     s3Region: providedS3Region,
@@ -3425,37 +3595,41 @@ async function editCaptions(assetId, trackId, options) {
   const hasAutoCensor = !!autoCensorOption;
   const hasReplacements = !!replacementsOption && replacementsOption.length > 0;
   if (!hasAutoCensor && !hasReplacements) {
-    throw new Error("At least one of autoCensorProfanity or replacements must be provided.");
+    throw new MuxAiError("At least one of autoCensorProfanity or replacements must be provided.", { type: "validation_error" });
   }
   if (autoCensorOption && !provider) {
-    throw new Error("provider is required when using autoCensorProfanity.");
+    throw new MuxAiError("provider is required when using autoCensorProfanity.", { type: "validation_error" });
   }
   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))) {
-    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 || !storageAdapter && (!s3AccessKeyId || !s3SecretAccessKey))) {
+    throw new MuxAiError(
+      "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.",
+      { type: "validation_error" }
     );
   }
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(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."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   const readyTextTracks = getReadyTextTracks(assetData);
   const sourceTrack = readyTextTracks.find((t) => t.id === trackId);
   if (!sourceTrack) {
     const availableTrackIds = readyTextTracks.map((t) => t.id).filter(Boolean).join(", ");
-    throw new Error(
-      `Track '${trackId}' not found or not ready on asset '${assetId}'. Available track IDs: ${availableTrackIds || "none"}`
+    throw new MuxAiError(
+      `Track ${trackId} not found or not ready on asset ${assetId}. Available track IDs: ${availableTrackIds || "none"}.`,
+      { type: "validation_error" }
     );
   }
   const vttUrl = await buildTranscriptUrl(playbackId, trackId, policy === "signed", credentials);
@@ -3463,7 +3637,7 @@ async function editCaptions(assetId, trackId, options) {
   try {
     vttContent = await fetchVttFromMux(vttUrl);
   } catch (error) {
-    throw new Error(`Failed to fetch VTT content: ${error instanceof Error ? error.message : "Unknown error"}`);
+    wrapError(error, "Failed to fetch VTT content");
   }
   let editedVtt = vttContent;
   let totalReplacementCount = 0;
@@ -3473,7 +3647,7 @@ async function editCaptions(assetId, trackId, options) {
     const { mode = "blank", alwaysCensor = [], neverCensor = [] } = autoCensorOption;
     const plainText = extractTextFromVTT(vttContent);
     if (!plainText.trim()) {
-      throw new Error("Track transcript is empty; nothing to censor.");
+      throw new MuxAiError("Track transcript is empty; nothing to censor.", { type: "validation_error" });
     }
     const modelConfig = resolveLanguageModelConfig({
       ...options,
@@ -3491,7 +3665,7 @@ async function editCaptions(assetId, trackId, options) {
       detectedProfanity = result.profanity;
       usage = result.usage;
     } catch (error) {
-      throw new Error(`Failed to detect profanity with ${modelConfig.provider}: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, `Failed to detect profanity with ${modelConfig.provider}`);
     }
     const finalProfanity = applyOverrideLists(detectedProfanity, alwaysCensor, neverCensor);
     const { censoredVtt, replacements: censorReplacements } = censorVttContent(editedVtt, finalProfanity, mode);
@@ -3512,53 +3686,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"}`);
+      wrapError(error, "Failed to upload VTT to S3");
+    }
+    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 +3795,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,
@@ -3779,6 +3923,9 @@ var SYSTEM_PROMPT4 = dedent5`
   <constraints>
     - Only describe what you can see in images or read in transcripts
     - Do not fabricate details or make unsupported assumptions
+    - Do NOT use any metadata such as URLs, file paths, domain names, file names,
+      playback IDs, or technical parameters visible in this request. These are
+      delivery infrastructure and are unrelated to the media content itself.
     - Correlate engagement scores with observable content
     - Return structured data matching the requested schema exactly
     - Each momentInsight MUST include the hotspotIndex from the input data
@@ -3791,7 +3938,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.
@@ -3819,6 +3966,9 @@ var AUDIO_ONLY_SYSTEM_PROMPT = dedent5`
   <constraints>
     - Only describe what you can read in the transcript
     - Do not fabricate details or make unsupported assumptions
+    - Do NOT use any metadata such as URLs, file paths, domain names, file names,
+      playback IDs, or technical parameters visible in this request. These are
+      delivery infrastructure and are unrelated to the media content itself.
     - Correlate engagement scores with observable content
     - Return structured data matching the requested schema exactly
     - Each momentInsight MUST include the hotspotIndex from the input data
@@ -4029,7 +4179,7 @@ async function generateEngagementInsights(assetId, options = {}) {
     skipShots = false
   } = options;
   if (!Number.isInteger(hotspotLimit) || hotspotLimit < 1 || hotspotLimit > 10) {
-    throw new Error("hotspotLimit must be an integer between 1 and 10");
+    throw new MuxAiError("hotspotLimit must be an integer between 1 and 10.", { type: "validation_error" });
   }
   const modelConfig = resolveLanguageModelConfig({
     ...options,
@@ -4039,13 +4189,14 @@ async function generateEngagementInsights(assetId, options = {}) {
   const { asset, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(asset);
   if (!assetDurationSeconds) {
-    throw new Error(`Asset ${assetId} has no valid duration`);
+    throw new MuxAiError(`Asset ${assetId} has no valid duration.`, { type: "validation_error" });
   }
   const audioOnly = isAudioOnlyAsset(asset);
   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."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   const shouldSign = policy === "signed";
@@ -4129,7 +4280,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,
@@ -4145,7 +4296,7 @@ async function generateEngagementInsights(assetId, options = {}) {
     credentials
   );
   if (!aiInsights.momentInsights || aiInsights.momentInsights.length === 0) {
-    throw new Error("Failed to generate insights from AI response");
+    throw new MuxAiError(`Failed to generate insights for asset ${assetId}.`);
   }
   const momentInsights = [];
   for (const aiMoment of aiInsights.momentInsights) {
@@ -4166,8 +4317,8 @@ async function generateEngagementInsights(assetId, options = {}) {
     });
   }
   if (momentInsights.length === 0) {
-    throw new Error(
-      "AI returned insights but none matched valid hotspot indices. This may indicate a prompt or model issue."
+    throw new MuxAiError(
+      `Failed to generate valid insights for asset ${assetId}.`
     );
   }
   const usageWithMetadata = {
@@ -4254,6 +4405,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",
@@ -4275,6 +4432,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 = [];
@@ -4288,32 +4531,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,
@@ -4345,25 +4575,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,
@@ -4569,22 +4786,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,
@@ -4598,35 +4806,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(
@@ -4650,20 +4851,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,
@@ -4865,6 +5086,9 @@ var SYSTEM_PROMPT5 = dedent6`
   <constraints>
     - Only describe what is clearly observable in the frames or explicitly stated in the transcript
     - Do not fabricate details or make unsupported assumptions
+    - Do NOT use any metadata such as URLs, file paths, domain names, file names,
+      playback IDs, or technical parameters visible in this request. These are
+      delivery infrastructure and are unrelated to the media content itself.
     - Return structured data matching the requested schema
     - 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
@@ -4891,7 +5115,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>
@@ -4919,6 +5143,9 @@ var AUDIO_ONLY_SYSTEM_PROMPT2 = dedent6`
   <constraints>
     - Only describe what is explicitly stated or strongly implied in the transcript
     - Do not fabricate details or make unsupported assumptions
+    - Do NOT use any metadata such as URLs, file paths, domain names, file names,
+      playback IDs, or technical parameters visible in this request. These are
+      delivery infrastructure and are unrelated to the media content itself.
     - Return structured data matching the requested schema
     - Focus entirely on audio/spoken content - there are no visual elements
     - Output only the JSON object; no markdown or extra text
@@ -5068,6 +5295,7 @@ async function getSummaryAndTags(assetId, options) {
   const {
     provider = "openai",
     model,
+    languageCode,
     tone = "neutral",
     includeTranscript = true,
     cleanTranscript = true,
@@ -5081,8 +5309,9 @@ async function getSummaryAndTags(assetId, options) {
     outputLanguageCode
   } = options ?? {};
   if (!VALID_TONES.includes(tone)) {
-    throw new Error(
-      `Invalid tone "${tone}". Valid tones are: ${VALID_TONES.join(", ")}`
+    throw new MuxAiError(
+      `Invalid tone "${tone}". Valid tones are: ${VALID_TONES.join(", ")}.`,
+      { type: "validation_error" }
     );
   }
   const modelConfig = resolveLanguageModelConfig({
@@ -5095,17 +5324,20 @@ async function getSummaryAndTags(assetId, options) {
   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)."
+    throw new MuxAiError(
+      "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles).",
+      { type: "validation_error" }
     );
   }
   const signingContext = await resolveMuxSigningContext(workflowCredentials);
   if (policy === "signed" && !signingContext) {
-    throw new Error(
-      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   const transcriptResult = includeTranscript ? await fetchTranscriptForAsset(assetData, playbackId, {
+    languageCode,
     cleanTranscript,
     shouldSign: policy === "signed",
     credentials: workflowCredentials,
@@ -5127,7 +5359,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(
@@ -5163,18 +5395,17 @@ async function getSummaryAndTags(assetId, options) {
     }
   } catch (error) {
     const contentType = isAudioOnly ? "audio" : "video";
-    throw new Error(
-      `Failed to analyze ${contentType} content with ${provider}: ${error instanceof Error ? error.message : "Unknown error"}`
-    );
+    wrapError(error, `Failed to analyze ${contentType} content with ${provider}`);
   }
   if (!analysisResponse.result) {
-    throw new Error(`Failed to analyze video content for asset ${assetId}`);
+    const contentType = isAudioOnly ? "audio" : "video";
+    throw new MuxAiError(`Failed to analyze ${contentType} content for asset ${assetId}.`);
   }
   if (!analysisResponse.result.title) {
-    throw new Error(`Failed to generate title for asset ${assetId}`);
+    throw new MuxAiError(`Failed to generate title for asset ${assetId}.`);
   }
   if (!analysisResponse.result.description) {
-    throw new Error(`Failed to generate description for asset ${assetId}`);
+    throw new MuxAiError(`Failed to generate description for asset ${assetId}.`);
   }
   return {
     assetId,
@@ -5233,12 +5464,11 @@ async function requestStaticRenditionCreation(assetId, credentials) {
   } catch (error) {
     const statusCode = error?.status ?? error?.statusCode;
     const messages = error?.error?.messages;
-    const alreadyDefined = messages?.some((message2) => message2.toLowerCase().includes("already defined")) ?? error?.message?.toLowerCase().includes("already defined");
+    const alreadyDefined = messages?.some((message) => message.toLowerCase().includes("already defined")) ?? error?.message?.toLowerCase().includes("already defined");
     if (statusCode === 409 || alreadyDefined) {
       return;
     }
-    const message = error instanceof Error ? error.message : "Unknown error";
-    throw new Error(`Failed to request static rendition from Mux: ${message}`);
+    wrapError(error, "Failed to request static rendition from Mux");
   }
 }
 async function waitForAudioStaticRendition({
@@ -5272,13 +5502,14 @@ async function waitForAudioStaticRendition({
       `\u231B Waiting for static rendition (attempt ${attempt}/${STATIC_RENDITION_MAX_ATTEMPTS}) \u2192 ${currentStatus}`
     );
     if (currentStatus === "errored") {
-      throw new Error(
+      throw new MuxAiError(
         "Mux failed to create the static rendition for this asset. Please check the asset in the Mux dashboard."
       );
     }
   }
-  throw new Error(
-    "Timed out waiting for the static rendition to become ready. Please try again in a moment."
+  throw new MuxAiError(
+    "Timed out waiting for the static rendition to become ready. Please try again in a moment.",
+    { type: "timeout_error", retryable: true }
   );
 }
 async function fetchAudioFromMux(audioUrl) {
@@ -5424,22 +5655,25 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     fromLanguageCode,
     numSpeakers = 0,
     // 0 = auto-detect
-    uploadToMux = true,
+    uploadToS3: uploadToS3Option,
+    uploadToMux: uploadToMuxOption,
     storageAdapter,
     credentials: providedCredentials
   } = options;
   if (provider !== "elevenlabs") {
-    throw new Error("Only ElevenLabs provider is currently supported for audio translation");
+    throw new MuxAiError("Only ElevenLabs provider is currently supported for audio translation.", { type: "validation_error" });
   }
   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 MuxAiError("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.", { type: "validation_error" });
   }
   const { asset: initialAsset, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(initialAsset);
@@ -5454,8 +5688,9 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   }
   const audioRendition = getReadyAudioStaticRendition(currentAsset);
   if (!audioRendition) {
-    throw new Error(
-      "Unable to obtain an audio-only static rendition for this asset. Please verify static renditions are enabled in Mux."
+    throw new MuxAiError(
+      "Unable to obtain an audio-only static rendition for this asset. Please verify static renditions are enabled in Mux.",
+      { type: "validation_error" }
     );
   }
   let audioUrl = `https://stream.mux.com/${playbackId}/audio.m4a`;
@@ -5467,7 +5702,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   try {
     audioBuffer = await fetchAudioFromMux(audioUrl);
   } catch (error) {
-    throw new Error(`Failed to fetch audio from Mux: ${error instanceof Error ? error.message : "Unknown error"}`);
+    wrapError(error, "Failed to fetch audio from Mux");
   }
   console.warn("\u{1F399}\uFE0F Creating dubbing job in ElevenLabs...");
   const elevenLabsLangCode = toISO639_3(toLanguageCode);
@@ -5488,7 +5723,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     });
     console.warn(`\u2705 Dubbing job created with ID: ${dubbingId}`);
   } catch (error) {
-    throw new Error(`Failed to create ElevenLabs dubbing job: ${error instanceof Error ? error.message : "Unknown error"}`);
+    wrapError(error, "Failed to create ElevenLabs dubbing job");
   }
   console.warn("\u23F3 Waiting for dubbing to complete...");
   let dubbingStatus = "dubbing";
@@ -5509,77 +5744,72 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
         throw new Error("ElevenLabs dubbing job failed");
       }
     } catch (error) {
-      throw new Error(`Failed to check dubbing status: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, "Failed to check dubbing status");
     }
   }
   if (dubbingStatus !== "dubbed") {
-    throw new Error(`Dubbing job timed out or failed. Final status: ${dubbingStatus}`);
+    throw new MuxAiError("Audio translation timed out or failed. Please try again.", { type: "timeout_error", retryable: true });
   }
   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) {
+      wrapError(error, "Failed to download dubbed audio");
+    }
+    console.warn("\u{1F4E4} Uploading dubbed audio to S3-compatible storage...");
+    try {
+      presignedUrl = await uploadDubbedAudioToS3({
+        dubbedAudioBuffer,
+        assetId,
+        toLanguageCode,
+        s3Endpoint,
+        s3Region,
+        s3Bucket,
+        storageAdapter: effectiveStorageAdapter,
+        s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
+      });
+    } catch (error) {
+      wrapError(error, "Failed to upload audio to S3");
+    }
+    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 {
@@ -5910,9 +6140,7 @@ async function translateChunkWithFallback({
     };
   } catch (error) {
     if (!shouldSplitChunkTranslationError(error) || chunk.cueCount <= 1) {
-      throw new Error(
-        `Chunk ${chunk.id} failed for ${Math.round(chunk.startTime)}s-${Math.round(chunk.endTime)}s: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
+      wrapError(error, `Chunk ${chunk.id} failed for ${Math.round(chunk.startTime)}s-${Math.round(chunk.endTime)}s`);
     }
     const [leftChunk, rightChunk] = splitTranslationChunkAtMidpoint(chunk);
     const [leftResult, rightResult] = await Promise.all([
@@ -6021,7 +6249,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",
@@ -6029,6 +6257,7 @@ async function translateCaptions(assetId, fromLanguageCode, toLanguageCode, opti
     s3Endpoint: providedS3Endpoint,
     s3Region: providedS3Region,
     s3Bucket: providedS3Bucket,
+    uploadToS3: uploadToS3Option,
     uploadToMux: uploadToMuxOption,
     storageAdapter,
     credentials: providedCredentials,
@@ -6042,53 +6271,46 @@ 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 MuxAiError("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.", { type: "validation_error" });
   }
   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."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   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"}`
-      );
-    }
-    throw new Error(
-      `No ready text track found with language code '${fromLanguageCode}' for this asset. Available languages: ${availableLanguages || "none"}`
+    const availableTrackIds = readyTextTracks.map((t) => t.id).filter(Boolean).join(", ");
+    throw new MuxAiError(
+      `Track ${trackId} not found or not ready on asset ${assetId}. Available track IDs: ${availableTrackIds || "none"}.`,
+      { type: "validation_error" }
     );
   }
-  if (!sourceTextTrack.id) {
-    throw new Error("Transcript track is missing an id");
+  const fromLanguageCode = sourceTextTrack.language_code;
+  if (!fromLanguageCode) {
+    throw new MuxAiError(
+      `Track ${trackId} is missing language metadata. Cannot determine source language for translation.`,
+      { type: "validation_error" }
+    );
   }
-  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);
   } catch (error) {
-    throw new Error(`Failed to fetch VTT content: ${error instanceof Error ? error.message : "Unknown error"}`);
+    wrapError(error, "Failed to fetch VTT content");
   }
   let translatedVtt;
   let usage;
@@ -6106,7 +6328,7 @@ async function translateCaptions(assetId, fromLanguageCode, toLanguageCode, opti
     translatedVtt = result.translatedVtt;
     usage = result.usage;
   } catch (error) {
-    throw new Error(`Failed to translate VTT with ${modelConfig.provider}: ${error instanceof Error ? error.message : "Unknown error"}`);
+    wrapError(error, `Failed to translate VTT with ${modelConfig.provider}`);
   }
   const usageWithMetadata = usage ? {
     ...usage,
@@ -6116,50 +6338,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) {
+      wrapError(error, "Failed to upload VTT to S3");
+    }
+    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,
@@ -6172,6 +6387,7 @@ async function translateCaptions(assetId, fromLanguageCode, toLanguageCode, opti
   };
 }
 export {
+  MuxAiError,
   WorkflowStorageClient,
   createWorkflowStorageClient,
   decryptFromWorkflow,
@@ -6179,6 +6395,7 @@ export {
   primitives_exports as primitives,
   setWorkflowCredentialsProvider,
   version,
-  workflows_exports as workflows
+  workflows_exports as workflows,
+  wrapError
 };
 //# sourceMappingURL=index.js.map