@mux/ai 0.14.0 → 0.15.1

package/dist/workflows/index.js

@@ -110,6 +110,26 @@ async function downloadImagesAsBase64(urls, options = {}, maxConcurrent = 5) {
   return results;
 }
 
+// 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/lib/providers.ts
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
@@ -725,8 +745,9 @@ function getPlaybackId(asset) {
   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."
+  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) {
@@ -1282,15 +1303,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 };
   }
@@ -1306,14 +1328,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 };
@@ -1401,6 +1421,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.
 
@@ -1470,6 +1495,10 @@ var AUDIO_ONLY_SYSTEM_PROMPT = dedent`
   </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.
@@ -1480,6 +1509,14 @@ var AUDIO_ONLY_SYSTEM_PROMPT = dedent`
     - 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}"
@@ -1601,12 +1638,13 @@ async function analyzeQuestions({
 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" }
       );
     }
   });
@@ -1628,7 +1666,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({
@@ -1640,14 +1678,16 @@ async function askQuestions(assetId, questions, 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(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 transcriptResult = includeTranscript ? await fetchTranscriptForAsset(assetData, playbackId, {
@@ -1713,16 +1753,14 @@ async function askQuestions(assetId, questions, options) {
     }
   } catch (error) {
     const contentType = isAudioOnly ? "audio" : "video";
-    throw new Error(
-      `Failed to analyze ${contentType} questions with ${provider}: ${error instanceof Error ? error.message : "Unknown error"}`
-    );
+    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) => {
@@ -1796,6 +1834,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({
@@ -2276,8 +2317,9 @@ async function generateChapters(assetId, 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);
@@ -2290,14 +2332,15 @@ async function generateChapters(assetId, options = {}) {
   });
   if (!transcriptResult.track || !transcriptResult.transcriptText) {
     const availableLanguages = readyTextTracks.map((t) => t.language_code).filter(Boolean).join(", ");
-    throw new Error(
-      `No caption 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" }
     );
   }
   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;
@@ -2319,17 +2362,15 @@ async function generateChapters(assetId, 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;
@@ -2835,10 +2876,10 @@ 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;
@@ -2849,24 +2890,27 @@ async function editCaptions(assetId, trackId, options) {
   const s3AccessKeyId = env_default.S3_ACCESS_KEY_ID;
   const s3SecretAccessKey = env_default.S3_SECRET_ACCESS_KEY;
   if (uploadToS3 && (!s3Endpoint || !s3Bucket || !storageAdapter && (!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."
+    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);
@@ -2874,7 +2918,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;
@@ -2884,7 +2928,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,
@@ -2902,7 +2946,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);
@@ -2938,7 +2982,7 @@ async function editCaptions(assetId, trackId, options) {
         s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
       });
     } catch (error) {
-      throw new Error(`Failed to upload VTT to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, "Failed to upload VTT to S3");
     }
     if (uploadToMux) {
       try {
@@ -3535,6 +3579,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
@@ -3575,6 +3622,9 @@ var AUDIO_ONLY_SYSTEM_PROMPT2 = 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
@@ -3785,7 +3835,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,
@@ -3795,13 +3845,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";
@@ -3901,7 +3952,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) {
@@ -3922,8 +3973,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 = {
@@ -4726,6 +4777,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
@@ -4780,6 +4834,9 @@ var AUDIO_ONLY_SYSTEM_PROMPT3 = 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
@@ -4943,8 +5000,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({
@@ -4957,14 +5015,16 @@ 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, {
@@ -5026,18 +5086,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,
@@ -5096,12 +5155,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({
@@ -5135,13 +5193,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) {
@@ -5293,7 +5352,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     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;
@@ -5305,7 +5364,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   const s3AccessKeyId = env_default.S3_ACCESS_KEY_ID;
   const s3SecretAccessKey = env_default.S3_SECRET_ACCESS_KEY;
   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.");
+    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);
@@ -5320,8 +5379,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`;
@@ -5333,7 +5393,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);
@@ -5354,7 +5414,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";
@@ -5375,11 +5435,11 @@ 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!");
   let presignedUrl;
@@ -5409,7 +5469,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
       });
       console.warn("\u2705 Dubbed audio downloaded successfully!");
     } catch (error) {
-      throw new Error(`Failed to download dubbed audio: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, "Failed to download dubbed audio");
     }
     console.warn("\u{1F4E4} Uploading dubbed audio to S3-compatible storage...");
     try {
@@ -5424,7 +5484,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
         s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
       });
     } catch (error) {
-      throw new Error(`Failed to upload audio to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, "Failed to upload audio to S3");
     }
     if (uploadToMux) {
       console.warn("\u{1F4F9} Adding dubbed audio track to Mux asset...");
@@ -5771,9 +5831,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([
@@ -5911,28 +5969,31 @@ async function translateCaptions(assetId, trackId, toLanguageCode, options) {
     provider
   });
   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.");
+    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 sourceTextTrack = readyTextTracks.find((t) => t.id === trackId);
   if (!sourceTextTrack) {
     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 fromLanguageCode = sourceTextTrack.language_code;
   if (!fromLanguageCode) {
-    throw new Error(
-      `Track '${trackId}' is missing language metadata (language_code). Cannot determine source language for translation.`
+    throw new MuxAiError(
+      `Track ${trackId} is missing language metadata. Cannot determine source language for translation.`,
+      { type: "validation_error" }
     );
   }
   const vttUrl = await buildTranscriptUrl(playbackId, trackId, policy === "signed", credentials);
@@ -5940,7 +6001,7 @@ async function translateCaptions(assetId, trackId, toLanguageCode, 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 translatedVtt;
   let usage;
@@ -5958,7 +6019,7 @@ async function translateCaptions(assetId, trackId, toLanguageCode, options) {
     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,
@@ -5984,7 +6045,7 @@ async function translateCaptions(assetId, trackId, toLanguageCode, options) {
         s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
       });
     } catch (error) {
-      throw new Error(`Failed to upload VTT to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, "Failed to upload VTT to S3");
     }
     if (uploadToMux) {
       try {