@mux/ai 0.40.0 → 0.42.0

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.40.0";
+var version = "0.42.0";
 
 // src/lib/language-codes.ts
 var ISO639_1_TO_3 = {
@@ -446,6 +446,7 @@ var PROMPT_TAG_NAMES = [
   "answer_guidelines",
   "relevance_filtering",
   "transcript_guidance",
+  "scene_guidance",
   "capabilities",
   "language_guidelines",
   "tone_guidance",
@@ -1113,6 +1114,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");
@@ -4540,6 +4769,17 @@ var AUDIO_ONLY_SYSTEM_PROMPT_OVERRIDES = {
     You receive a timestamped transcript from audio-only content with lines in the form "[12s] Transcript text".
     Use those timestamps as anchors to determine chapter start times in seconds.`
 };
+var SCENE_CONTEXT_SYSTEM_PROMPT_OVERRIDES = {
+  context: dedent4`
+    You receive a timestamped transcript with lines in the form "[12s] Caption text" and an ordered scene context.
+    Transcript timestamps are in seconds. Scene start and end timestamps are in milliseconds.
+    Use the scene progression to choose logical chapter groupings and scene starts as chapter boundaries.`,
+  constraints: dedent4`
+    - Only use information present in the transcript and scene context
+    - Return structured data that matches the requested JSON schema
+    - Do not add commentary or extra text outside the JSON
+    - When a <language> section is provided, all chapter titles MUST be written in that language`
+};
 var chaptersPromptBuilder = createPromptBuilder({
   template: {
     task: {
@@ -4577,6 +4817,7 @@ var chaptersPromptBuilder = createPromptBuilder({
 });
 function buildUserPrompt3({
   timestampedTranscript,
+  sceneContext,
   promptOverrides,
   minChaptersPerHour = 3,
   maxChaptersPerHour = 8,
@@ -4590,14 +4831,31 @@ function buildUserPrompt3({
       attributes: { format: "seconds" }
     }
   ];
+  if (sceneContext?.length) {
+    contextSections.push({
+      tag: "scene_context",
+      content: JSON.stringify(sceneContext, null, 2),
+      attributes: { timestamps: "milliseconds", trust: "untrusted_evidence" }
+    });
+  }
   if (languageName) {
     contextSections.push(createLanguageSection(languageName));
   }
+  const sceneBoundarySeconds = getSceneBoundarySeconds(sceneContext).filter(
+    (boundary) => scope ? boundary >= scope.startTime && boundary < scope.endTime : true
+  );
+  let firstChapterGuideline = "";
+  if (sceneBoundarySeconds.length > 0) {
+    firstChapterGuideline = `- The first chapter must start at ${sceneBoundarySeconds[0]}s, the first scene boundary inside the analyzed range`;
+  } else if (scope) {
+    firstChapterGuideline = `- The first chapter must start at ${scope.startTime}s`;
+  }
   const dynamicChapterGuidelines = dedent4`
     - Create at least ${minChaptersPerHour} and at most ${maxChaptersPerHour} chapters per hour of content
     - Use start times in seconds (not HH:MM:SS)
-    ${scope ? `- Analyze only the range from ${scope.startTime}s (inclusive) to ${scope.endTime}s (exclusive)
-- The first chapter must start at ${scope.startTime}s` : ""}
+    ${scope ? `- Analyze only the range from ${scope.startTime}s (inclusive) to ${scope.endTime}s (exclusive)` : ""}
+    ${firstChapterGuideline}
+    ${sceneContext?.length ? "- Use the ordered scene context to identify chapter-sized runs of consecutive scenes\n- Every chapter startTime must exactly equal a scene start_ms divided by 1000; never split a scene" : ""}
     - Chapter start times should be non-decreasing
     - Do not include text before or after the JSON`;
   const mergedOverrides = {
@@ -4606,6 +4864,32 @@ function buildUserPrompt3({
   };
   return chaptersPromptBuilder.buildWithContext(mergedOverrides, contextSections);
 }
+function getSceneBoundarySeconds(sceneContext) {
+  if (!sceneContext?.length) {
+    return [];
+  }
+  return [...new Set(sceneContext.map((scene) => scene.start_ms / 1e3))].sort((a, b) => a - b);
+}
+function alignChaptersToSceneBoundaries(chapters, sceneBoundarySeconds) {
+  if (sceneBoundarySeconds.length === 0) {
+    return chapters;
+  }
+  const chapterByBoundary = /* @__PURE__ */ new Map();
+  for (const chapter of chapters) {
+    const startTime = sceneBoundarySeconds.reduce(
+      (closest, boundary) => Math.abs(boundary - chapter.startTime) < Math.abs(closest - chapter.startTime) ? boundary : closest
+    );
+    const distance = Math.abs(startTime - chapter.startTime);
+    const existing = chapterByBoundary.get(startTime);
+    if (!existing || distance === 0 && existing.distance !== 0) {
+      chapterByBoundary.set(startTime, {
+        chapter: { ...chapter, startTime },
+        distance
+      });
+    }
+  }
+  return [...chapterByBoundary.values()].map(({ chapter }) => chapter).sort((a, b) => a.startTime - b.startTime);
+}
 async function generateChapters(assetId, options = {}) {
   "use workflow";
   const collectedUsage = [];
@@ -4625,7 +4909,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     maxChaptersPerHour,
     credentials,
     outputLanguageCode,
-    scope
+    scope,
+    sceneContext
   } = options;
   const modelConfig = resolveLanguageModelConfig({
     ...options,
@@ -4667,8 +4952,18 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
   }
   const resolvedLanguageCode = outputLanguageCode && outputLanguageCode !== "auto" ? outputLanguageCode : getReliableLanguageCode(transcriptResult.track) ?? languageCode;
   const languageName = resolvedLanguageCode ? getLanguageName(resolvedLanguageCode) : void 0;
+  const sceneBoundarySeconds = getSceneBoundarySeconds(sceneContext).filter(
+    (boundary) => resolvedScope ? boundary >= resolvedScope.startTime && boundary < resolvedScope.endTime : true
+  );
+  if (sceneContext?.length && sceneBoundarySeconds.length === 0) {
+    throw new MuxAiError(
+      "Scene context has no chapter boundaries within the requested scope.",
+      { type: "validation_error" }
+    );
+  }
   const userPrompt = buildUserPrompt3({
     timestampedTranscript,
+    sceneContext,
     promptOverrides,
     minChaptersPerHour,
     maxChaptersPerHour,
@@ -4677,7 +4972,11 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
   });
   let chaptersData = null;
   try {
-    const systemPrompt = isAudioOnly ? chapterSystemPromptBuilder.build(AUDIO_ONLY_SYSTEM_PROMPT_OVERRIDES) : chapterSystemPromptBuilder.build();
+    const systemPromptOverrides = {
+      ...isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT_OVERRIDES : {},
+      ...sceneContext?.length ? SCENE_CONTEXT_SYSTEM_PROMPT_OVERRIDES : {}
+    };
+    const systemPrompt = chapterSystemPromptBuilder.build(systemPromptOverrides);
     chaptersData = await generateChaptersWithAI({
       provider: modelConfig.provider,
       modelId: modelConfig.modelId,
@@ -4695,9 +4994,13 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     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").filter(
+  const scopedChapters = chaptersPayload.chapters.filter((chapter) => typeof chapter.startTime === "number" && typeof chapter.title === "string").filter(
     (chapter) => resolvedScope ? chapter.startTime >= resolvedScope.startTime && chapter.startTime < resolvedScope.endTime : true
   ).sort((a, b) => a.startTime - b.startTime);
+  const validChapters = alignChaptersToSceneBoundaries(
+    scopedChapters,
+    sceneBoundarySeconds
+  );
   if (validChapters.length === 0) {
     throw new MuxAiError(`Failed to generate valid chapters for asset ${assetId}.`);
   }
@@ -4723,9 +5026,11 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
   if (scrubbedChapters.length === 0) {
     throw new MuxAiError(`Failed to generate valid chapters for asset ${assetId}.`);
   }
-  const firstChapterStartTime = resolvedScope?.startTime ?? 0;
-  if (scrubbedChapters[0].startTime !== firstChapterStartTime) {
-    scrubbedChapters[0].startTime = firstChapterStartTime;
+  if (sceneBoundarySeconds.length === 0) {
+    const firstChapterStartTime = resolvedScope?.startTime ?? 0;
+    if (scrubbedChapters[0].startTime !== firstChapterStartTime) {
+      scrubbedChapters[0].startTime = firstChapterStartTime;
+    }
   }
   const usageWithMetadata = {
     ...usage,
@@ -4747,32 +5052,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 +5330,7 @@ async function uploadEditedVttToS3({
   editedVtt,
   assetId,
   trackId,
+  variant = "edited",
   s3Endpoint,
   s3Region,
   s3Bucket,
@@ -5060,7 +5340,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 +5390,9 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
     s3Region: providedS3Region,
     s3Bucket: providedS3Bucket,
     trackNameSuffix,
+    replaceExistingTracks: replaceExistingTracksOption,
+    trackName: providedTrackName,
+    trackPassthrough: providedTrackPassthrough,
     storageAdapter,
     credentials
   } = options;
@@ -5122,6 +5405,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 +5462,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 +5558,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 +5595,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 +5649,7 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
     replacements: replacementsResult,
     speakerReplacements: speakerReplacementsResult,
     uploadedTrackId,
+    replacedTracks,
     presignedUrl,
     usage: usageWithMetadata,
     safety: safety.report()
@@ -6777,14 +7137,44 @@ function buildDescriptionGuidance(wordCount, contentType) {
     Write in present tense. Be specific about what is discussed or presented rather than making assumptions.
     Focus on the spoken content and any key insights, dialogue, or narrative elements.`;
 }
-function createSummarizationBuilder({ titleLength, descriptionLength, tagCount } = {}) {
+function buildSceneAwareDescriptionGuidance(wordCount) {
+  if (wordCount < DESCRIPTION_LENGTH_THRESHOLD_SMALL) {
+    return dedent6`A brief summary of the video in no more than ${wordCount} words. Shorter is fine.
+      Focus on the single most important subject or action across the ordered scenes.
+      Use the storyboard as direct visual evidence and the scene context to preserve progression.
+      Write in present tense.`;
+  }
+  if (wordCount > DESCRIPTION_LENGTH_THRESHOLD_LARGE) {
+    return dedent6`A detailed summary that describes what happens across the ordered scenes.
+      Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
+      Be thorough: cover subjects, actions, setting, progression, and notable details supported across scenes.
+      Use the storyboard as direct visual evidence and the scene context to preserve progression.
+      Write in present tense. If the transcript provides dialogue or narration, incorporate key points while preserving scene progression.`;
+  }
+  return dedent6`A summary that describes what happens across the ordered scenes.
+    Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
+    Cover the main subjects, actions, setting, and notable progression supported across scenes.
+    Use the storyboard as direct visual evidence and the scene context to preserve progression.
+    Write in present tense. If the transcript provides dialogue or narration, incorporate key points while preserving scene progression.`;
+}
+function createSummarizationBuilder({ titleLength, descriptionLength, tagCount } = {}, { hasSceneContext = false } = {}) {
   const titleLimit = titleLength ?? DEFAULT_TITLE_LENGTH;
   const keywordLimit = tagCount ?? DEFAULT_SUMMARY_KEYWORD_LIMIT;
+  const task = hasSceneContext ? "Analyze the storyboard frames and ordered scene context together, then generate metadata that captures the full progression of the video content." : "Analyze the storyboard frames and generate metadata that captures the essence of the video content.";
+  const qualityGuidelines = hasSceneContext ? dedent6`
+      - Follow scene_index order to understand what begins, develops, and concludes
+      - Use scene narratives and concepts as grounded evidence, preserving consistent terminology across the output
+      - Use the storyboard as direct visual evidence for whole-asset details
+      - Balance brevity with informativeness` : dedent6`
+      - Examine all frames to understand the full context and progression
+      - Be precise: "golden retriever" is better than "dog" when identifiable
+      - Capture the narrative: what begins, develops, and concludes
+      - Balance brevity with informativeness`;
   return createPromptBuilder({
     template: {
       task: {
         tag: "task",
-        content: "Analyze the storyboard frames and generate metadata that captures the essence of the video content."
+        content: task
       },
       title: {
         tag: "title_requirements",
@@ -6797,7 +7187,7 @@ function createSummarizationBuilder({ titleLength, descriptionLength, tagCount }
       },
       description: {
         tag: "description_requirements",
-        content: buildDescriptionGuidance(descriptionLength ?? DEFAULT_DESCRIPTION_LENGTH, "video")
+        content: hasSceneContext ? buildSceneAwareDescriptionGuidance(descriptionLength ?? DEFAULT_DESCRIPTION_LENGTH) : buildDescriptionGuidance(descriptionLength ?? DEFAULT_DESCRIPTION_LENGTH, "video")
       },
       keywords: {
         tag: "keywords_requirements",
@@ -6813,11 +7203,7 @@ function createSummarizationBuilder({ titleLength, descriptionLength, tagCount }
       },
       qualityGuidelines: {
         tag: "quality_guidelines",
-        content: dedent6`
-          - Examine all frames to understand the full context and progression
-          - Be precise: "golden retriever" is better than "dog" when identifiable
-          - Capture the narrative: what begins, develops, and concludes
-          - Balance brevity with informativeness`
+        content: qualityGuidelines
       }
     },
     sectionOrder: ["task", "title", "description", "keywords", "qualityGuidelines"]
@@ -6869,59 +7255,83 @@ function createAudioOnlyBuilder({ titleLength, descriptionLength, tagCount } = {
     sectionOrder: ["task", "title", "description", "keywords", "qualityGuidelines"]
   });
 }
-var SYSTEM_PROMPT5 = promptDedent`
-  <role>
-    You are a video content analyst specializing in storyboard interpretation and multimodal analysis.
-  </role>
-
-  <context>
-    You receive storyboard images containing multiple sequential frames extracted from a video.
-    ${STORYBOARD_FRAME_INSTRUCTIONS}
-  </context>
-
-  <transcript_guidance>
-    When a transcript is provided alongside the storyboard:
-    - Use it to understand spoken content, dialogue, narration, and audio context
-    - Correlate transcript content with visual frames to build a complete picture
-    - Extract key terminology, names, and specific language used by speakers
-    - Let the transcript inform keyword selection, especially for topics not visually obvious
-    - Prioritize visual content for the description, but enrich it with transcript insights
-    - If transcript and visuals conflict, trust the visual evidence
-  </transcript_guidance>
-
-  <capabilities>
-    - Extract meaning from visual sequences
-    - Identify subjects, actions, settings, and narrative arcs
-    - Generate accurate, searchable metadata
-    - Synthesize visual and transcript information when provided
-  </capabilities>
-
-  <security>
-    ${NON_DISCLOSURE_CONSTRAINT}
-
-    ${UNTRUSTED_USER_INPUT_NOTICE}
-
-    ${VISUAL_TEXT_AS_CONTENT}
-
-    ${CANARY_TRIPWIRE}
-  </security>
-
-  <constraints>
-    - Only describe what is clearly observable in the frames or explicitly stated in the transcript
-    - ${NO_FABRICATION_CONSTRAINT}
-    - ${METADATA_BOUNDARY_WARNING}
-    - ${STRUCTURED_DATA_CONSTRAINT}
-    - 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
-  </constraints>
-
-  <tone_guidance>
-    ${TONE_GUIDANCE}
-  </tone_guidance>
-
-  <language_guidelines>
-    ${createLanguageGuidelines("video")}
-  </language_guidelines>`;
+function createVideoSystemPrompt(hasSceneContext) {
+  let sceneContext = "";
+  let sceneGuidance = "";
+  if (hasSceneContext) {
+    sceneContext = promptDedent`
+      Ordered scene context is also provided as structured evidence of the video's progression.
+      Entries use stable, zero-based scene_index values and absolute millisecond timestamps.
+      Read scenes in scene_index order to understand what begins, develops, and concludes.`;
+    sceneGuidance = promptDedent`
+      <scene_guidance>
+        - Use scene titles, narratives, and concepts to understand temporal progression
+        - Use storyboard frames as direct visual evidence for subjects, actions, settings, and details
+        - Preserve consistent terminology from the scene context across the title, description, and keywords
+        - Treat optional scene fields as evidence only when present; do not infer omitted details
+        - Consider all provided evidence together; if derived scene context conflicts with storyboard visuals, trust the visuals
+      </scene_guidance>`;
+  }
+  const transcriptEvidence = hasSceneContext ? "storyboard frames and ordered scenes" : "visual frames";
+  const descriptionPriority = hasSceneContext ? "Use the scene context for temporal structure and the storyboard for direct visual details, enriching both with transcript insights" : "Prioritize visual content for the description, but enrich it with transcript insights";
+  const groundingConstraint = hasSceneContext ? "Use all provided evidence together. Ground each claim in the storyboard, scene context, or transcript" : "Only describe what is clearly observable in the frames or explicitly stated in the transcript";
+  return promptDedent`
+    <role>
+      You are a video content analyst specializing in storyboard interpretation and multimodal analysis.
+    </role>
+
+    <context>
+      You receive storyboard images containing multiple sequential frames extracted from a video.
+      ${STORYBOARD_FRAME_INSTRUCTIONS}
+      ${sceneContext}
+    </context>
+
+    ${sceneGuidance}
+
+    <transcript_guidance>
+      When a transcript is provided alongside the storyboard:
+      - Use it to understand spoken content, dialogue, narration, and audio context
+      - Correlate transcript content with ${transcriptEvidence} to build a complete picture
+      - Extract key terminology, names, and specific language used by speakers
+      - Let the transcript inform keyword selection, especially for topics not visually obvious
+      - ${descriptionPriority}
+      - If transcript and visuals conflict, trust the visual evidence
+    </transcript_guidance>
+
+    <capabilities>
+      - Extract meaning from visual sequences
+      - Identify subjects, actions, settings, and narrative arcs
+      - Generate accurate, searchable metadata
+      - Synthesize visual and transcript information when provided
+    </capabilities>
+
+    <security>
+      ${NON_DISCLOSURE_CONSTRAINT}
+
+      ${UNTRUSTED_USER_INPUT_NOTICE}
+
+      ${VISUAL_TEXT_AS_CONTENT}
+
+      ${CANARY_TRIPWIRE}
+    </security>
+
+    <constraints>
+      - ${groundingConstraint}
+      - ${NO_FABRICATION_CONSTRAINT}
+      - ${METADATA_BOUNDARY_WARNING}
+      - ${STRUCTURED_DATA_CONSTRAINT}
+      - 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
+    </constraints>
+
+    <tone_guidance>
+      ${TONE_GUIDANCE}
+    </tone_guidance>
+
+    <language_guidelines>
+      ${createLanguageGuidelines("video")}
+    </language_guidelines>`;
+}
 var AUDIO_ONLY_SYSTEM_PROMPT3 = promptDedent`
   <role>
     You are an audio content analyst specializing in transcript analysis and metadata generation.
@@ -6972,6 +7382,16 @@ var AUDIO_ONLY_SYSTEM_PROMPT3 = promptDedent`
   <language_guidelines>
     ${createLanguageGuidelines("audio")}
   </language_guidelines>`;
+function createSceneContextSection(sceneContext) {
+  return {
+    tag: "scene_context",
+    content: JSON.stringify(sceneContext),
+    attributes: {
+      format: "json",
+      order: "scene_index_ascending"
+    }
+  };
+}
 function buildUserPrompt5({
   tone,
   transcriptText,
@@ -6981,7 +7401,8 @@ function buildUserPrompt5({
   titleLength,
   descriptionLength,
   tagCount,
-  languageName
+  languageName,
+  sceneContext
 }) {
   const contextSections = [createToneSection(TONE_INSTRUCTIONS[tone])];
   if (languageName) {
@@ -6996,11 +7417,15 @@ function buildUserPrompt5({
     const format = isCleanTranscript ? "plain text" : "WebVTT";
     contextSections.push(createTranscriptSection(transcriptText, format));
   }
+  const hasSceneContext = !isAudioOnly && Boolean(sceneContext?.length);
+  if (hasSceneContext && sceneContext) {
+    contextSections.push(createSceneContextSection(sceneContext));
+  }
   const constraints = { titleLength, descriptionLength, tagCount };
-  const promptBuilder = isAudioOnly ? createAudioOnlyBuilder(constraints) : createSummarizationBuilder(constraints);
+  const promptBuilder = isAudioOnly ? createAudioOnlyBuilder(constraints) : createSummarizationBuilder(constraints, { hasSceneContext });
   return promptBuilder.buildWithContext(promptOverrides, contextSections);
 }
-async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, systemPrompt, descriptionLength, credentials) {
+async function analyzeVideo(imageDataUrl, provider, modelId, userPrompt, systemPrompt, descriptionLength, credentials) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const schema = buildSummarySchema(descriptionLength);
@@ -7016,10 +7441,10 @@ async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, s
     messages: [
       {
         role: "user",
-        content: [
+        content: imageDataUrl ? [
           { type: "text", text: userPrompt },
           { type: "image", image: imageDataUrl }
-        ]
+        ] : userPrompt
       }
     ]
   }));
@@ -7129,6 +7554,7 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     cleanTranscript = true,
     imageSubmissionMode = "url",
     imageDownloadOptions,
+    sceneContext,
     promptOverrides,
     credentials,
     titleLength,
@@ -7152,6 +7578,7 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, workflowCredentials, options?.assetSnapshot);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
   const isAudioOnly = isAudioOnlyAsset(assetData);
+  const hasSceneContext = !isAudioOnly && Boolean(sceneContext?.length);
   const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
   const storyboardScope = isAudioOnly ? void 0 : resolveRenderableVideoScope(
     effectiveScope,
@@ -7168,7 +7595,8 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     );
   }
   const signingContext = await resolveMuxSigningContext(workflowCredentials);
-  if (policy === "signed" && !signingContext) {
+  const requiresSignedPlaybackAccess = includeTranscript || !isAudioOnly;
+  if (policy === "signed" && requiresSignedPlaybackAccess && !signingContext) {
     throw new MuxAiError(
       "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
       { type: "validation_error" }
@@ -7194,11 +7622,15 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     titleLength,
     descriptionLength,
     tagCount,
-    languageName
+    languageName,
+    sceneContext: hasSceneContext ? sceneContext : void 0
   });
   let analysisResponse;
   let imageUrl;
-  const systemPrompt = isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT3 : SYSTEM_PROMPT5;
+  let systemPrompt = AUDIO_ONLY_SYSTEM_PROMPT3;
+  if (!isAudioOnly) {
+    systemPrompt = createVideoSystemPrompt(hasSceneContext);
+  }
   const effectiveDescriptionLength = descriptionLength ?? DEFAULT_DESCRIPTION_LENGTH;
   try {
     if (isAudioOnly) {
@@ -7221,7 +7653,7 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
       imageUrl = storyboardUrl;
       if (imageSubmissionMode === "base64") {
         const downloadResult = await downloadImageAsBase64(storyboardUrl, imageDownloadOptions);
-        analysisResponse = await analyzeStoryboard2(
+        analysisResponse = await analyzeVideo(
           downloadResult.base64Data,
           modelConfig.provider,
           modelConfig.modelId,
@@ -7231,7 +7663,7 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
           workflowCredentials
         );
       } else {
-        analysisResponse = await analyzeStoryboard2(
+        analysisResponse = await analyzeVideo(
           storyboardUrl,
           modelConfig.provider,
           modelConfig.modelId,
@@ -7550,23 +7982,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 +7994,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 +8021,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 +8045,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   let dubbingId;
   let presignedUrl;
   let uploadedTrackId;
+  let replacedTracks;
   let captionsPresignedUrl;
   let captionsTrackId;
   try {
@@ -7703,18 +8136,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 +8176,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 +8221,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     dubbingId,
     uploadedTrackId,
     presignedUrl,
+    replacedTracks,
     captionsTrackId,
     captionsPresignedUrl,
     createdStaticRenditionId,
@@ -7797,7 +8248,7 @@ import { z as z9 } from "zod";
 var translationSchema = z9.object({
   translation: z9.string()
 });
-var SYSTEM_PROMPT6 = promptDedent`
+var SYSTEM_PROMPT5 = promptDedent`
   You are a subtitle translation expert. Translate VTT subtitle files to the target language specified by the user.
   You may receive either a full VTT file or a chunk from a larger VTT.
   Preserve all timestamps, cue ordering, and VTT formatting exactly as they appear.
@@ -8122,7 +8573,7 @@ async function translateVttWithAI({
     model,
     maxRetries: 0,
     output: Output7.object({ schema: translationSchema }),
-    system: SYSTEM_PROMPT6,
+    system: SYSTEM_PROMPT5,
     messages: [
       {
         role: "user",
@@ -8440,11 +8891,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 +8940,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 +9017,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 +9035,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 +9069,7 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
     originalVtt: vttContent,
     translatedVtt,
     uploadedTrackId,
+    replacedTracks,
     presignedUrl,
     usage: usageWithMetadata,
     safety,
@@ -8601,20 +9077,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