@mux/ai 0.9.0 → 0.11.0

package/README.md

@@ -5,7 +5,7 @@
 
 Easy to use, purpose-driven, cost effective, configurable **_workflow functions_** in a TypeScript SDK for building AI-powered video and audio workflows on the server, powered by [Mux](https://www.mux.com), with support for popular AI/LLM providers (OpenAI, Anthropic, Google).
 
-- **Examples:** [`getSummaryAndTags`](#video-summarization), [`getModerationScores`](#content-moderation), [`hasBurnedInCaptions`](#burned-in-caption-detection), [`generateChapters`](#chapter-generation), [`generateEmbeddings`](#search-with-embeddings), [`translateCaptions`](#caption-translation), [`translateAudio`](#audio-dubbing)
+- **Examples:** [`getSummaryAndTags`](#video-summarization), [`getModerationScores`](#content-moderation), [`hasBurnedInCaptions`](#burned-in-caption-detection), [`generateChapters`](#chapter-generation), [`generateEmbeddings`](#search-with-embeddings), [`translateCaptions`](#caption-translation), [`editCaptions`](#caption-editing), [`translateAudio`](#audio-dubbing)
 - Workflows automatically ship with `"use workflow"` [compatability with Workflow DevKit](#compatability-with-workflow-devkit)
 
 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.
@@ -75,6 +75,7 @@ Workflows are high-level functions that handle complete media AI tasks end-to-en
 | [`generateChapters`](./docs/WORKFLOWS.md#chapter-generation) | Create chapter markers from transcripts | OpenAI, Anthropic, Google | Yes |
 | [`generateEmbeddings`](./docs/WORKFLOWS.md#embeddings) | Generate vector embeddings for semantic search | OpenAI, Google | Yes |
 | [`translateCaptions`](./docs/WORKFLOWS.md#caption-translation) | Translate captions into other languages | OpenAI, Anthropic, Google | Yes |
+| [`editCaptions`](./docs/WORKFLOWS.md#caption-editing) | Edit captions: censor profanity and/or apply static replacements | OpenAI, Anthropic, Google | Yes |
 | [`translateAudio`](./docs/WORKFLOWS.md#audio-dubbing) | Create AI-dubbed audio tracks | ElevenLabs | Yes |
 
 See the [Workflows guide](./docs/WORKFLOWS.md) for detailed documentation, options, and examples for each workflow. See the [API Reference](./docs/API.md) for complete parameter and return type details.
@@ -108,6 +109,27 @@ const result = await generateChapters("your-asset-id", "en", {
 // [{ startTime: 0, title: "Introduction" }, { startTime: 45, title: "Main Content" }, ...]
 ```
 
+**Caption editing:**
+
+```ts
+import { editCaptions } from "@mux/ai/workflows";
+
+const result = await editCaptions("your-asset-id", "track-id", {
+  provider: "anthropic",
+  autoCensorProfanity: {
+    mode: "blank", // "blank" ([____]), "remove", or "mask" (????)
+    alwaysCensor: ["brandname"],
+    neverCensor: ["damn"],
+  },
+  replacements: [
+    { find: "Mucks", replace: "Mux" },
+  ],
+});
+
+console.log(result.totalReplacementCount); // 8
+console.log(result.autoCensorProfanity?.replacements); // [{cueStartTime: 5, before: "shit", after: "[____]"}, ...]
+```
+
 **Semantic search embeddings:**
 
 ```ts

package/dist/{index-CkJStzYO.d.ts → index-BapL6paa.d.ts}

@@ -256,11 +256,11 @@ declare const chapterSchema: z.ZodObject<{
     startTime: z.ZodNumber;
     title: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    title: string;
     startTime: number;
-}, {
     title: string;
+}, {
     startTime: number;
+    title: string;
 }>;
 type Chapter = z.infer<typeof chapterSchema>;
 declare const chaptersSchema: z.ZodObject<{
@@ -268,21 +268,21 @@ declare const chaptersSchema: z.ZodObject<{
         startTime: z.ZodNumber;
         title: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        title: string;
         startTime: number;
-    }, {
         title: string;
+    }, {
         startTime: number;
+        title: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     chapters: {
-        title: string;
         startTime: number;
+        title: string;
     }[];
 }, {
     chapters: {
-        title: string;
         startTime: number;
+        title: string;
     }[];
 }>;
 type ChaptersType = z.infer<typeof chaptersSchema>;
@@ -348,6 +348,119 @@ interface ChaptersOptions extends MuxAIOptions {
 type ChapterSystemPromptSections = "role" | "context" | "constraints" | "qualityGuidelines";
 declare function generateChapters(assetId: string, languageCode: string, options?: ChaptersOptions): Promise<ChaptersResult>;
 
+/** Replacement strategy for censored words. */
+type CensorMode = "blank" | "remove" | "mask";
+interface AutoCensorProfanityOptions {
+    mode?: CensorMode;
+    alwaysCensor?: string[];
+    neverCensor?: string[];
+}
+interface CaptionReplacement {
+    find: string;
+    replace: string;
+}
+interface ReplacementRecord {
+    cueStartTime: number;
+    before: string;
+    after: string;
+}
+/** Configuration accepted by `editCaptions`. */
+interface EditCaptionsOptions<P extends SupportedProvider = SupportedProvider> extends MuxAIOptions {
+    /** Provider responsible for profanity detection. Required when autoCensorProfanity is set. */
+    provider?: P;
+    /** Provider-specific chat model identifier. */
+    model?: ModelIdByProvider[P];
+    /** LLM-powered profanity censorship. */
+    autoCensorProfanity?: AutoCensorProfanityOptions;
+    /** Static find/replace pairs (no LLM needed). */
+    replacements?: CaptionReplacement[];
+    /** Delete the original track after creating the edited one. Defaults to true. */
+    deleteOriginalTrack?: boolean;
+    /**
+     * When true (default) the edited VTT is uploaded to the configured
+     * bucket and attached to the Mux asset.
+     */
+    uploadToMux?: boolean;
+    /** Optional override for the S3-compatible endpoint used for uploads. */
+    s3Endpoint?: string;
+    /** S3 region (defaults to env.S3_REGION or 'auto'). */
+    s3Region?: string;
+    /** Bucket that will store edited VTT files. */
+    s3Bucket?: string;
+    /** Suffix appended to the original track name, e.g. "edited" produces "Subtitles (edited)". Defaults to "edited". */
+    trackNameSuffix?: string;
+    /** Expiry duration in seconds for S3 presigned GET URLs. Defaults to 86400 (24 hours). */
+    s3SignedUrlExpirySeconds?: number;
+}
+/** Output returned from `editCaptions`. */
+interface EditCaptionsResult {
+    assetId: string;
+    trackId: string;
+    originalVtt: string;
+    editedVtt: string;
+    totalReplacementCount: number;
+    autoCensorProfanity?: {
+        replacements: ReplacementRecord[];
+    };
+    replacements?: {
+        replacements: ReplacementRecord[];
+    };
+    uploadedTrackId?: string;
+    presignedUrl?: string;
+    usage?: TokenUsage;
+}
+/** Schema used when requesting profanity detection from a language model. */
+declare const profanityDetectionSchema: z.ZodObject<{
+    profanity: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    profanity: string[];
+}, {
+    profanity: string[];
+}>;
+/** Inferred shape returned by `profanityDetectionSchema`. */
+type ProfanityDetectionPayload = z.infer<typeof profanityDetectionSchema>;
+/**
+ * Applies a transform function only to VTT cue text lines, leaving headers,
+ * timestamps, and cue identifiers untouched. A cue text line is any line that
+ * follows a timestamp line (contains "-->") up until the next blank line.
+ * The transform receives the line text and the cue's start time in seconds.
+ */
+declare function transformCueText(rawVtt: string, transform: (line: string, cueStartTime: number) => string): string;
+/**
+ * Builds a case-insensitive word-boundary regex from an array of profane words.
+ * Words are sorted longest-first so multi-word phrases match before individual words.
+ */
+declare function buildReplacementRegex(words: string[]): RegExp | null;
+/**
+ * Returns a replacer function for the given censor mode.
+ */
+declare function createReplacer(mode: CensorMode): (match: string) => string;
+/**
+ * Applies profanity censorship to cue text lines in raw VTT content via
+ * regex replacement. Headers, timestamps, and cue identifiers are untouched.
+ */
+declare function censorVttContent(rawVtt: string, profanity: string[], mode: CensorMode): {
+    censoredVtt: string;
+    replacements: ReplacementRecord[];
+};
+/**
+ * Merges `alwaysCensor` into and filters `neverCensor` from an LLM-detected
+ * profanity list. Comparison is case-insensitive. `neverCensor` takes
+ * precedence over `alwaysCensor` when the same word appears in both.
+ */
+declare function applyOverrideLists(detected: string[], alwaysCensor: string[], neverCensor: string[]): string[];
+/**
+ * Applies static find/replace pairs to cue text lines in raw VTT content
+ * using word-boundary regex. Case-sensitive matching since static replacements
+ * target specific known strings. Headers, timestamps, and cue identifiers are
+ * untouched. Returns the edited VTT and the total number of replacements.
+ */
+declare function applyReplacements(rawVtt: string, replacements: CaptionReplacement[]): {
+    editedVtt: string;
+    replacements: ReplacementRecord[];
+};
+declare function editCaptions<P extends SupportedProvider = SupportedProvider>(assetId: string, trackId: string, options: EditCaptionsOptions<P>): Promise<EditCaptionsResult>;
+
 /** Configuration accepted by `generateEmbeddings`. */
 interface EmbeddingsOptions extends MuxAIOptions {
     /** AI provider used to generate embeddings (defaults to 'openai'). */
@@ -372,6 +485,8 @@ declare function generateVideoEmbeddings(assetId: string, options?: EmbeddingsOp
 /** Per-thumbnail moderation result returned from `getModerationScores`. */
 interface ThumbnailModerationScore {
     url: string;
+    /** Time in seconds of the thumbnail within the video. Absent for transcript moderation entries. */
+    time?: number;
     sexual: number;
     violence: number;
     error: boolean;
@@ -456,7 +571,9 @@ declare const HIVE_VIOLENCE_CATEGORIES: string[];
  */
 declare function getModerationScores(assetId: string, options?: ModerationOptions): Promise<ModerationResult>;
 
-declare const SUMMARY_KEYWORD_LIMIT = 10;
+declare const DEFAULT_SUMMARY_KEYWORD_LIMIT = 10;
+declare const DEFAULT_TITLE_LENGTH = 10;
+declare const DEFAULT_DESCRIPTION_LENGTH = 50;
 declare const summarySchema: z.ZodObject<{
     keywords: z.ZodArray<z.ZodString, "many">;
     title: z.ZodString;
@@ -529,9 +646,9 @@ interface SummarizationOptions extends MuxAIOptions {
      * Useful for customizing the AI's output for specific use cases (SEO, social media, etc.)
      */
     promptOverrides?: SummarizationPromptOverrides;
-    /** Desired title length in characters. */
+    /** Desired title length in words. */
     titleLength?: number;
-    /** Desired description length in characters. */
+    /** Desired description length in words. */
     descriptionLength?: number;
     /** Desired number of tags. */
     tagCount?: number;
@@ -680,6 +797,8 @@ interface AudioTranslationOptions extends MuxAIOptions {
     uploadToMux?: boolean;
     /** Optional storage adapter override for upload + presign operations. */
     storageAdapter?: StorageAdapter;
+    /** Expiry duration in seconds for S3 presigned GET URLs. Defaults to 86400 (24 hours). */
+    s3SignedUrlExpirySeconds?: number;
 }
 declare function translateAudio(assetId: string, toLanguageCode: string, options?: AudioTranslationOptions): Promise<AudioTranslationResult>;
 
@@ -726,6 +845,28 @@ interface TranslationOptions<P extends SupportedProvider = SupportedProvider> ex
     uploadToMux?: boolean;
     /** Optional storage adapter override for upload + presign operations. */
     storageAdapter?: StorageAdapter;
+    /** Expiry duration in seconds for S3 presigned GET URLs. Defaults to 86400 (24 hours). */
+    s3SignedUrlExpirySeconds?: number;
+    /**
+     * Optional VTT-aware chunking for caption translation.
+     * When enabled, the workflow splits cue-aligned translation requests by
+     * cue count and text token budget, then rebuilds the final VTT locally.
+     */
+    chunking?: TranslationChunkingOptions;
+}
+interface TranslationChunkingOptions {
+    /** Set to false to translate all cues in a single structured request. Defaults to true. */
+    enabled?: boolean;
+    /** Prefer a single request until the asset is at least this long. Defaults to 30 minutes. */
+    minimumAssetDurationSeconds?: number;
+    /** Soft target for chunk duration once chunking starts. Defaults to 30 minutes. */
+    targetChunkDurationSeconds?: number;
+    /** Max number of concurrent translation requests when chunking. Defaults to 4. */
+    maxConcurrentTranslations?: number;
+    /** Hard cap for cues included in a single AI translation chunk. Defaults to 80. */
+    maxCuesPerChunk?: number;
+    /** Approximate cap for cue text tokens included in a single AI translation chunk. Defaults to 2000. */
+    maxCueTextTokensPerChunk?: number;
 }
 /** Schema used when requesting caption translation from a language model. */
 declare const translationSchema: z.ZodObject<{
@@ -737,6 +878,8 @@ declare const translationSchema: z.ZodObject<{
 }>;
 /** Inferred shape returned by `translationSchema`. */
 type TranslationPayload = z.infer<typeof translationSchema>;
+declare function shouldSplitChunkTranslationError(error: unknown): boolean;
+declare function aggregateTokenUsage(usages: TokenUsage[]): TokenUsage;
 declare function translateCaptions<P extends SupportedProvider = SupportedProvider>(assetId: string, fromLanguageCode: string, toLanguageCode: string, options: TranslationOptions<P>): Promise<TranslationResult>;
 
 type index_AskQuestionsOptions = AskQuestionsOptions;
@@ -744,11 +887,14 @@ type index_AskQuestionsResult = AskQuestionsResult;
 type index_AskQuestionsType = AskQuestionsType;
 type index_AudioTranslationOptions = AudioTranslationOptions;
 type index_AudioTranslationResult = AudioTranslationResult;
+type index_AutoCensorProfanityOptions = AutoCensorProfanityOptions;
 type index_BurnedInCaptionsAnalysis = BurnedInCaptionsAnalysis;
 type index_BurnedInCaptionsOptions = BurnedInCaptionsOptions;
 type index_BurnedInCaptionsPromptOverrides = BurnedInCaptionsPromptOverrides;
 type index_BurnedInCaptionsPromptSections = BurnedInCaptionsPromptSections;
 type index_BurnedInCaptionsResult = BurnedInCaptionsResult;
+type index_CaptionReplacement = CaptionReplacement;
+type index_CensorMode = CensorMode;
 type index_Chapter = Chapter;
 type index_ChapterSystemPromptSections = ChapterSystemPromptSections;
 type index_ChaptersOptions = ChaptersOptions;
@@ -756,6 +902,11 @@ type index_ChaptersPromptOverrides = ChaptersPromptOverrides;
 type index_ChaptersPromptSections = ChaptersPromptSections;
 type index_ChaptersResult = ChaptersResult;
 type index_ChaptersType = ChaptersType;
+declare const index_DEFAULT_DESCRIPTION_LENGTH: typeof DEFAULT_DESCRIPTION_LENGTH;
+declare const index_DEFAULT_SUMMARY_KEYWORD_LIMIT: typeof DEFAULT_SUMMARY_KEYWORD_LIMIT;
+declare const index_DEFAULT_TITLE_LENGTH: typeof DEFAULT_TITLE_LENGTH;
+type index_EditCaptionsOptions<P extends SupportedProvider = SupportedProvider> = EditCaptionsOptions<P>;
+type index_EditCaptionsResult = EditCaptionsResult;
 type index_EmbeddingsOptions = EmbeddingsOptions;
 type index_EmbeddingsResult = EmbeddingsResult;
 declare const index_HIVE_SEXUAL_CATEGORIES: typeof HIVE_SEXUAL_CATEGORIES;
@@ -765,36 +916,48 @@ type index_HiveModerationSource = HiveModerationSource;
 type index_ModerationOptions = ModerationOptions;
 type index_ModerationProvider = ModerationProvider;
 type index_ModerationResult = ModerationResult;
+type index_ProfanityDetectionPayload = ProfanityDetectionPayload;
 type index_Question = Question;
 type index_QuestionAnswer = QuestionAnswer;
 type index_QuestionAnswerType = QuestionAnswerType;
-declare const index_SUMMARY_KEYWORD_LIMIT: typeof SUMMARY_KEYWORD_LIMIT;
+type index_ReplacementRecord = ReplacementRecord;
 type index_SummarizationOptions = SummarizationOptions;
 type index_SummarizationPromptOverrides = SummarizationPromptOverrides;
 type index_SummarizationPromptSections = SummarizationPromptSections;
 type index_SummaryAndTagsResult = SummaryAndTagsResult;
 type index_SummaryType = SummaryType;
 type index_ThumbnailModerationScore = ThumbnailModerationScore;
+type index_TranslationChunkingOptions = TranslationChunkingOptions;
 type index_TranslationOptions<P extends SupportedProvider = SupportedProvider> = TranslationOptions<P>;
 type index_TranslationPayload = TranslationPayload;
 type index_TranslationResult = TranslationResult;
+declare const index_aggregateTokenUsage: typeof aggregateTokenUsage;
+declare const index_applyOverrideLists: typeof applyOverrideLists;
+declare const index_applyReplacements: typeof applyReplacements;
 declare const index_askQuestions: typeof askQuestions;
+declare const index_buildReplacementRegex: typeof buildReplacementRegex;
 declare const index_burnedInCaptionsSchema: typeof burnedInCaptionsSchema;
+declare const index_censorVttContent: typeof censorVttContent;
 declare const index_chapterSchema: typeof chapterSchema;
 declare const index_chaptersSchema: typeof chaptersSchema;
+declare const index_createReplacer: typeof createReplacer;
+declare const index_editCaptions: typeof editCaptions;
 declare const index_generateChapters: typeof generateChapters;
 declare const index_generateEmbeddings: typeof generateEmbeddings;
 declare const index_generateVideoEmbeddings: typeof generateVideoEmbeddings;
 declare const index_getModerationScores: typeof getModerationScores;
 declare const index_getSummaryAndTags: typeof getSummaryAndTags;
 declare const index_hasBurnedInCaptions: typeof hasBurnedInCaptions;
+declare const index_profanityDetectionSchema: typeof profanityDetectionSchema;
 declare const index_questionAnswerSchema: typeof questionAnswerSchema;
+declare const index_shouldSplitChunkTranslationError: typeof shouldSplitChunkTranslationError;
 declare const index_summarySchema: typeof summarySchema;
+declare const index_transformCueText: typeof transformCueText;
 declare const index_translateAudio: typeof translateAudio;
 declare const index_translateCaptions: typeof translateCaptions;
 declare const index_translationSchema: typeof translationSchema;
 declare namespace index {
-  export { 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_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_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, type index_EmbeddingsOptions as EmbeddingsOptions, type index_EmbeddingsResult as EmbeddingsResult, 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_Question as Question, type index_QuestionAnswer as QuestionAnswer, type index_QuestionAnswerType as QuestionAnswerType, index_SUMMARY_KEYWORD_LIMIT as SUMMARY_KEYWORD_LIMIT, 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_TranslationOptions as TranslationOptions, type index_TranslationPayload as TranslationPayload, type index_TranslationResult as TranslationResult, index_askQuestions as askQuestions, index_burnedInCaptionsSchema as burnedInCaptionsSchema, index_chapterSchema as chapterSchema, index_chaptersSchema as chaptersSchema, index_generateChapters as generateChapters, index_generateEmbeddings as generateEmbeddings, index_generateVideoEmbeddings as generateVideoEmbeddings, index_getModerationScores as getModerationScores, index_getSummaryAndTags as getSummaryAndTags, index_hasBurnedInCaptions as hasBurnedInCaptions, index_questionAnswerSchema as questionAnswerSchema, index_summarySchema as summarySchema, index_translateAudio as translateAudio, index_translateCaptions as translateCaptions, index_translationSchema as translationSchema };
+  export { 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, 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_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_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_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_generateChapters as generateChapters, index_generateEmbeddings as generateEmbeddings, index_generateVideoEmbeddings as generateVideoEmbeddings, index_getModerationScores as getModerationScores, index_getSummaryAndTags as getSummaryAndTags, index_hasBurnedInCaptions as hasBurnedInCaptions, index_profanityDetectionSchema as profanityDetectionSchema, index_questionAnswerSchema as questionAnswerSchema, index_shouldSplitChunkTranslationError as shouldSplitChunkTranslationError, index_summarySchema as summarySchema, index_transformCueText as transformCueText, index_translateAudio as translateAudio, index_translateCaptions as translateCaptions, index_translationSchema as translationSchema };
 }
 
-export { translateCaptions as $, type AskQuestionsOptions as A, type BurnedInCaptionsAnalysis as B, type Chapter as C, type SummaryAndTagsResult as D, type EmbeddingsOptions as E, type SummaryType as F, type TranslationOptions as G, HIVE_SEXUAL_CATEGORIES as H, type TranslationPayload as I, type TranslationResult as J, askQuestions as K, burnedInCaptionsSchema as L, type ModerationOptions as M, chapterSchema as N, chaptersSchema as O, generateChapters as P, type Question as Q, generateEmbeddings as R, SUMMARY_KEYWORD_LIMIT as S, type ThumbnailModerationScore as T, generateVideoEmbeddings as U, getModerationScores as V, getSummaryAndTags as W, hasBurnedInCaptions as X, questionAnswerSchema as Y, summarySchema as Z, translateAudio as _, type AskQuestionsResult as a, translationSchema as a0, type AskQuestionsType as b, type AudioTranslationOptions as c, type AudioTranslationResult as d, type BurnedInCaptionsOptions as e, type BurnedInCaptionsPromptOverrides as f, type BurnedInCaptionsPromptSections as g, type BurnedInCaptionsResult as h, index as i, type ChapterSystemPromptSections as j, type ChaptersOptions as k, type ChaptersPromptOverrides as l, type ChaptersPromptSections as m, type ChaptersResult as n, type ChaptersType as o, type EmbeddingsResult as p, HIVE_VIOLENCE_CATEGORIES as q, type HiveModerationOutput as r, type HiveModerationSource as s, type ModerationProvider as t, type ModerationResult as u, type QuestionAnswer as v, type QuestionAnswerType as w, type SummarizationOptions as x, type SummarizationPromptOverrides as y, type SummarizationPromptSections as z };
+export { askQuestions as $, type AskQuestionsOptions as A, type BurnedInCaptionsAnalysis as B, type CaptionReplacement as C, DEFAULT_DESCRIPTION_LENGTH as D, type EditCaptionsOptions as E, type ModerationProvider as F, type ModerationResult as G, HIVE_SEXUAL_CATEGORIES as H, type QuestionAnswer as I, type QuestionAnswerType as J, type SummarizationPromptOverrides as K, type SummarizationPromptSections as L, type ModerationOptions as M, type SummaryAndTagsResult as N, type SummaryType as O, type ProfanityDetectionPayload as P, type Question as Q, type ReplacementRecord as R, type SummarizationOptions as S, type ThumbnailModerationScore as T, type TranslationChunkingOptions as U, type TranslationOptions as V, type TranslationPayload as W, type TranslationResult as X, aggregateTokenUsage as Y, applyOverrideLists as Z, applyReplacements as _, type AskQuestionsResult as a, buildReplacementRegex as a0, burnedInCaptionsSchema as a1, censorVttContent as a2, chapterSchema as a3, chaptersSchema as a4, createReplacer as a5, editCaptions as a6, generateChapters as a7, generateEmbeddings as a8, generateVideoEmbeddings as a9, getModerationScores as aa, getSummaryAndTags as ab, hasBurnedInCaptions as ac, profanityDetectionSchema as ad, questionAnswerSchema as ae, shouldSplitChunkTranslationError as af, summarySchema as ag, transformCueText as ah, translateAudio as ai, translateCaptions as aj, translationSchema as ak, type AskQuestionsType as b, type AudioTranslationOptions as c, type AudioTranslationResult as d, type AutoCensorProfanityOptions as e, type BurnedInCaptionsOptions as f, type BurnedInCaptionsPromptOverrides as g, type BurnedInCaptionsPromptSections as h, index as i, type BurnedInCaptionsResult as j, type CensorMode as k, type Chapter as l, type ChapterSystemPromptSections as m, type ChaptersOptions as n, type ChaptersPromptOverrides as o, type ChaptersPromptSections as p, type ChaptersResult as q, type ChaptersType as r, DEFAULT_SUMMARY_KEYWORD_LIMIT as s, DEFAULT_TITLE_LENGTH as t, type EditCaptionsResult as u, type EmbeddingsOptions as v, type EmbeddingsResult as w, HIVE_VIOLENCE_CATEGORIES as x, type HiveModerationOutput as y, type HiveModerationSource as z };

package/dist/{index-Nxf6BaBO.d.ts → index-DLhfJsOd.d.ts}

@@ -99,6 +99,67 @@ declare function getHotspotsForVideo(videoId: string, options?: HotspotOptions):
  */
 declare function getHotspotsForPlaybackId(playbackId: string, options?: HotspotOptions): Promise<Hotspot[]>;
 
+interface Shot {
+    /** Start time of the shot in seconds from the beginning of the asset. */
+    startTime: number;
+    /** Signed URL for a representative image of the shot. */
+    imageUrl: string;
+}
+interface PendingShotsResult {
+    status: "pending";
+    createdAt: string;
+}
+interface ErroredShotsResult {
+    status: "errored";
+    createdAt: string;
+    error: {
+        type: string;
+        messages: string[];
+    };
+}
+interface CompletedShotsResult {
+    status: "completed";
+    createdAt: string;
+    shots: Shot[];
+}
+type ShotsResult = PendingShotsResult | ErroredShotsResult | CompletedShotsResult;
+interface ShotRequestOptions {
+    /** Optional workflow credentials */
+    credentials?: WorkflowCredentialsInput;
+}
+interface WaitForShotsOptions extends ShotRequestOptions {
+    /** Polling interval in milliseconds (default: 2000, minimum enforced: 1000) */
+    pollIntervalMs?: number;
+    /** Maximum number of polling attempts (default: 60) */
+    maxAttempts?: number;
+    /** When true, request shot generation before polling (default: true) */
+    createIfMissing?: boolean;
+}
+/**
+ * Starts generating shots for an asset.
+ *
+ * @param assetId - The Mux asset ID
+ * @param options - Request options
+ * @returns Pending shot generation state
+ */
+declare function requestShotsForAsset(assetId: string, options?: ShotRequestOptions): Promise<PendingShotsResult>;
+/**
+ * Gets the current shot generation status for an asset.
+ *
+ * @param assetId - The Mux asset ID
+ * @param options - Request options
+ * @returns Pending, errored, or completed shot result
+ */
+declare function getShotsForAsset(assetId: string, options?: ShotRequestOptions): Promise<ShotsResult>;
+/**
+ * Requests shot generation if needed and polls until shots are completed.
+ *
+ * @param assetId - The Mux asset ID
+ * @param options - Polling options
+ * @returns Completed shot result
+ */
+declare function waitForShotsForAsset(assetId: string, options?: WaitForShotsOptions): Promise<CompletedShotsResult>;
+
 declare const DEFAULT_STORYBOARD_WIDTH = 640;
 /**
  * Generates a storyboard URL for the given playback ID.
@@ -156,6 +217,14 @@ declare function extractTimestampedTranscript(vttContent: string): string;
  * @returns Array of VTT cues with start/end times and text
  */
 declare function parseVTTCues(vttContent: string): VTTCue[];
+declare function splitVttPreambleAndCueBlocks(vttContent: string): {
+    preamble: string;
+    cueBlocks: string[];
+};
+declare function buildVttFromCueBlocks(cueBlocks: string[], preamble?: string): string;
+declare function replaceCueText(cueBlock: string, translatedText: string): string;
+declare function buildVttFromTranslatedCueBlocks(cueBlocks: string[], translatedTexts: string[], preamble?: string): string;
+declare function concatenateVttSegments(segments: string[], preamble?: string): string;
 /**
  * Builds a transcript URL for the given playback ID and track ID.
  * If a signing context is provided, the URL will be signed with a token.
@@ -168,6 +237,38 @@ declare function parseVTTCues(vttContent: string): VTTCue[];
 declare function buildTranscriptUrl(playbackId: string, trackId: string, shouldSign?: boolean, credentials?: WorkflowCredentialsInput): Promise<string>;
 declare function fetchTranscriptForAsset(asset: MuxAsset, playbackId: string, options?: TranscriptFetchOptions): Promise<TranscriptResult>;
 
+/**
+ * Generic text-first chunking utilities.
+ *
+ * Reach for this module when the downstream consumer only needs chunk text plus
+ * lightweight metadata such as token count or approximate start/end times.
+ * These helpers are ideal for embeddings, retrieval, summarization inputs, or
+ * other workflows where preserving the original document format is not required.
+ *
+ * This module also includes cue-preserving chunk planners for VTT workflows.
+ * Those helpers still operate at the chunk-planning layer; if you need to split
+ * or rebuild full VTT documents, use the VTT structure helpers from
+ * `@mux/ai/primitives/transcripts`.
+ */
+interface VTTDurationChunkingOptions {
+    targetChunkDurationSeconds: number;
+    maxChunkDurationSeconds: number;
+    minChunkDurationSeconds?: number;
+    boundaryLookaheadCues?: number;
+    boundaryPauseSeconds?: number;
+}
+interface VTTCueBudgetChunkingOptions {
+    maxCuesPerChunk: number;
+    maxTextTokensPerChunk?: number;
+}
+interface VTTDurationChunk {
+    id: string;
+    cueStartIndex: number;
+    cueEndIndex: number;
+    cueCount: number;
+    startTime: number;
+    endTime: number;
+}
 /**
  * Simple token counter that approximates tokens by word count.
  * For production use with OpenAI, consider using a proper tokenizer like tiktoken.
@@ -193,6 +294,8 @@ declare function chunkByTokens(text: string, maxTokens: number, overlapTokens?:
  * @returns Array of text chunks with accurate start/end times
  */
 declare function chunkVTTCues(cues: VTTCue[], maxTokens: number, overlapCues?: number): TextChunk[];
+declare function chunkVTTCuesByBudget(cues: VTTCue[], options: VTTCueBudgetChunkingOptions): VTTDurationChunk[];
+declare function chunkVTTCuesByDuration(cues: VTTCue[], options: VTTDurationChunkingOptions): VTTDurationChunk[];
 /**
  * Chunks text according to the specified strategy.
  *
@@ -221,24 +324,42 @@ interface ThumbnailOptions {
  * @param playbackId - The Mux playback ID
  * @param duration - Video duration in seconds
  * @param options - Thumbnail generation options
- * @returns Array of thumbnail URLs (signed if shouldSign is true)
+ * @returns Array of objects containing the thumbnail URL and its time in seconds
  */
-declare function getThumbnailUrls(playbackId: string, duration: number, options?: ThumbnailOptions): Promise<string[]>;
+declare function getThumbnailUrls(playbackId: string, duration: number, options?: ThumbnailOptions): Promise<Array<{
+    url: string;
+    time: number;
+}>>;
 
+type index_CompletedShotsResult = CompletedShotsResult;
 declare const index_DEFAULT_STORYBOARD_WIDTH: typeof DEFAULT_STORYBOARD_WIDTH;
+type index_ErroredShotsResult = ErroredShotsResult;
 type index_HeatmapOptions = HeatmapOptions;
 type index_HeatmapResponse = HeatmapResponse;
 type index_Hotspot = Hotspot;
 type index_HotspotOptions = HotspotOptions;
 type index_HotspotResponse = HotspotResponse;
+type index_PendingShotsResult = PendingShotsResult;
+type index_Shot = Shot;
+type index_ShotRequestOptions = ShotRequestOptions;
+type index_ShotsResult = ShotsResult;
 type index_ThumbnailOptions = ThumbnailOptions;
 type index_TranscriptFetchOptions = TranscriptFetchOptions;
 type index_TranscriptResult = TranscriptResult;
 type index_VTTCue = VTTCue;
+type index_VTTCueBudgetChunkingOptions = VTTCueBudgetChunkingOptions;
+type index_VTTDurationChunk = VTTDurationChunk;
+type index_VTTDurationChunkingOptions = VTTDurationChunkingOptions;
+type index_WaitForShotsOptions = WaitForShotsOptions;
 declare const index_buildTranscriptUrl: typeof buildTranscriptUrl;
+declare const index_buildVttFromCueBlocks: typeof buildVttFromCueBlocks;
+declare const index_buildVttFromTranslatedCueBlocks: typeof buildVttFromTranslatedCueBlocks;
 declare const index_chunkByTokens: typeof chunkByTokens;
 declare const index_chunkText: typeof chunkText;
 declare const index_chunkVTTCues: typeof chunkVTTCues;
+declare const index_chunkVTTCuesByBudget: typeof chunkVTTCuesByBudget;
+declare const index_chunkVTTCuesByDuration: typeof chunkVTTCuesByDuration;
+declare const index_concatenateVttSegments: typeof concatenateVttSegments;
 declare const index_estimateTokenCount: typeof estimateTokenCount;
 declare const index_extractTextFromVTT: typeof extractTextFromVTT;
 declare const index_extractTimestampedTranscript: typeof extractTimestampedTranscript;
@@ -251,13 +372,18 @@ declare const index_getHotspotsForAsset: typeof getHotspotsForAsset;
 declare const index_getHotspotsForPlaybackId: typeof getHotspotsForPlaybackId;
 declare const index_getHotspotsForVideo: typeof getHotspotsForVideo;
 declare const index_getReadyTextTracks: typeof getReadyTextTracks;
+declare const index_getShotsForAsset: typeof getShotsForAsset;
 declare const index_getStoryboardUrl: typeof getStoryboardUrl;
 declare const index_getThumbnailUrls: typeof getThumbnailUrls;
 declare const index_parseVTTCues: typeof parseVTTCues;
+declare const index_replaceCueText: typeof replaceCueText;
+declare const index_requestShotsForAsset: typeof requestShotsForAsset;
 declare const index_secondsToTimestamp: typeof secondsToTimestamp;
+declare const index_splitVttPreambleAndCueBlocks: typeof splitVttPreambleAndCueBlocks;
 declare const index_vttTimestampToSeconds: typeof vttTimestampToSeconds;
+declare const index_waitForShotsForAsset: typeof waitForShotsForAsset;
 declare namespace index {
-  export { index_DEFAULT_STORYBOARD_WIDTH as DEFAULT_STORYBOARD_WIDTH, type index_HeatmapOptions as HeatmapOptions, type index_HeatmapResponse as HeatmapResponse, type index_Hotspot as Hotspot, type index_HotspotOptions as HotspotOptions, type index_HotspotResponse as HotspotResponse, type index_ThumbnailOptions as ThumbnailOptions, type index_TranscriptFetchOptions as TranscriptFetchOptions, type index_TranscriptResult as TranscriptResult, type index_VTTCue as VTTCue, index_buildTranscriptUrl as buildTranscriptUrl, index_chunkByTokens as chunkByTokens, index_chunkText as chunkText, index_chunkVTTCues as chunkVTTCues, index_estimateTokenCount as estimateTokenCount, index_extractTextFromVTT as extractTextFromVTT, index_extractTimestampedTranscript as extractTimestampedTranscript, index_fetchTranscriptForAsset as fetchTranscriptForAsset, index_findCaptionTrack as findCaptionTrack, index_getHeatmapForAsset as getHeatmapForAsset, index_getHeatmapForPlaybackId as getHeatmapForPlaybackId, index_getHeatmapForVideo as getHeatmapForVideo, index_getHotspotsForAsset as getHotspotsForAsset, index_getHotspotsForPlaybackId as getHotspotsForPlaybackId, index_getHotspotsForVideo as getHotspotsForVideo, index_getReadyTextTracks as getReadyTextTracks, index_getStoryboardUrl as getStoryboardUrl, index_getThumbnailUrls as getThumbnailUrls, index_parseVTTCues as parseVTTCues, index_secondsToTimestamp as secondsToTimestamp, index_vttTimestampToSeconds as vttTimestampToSeconds };
+  export { type index_CompletedShotsResult as CompletedShotsResult, index_DEFAULT_STORYBOARD_WIDTH as DEFAULT_STORYBOARD_WIDTH, type index_ErroredShotsResult as ErroredShotsResult, type index_HeatmapOptions as HeatmapOptions, type index_HeatmapResponse as HeatmapResponse, type index_Hotspot as Hotspot, type index_HotspotOptions as HotspotOptions, type index_HotspotResponse as HotspotResponse, type index_PendingShotsResult as PendingShotsResult, type index_Shot as Shot, type index_ShotRequestOptions as ShotRequestOptions, type index_ShotsResult as ShotsResult, type index_ThumbnailOptions as ThumbnailOptions, type index_TranscriptFetchOptions as TranscriptFetchOptions, type index_TranscriptResult as TranscriptResult, type index_VTTCue as VTTCue, type index_VTTCueBudgetChunkingOptions as VTTCueBudgetChunkingOptions, type index_VTTDurationChunk as VTTDurationChunk, type index_VTTDurationChunkingOptions as VTTDurationChunkingOptions, type index_WaitForShotsOptions as WaitForShotsOptions, index_buildTranscriptUrl as buildTranscriptUrl, index_buildVttFromCueBlocks as buildVttFromCueBlocks, index_buildVttFromTranslatedCueBlocks as buildVttFromTranslatedCueBlocks, index_chunkByTokens as chunkByTokens, index_chunkText as chunkText, index_chunkVTTCues as chunkVTTCues, index_chunkVTTCuesByBudget as chunkVTTCuesByBudget, index_chunkVTTCuesByDuration as chunkVTTCuesByDuration, index_concatenateVttSegments as concatenateVttSegments, index_estimateTokenCount as estimateTokenCount, index_extractTextFromVTT as extractTextFromVTT, index_extractTimestampedTranscript as extractTimestampedTranscript, index_fetchTranscriptForAsset as fetchTranscriptForAsset, index_findCaptionTrack as findCaptionTrack, index_getHeatmapForAsset as getHeatmapForAsset, index_getHeatmapForPlaybackId as getHeatmapForPlaybackId, index_getHeatmapForVideo as getHeatmapForVideo, index_getHotspotsForAsset as getHotspotsForAsset, index_getHotspotsForPlaybackId as getHotspotsForPlaybackId, index_getHotspotsForVideo as getHotspotsForVideo, index_getReadyTextTracks as getReadyTextTracks, index_getShotsForAsset as getShotsForAsset, index_getStoryboardUrl as getStoryboardUrl, index_getThumbnailUrls as getThumbnailUrls, index_parseVTTCues as parseVTTCues, index_replaceCueText as replaceCueText, index_requestShotsForAsset as requestShotsForAsset, index_secondsToTimestamp as secondsToTimestamp, index_splitVttPreambleAndCueBlocks as splitVttPreambleAndCueBlocks, index_vttTimestampToSeconds as vttTimestampToSeconds, index_waitForShotsForAsset as waitForShotsForAsset };
 }
 
-export { secondsToTimestamp as A, vttTimestampToSeconds as B, DEFAULT_STORYBOARD_WIDTH as D, type HeatmapOptions as H, type ThumbnailOptions as T, type VTTCue as V, type HeatmapResponse as a, type Hotspot as b, type HotspotOptions as c, type HotspotResponse as d, type TranscriptFetchOptions as e, type TranscriptResult as f, buildTranscriptUrl as g, chunkByTokens as h, index as i, chunkText as j, chunkVTTCues as k, estimateTokenCount as l, extractTextFromVTT as m, extractTimestampedTranscript as n, fetchTranscriptForAsset as o, findCaptionTrack as p, getHeatmapForAsset as q, getHeatmapForPlaybackId as r, getHeatmapForVideo as s, getHotspotsForAsset as t, getHotspotsForPlaybackId as u, getHotspotsForVideo as v, getReadyTextTracks as w, getStoryboardUrl as x, getThumbnailUrls as y, parseVTTCues as z };
+export { getHeatmapForAsset as A, getHeatmapForPlaybackId as B, type CompletedShotsResult as C, DEFAULT_STORYBOARD_WIDTH as D, type ErroredShotsResult as E, getHeatmapForVideo as F, getHotspotsForAsset as G, type HeatmapOptions as H, getHotspotsForPlaybackId as I, getHotspotsForVideo as J, getReadyTextTracks as K, getShotsForAsset as L, getStoryboardUrl as M, getThumbnailUrls as N, parseVTTCues as O, type PendingShotsResult as P, replaceCueText as Q, requestShotsForAsset as R, type Shot as S, type ThumbnailOptions as T, secondsToTimestamp as U, type VTTCue as V, type WaitForShotsOptions as W, splitVttPreambleAndCueBlocks as X, vttTimestampToSeconds as Y, waitForShotsForAsset as Z, type HeatmapResponse as a, type Hotspot as b, type HotspotOptions as c, type HotspotResponse as d, type ShotRequestOptions as e, type ShotsResult as f, type TranscriptFetchOptions as g, type TranscriptResult as h, index as i, type VTTCueBudgetChunkingOptions as j, type VTTDurationChunk as k, type VTTDurationChunkingOptions as l, buildTranscriptUrl as m, buildVttFromCueBlocks as n, buildVttFromTranslatedCueBlocks as o, chunkByTokens as p, chunkText as q, chunkVTTCues as r, chunkVTTCuesByBudget as s, chunkVTTCuesByDuration as t, concatenateVttSegments as u, estimateTokenCount as v, extractTextFromVTT as w, extractTimestampedTranscript as x, fetchTranscriptForAsset as y, findCaptionTrack as z };

package/dist/index.d.ts

@@ -1,15 +1,15 @@
 import { W as WorkflowCredentials, S as StoragePutObjectInput, a as StoragePresignGetObjectInput } from './types-BRbaGW3t.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 StorageAdapter, T as TextChunk, g as TokenChunkingConfig, h as TokenUsage, i as ToneType, U as UsageMetadata, V as VTTChunkingConfig, j as VideoEmbeddingsResult, k as WorkflowCredentialsInput, l as WorkflowMuxClient, m as decryptFromWorkflow, n as encryptForWorkflow } from './types-BRbaGW3t.js';
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
-export { i as primitives } from './index-Nxf6BaBO.js';
-export { i as workflows } from './index-CkJStzYO.js';
+export { i as primitives } from './index-DLhfJsOd.js';
+export { i as workflows } from './index-BapL6paa.js';
 import '@mux/mux-node';
 import 'zod';
 import '@ai-sdk/anthropic';
 import '@ai-sdk/google';
 import '@ai-sdk/openai';
 
-var version = "0.9.0";
+var version = "0.11.0";
 
 /**
  * A function that returns workflow credentials, either synchronously or asynchronously.