@mux/ai 0.46.0 → 0.48.0

package/README.md

@@ -10,6 +10,11 @@ Easy to use, purpose-driven, cost effective, configurable **_workflow functions_
 
 Turn your Mux video and audio assets into structured, actionable data — summaries, chapters, moderation scores, translations, embeddings, and more — with a single function call. `@mux/ai` handles fetching media data from Mux, formatting it for AI providers, and returning typed results so you can focus on building your product instead of wrangling prompts and media pipelines.
 
+> [!TIP]
+> **🤖 Beep boop! And now a word from our sponsors:** [Mux Robots](https://www.mux.com/robots) gives you hosted versions of these workflows behind a single API request, with no pipeline to build or run and no need to BYO LLM. It also goes further than this SDK, with premium caption generation, key moment detection, thumbnail ranking, scene segmentation and more. The first 100,000 units each month are free.
+>
+> `@mux/ai` is the open-source part. We develop and maintain it in public, and it's the right choice when you want full control over prompts, providers and models, or need to build your own workflows from the primitives.
+
 ## Quick Start
 
 ### Install

package/dist/{index-CIcGZD3x.d.ts → index-DxAt9Jq8.d.ts}

@@ -180,6 +180,15 @@ declare function getLanguageName(code: string): string | undefined;
  *   Audio tracks are never Mux-generated, so for audio this behaves like `fail`.
  */
 type ReplaceExistingTracksPolicy = "fail" | "replace_all" | "replace_generated";
+/**
+ * How a workflow that edits an existing track treats that source track.
+ *
+ * - `replace`: delete the source and create the new track in its place. No other track is deleted.
+ * - `fail`: delete nothing; the new track is added alongside the source and must have a different name.
+ *
+ * Only name collisions count: the new track is always in the source's language.
+ */
+type SourceTrackReplacementPolicy = "replace" | "fail";
 /** Mux track types that share a name-uniqueness group among themselves. */
 type ReplaceableTrackType = "text" | "audio";
 /** The `(type, language_code, name)` a workflow is about to write to Mux. `type` defaults to `text`. */
@@ -255,34 +264,35 @@ declare function findNameCollisionTextTracks(asset: MuxAsset, target: TextTrackT
  * Decides which existing tracks stand in the way of `target` and what `policy`
  * says to do about them. Pure: pass the freshest asset you have.
  *
- * `keepTrackIds` marks tracks that are allowed to coexist with the new one and
- * are never treated as conflicts. edit-captions uses it under `fail` to keep
- * the source track it is editing.
- *
  * A conflicting primary audio track always blocks: Mux refuses to delete it and
  * it is the customer's original audio.
  */
-declare function planTextTrackReplacement(asset: MuxAsset, target: TextTrackTarget, policy: ReplaceExistingTracksPolicy, options?: {
-    keepTrackIds?: string[];
-}): TextTrackReplacementPlan;
+declare function planTextTrackReplacement(asset: MuxAsset, target: TextTrackTarget, policy: ReplaceExistingTracksPolicy): TextTrackReplacementPlan;
+/** Plans an edit of `sourceTrackId` into `target`: deletes at most the source, and blocks if any other track has the target's name. */
+declare function planSourceTrackReplacement(asset: MuxAsset, sourceTrackId: string, target: TextTrackTarget, policy: SourceTrackReplacementPolicy): TextTrackReplacementPlan;
 /** True for Mux's `400 invalid_parameters` "Track name 'X' is not unique" rejection. */
 declare function isDuplicateTrackNameError(error: unknown): boolean;
 /** Default audit tag written to `passthrough` on tracks created by `@mux/ai`. */
 declare function buildMuxAiTrackPassthrough(workflow: string): string;
 declare function validateTrackPassthrough(passthrough: string | undefined): string | undefined;
-interface ReplaceAndCreateTextTrackInput {
+interface CreateTrackWriteInput {
     assetId: string;
     target: TextTrackTarget;
-    policy: ReplaceExistingTracksPolicy;
     presignedUrl: string;
     /** Text tracks only. */
     closedCaptions?: boolean;
     passthrough?: string;
-    /** Tracks that may coexist with the new one; see `planTextTrackReplacement`. */
-    keepTrackIds?: string[];
     credentials?: WorkflowCredentialsInput;
 }
+interface ReplaceAndCreateTextTrackInput extends CreateTrackWriteInput {
+    policy: ReplaceExistingTracksPolicy;
+}
 type ReplaceAndCreateTrackInput = ReplaceAndCreateTextTrackInput;
+interface ReplaceSourceTrackInput extends CreateTrackWriteInput {
+    /** The track being edited; see `planSourceTrackReplacement`. */
+    sourceTrackId: string;
+    policy: SourceTrackReplacementPolicy;
+}
 /**
  * Fetches the asset fresh, deletes whatever `policy` allows, then creates the
  * new track of `target.type` (default `text`). Known outcomes come back as
@@ -299,6 +309,12 @@ type ReplaceAndCreateTrackInput = ReplaceAndCreateTextTrackInput;
  * the create.
  */
 declare function replaceAndCreateTrack(input: ReplaceAndCreateTextTrackInput): Promise<ReplaceAndCreateTextTrackResult>;
+/**
+ * `replaceAndCreateTrack` for a workflow that edits an existing text track: plans
+ * with `planSourceTrackReplacement`, so at most the source itself is deleted.
+ * Same outcomes and retry behaviour.
+ */
+declare function replaceSourceTrack(input: ReplaceSourceTrackInput): Promise<ReplaceAndCreateTextTrackResult>;
 /** `replaceAndCreateTrack` pinned to text tracks. */
 declare function replaceAndCreateTextTrack(input: ReplaceAndCreateTextTrackInput): Promise<ReplaceAndCreateTextTrackResult>;
 
@@ -838,12 +854,12 @@ interface EditCaptionsOptions<P extends SupportedProvider = SupportedProvider> e
     /** Replacements applied only to bracketed speaker labels at the start of cues. */
     speakerReplacements?: SpeakerReplacement[];
     /**
-     * What to do with the source track and any other text track in the same
-     * language or with the same name as the edited track. Defaults to
-     * `"replace_all"`: the edited track takes the source track's place.
-     * `"fail"` keeps the source and requires `trackName`.
+     * What to do with the source track. Defaults to `"replace"`: the source is
+     * deleted and the edited track takes its place; no other track is touched.
+     * `"fail"` deletes nothing and adds the edited track alongside the source,
+     * so it requires a `trackName` different from the source's.
      */
-    replaceExistingTracks?: ReplaceExistingTracksPolicy;
+    replaceExistingTracks?: SourceTrackReplacementPolicy;
     /** Name for the edited Mux text track. Defaults to the source track's name. */
     trackName?: string;
     /**
@@ -903,7 +919,7 @@ interface EditCaptionsResult {
         replacements: ReplacementRecord[];
     };
     uploadedTrackId?: string;
-    /** Existing text tracks deleted before the edited track was created. Includes the source track when it was replaced. */
+    /** Tracks deleted before the edited track was created: the source track, when it was replaced. */
     replacedTracks?: TextTrackSummary[];
     presignedUrl?: string;
     usage?: TokenUsage;
@@ -1962,4 +1978,4 @@ declare namespace index {
   export { index_ASK_QUESTIONS_DEFAULT_MAX_ANSWER_OPTION_LENGTH as ASK_QUESTIONS_DEFAULT_MAX_ANSWER_OPTION_LENGTH, index_ASK_QUESTIONS_DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH as ASK_QUESTIONS_DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH, index_ASK_QUESTIONS_MAX_QUESTIONS_PER_CALL as ASK_QUESTIONS_MAX_QUESTIONS_PER_CALL, index_ASK_QUESTIONS_MAX_QUESTION_LENGTH as ASK_QUESTIONS_MAX_QUESTION_LENGTH, type index_AskQuestionsOptions as AskQuestionsOptions, type index_AskQuestionsResult as AskQuestionsResult, type index_AskQuestionsType as AskQuestionsType, type index_AudioTranslationOptions as AudioTranslationOptions, type index_AudioTranslationResult as AudioTranslationResult, type index_AutoCensorProfanityOptions as AutoCensorProfanityOptions, type index_BurnedInCaptionsAnalysis as BurnedInCaptionsAnalysis, type index_BurnedInCaptionsOptions as BurnedInCaptionsOptions, type index_BurnedInCaptionsPromptOverrides as BurnedInCaptionsPromptOverrides, type index_BurnedInCaptionsPromptSections as BurnedInCaptionsPromptSections, type index_BurnedInCaptionsResult as BurnedInCaptionsResult, type index_CaptionReplacement as CaptionReplacement, type index_CensorMode as CensorMode, type index_Chapter as Chapter, type index_ChapterSystemPromptSections as ChapterSystemPromptSections, type index_ChaptersOptions as ChaptersOptions, type index_ChaptersPromptOverrides as ChaptersPromptOverrides, type index_ChaptersPromptSections as ChaptersPromptSections, type index_ChaptersResult as ChaptersResult, type index_ChaptersType as ChaptersType, index_DEFAULT_DESCRIPTION_LENGTH as DEFAULT_DESCRIPTION_LENGTH, index_DEFAULT_SUMMARY_KEYWORD_LIMIT as DEFAULT_SUMMARY_KEYWORD_LIMIT, index_DEFAULT_TITLE_LENGTH as DEFAULT_TITLE_LENGTH, type index_EditCaptionsOptions as EditCaptionsOptions, type index_EditCaptionsResult as EditCaptionsResult, type index_EmbeddingsOptions as EmbeddingsOptions, type index_EmbeddingsResult as EmbeddingsResult, type index_EngagementInsightsOptions as EngagementInsightsOptions, type index_EngagementInsightsResult as EngagementInsightsResult, index_GENERATE_TEXT_CALLS_TO_ACTION as GENERATE_TEXT_CALLS_TO_ACTION, index_GENERATE_TEXT_CHANNELS as GENERATE_TEXT_CHANNELS, index_GENERATE_TEXT_CHANNEL_CEILINGS as GENERATE_TEXT_CHANNEL_CEILINGS, index_GENERATE_TEXT_FORMATS as GENERATE_TEXT_FORMATS, index_GENERATE_TEXT_LENGTH_BOUNDS as GENERATE_TEXT_LENGTH_BOUNDS, index_GENERATE_TEXT_MAX_ARTIFACTS as GENERATE_TEXT_MAX_ARTIFACTS, index_GENERATE_TEXT_MAX_AUDIENCE_CHARS as GENERATE_TEXT_MAX_AUDIENCE_CHARS, index_GENERATE_TEXT_MAX_BRAND_TERMS as GENERATE_TEXT_MAX_BRAND_TERMS, index_GENERATE_TEXT_MAX_BRAND_TERMS_TOTAL_CHARS as GENERATE_TEXT_MAX_BRAND_TERMS_TOTAL_CHARS, index_GENERATE_TEXT_MAX_BRAND_TERM_CHARS as GENERATE_TEXT_MAX_BRAND_TERM_CHARS, index_GENERATE_TEXT_MAX_CONCURRENT_GENERATIONS as GENERATE_TEXT_MAX_CONCURRENT_GENERATIONS, index_GENERATE_TEXT_MAX_INSTRUCTIONS_CHARS as GENERATE_TEXT_MAX_INSTRUCTIONS_CHARS, index_GENERATE_TEXT_MAX_SHOT_FRAMES as GENERATE_TEXT_MAX_SHOT_FRAMES, index_GENERATE_TEXT_MAX_VARIANTS as GENERATE_TEXT_MAX_VARIANTS, index_GENERATE_TEXT_VOICES as GENERATE_TEXT_VOICES, index_GOOGLE_VISION_LIKELIHOOD_TO_SCORE as GOOGLE_VISION_LIKELIHOOD_TO_SCORE, type index_GenerateTextArtifact as GenerateTextArtifact, type index_GenerateTextCallToAction as GenerateTextCallToAction, type index_GenerateTextChannel as GenerateTextChannel, type index_GenerateTextFormat as GenerateTextFormat, type index_GenerateTextKeyedItem as GenerateTextKeyedItem, type index_GenerateTextLengthLimit as GenerateTextLengthLimit, type index_GenerateTextOptions as GenerateTextOptions, type index_GenerateTextResult as GenerateTextResult, type index_GenerateTextVariant as GenerateTextVariant, type index_GenerateTextVoice as GenerateTextVoice, type index_GeneratedTextArtifact as GeneratedTextArtifact, type index_GeneratedTextVariant as GeneratedTextVariant, index_HIVE_SEXUAL_CATEGORIES as HIVE_SEXUAL_CATEGORIES, index_HIVE_VIOLENCE_CATEGORIES as HIVE_VIOLENCE_CATEGORIES, type index_HiveModerationOutput as HiveModerationOutput, type index_HiveModerationSource as HiveModerationSource, type index_ModerationOptions as ModerationOptions, type index_ModerationProvider as ModerationProvider, type index_ModerationResult as ModerationResult, type index_MomentInsight as MomentInsight, type index_OverallInsight as OverallInsight, type index_ProfanityDetectionPayload as ProfanityDetectionPayload, type index_Question as Question, type index_QuestionAnswer as QuestionAnswer, type index_QuestionAnswerType as QuestionAnswerType, type index_ReplacementRecord as ReplacementRecord, type index_SpeakerReplacement as SpeakerReplacement, type index_StaticRenditionCleanupOutcome as StaticRenditionCleanupOutcome, type index_SummarizationOptions as SummarizationOptions, type index_SummarizationPromptOverrides as SummarizationPromptOverrides, type index_SummarizationPromptSections as SummarizationPromptSections, type index_SummaryAndTagsResult as SummaryAndTagsResult, type index_SummaryType as SummaryType, type index_ThumbnailModerationScore as ThumbnailModerationScore, type index_TranslationChunkingOptions as TranslationChunkingOptions, type index_TranslationOptions as TranslationOptions, type index_TranslationPayload as TranslationPayload, type index_TranslationResult as TranslationResult, index_aggregateTokenUsage as aggregateTokenUsage, index_applyOverrideLists as applyOverrideLists, index_applyReplacements as applyReplacements, index_applySpeakerReplacements as applySpeakerReplacements, index_askQuestions as askQuestions, index_buildReplacementRegex as buildReplacementRegex, index_burnedInCaptionsSchema as burnedInCaptionsSchema, index_censorVttContent as censorVttContent, index_chapterSchema as chapterSchema, index_chaptersSchema as chaptersSchema, index_createReplacer as createReplacer, index_editCaptions as editCaptions, index_extractTranscriptSegmentsForHotspots as extractTranscriptSegmentsForHotspots, index_findGenerateTextLengthViolation as findGenerateTextLengthViolation, index_generateChapters as generateChapters, index_generateEmbeddings as generateEmbeddings, index_generateEngagementInsights as generateEngagementInsights, index_generateText as generateText, index_generateVideoEmbeddings as generateVideoEmbeddings, index_getModerationScores as getModerationScores, index_getSummaryAndTags as getSummaryAndTags, index_hasBurnedInCaptions as hasBurnedInCaptions, index_mapShotsToHotspots as mapShotsToHotspots, index_measureGenerateTextLength as measureGenerateTextLength, index_normalizeTranslatedVtt as normalizeTranslatedVtt, index_profanityDetectionSchema as profanityDetectionSchema, index_questionAnswerSchema as questionAnswerSchema, index_resolveGenerateTextLengthLimit as resolveGenerateTextLengthLimit, index_resolveGenerateTextLengthLimits as resolveGenerateTextLengthLimits, index_resolveGenerateTextOptions as resolveGenerateTextOptions, index_selectGenerateTextShotFrames as selectGenerateTextShotFrames, index_shouldSplitChunkTranslationError as shouldSplitChunkTranslationError, index_summarySchema as summarySchema, index_transformCueText as transformCueText, index_translateAudio as translateAudio, index_translateCaptions as translateCaptions, index_translationSchema as translationSchema, index_validateNeverTranslateTerms as validateNeverTranslateTerms, index_verifyNeverTranslateTerms as verifyNeverTranslateTerms };
 }
 
-export { type Chapter as $, toISO639_1 as A, toISO639_3 as B, validateTrackPassthrough as C, index as D, ASK_QUESTIONS_DEFAULT_MAX_ANSWER_OPTION_LENGTH as E, ASK_QUESTIONS_DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH as F, ASK_QUESTIONS_MAX_QUESTIONS_PER_CALL as G, ASK_QUESTIONS_MAX_QUESTION_LENGTH as H, type ISO639_1 as I, type AskQuestionsOptions as J, type AskQuestionsResult as K, type LanguageCodePair as L, MUX_TRACK_PASSTHROUGH_MAX_CHARS as M, type AskQuestionsType as N, type AudioTranslationOptions as O, type AudioTranslationResult as P, type AutoCensorProfanityOptions as Q, type ReplaceAndCreateTextTrackInput as R, type SupportedISO639_1 as S, type TextTrackReplacementPlan as T, type BurnedInCaptionsAnalysis as U, type BurnedInCaptionsOptions as V, type BurnedInCaptionsPromptOverrides as W, type BurnedInCaptionsPromptSections as X, type BurnedInCaptionsResult as Y, type CaptionReplacement as Z, type CensorMode as _, type ISO639_3 as a, type TranslationOptions as a$, type ChapterSystemPromptSections as a0, type ChaptersOptions as a1, type ChaptersPromptOverrides as a2, type ChaptersPromptSections as a3, type ChaptersResult as a4, type ChaptersType as a5, type EditCaptionsOptions as a6, type EditCaptionsResult as a7, type EmbeddingsOptions as a8, type EmbeddingsResult as a9, type GenerateTextVariant as aA, type GenerateTextVoice as aB, type GeneratedTextArtifact as aC, type GeneratedTextVariant as aD, HIVE_SEXUAL_CATEGORIES as aE, HIVE_VIOLENCE_CATEGORIES as aF, type HiveModerationOutput as aG, type HiveModerationSource as aH, type ModerationOptions as aI, type ModerationProvider as aJ, type ModerationResult as aK, type MomentInsight as aL, type OverallInsight as aM, type ProfanityDetectionPayload as aN, type Question as aO, type QuestionAnswer as aP, type QuestionAnswerType as aQ, type ReplacementRecord as aR, type SpeakerReplacement as aS, type StaticRenditionCleanupOutcome as aT, type SummarizationOptions as aU, type SummarizationPromptOverrides as aV, type SummarizationPromptSections as aW, type SummaryAndTagsResult as aX, type SummaryType as aY, type ThumbnailModerationScore as aZ, type TranslationChunkingOptions as a_, type EngagementInsightsOptions as aa, type EngagementInsightsResult as ab, GENERATE_TEXT_CALLS_TO_ACTION as ac, GENERATE_TEXT_CHANNELS as ad, GENERATE_TEXT_CHANNEL_CEILINGS as ae, GENERATE_TEXT_FORMATS as af, GENERATE_TEXT_LENGTH_BOUNDS as ag, GENERATE_TEXT_MAX_ARTIFACTS as ah, GENERATE_TEXT_MAX_AUDIENCE_CHARS as ai, GENERATE_TEXT_MAX_BRAND_TERMS as aj, GENERATE_TEXT_MAX_BRAND_TERMS_TOTAL_CHARS as ak, GENERATE_TEXT_MAX_BRAND_TERM_CHARS as al, GENERATE_TEXT_MAX_CONCURRENT_GENERATIONS as am, GENERATE_TEXT_MAX_INSTRUCTIONS_CHARS as an, GENERATE_TEXT_MAX_SHOT_FRAMES as ao, GENERATE_TEXT_MAX_VARIANTS as ap, GENERATE_TEXT_VOICES as aq, GOOGLE_VISION_LIKELIHOOD_TO_SCORE as ar, type GenerateTextArtifact as as, type GenerateTextCallToAction as at, type GenerateTextChannel as au, type GenerateTextFormat as av, type GenerateTextKeyedItem as aw, type GenerateTextLengthLimit as ax, type GenerateTextOptions as ay, type GenerateTextResult as az, type ReplaceAndCreateTextTrackResult as b, type TranslationPayload as b0, type TranslationResult as b1, aggregateTokenUsage as b2, applyOverrideLists as b3, applyReplacements as b4, applySpeakerReplacements as b5, askQuestions as b6, buildReplacementRegex as b7, burnedInCaptionsSchema as b8, censorVttContent as b9, translateAudio as bA, translateCaptions as bB, translationSchema as bC, validateNeverTranslateTerms as bD, verifyNeverTranslateTerms as bE, chapterSchema as ba, chaptersSchema as bb, createReplacer as bc, editCaptions as bd, extractTranscriptSegmentsForHotspots as be, findGenerateTextLengthViolation as bf, generateChapters as bg, generateEmbeddings as bh, generateEngagementInsights as bi, generateText as bj, generateVideoEmbeddings as bk, getModerationScores as bl, getSummaryAndTags as bm, hasBurnedInCaptions as bn, mapShotsToHotspots as bo, measureGenerateTextLength as bp, normalizeTranslatedVtt as bq, profanityDetectionSchema as br, questionAnswerSchema as bs, resolveGenerateTextLengthLimit as bt, resolveGenerateTextLengthLimits as bu, resolveGenerateTextOptions as bv, selectGenerateTextShotFrames as bw, shouldSplitChunkTranslationError as bx, summarySchema as by, transformCueText as bz, type ReplaceAndCreateTrackInput as c, type ReplaceExistingTracksPolicy as d, type ReplaceableTrackType as e, type SupportedISO639_3 as f, type TextTrackSummary as g, type TextTrackTarget as h, type TrackSummary as i, type TrackTarget as j, buildMuxAiTrackPassthrough as k, findNameCollisionTextTracks as l, findSameLanguageTextTracks as m, getLanguageCodePair as n, getLanguageName as o, isDuplicateTrackNameError as p, isMuxGeneratedTextTrack as q, isUndeterminedLanguageCode as r, isValidISO639_1 as s, isValidISO639_3 as t, normalizeTrackLanguageCode as u, normalizeTrackName as v, planTextTrackReplacement as w, replaceAndCreateTextTrack as x, replaceAndCreateTrack as y, summarizeTextTrack as z };
+export { type BurnedInCaptionsPromptSections as $, replaceAndCreateTextTrack as A, replaceAndCreateTrack as B, replaceSourceTrack as C, summarizeTextTrack as D, toISO639_1 as E, toISO639_3 as F, validateTrackPassthrough as G, index as H, type ISO639_1 as I, ASK_QUESTIONS_DEFAULT_MAX_ANSWER_OPTION_LENGTH as J, ASK_QUESTIONS_DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH as K, type LanguageCodePair as L, MUX_TRACK_PASSTHROUGH_MAX_CHARS as M, ASK_QUESTIONS_MAX_QUESTIONS_PER_CALL as N, ASK_QUESTIONS_MAX_QUESTION_LENGTH as O, type AskQuestionsOptions as P, type AskQuestionsResult as Q, type ReplaceAndCreateTextTrackInput as R, type SourceTrackReplacementPolicy as S, type TextTrackReplacementPlan as T, type AskQuestionsType as U, type AudioTranslationOptions as V, type AudioTranslationResult as W, type AutoCensorProfanityOptions as X, type BurnedInCaptionsAnalysis as Y, type BurnedInCaptionsOptions as Z, type BurnedInCaptionsPromptOverrides as _, type ISO639_3 as a, type SummaryAndTagsResult as a$, type BurnedInCaptionsResult as a0, type CaptionReplacement as a1, type CensorMode as a2, type Chapter as a3, type ChapterSystemPromptSections as a4, type ChaptersOptions as a5, type ChaptersPromptOverrides as a6, type ChaptersPromptSections as a7, type ChaptersResult as a8, type ChaptersType as a9, type GenerateTextKeyedItem as aA, type GenerateTextLengthLimit as aB, type GenerateTextOptions as aC, type GenerateTextResult as aD, type GenerateTextVariant as aE, type GenerateTextVoice as aF, type GeneratedTextArtifact as aG, type GeneratedTextVariant as aH, HIVE_SEXUAL_CATEGORIES as aI, HIVE_VIOLENCE_CATEGORIES as aJ, type HiveModerationOutput as aK, type HiveModerationSource as aL, type ModerationOptions as aM, type ModerationProvider as aN, type ModerationResult as aO, type MomentInsight as aP, type OverallInsight as aQ, type ProfanityDetectionPayload as aR, type Question as aS, type QuestionAnswer as aT, type QuestionAnswerType as aU, type ReplacementRecord as aV, type SpeakerReplacement as aW, type StaticRenditionCleanupOutcome as aX, type SummarizationOptions as aY, type SummarizationPromptOverrides as aZ, type SummarizationPromptSections as a_, type EditCaptionsOptions as aa, type EditCaptionsResult as ab, type EmbeddingsOptions as ac, type EmbeddingsResult as ad, type EngagementInsightsOptions as ae, type EngagementInsightsResult as af, GENERATE_TEXT_CALLS_TO_ACTION as ag, GENERATE_TEXT_CHANNELS as ah, GENERATE_TEXT_CHANNEL_CEILINGS as ai, GENERATE_TEXT_FORMATS as aj, GENERATE_TEXT_LENGTH_BOUNDS as ak, GENERATE_TEXT_MAX_ARTIFACTS as al, GENERATE_TEXT_MAX_AUDIENCE_CHARS as am, GENERATE_TEXT_MAX_BRAND_TERMS as an, GENERATE_TEXT_MAX_BRAND_TERMS_TOTAL_CHARS as ao, GENERATE_TEXT_MAX_BRAND_TERM_CHARS as ap, GENERATE_TEXT_MAX_CONCURRENT_GENERATIONS as aq, GENERATE_TEXT_MAX_INSTRUCTIONS_CHARS as ar, GENERATE_TEXT_MAX_SHOT_FRAMES as as, GENERATE_TEXT_MAX_VARIANTS as at, GENERATE_TEXT_VOICES as au, GOOGLE_VISION_LIKELIHOOD_TO_SCORE as av, type GenerateTextArtifact as aw, type GenerateTextCallToAction as ax, type GenerateTextChannel as ay, type GenerateTextFormat as az, type ReplaceAndCreateTextTrackResult as b, type SummaryType as b0, type ThumbnailModerationScore as b1, type TranslationChunkingOptions as b2, type TranslationOptions as b3, type TranslationPayload as b4, type TranslationResult as b5, aggregateTokenUsage as b6, applyOverrideLists as b7, applyReplacements as b8, applySpeakerReplacements as b9, selectGenerateTextShotFrames as bA, shouldSplitChunkTranslationError as bB, summarySchema as bC, transformCueText as bD, translateAudio as bE, translateCaptions as bF, translationSchema as bG, validateNeverTranslateTerms as bH, verifyNeverTranslateTerms as bI, askQuestions as ba, buildReplacementRegex as bb, burnedInCaptionsSchema as bc, censorVttContent as bd, chapterSchema as be, chaptersSchema as bf, createReplacer as bg, editCaptions as bh, extractTranscriptSegmentsForHotspots as bi, findGenerateTextLengthViolation as bj, generateChapters as bk, generateEmbeddings as bl, generateEngagementInsights as bm, generateText as bn, generateVideoEmbeddings as bo, getModerationScores as bp, getSummaryAndTags as bq, hasBurnedInCaptions as br, mapShotsToHotspots as bs, measureGenerateTextLength as bt, normalizeTranslatedVtt as bu, profanityDetectionSchema as bv, questionAnswerSchema as bw, resolveGenerateTextLengthLimit as bx, resolveGenerateTextLengthLimits as by, resolveGenerateTextOptions as bz, type ReplaceAndCreateTrackInput as c, type ReplaceExistingTracksPolicy as d, type ReplaceSourceTrackInput as e, type ReplaceableTrackType as f, type SupportedISO639_1 as g, type SupportedISO639_3 as h, type TextTrackSummary as i, type TextTrackTarget as j, type TrackSummary as k, type TrackTarget as l, buildMuxAiTrackPassthrough as m, findNameCollisionTextTracks as n, findSameLanguageTextTracks as o, getLanguageCodePair as p, getLanguageName as q, isDuplicateTrackNameError as r, isMuxGeneratedTextTrack as s, isUndeterminedLanguageCode as t, isValidISO639_1 as u, isValidISO639_3 as v, normalizeTrackLanguageCode as w, normalizeTrackName as x, planSourceTrackReplacement as y, planTextTrackReplacement as z };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { I as ISO639_1, a as ISO639_3, L as LanguageCodePair, M as MUX_TRACK_PASSTHROUGH_MAX_CHARS, R as ReplaceAndCreateTextTrackInput, b as ReplaceAndCreateTextTrackResult, c as ReplaceAndCreateTrackInput, d as ReplaceExistingTracksPolicy, e as ReplaceableTrackType, S as SupportedISO639_1, f as SupportedISO639_3, T as TextTrackReplacementPlan, g as TextTrackSummary, h as TextTrackTarget, i as TrackSummary, j as TrackTarget, k as buildMuxAiTrackPassthrough, l as findNameCollisionTextTracks, m as findSameLanguageTextTracks, n as getLanguageCodePair, o as getLanguageName, p as isDuplicateTrackNameError, q as isMuxGeneratedTextTrack, r as isUndeterminedLanguageCode, s as isValidISO639_1, t as isValidISO639_3, u as normalizeTrackLanguageCode, v as normalizeTrackName, w as planTextTrackReplacement, x as replaceAndCreateTextTrack, y as replaceAndCreateTrack, z as summarizeTextTrack, A as toISO639_1, B as toISO639_3, C as validateTrackPassthrough, D as workflows } from './index-CIcGZD3x.js';
+export { I as ISO639_1, a as ISO639_3, L as LanguageCodePair, M as MUX_TRACK_PASSTHROUGH_MAX_CHARS, R as ReplaceAndCreateTextTrackInput, b as ReplaceAndCreateTextTrackResult, c as ReplaceAndCreateTrackInput, d as ReplaceExistingTracksPolicy, e as ReplaceSourceTrackInput, f as ReplaceableTrackType, S as SourceTrackReplacementPolicy, g as SupportedISO639_1, h as SupportedISO639_3, T as TextTrackReplacementPlan, i as TextTrackSummary, j as TextTrackTarget, k as TrackSummary, l as TrackTarget, m as buildMuxAiTrackPassthrough, n as findNameCollisionTextTracks, o as findSameLanguageTextTracks, p as getLanguageCodePair, q as getLanguageName, r as isDuplicateTrackNameError, s as isMuxGeneratedTextTrack, t as isUndeterminedLanguageCode, u as isValidISO639_1, v as isValidISO639_3, w as normalizeTrackLanguageCode, x as normalizeTrackName, y as planSourceTrackReplacement, z as planTextTrackReplacement, A as replaceAndCreateTextTrack, B as replaceAndCreateTrack, C as replaceSourceTrack, D as summarizeTextTrack, E as toISO639_1, F as toISO639_3, G as validateTrackPassthrough, H as workflows } from './index-DxAt9Jq8.js';
 import { W as WorkflowCredentials, S as StoragePutObjectInput, a as StoragePresignGetObjectInput } from './shots-BwpjZDpr.js';
 export { A as AssetTextTrack, C as ChunkEmbedding, b as ChunkingStrategy, E as Encrypted, c as EncryptedPayload, I as ImageSubmissionMode, M as MuxAIOptions, d as MuxAsset, P as PlaybackAsset, e as PlaybackPolicy, f as ScopedMuxAIOptions, g as StorageAdapter, T as TextChunk, h as TokenChunkingConfig, i as TokenUsage, j as ToneType, U as UsageMetadata, V as VTTChunkingConfig, k as VideoEmbeddingsResult, l as WorkflowCredentialsInput, m as WorkflowMuxClient, n as WorkflowScope, o as decryptFromWorkflow, p as encryptForWorkflow } from './shots-BwpjZDpr.js';
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
@@ -10,7 +10,7 @@ import '@ai-sdk/google';
 import '@ai-sdk/openai';
 import '@mux/ts';
 
-var version = "0.46.0";
+var version = "0.48.0";
 
 type MuxAiErrorType = "validation_error" | "processing_error" | "timeout_error" | "content_policy_error";
 /**

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.46.0";
+var version = "0.48.0";
 
 // src/lib/language-codes.ts
 var ISO639_1_TO_3 = {
@@ -1195,17 +1195,24 @@ function findNameCollisionTextTracks(asset, target) {
   }
   return listTracks(asset, targetType(target)).filter((track) => normalizeTrackName(track.name) === targetName);
 }
+function countTracks(tracks, label, singularVerb, pluralVerb) {
+  const kind = label.toLowerCase();
+  if (tracks.length === 1) {
+    return `${kind === "audio" ? "An" : "A"} ${kind} track ${singularVerb}`;
+  }
+  return `${tracks.length} ${kind} tracks ${pluralVerb}`;
+}
+function itOrThem(tracks) {
+  return tracks.length === 1 ? "it" : "them";
+}
 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 = {}) {
+function planTextTrackReplacement(asset, target, policy) {
   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);
-    }
+    conflicts.set(track.id, track);
   }
   const conflicting = [...conflicts.values()];
   if (conflicting.length === 0) {
@@ -1214,7 +1221,7 @@ function planTextTrackReplacement(asset, target, policy, options = {}) {
   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.`,
+      reason: `${countTracks(conflicting, label, "already exists", "already exist")} for language '${target.languageCode}' or name '${target.name}': ${describeTracks(conflicting)}. Set replaceExistingTracks to replace ${itOrThem(conflicting)}.`,
       tracks: conflicting.map(summarizeTextTrack)
     };
   }
@@ -1231,13 +1238,26 @@ function planTextTrackReplacement(asset, target, policy, options = {}) {
     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.`,
+        reason: `${countTracks(notGenerated, label, "that is not Mux-generated exists", "that are not Mux-generated exist")} for language '${target.languageCode}' or name '${target.name}': ${describeTracks(notGenerated)}. Use replaceExistingTracks: "replace_all" to replace ${itOrThem(notGenerated)}.`,
         tracks: notGenerated.map(summarizeTextTrack)
       };
     }
   }
   return { kind: "replace", toDelete: conflicting.map(summarizeTextTrack) };
 }
+function planSourceTrackReplacement(asset, sourceTrackId, target, policy) {
+  const colliding = findNameCollisionTextTracks(asset, target);
+  const blocking = policy === "fail" ? colliding : colliding.filter((track) => track.id !== sourceTrackId);
+  if (blocking.length > 0) {
+    return {
+      kind: "blocked",
+      reason: `${countTracks(blocking, "Text", "already has", "already have")} the name '${target.name}': ${describeTracks(blocking)}. Choose a different trackName.`,
+      tracks: blocking.map(summarizeTextTrack)
+    };
+  }
+  const source = policy === "replace" ? listTracks(asset, targetType(target)).find((track) => track.id === sourceTrackId) : void 0;
+  return source ? { kind: "replace", toDelete: [summarizeTextTrack(source)] } : { kind: "clear" };
+}
 function isDuplicateTrackNameError(error) {
   if (typeof error !== "object" || error === null) {
     return false;
@@ -1293,6 +1313,14 @@ async function createTextTrackOnMux(assetId, languageCode, trackName, presignedU
 }
 async function replaceAndCreateTrack(input) {
   "use step";
+  return writeTrack(input, (asset) => planTextTrackReplacement(asset, input.target, input.policy));
+}
+async function replaceSourceTrack(input) {
+  "use step";
+  const target = { ...input.target, type: "text" };
+  return writeTrack({ ...input, target }, (asset) => planSourceTrackReplacement(asset, input.sourceTrackId, target, input.policy));
+}
+async function writeTrack(input, plan) {
   const muxClient = await resolveMuxClient(input.credentials);
   const mux = await muxClient.createClient();
   const type = targetType(input.target);
@@ -1312,12 +1340,12 @@ async function replaceAndCreateTrack(input) {
       }
       return failed(error);
     }
-    const plan = planTextTrackReplacement(asset, input.target, input.policy, { keepTrackIds: input.keepTrackIds });
-    if (plan.kind === "blocked") {
-      return { ...plan, deleted };
+    const planned = plan(asset);
+    if (planned.kind === "blocked") {
+      return { ...planned, deleted };
     }
-    if (plan.kind === "replace") {
-      for (const track of plan.toDelete) {
+    if (planned.kind === "replace") {
+      for (const track of planned.toDelete) {
         try {
           await mux.video.assets.deleteTrack(input.assetId, track.id);
           deleted.push(track);
@@ -2297,17 +2325,15 @@ async function transformShotsResponse(data) {
         status: "pending",
         createdAt: data.created_at
       };
-    case "errored": {
-      const details = data.errors ?? data.error;
+    case "errored":
       return {
         status: "errored",
         createdAt: data.created_at,
         error: {
-          type: details?.type ?? "unknown",
-          messages: details?.messages ?? []
+          type: data.errors?.type ?? "unknown",
+          messages: data.errors?.messages ?? []
         }
       };
-    }
     case "completed":
       if (!data.shots_manifest_url) {
         throw new Error("Completed shots response is missing shots_manifest_url");
@@ -5496,7 +5522,13 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
       { type: "validation_error" }
     );
   }
-  const replaceExistingTracks = replaceExistingTracksOption ?? "replace_all";
+  if (replaceExistingTracksOption !== void 0 && replaceExistingTracksOption !== "replace" && replaceExistingTracksOption !== "fail") {
+    throw new MuxAiError(
+      `replaceExistingTracks must be "replace" or "fail" for editCaptions (received "${String(replaceExistingTracksOption)}").`,
+      { type: "validation_error" }
+    );
+  }
+  const replaceExistingTracks = replaceExistingTracksOption ?? "replace";
   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.`,
@@ -5552,15 +5584,14 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
     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.`,
+      `trackName "${outputTrack.name}" matches the source track's name. Mux track names must be unique; choose a different trackName or use replaceExistingTracks: "replace" to replace the source.`,
       { type: "validation_error" }
     );
   }
   if (uploadToMux && !legacyTrackNaming) {
-    const plan = planTextTrackReplacement(assetData, outputTrack, replaceExistingTracks, { keepTrackIds });
+    const plan = planSourceTrackReplacement(assetData, trackId, outputTrack, replaceExistingTracks);
     if (plan.kind === "blocked") {
       throw new MuxAiError(plan.reason, { type: "validation_error" });
     }
@@ -5682,14 +5713,14 @@ async function editCaptionsInternal(assetId, trackId, options, collectedUsage) {
     } else if (uploadToMux) {
       let outcome;
       try {
-        outcome = await replaceAndCreateTextTrack({
+        outcome = await replaceSourceTrack({
           assetId,
+          sourceTrackId: trackId,
           target: outputTrack,
           policy: replaceExistingTracks,
           presignedUrl,
           closedCaptions: sourceTrack.closed_captions,
           passthrough: trackPassthrough,
-          keepTrackIds,
           credentials
         });
       } catch (error) {
@@ -9889,10 +9920,12 @@ export {
   isValidISO639_3,
   normalizeTrackLanguageCode,
   normalizeTrackName,
+  planSourceTrackReplacement,
   planTextTrackReplacement,
   primitives_exports as primitives,
   replaceAndCreateTextTrack,
   replaceAndCreateTrack,
+  replaceSourceTrack,
   setWorkflowCredentialsProvider,
   summarizeTextTrack,
   toISO639_1,