@mux/ai 0.39.0 → 0.41.0

package/dist/workflows/index.js

@@ -2928,11 +2928,8 @@ async function analyzeQuestions({
     maxRetries: 0,
     output: Output.object({ schema: responseSchema }),
     experimental_telemetry: { isEnabled: true },
+    system: systemPrompt,
     messages: [
-      {
-        role: "system",
-        content: systemPrompt
-      },
       {
         role: "user",
         content: imageDataUrl ? [
@@ -3346,11 +3343,8 @@ async function analyzeStoryboard({
     maxRetries: 0,
     output: Output2.object({ schema: burnedInCaptionsSchema }),
     experimental_telemetry: { isEnabled: true },
+    system: systemPrompt,
     messages: [
-      {
-        role: "system",
-        content: systemPrompt
-      },
       {
         role: "user",
         content: [
@@ -3495,11 +3489,8 @@ async function generateChaptersWithAI({
     model,
     maxRetries: 0,
     output: Output3.object({ schema: chaptersSchema }),
+    system: systemPrompt,
     messages: [
-      {
-        role: "system",
-        content: systemPrompt
-      },
       {
         role: "user",
         content: userPrompt
@@ -3788,6 +3779,129 @@ import { generateText as generateText4, Output as Output4 } from "ai";
 import { z as z6 } from "zod";
 
 // src/lib/mux-tracks.ts
+var MUX_TRACK_PASSTHROUGH_MAX_CHARS = 255;
+function normalizeTrackLanguageCode(code) {
+  if (!code) {
+    return void 0;
+  }
+  const primarySubtag = code.trim().toLowerCase().split(/[-_]/)[0];
+  if (!primarySubtag || primarySubtag === "auto" || isUndeterminedLanguageCode(primarySubtag)) {
+    return void 0;
+  }
+  return toISO639_1(primarySubtag);
+}
+function normalizeTrackName(name) {
+  const normalized = name?.trim().toLowerCase();
+  return normalized || void 0;
+}
+function isMuxGeneratedTextTrack(track) {
+  return track.text_source === "generated_vod" || track.text_source === "generated_live" || track.text_source === "generated_live_final";
+}
+function targetType(target) {
+  return target.type ?? "text";
+}
+function listTracks(asset, type) {
+  return (asset.tracks ?? []).filter((track) => track.type === type && track.status !== "deleted" && !!track.id);
+}
+function summarizeTextTrack(track) {
+  return {
+    id: track.id,
+    type: track.type === "audio" ? "audio" : "text",
+    name: track.name,
+    languageCode: track.language_code,
+    status: track.status,
+    textSource: track.text_source,
+    passthrough: track.passthrough,
+    ...track.type === "audio" ? { primary: track.primary === true } : {}
+  };
+}
+function findSameLanguageTextTracks(asset, target) {
+  const targetLanguage = normalizeTrackLanguageCode(target.languageCode);
+  if (!targetLanguage) {
+    return [];
+  }
+  const type = targetType(target);
+  return listTracks(asset, type).filter(
+    (track) => (type === "audio" || track.text_type === "subtitles") && normalizeTrackLanguageCode(track.language_code) === targetLanguage
+  );
+}
+function findNameCollisionTextTracks(asset, target) {
+  const targetName = normalizeTrackName(target.name);
+  if (!targetName) {
+    return [];
+  }
+  return listTracks(asset, targetType(target)).filter((track) => normalizeTrackName(track.name) === targetName);
+}
+function describeTracks(tracks) {
+  return tracks.map((track) => `${track.name ?? "(unnamed)"} [${track.language_code ?? "?"}, ${track.type === "audio" ? track.primary ? "primary audio" : "audio" : track.text_source ?? "unknown source"}, ${track.status ?? "ready"}]`).join("; ");
+}
+function planTextTrackReplacement(asset, target, policy, options = {}) {
+  const label = targetType(target) === "audio" ? "Audio" : "Text";
+  const keep = new Set(options.keepTrackIds ?? []);
+  const conflicts = /* @__PURE__ */ new Map();
+  for (const track of [...findSameLanguageTextTracks(asset, target), ...findNameCollisionTextTracks(asset, target)]) {
+    if (!keep.has(track.id)) {
+      conflicts.set(track.id, track);
+    }
+  }
+  const conflicting = [...conflicts.values()];
+  if (conflicting.length === 0) {
+    return { kind: "clear" };
+  }
+  if (policy === "fail") {
+    return {
+      kind: "blocked",
+      reason: `${label} track(s) already exist for language '${target.languageCode}' or name '${target.name}': ${describeTracks(conflicting)}. Set replaceExistingTracks to replace them.`,
+      tracks: conflicting.map(summarizeTextTrack)
+    };
+  }
+  const primary = conflicting.filter((track) => track.type === "audio" && track.primary === true);
+  if (primary.length > 0) {
+    return {
+      kind: "blocked",
+      reason: `The asset's primary audio track is in the way for language '${target.languageCode}' or name '${target.name}': ${describeTracks(primary)}. Primary audio cannot be replaced; choose a different trackName.`,
+      tracks: primary.map(summarizeTextTrack)
+    };
+  }
+  if (policy === "replace_generated") {
+    const notGenerated = conflicting.filter((track) => track.type !== "text" || !isMuxGeneratedTextTrack(track));
+    if (notGenerated.length > 0) {
+      return {
+        kind: "blocked",
+        reason: `${label} track(s) that are not Mux-generated exist for language '${target.languageCode}' or name '${target.name}': ${describeTracks(notGenerated)}. Use replaceExistingTracks: "replace_all" to replace them.`,
+        tracks: notGenerated.map(summarizeTextTrack)
+      };
+    }
+  }
+  return { kind: "replace", toDelete: conflicting.map(summarizeTextTrack) };
+}
+function isDuplicateTrackNameError(error) {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const record = error;
+  if (record.status !== 400) {
+    return false;
+  }
+  const messages = Array.isArray(record.error?.messages) ? record.error.messages : [];
+  const haystack = [...messages, record.message].filter((value) => typeof value === "string").map((value) => value.toLowerCase());
+  return haystack.some((value) => value.includes("is not unique"));
+}
+function isNotFoundError(error) {
+  return typeof error === "object" && error !== null && error.status === 404;
+}
+function buildMuxAiTrackPassthrough(workflow) {
+  return JSON.stringify({ mux_ai: { workflow } });
+}
+function validateTrackPassthrough(passthrough) {
+  if (passthrough !== void 0 && passthrough.length > MUX_TRACK_PASSTHROUGH_MAX_CHARS) {
+    throw new MuxAiError(
+      `Track passthrough must be at most ${MUX_TRACK_PASSTHROUGH_MAX_CHARS} characters (received ${passthrough.length}).`,
+      { type: "validation_error" }
+    );
+  }
+  return passthrough;
+}
 async function fetchVttFromMux(vttUrl) {
   "use step";
   const vttResponse = await fetch(vttUrl);
@@ -3796,7 +3910,7 @@ async function fetchVttFromMux(vttUrl) {
   }
   return vttResponse.text();
 }
-async function createTextTrackOnMux(assetId, languageCode, trackName, presignedUrl, credentials) {
+async function createTextTrackOnMux(assetId, languageCode, trackName, presignedUrl, credentials, options = {}) {
   "use step";
   const muxClient = await resolveMuxClient(credentials);
   const mux = await muxClient.createClient();
@@ -3805,13 +3919,92 @@ async function createTextTrackOnMux(assetId, languageCode, trackName, presignedU
     text_type: "subtitles",
     language_code: languageCode,
     name: trackName,
-    url: presignedUrl
+    url: presignedUrl,
+    closed_captions: options.closedCaptions,
+    passthrough: options.passthrough
   });
   if (!trackResponse.id) {
     throw new Error("Failed to create text track: no track ID returned from Mux");
   }
   return trackResponse.id;
 }
+async function replaceAndCreateTrack(input) {
+  "use step";
+  const muxClient = await resolveMuxClient(input.credentials);
+  const mux = await muxClient.createClient();
+  const type = targetType(input.target);
+  const deleted = [];
+  const failed = (error) => ({
+    kind: "create_failed",
+    reason: error instanceof Error ? error.message : String(error),
+    deleted
+  });
+  const clearConflicts = async () => {
+    let asset;
+    try {
+      asset = await mux.video.assets.retrieve(input.assetId);
+    } catch (error) {
+      if (deleted.length === 0) {
+        throw error;
+      }
+      return failed(error);
+    }
+    const plan = planTextTrackReplacement(asset, input.target, input.policy, { keepTrackIds: input.keepTrackIds });
+    if (plan.kind === "blocked") {
+      return { ...plan, deleted };
+    }
+    if (plan.kind === "replace") {
+      for (const track of plan.toDelete) {
+        try {
+          await mux.video.assets.deleteTrack(input.assetId, track.id);
+          deleted.push(track);
+        } catch (error) {
+          if (!isNotFoundError(error)) {
+            return failed(error);
+          }
+        }
+      }
+    }
+    return void 0;
+  };
+  const create = async () => {
+    const track = await mux.video.assets.createTrack(input.assetId, {
+      type,
+      ...type === "text" ? { text_type: "subtitles", closed_captions: input.closedCaptions } : {},
+      language_code: input.target.languageCode,
+      name: input.target.name.trim(),
+      url: input.presignedUrl,
+      passthrough: input.passthrough
+    });
+    if (!track.id) {
+      throw new Error(`Failed to create ${type} track: no track ID returned from Mux`);
+    }
+    return track.id;
+  };
+  const stopped = await clearConflicts();
+  if (stopped) {
+    return stopped;
+  }
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      return { kind: "created", trackId: await create(), deleted };
+    } catch (error) {
+      if (isDuplicateTrackNameError(error) && attempt === 0) {
+        const stoppedOnRetry = await clearConflicts();
+        if (stoppedOnRetry) {
+          return stoppedOnRetry;
+        }
+        continue;
+      }
+      return failed(error);
+    }
+  }
+  return { kind: "create_failed", reason: "Mux rejected the track name as not unique after retrying.", deleted };
+}
+async function replaceAndCreateTextTrack(input) {
+  "use step";
+  return replaceAndCreateTrack({ ...input, target: { ...input.target, type: "text" } });
+}
 
 // src/lib/s3-sigv4.ts
 var AWS4_ALGORITHM = "AWS4-HMAC-SHA256";
@@ -4271,11 +4464,8 @@ async function identifyProfanityWithAI({
     model,
     maxRetries: 0,
     output: Output4.object({ schema: profanityDetectionSchema }),
+    system: SYSTEM_PROMPT3,
     messages: [
-      {
-        role: "system",
-        content: SYSTEM_PROMPT3
-      },
       {
         role: "user",
         content: `Identify all profane words and phrases in the following subtitle transcript. Return each unique profane word or phrase exactly as it appears in the text.
@@ -4306,6 +4496,7 @@ async function uploadEditedVttToS3({
   editedVtt,
   assetId,
   trackId,
+  variant = "edited",
   s3Endpoint,
   s3Region,
   s3Bucket,
@@ -4315,7 +4506,7 @@ async function uploadEditedVttToS3({
   "use step";
   const s3AccessKeyId = env_default.S3_ACCESS_KEY_ID;
   const s3SecretAccessKey = env_default.S3_SECRET_ACCESS_KEY;
-  const vttKey = `edited/${assetId}/${trackId}-edited-${Date.now()}.vtt`;
+  const vttKey = `edited/${assetId}/${trackId}-${variant}-${Date.now()}.vtt`;
   await putObjectWithStorageAdapter({
     accessKeyId: s3AccessKeyId,
     secretAccessKey: s3SecretAccessKey,
@@ -4365,6 +4556,9 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
     s3Region: providedS3Region,
     s3Bucket: providedS3Bucket,
     trackNameSuffix,
+    replaceExistingTracks: replaceExistingTracksOption,
+    trackName: providedTrackName,
+    trackPassthrough: providedTrackPassthrough,
     storageAdapter,
     credentials
   } = options;
@@ -4377,6 +4571,21 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
   if (autoCensorOption && !provider) {
     throw new MuxAiError("provider is required when using autoCensorProfanity.", { type: "validation_error" });
   }
+  const legacyTrackNaming = deleteOriginalTrack !== void 0 || trackNameSuffix !== void 0;
+  if (legacyTrackNaming && (replaceExistingTracksOption !== void 0 || providedTrackName !== void 0)) {
+    throw new MuxAiError(
+      "deleteOriginalTrack and trackNameSuffix are deprecated and cannot be combined with replaceExistingTracks or trackName.",
+      { type: "validation_error" }
+    );
+  }
+  const replaceExistingTracks = replaceExistingTracksOption ?? "replace_all";
+  if (!legacyTrackNaming && replaceExistingTracks === "fail" && !providedTrackName) {
+    throw new MuxAiError(
+      `trackName is required when replaceExistingTracks is "fail": the edited track cannot reuse the source track's name while the source is kept.`,
+      { type: "validation_error" }
+    );
+  }
+  const trackPassthrough = validateTrackPassthrough(providedTrackPassthrough) ?? buildMuxAiTrackPassthrough("edit-captions");
   const deleteOriginal = deleteOriginalTrack !== false;
   const uploadToMux = uploadToMuxOption !== false;
   const uploadToS3 = uploadToS3Option || uploadToMux;
@@ -4419,6 +4628,25 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
       { type: "validation_error" }
     );
   }
+  const sourceLanguageCode = sourceTrack.language_code || "en";
+  const sourceName = sourceTrack.name || "Subtitles";
+  const outputTrack = {
+    languageCode: sourceLanguageCode,
+    name: providedTrackName ?? sourceName
+  };
+  const keepTrackIds = replaceExistingTracks === "fail" ? [trackId] : [];
+  if (replaceExistingTracks === "fail" && normalizeTrackName(outputTrack.name) === normalizeTrackName(sourceName)) {
+    throw new MuxAiError(
+      `trackName "${outputTrack.name}" matches the source track's name. Mux track names must be unique; choose a different trackName or use replaceExistingTracks: "replace_all" to replace the source.`,
+      { type: "validation_error" }
+    );
+  }
+  if (uploadToMux && !legacyTrackNaming) {
+    const plan = planTextTrackReplacement(assetData, outputTrack, replaceExistingTracks, { keepTrackIds });
+    if (plan.kind === "blocked") {
+      throw new MuxAiError(plan.reason, { type: "validation_error" });
+    }
+  }
   const vttUrl = await buildTranscriptUrl(playbackId, trackId, policy === "signed", credentials);
   let vttContent;
   try {
@@ -4496,32 +4724,32 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
   } : void 0;
   let presignedUrl;
   let uploadedTrackId;
+  let replacedTracks;
   if (uploadToS3) {
+    const s3Config = {
+      assetId,
+      trackId,
+      s3Endpoint,
+      s3Region,
+      s3Bucket,
+      storageAdapter,
+      s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
+    };
     try {
-      presignedUrl = await uploadEditedVttToS3({
-        editedVtt,
-        assetId,
-        trackId,
-        s3Endpoint,
-        s3Region,
-        s3Bucket,
-        storageAdapter,
-        s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
-      });
+      presignedUrl = await uploadEditedVttToS3({ editedVtt, ...s3Config });
     } catch (error) {
       wrapError(error, "Failed to upload VTT to S3");
     }
-    if (uploadToMux) {
+    if (uploadToMux && legacyTrackNaming) {
       try {
-        const languageCode = sourceTrack.language_code || "en";
-        const suffix = trackNameSuffix ?? "edited";
-        const trackName = `${sourceTrack.name || "Subtitles"} (${suffix})`;
+        const trackName = `${sourceName} (${trackNameSuffix ?? "edited"})`;
         uploadedTrackId = await createTextTrackOnMux(
           assetId,
-          languageCode,
+          sourceLanguageCode,
           trackName,
           presignedUrl,
-          credentials
+          credentials,
+          { closedCaptions: sourceTrack.closed_captions, passthrough: trackPassthrough }
         );
       } catch (error) {
         wrapError(error, "Failed to add edited track to Mux asset");
@@ -4533,6 +4761,48 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
           wrapError(error, "Failed to delete original track");
         }
       }
+    } else if (uploadToMux) {
+      let outcome;
+      try {
+        outcome = await replaceAndCreateTextTrack({
+          assetId,
+          target: outputTrack,
+          policy: replaceExistingTracks,
+          presignedUrl,
+          closedCaptions: sourceTrack.closed_captions,
+          passthrough: trackPassthrough,
+          keepTrackIds,
+          credentials
+        });
+      } catch (error) {
+        wrapError(error, "Failed to add edited track to Mux asset");
+      }
+      if (outcome.kind !== "created") {
+        const sourceWasDeleted = outcome.deleted.some((track) => track.id === trackId);
+        let restoreNote = "";
+        if (sourceWasDeleted) {
+          try {
+            const originalUrl = await uploadEditedVttToS3({ editedVtt: vttContent, variant: "original", ...s3Config });
+            const restoredTrackId = await createTextTrackOnMux(
+              assetId,
+              sourceLanguageCode,
+              sourceName,
+              originalUrl,
+              credentials,
+              { closedCaptions: sourceTrack.closed_captions, passthrough: sourceTrack.passthrough }
+            );
+            restoreNote = ` The source track was restored as ${restoredTrackId}.`;
+          } catch (restoreError) {
+            restoreNote = ` Restoring the source track also failed: ${restoreError instanceof Error ? restoreError.message : String(restoreError)}.`;
+          }
+        }
+        if (outcome.kind === "blocked") {
+          throw new MuxAiError(`${outcome.reason}${restoreNote}`, { type: "validation_error" });
+        }
+        throw new Error(`Failed to add edited track to Mux asset: ${outcome.reason}.${restoreNote}`);
+      }
+      uploadedTrackId = outcome.trackId;
+      replacedTracks = outcome.deleted;
     }
   }
   return {
@@ -4545,6 +4815,7 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
     replacements: replacementsResult,
     speakerReplacements: speakerReplacementsResult,
     uploadedTrackId,
+    replacedTracks,
     presignedUrl,
     usage: usageWithMetadata,
     safety: safety.report()
@@ -5390,11 +5661,8 @@ async function generateInsightsWithAI(provider, modelId, systemPrompt, userPromp
     maxRetries: 0,
     output: Output5.object({ schema: engagementInsightsSchema }),
     experimental_telemetry: { isEnabled: true },
+    system: systemPrompt,
     messages: [
-      {
-        role: "system",
-        content: systemPrompt
-      },
       {
         role: "user",
         content: [
@@ -6697,11 +6965,8 @@ async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, s
       description: "Structured summary with title, description, and keywords.",
       schema
     }),
+    system: systemPrompt,
     messages: [
-      {
-        role: "system",
-        content: systemPrompt
-      },
       {
         role: "user",
         content: [
@@ -6745,11 +7010,8 @@ async function analyzeAudioOnly(provider, modelId, userPrompt, systemPrompt, des
       description: "Structured summary with title, description, and keywords.",
       schema
     }),
+    system: systemPrompt,
     messages: [
-      {
-        role: "system",
-        content: systemPrompt
-      },
       {
         role: "user",
         content: userPrompt
@@ -7241,23 +7503,6 @@ async function downloadAndUploadDubTranscript({
   console.warn(`\u2705 Dub transcript uploaded successfully to: ${vttKey}`);
   return presignedUrl;
 }
-async function createAudioTrackOnMux(assetId, languageCode, presignedUrl, credentials) {
-  "use step";
-  const muxClient = await resolveMuxClient(credentials);
-  const mux = await muxClient.createClient();
-  const languageName = new Intl.DisplayNames(["en"], { type: "language" }).of(languageCode) || languageCode.toUpperCase();
-  const trackName = `${languageName} (auto-dubbed)`;
-  const trackResponse = await mux.video.assets.createTrack(assetId, {
-    type: "audio",
-    language_code: languageCode,
-    name: trackName,
-    url: presignedUrl
-  });
-  if (!trackResponse.id) {
-    throw new Error("Failed to create audio track: no track ID returned from Mux");
-  }
-  return trackResponse.id;
-}
 async function translateAudio(assetId, toLanguageCode, options = {}) {
   "use workflow";
   const {
@@ -7270,15 +7515,23 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     uploadCaptionsToMux = false,
     staticRenditionCleanup: staticRenditionCleanupOption = "delete",
     storageAdapter,
-    credentials: providedCredentials
+    credentials: providedCredentials,
+    replaceExistingTracks = "fail",
+    trackName: providedTrackName,
+    trackPassthrough: providedTrackPassthrough
   } = options;
   if (provider !== "elevenlabs") {
     throw new MuxAiError("Only ElevenLabs provider is currently supported for audio translation.", { type: "validation_error" });
   }
   const credentials = providedCredentials;
   const effectiveStorageAdapter = storageAdapter;
+  const trackPassthrough = validateTrackPassthrough(providedTrackPassthrough) ?? buildMuxAiTrackPassthrough("translate-audio");
   const uploadToMux = uploadToMuxOption !== false;
   const uploadToS3 = uploadToS3Option || uploadToMux || uploadCaptionsToMux;
+  const muxLangCode = toISO639_1(toLanguageCode);
+  const trackName = providedTrackName ?? `${getLanguageName(muxLangCode) ?? muxLangCode.toUpperCase()} (Auto-dubbed)`;
+  const audioTrackTarget = { type: "audio", languageCode: muxLangCode, name: trackName };
+  const captionsTrackTarget = { type: "text", languageCode: muxLangCode, name: trackName };
   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;
@@ -7289,6 +7542,15 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   }
   const { asset: initialAsset, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials, options.assetSnapshot);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(initialAsset);
+  for (const target of [
+    ...uploadToMux ? [audioTrackTarget] : [],
+    ...uploadCaptionsToMux ? [captionsTrackTarget] : []
+  ]) {
+    const plan = planTextTrackReplacement(initialAsset, target, replaceExistingTracks);
+    if (plan.kind === "blocked") {
+      throw new MuxAiError(plan.reason, { type: "validation_error" });
+    }
+  }
   let currentAsset = initialAsset;
   let createdStaticRenditionId;
   if (!hasReadyAudioStaticRendition(currentAsset)) {
@@ -7304,6 +7566,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   let dubbingId;
   let presignedUrl;
   let uploadedTrackId;
+  let replacedTracks;
   let captionsPresignedUrl;
   let captionsTrackId;
   try {
@@ -7394,18 +7657,29 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
       }
       if (uploadToMux) {
         console.warn("\u{1F4F9} Adding dubbed audio track to Mux asset...");
-        const muxLangCode = toISO639_1(toLanguageCode);
+        let outcome;
         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}"`);
+          outcome = await replaceAndCreateTrack({
+            assetId,
+            target: audioTrackTarget,
+            policy: replaceExistingTracks,
+            presignedUrl,
+            passthrough: trackPassthrough,
+            credentials
+          });
         } 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);
+          wrapError(error, `Failed to add dubbed audio track to Mux asset (dubbed audio is staged at: ${presignedUrl})`);
+        }
+        if (outcome.kind === "blocked") {
+          throw new MuxAiError(`${outcome.reason} Dubbed audio is staged at: ${presignedUrl}`, { type: "validation_error" });
         }
+        if (outcome.kind === "create_failed") {
+          throw new Error(`Failed to add dubbed audio track to Mux asset: ${outcome.reason}. Dubbed audio is staged at: ${presignedUrl}`);
+        }
+        uploadedTrackId = outcome.trackId;
+        replacedTracks = outcome.deleted;
+        console.warn(`\u2705 Track added to Mux asset with ID: ${uploadedTrackId}`);
+        console.warn(`\u{1F4CB} Track name: "${trackName}"`);
       }
       try {
         console.warn("\u{1F4E5} Downloading dub transcript from ElevenLabs and staging to S3...");
@@ -7423,15 +7697,21 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
         });
         if (uploadCaptionsToMux) {
           console.warn("\u{1F4F9} Adding dubbed captions track to Mux asset...");
-          const muxLangCode = toISO639_1(toLanguageCode);
-          const languageName = new Intl.DisplayNames(["en"], { type: "language" }).of(muxLangCode) || muxLangCode.toUpperCase();
-          captionsTrackId = await createTextTrackOnMux(
+          const captionsOutcome = await replaceAndCreateTrack({
             assetId,
-            muxLangCode,
-            `${languageName} (auto-dubbed)`,
-            captionsPresignedUrl,
+            target: captionsTrackTarget,
+            policy: replaceExistingTracks,
+            presignedUrl: captionsPresignedUrl,
+            passthrough: trackPassthrough,
             credentials
-          );
+          });
+          if (captionsOutcome.deleted.length > 0) {
+            replacedTracks = [...replacedTracks ?? [], ...captionsOutcome.deleted];
+          }
+          if (captionsOutcome.kind !== "created") {
+            throw new Error(captionsOutcome.reason);
+          }
+          captionsTrackId = captionsOutcome.trackId;
           console.warn(`\u2705 Captions track added to Mux asset with ID: ${captionsTrackId}`);
         }
       } catch (error) {
@@ -7462,6 +7742,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     dubbingId,
     uploadedTrackId,
     presignedUrl,
+    replacedTracks,
     captionsTrackId,
     captionsPresignedUrl,
     createdStaticRenditionId,
@@ -7813,11 +8094,8 @@ async function translateVttWithAI({
     model,
     maxRetries: 0,
     output: Output7.object({ schema: translationSchema }),
+    system: SYSTEM_PROMPT6,
     messages: [
-      {
-        role: "system",
-        content: SYSTEM_PROMPT6
-      },
       {
         role: "user",
         content: `Translate from ${fromLanguageCode} to ${toLanguageCode}:${buildNeverTranslateSection(neverTranslate)}
@@ -7881,11 +8159,8 @@ async function translateCueChunkWithAI({
     model,
     maxRetries: 0,
     output: Output7.object({ schema }),
+    system: CUE_TRANSLATION_SYSTEM_PROMPT,
     messages: [
-      {
-        role: "system",
-        content: CUE_TRANSLATION_SYSTEM_PROMPT
-      },
       {
         role: "user",
         content: `Translate from ${fromLanguageCode} to ${toLanguageCode}.
@@ -8137,11 +8412,15 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
     storageAdapter,
     credentials: providedCredentials,
     chunking,
-    neverTranslate: neverTranslateOption
+    neverTranslate: neverTranslateOption,
+    replaceExistingTracks = "fail",
+    trackName: providedTrackName,
+    trackPassthrough: providedTrackPassthrough
   } = options;
   const credentials = providedCredentials;
   const effectiveStorageAdapter = storageAdapter;
   const neverTranslateTerms = neverTranslateOption ? validateNeverTranslateTerms(neverTranslateOption) : [];
+  const trackPassthrough = validateTrackPassthrough(providedTrackPassthrough) ?? buildMuxAiTrackPassthrough("translate-captions");
   const s3Endpoint = providedS3Endpoint ?? env_default.S3_ENDPOINT;
   const s3Region = providedS3Region ?? env_default.S3_REGION ?? "auto";
   const s3Bucket = providedS3Bucket ?? env_default.S3_BUCKET;
@@ -8182,6 +8461,16 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
       { type: "validation_error" }
     );
   }
+  const outputTrack = {
+    languageCode: toLanguageCode,
+    name: providedTrackName ?? `${getLanguageName(toLanguageCode) ?? toLanguageCode.toUpperCase()} (Auto-translated)`
+  };
+  if (uploadToMux) {
+    const plan = planTextTrackReplacement(assetData, outputTrack, replaceExistingTracks);
+    if (plan.kind === "blocked") {
+      throw new MuxAiError(plan.reason, { type: "validation_error" });
+    }
+  }
   const vttUrl = await buildTranscriptUrl(playbackId, trackId, policy === "signed", credentials);
   let vttContent;
   try {
@@ -8249,6 +8538,7 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
   const targetLanguage = getLanguageCodePair(toLanguageCode);
   let presignedUrl;
   let uploadedTrackId;
+  let replacedTracks;
   if (uploadToS3) {
     try {
       presignedUrl = await uploadVttToS3({
@@ -8266,19 +8556,28 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
       wrapError(error, "Failed to upload VTT to S3");
     }
     if (uploadToMux) {
+      let outcome;
       try {
-        const languageName = getLanguageName(toLanguageCode) ?? toLanguageCode.toUpperCase();
-        const trackName = `${languageName} (auto-translated)`;
-        uploadedTrackId = await createTextTrackOnMux(
+        outcome = await replaceAndCreateTextTrack({
           assetId,
-          toLanguageCode,
-          trackName,
+          target: outputTrack,
+          policy: replaceExistingTracks,
           presignedUrl,
+          passthrough: trackPassthrough,
           credentials
-        );
+        });
       } catch (error) {
-        console.warn(`Failed to add track to Mux asset: ${error instanceof Error ? error.message : "Unknown error"}`);
+        wrapError(error, "Failed to add translated track to Mux asset");
+      }
+      if (outcome.kind !== "created") {
+        const deletedNote = outcome.deleted.length > 0 ? ` Tracks already deleted before the failure: ${outcome.deleted.map((track) => `${track.name ?? track.id} (${track.id})`).join(", ")}.` : "";
+        if (outcome.kind === "blocked") {
+          throw new MuxAiError(`${outcome.reason}${deletedNote}`, { type: "validation_error" });
+        }
+        throw new Error(`Failed to add translated track to Mux asset: ${outcome.reason}.${deletedNote}`);
       }
+      uploadedTrackId = outcome.trackId;
+      replacedTracks = outcome.deleted;
     }
   }
   return {
@@ -8291,6 +8590,7 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
     originalVtt: vttContent,
     translatedVtt,
     uploadedTrackId,
+    replacedTracks,
     presignedUrl,
     usage: usageWithMetadata,
     safety,