@mux/ai 0.40.0 → 0.41.0

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.40.0";
+var version = "0.41.0";
 
 // src/lib/language-codes.ts
 var ISO639_1_TO_3 = {
@@ -1113,6 +1113,234 @@ async function resolveMuxSigningContext(credentials) {
   return { keyId, keySecret };
 }
 
+// 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);
+  if (!vttResponse.ok) {
+    throw new Error(`Failed to fetch VTT file: ${vttResponse.statusText}`);
+  }
+  return vttResponse.text();
+}
+async function createTextTrackOnMux(assetId, languageCode, trackName, presignedUrl, credentials, options = {}) {
+  "use step";
+  const muxClient = await resolveMuxClient(credentials);
+  const mux = await muxClient.createClient();
+  const trackResponse = await mux.video.assets.createTrack(assetId, {
+    type: "text",
+    text_type: "subtitles",
+    language_code: languageCode,
+    name: trackName,
+    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" } });
+}
+
 // node_modules/@workflow/serde/dist/index.js
 var WORKFLOW_SERIALIZE = /* @__PURE__ */ Symbol.for("workflow-serialize");
 var WORKFLOW_DESERIALIZE = /* @__PURE__ */ Symbol.for("workflow-deserialize");
@@ -4747,32 +4975,6 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
 import { generateText as generateText4, Output as Output4 } from "ai";
 import { z as z6 } from "zod";
 
-// src/lib/mux-tracks.ts
-async function fetchVttFromMux(vttUrl) {
-  "use step";
-  const vttResponse = await fetch(vttUrl);
-  if (!vttResponse.ok) {
-    throw new Error(`Failed to fetch VTT file: ${vttResponse.statusText}`);
-  }
-  return vttResponse.text();
-}
-async function createTextTrackOnMux(assetId, languageCode, trackName, presignedUrl, credentials) {
-  "use step";
-  const muxClient = await resolveMuxClient(credentials);
-  const mux = await muxClient.createClient();
-  const trackResponse = await mux.video.assets.createTrack(assetId, {
-    type: "text",
-    text_type: "subtitles",
-    language_code: languageCode,
-    name: trackName,
-    url: presignedUrl
-  });
-  if (!trackResponse.id) {
-    throw new Error("Failed to create text track: no track ID returned from Mux");
-  }
-  return trackResponse.id;
-}
-
 // src/lib/storage-adapter.ts
 function requireCredentials(accessKeyId, secretAccessKey) {
   if (!accessKeyId || !secretAccessKey) {
@@ -5051,6 +5253,7 @@ async function uploadEditedVttToS3({
   editedVtt,
   assetId,
   trackId,
+  variant = "edited",
   s3Endpoint,
   s3Region,
   s3Bucket,
@@ -5060,7 +5263,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,
@@ -5110,6 +5313,9 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
     s3Region: providedS3Region,
     s3Bucket: providedS3Bucket,
     trackNameSuffix,
+    replaceExistingTracks: replaceExistingTracksOption,
+    trackName: providedTrackName,
+    trackPassthrough: providedTrackPassthrough,
     storageAdapter,
     credentials
   } = options;
@@ -5122,6 +5328,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;
@@ -5164,6 +5385,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 {
@@ -5241,32 +5481,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");
@@ -5278,6 +5518,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 {
@@ -5290,6 +5572,7 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
     replacements: replacementsResult,
     speakerReplacements: speakerReplacementsResult,
     uploadedTrackId,
+    replacedTracks,
     presignedUrl,
     usage: usageWithMetadata,
     safety: safety.report()
@@ -7550,23 +7833,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 {
@@ -7579,15 +7845,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;
@@ -7598,6 +7872,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)) {
@@ -7613,6 +7896,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   let dubbingId;
   let presignedUrl;
   let uploadedTrackId;
+  let replacedTracks;
   let captionsPresignedUrl;
   let captionsTrackId;
   try {
@@ -7703,18 +7987,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...");
@@ -7732,15 +8027,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) {
@@ -7771,6 +8072,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     dubbingId,
     uploadedTrackId,
     presignedUrl,
+    replacedTracks,
     captionsTrackId,
     captionsPresignedUrl,
     createdStaticRenditionId,
@@ -8440,11 +8742,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;
@@ -8485,6 +8791,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 {
@@ -8552,6 +8868,7 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
   const targetLanguage = getLanguageCodePair(toLanguageCode);
   let presignedUrl;
   let uploadedTrackId;
+  let replacedTracks;
   if (uploadToS3) {
     try {
       presignedUrl = await uploadVttToS3({
@@ -8569,19 +8886,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 {
@@ -8594,6 +8920,7 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
     originalVtt: vttContent,
     translatedVtt,
     uploadedTrackId,
+    replacedTracks,
     presignedUrl,
     usage: usageWithMetadata,
     safety,
@@ -8601,20 +8928,33 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
   };
 }
 export {
+  MUX_TRACK_PASSTHROUGH_MAX_CHARS,
   MuxAiError,
   WorkflowStorageClient,
+  buildMuxAiTrackPassthrough,
   createWorkflowStorageClient,
   decryptFromWorkflow,
   encryptForWorkflow,
+  findNameCollisionTextTracks,
+  findSameLanguageTextTracks,
   getLanguageCodePair,
   getLanguageName,
+  isDuplicateTrackNameError,
+  isMuxGeneratedTextTrack,
   isUndeterminedLanguageCode,
   isValidISO639_1,
   isValidISO639_3,
+  normalizeTrackLanguageCode,
+  normalizeTrackName,
+  planTextTrackReplacement,
   primitives_exports as primitives,
+  replaceAndCreateTextTrack,
+  replaceAndCreateTrack,
   setWorkflowCredentialsProvider,
+  summarizeTextTrack,
   toISO639_1,
   toISO639_3,
+  validateTrackPassthrough,
   version,
   workflows_exports as workflows,
   wrapError