@mux/ai 0.13.1 → 0.15.1

package/README.md

@@ -71,7 +71,7 @@ Workflows are high-level functions that handle complete media AI tasks end-to-en
 | [`getSummaryAndTags`](./docs/WORKFLOWS.md#video-summarization) | Generate titles, descriptions, and tags | OpenAI, Anthropic, Google | Yes |
 | [`getModerationScores`](./docs/WORKFLOWS.md#content-moderation) | Detect inappropriate content | OpenAI, Hive | Yes |
 | [`hasBurnedInCaptions`](./docs/WORKFLOWS.md#burned-in-caption-detection) | Detect hardcoded subtitles in video frames | OpenAI, Anthropic, Google | — |
-| [`askQuestions`](./docs/WORKFLOWS.md#ask-questions) | Answer yes/no questions about asset content | OpenAI, Anthropic, Google | — |
+| [`askQuestions`](./docs/WORKFLOWS.md#ask-questions) | Answer yes/no questions about asset content | OpenAI, Anthropic, Google | Yes |
 | [`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 |
@@ -102,7 +102,7 @@ if (result.exceedsThreshold) {
 ```ts
 import { generateChapters } from "@mux/ai/workflows";
 
-const result = await generateChapters("your-asset-id", "en", {
+const result = await generateChapters("your-asset-id", {
   provider: "anthropic"
 });
 

package/dist/{index-BeX_4DL7.d.ts → index-yn3fUDgv.d.ts}

@@ -34,7 +34,7 @@ interface EmbeddingModelIdByProvider {
     google: GoogleEmbeddingModelId;
 }
 
-/** A single yes/no question to be answered about video content. */
+/** A single yes/no question to be answered about asset content. */
 interface Question {
     /** The question text */
     question: string;
@@ -49,7 +49,7 @@ interface QuestionAnswer {
     confidence: number;
     /** Reasoning explaining the answer, or why the question was skipped */
     reasoning: string;
-    /** Whether the question was skipped due to irrelevance to the video content */
+    /** Whether the question was skipped due to irrelevance to the asset content */
     skipped: boolean;
 }
 /** Configuration options for askQuestions workflow. */
@@ -58,9 +58,11 @@ interface AskQuestionsOptions extends MuxAIOptions {
     provider?: SupportedProvider;
     /** Provider-specific chat model identifier. */
     model?: ModelIdByProvider[SupportedProvider];
+    /** BCP 47 language code of the caption track to use (e.g. "en", "fr"). When omitted, prefers English if available. */
+    languageCode?: string;
     /** Allowed answers for each question (defaults to ["yes", "no"]). */
     answerOptions?: string[];
-    /** Fetch transcript alongside storyboard (defaults to true). */
+    /** Fetch transcript alongside storyboard (defaults to true, required for audio-only assets). */
     includeTranscript?: boolean;
     /** Strip timestamps/markup from transcripts (defaults to true). */
     cleanTranscript?: boolean;
@@ -77,8 +79,8 @@ interface AskQuestionsResult {
     assetId: string;
     /** Array of answers for each question. */
     answers: QuestionAnswer[];
-    /** Storyboard image URL that was analyzed. */
-    storyboardUrl: string;
+    /** Storyboard image URL that was analyzed (undefined for audio-only assets). */
+    storyboardUrl?: string;
     /** Token usage from the AI provider (for efficiency/cost analysis). */
     usage?: TokenUsage;
     /** Raw transcript text used for analysis (when includeTranscript is true). */
@@ -146,7 +148,8 @@ declare function createAskQuestionsSchema(allowedAnswers: [string, ...string[]])
 type AskQuestionsSchema = ReturnType<typeof createAskQuestionsSchema>;
 type AskQuestionsType = z.infer<AskQuestionsSchema>;
 /**
- * Answer questions about a Mux video asset by analyzing storyboard frames and transcript.
+ * Answer questions about a Mux asset by analyzing storyboard frames and transcript.
+ * For audio-only assets, this workflow analyzes transcript content only.
  * Defaults to yes/no answers unless `answerOptions` are provided.
  *
  * This workflow takes a list of questions and returns structured answers with confidence
@@ -315,7 +318,7 @@ type ChaptersPromptSections = "task" | "outputFormat" | "chapterGuidelines" | "t
  *
  * @example
  * ```typescript
- * const result = await generateChapters(assetId, "en", {
+ * const result = await generateChapters(assetId, {
  *   promptOverrides: {
  *     titleGuidelines: "Use short, punchy titles under 6 words.",
  *   },
@@ -325,6 +328,8 @@ type ChaptersPromptSections = "task" | "outputFormat" | "chapterGuidelines" | "t
 type ChaptersPromptOverrides = PromptOverrides<ChaptersPromptSections>;
 /** Configuration accepted by `generateChapters`. */
 interface ChaptersOptions extends MuxAIOptions {
+    /** BCP 47 language code of the caption track to use (e.g. "en", "fr"). When omitted, prefers English if available. */
+    languageCode?: string;
     /** AI provider used to interpret the transcript (defaults to 'openai'). */
     provider?: SupportedProvider;
     /** Provider-specific model identifier. */
@@ -356,7 +361,7 @@ interface ChaptersOptions extends MuxAIOptions {
  * Use these to customize the AI's persona and constraints.
  */
 type ChapterSystemPromptSections = "role" | "context" | "constraints" | "qualityGuidelines";
-declare function generateChapters(assetId: string, languageCode: string, options?: ChaptersOptions): Promise<ChaptersResult>;
+declare function generateChapters(assetId: string, options?: ChaptersOptions): Promise<ChaptersResult>;
 
 /** Replacement strategy for censored words. */
 type CensorMode = "blank" | "remove" | "mask";
@@ -387,8 +392,17 @@ interface EditCaptionsOptions<P extends SupportedProvider = SupportedProvider> e
     /** 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.
+     * When `true` the edited VTT is uploaded to the configured
+     * S3-compatible bucket and a `presignedUrl` is returned.
+     * Defaults to the value of `uploadToMux` when omitted.
+     * Ignored (treated as `true`) when `uploadToMux` is `true`,
+     * since Mux track creation requires a presigned URL.
+     */
+    uploadToS3?: boolean;
+    /**
+     * When true (default) the edited VTT is attached as a track on the
+     * Mux asset. Implies `uploadToS3: true` because a presigned URL is
+     * required for track creation.
      */
     uploadToMux?: boolean;
     /** Optional override for the S3-compatible endpoint used for uploads. */
@@ -608,6 +622,22 @@ interface ModerationResult {
     /** Convenience flag so callers can understand why `thumbnailScores` may contain a transcript entry. */
     isAudioOnly: boolean;
     thumbnailScores: ThumbnailModerationScore[];
+    /** Coverage metadata describing how many requested moderation samples actually succeeded. */
+    coverage: {
+        requestedSampleCount: number;
+        successfulSampleCount: number;
+        failedSampleCount: number;
+        /** Fraction of requested samples that produced a usable moderation result. */
+        sampleCoverage: number;
+        /** True when at least one sample failed but the workflow still returned a result. */
+        isPartial: boolean;
+        /**
+         * True when threshold interpretation should be treated cautiously.
+         * For thumbnail moderation, this means we either covered less than half of planned samples
+         * or ended up with fewer than 3 successful thumbnails.
+         */
+        isLowConfidence: boolean;
+    };
     /** Workflow usage metadata (asset duration, thumbnails, etc.). */
     usage?: TokenUsage;
     maxScores: {
@@ -656,7 +686,7 @@ interface ModerationOptions extends MuxAIOptions {
     thumbnailInterval?: number;
     /** Width of storyboard thumbnails in pixels (defaults to 640). */
     thumbnailWidth?: number;
-    /** Maximum number of thumbnails to sample (defaults to unlimited). When set, samples are evenly distributed with first and last frames pinned. */
+    /** Maximum number of thumbnails to sample (defaults to unlimited). Acts as a cap: if `thumbnailInterval` produces fewer samples than this limit the interval is respected; otherwise samples are evenly distributed with first and last frames pinned. */
     maxSamples?: number;
     /** Max concurrent moderation requests (defaults to 5). */
     maxConcurrent?: number;
@@ -739,6 +769,8 @@ interface SummarizationOptions extends MuxAIOptions {
     provider?: SupportedProvider;
     /** Provider-specific chat model identifier. */
     model?: ModelIdByProvider[SupportedProvider];
+    /** BCP 47 language code of the caption track to use (e.g. "en", "fr"). When omitted, prefers English if available. */
+    languageCode?: string;
     /** Prompt tone shim applied to the system instruction (defaults to 'neutral'). */
     tone?: ToneType;
     /** Fetch the transcript and send it alongside the storyboard (defaults to true). */
@@ -899,8 +931,17 @@ interface AudioTranslationOptions extends MuxAIOptions {
     /** Bucket that will store dubbed audio files. */
     s3Bucket?: string;
     /**
-     * When true (default) the dubbed audio file is uploaded to the configured
-     * bucket and attached to the Mux asset.
+     * When `true` the dubbed audio is uploaded to the configured
+     * S3-compatible bucket and a `presignedUrl` is returned.
+     * Defaults to the value of `uploadToMux` when omitted.
+     * Ignored (treated as `true`) when `uploadToMux` is `true`,
+     * since Mux track creation requires a presigned URL.
+     */
+    uploadToS3?: boolean;
+    /**
+     * When true (default) the dubbed audio is attached as a track on the
+     * Mux asset. Implies `uploadToS3: true` because a presigned URL is
+     * required for track creation.
      */
     uploadToMux?: boolean;
     /** Optional storage adapter override for upload + presign operations. */
@@ -913,6 +954,7 @@ declare function translateAudio(assetId: string, toLanguageCode: string, options
 /** Output returned from `translateCaptions`. */
 interface TranslationResult {
     assetId: string;
+    trackId: string;
     /** Source language code (ISO 639-1 two-letter format). */
     sourceLanguageCode: SupportedISO639_1;
     /** Target language code (ISO 639-1 two-letter format). */
@@ -947,8 +989,17 @@ interface TranslationOptions<P extends SupportedProvider = SupportedProvider> ex
     /** Bucket that will store translated VTT files. */
     s3Bucket?: string;
     /**
-     * When true (default) the translated VTT is uploaded to the configured
-     * bucket and attached to the Mux asset.
+     * When `true` the translated VTT is uploaded to the configured
+     * S3-compatible bucket and a `presignedUrl` is returned.
+     * Defaults to the value of `uploadToMux` when omitted.
+     * Ignored (treated as `true`) when `uploadToMux` is `true`,
+     * since Mux track creation requires a presigned URL.
+     */
+    uploadToS3?: boolean;
+    /**
+     * When true (default) the translated VTT is attached as a track on the
+     * Mux asset. Implies `uploadToS3: true` because a presigned URL is
+     * required for track creation.
      */
     uploadToMux?: boolean;
     /** Optional storage adapter override for upload + presign operations. */
@@ -988,7 +1039,7 @@ declare const translationSchema: z.ZodObject<{
 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>;
+declare function translateCaptions<P extends SupportedProvider = SupportedProvider>(assetId: string, trackId: string, toLanguageCode: string, options: TranslationOptions<P>): Promise<TranslationResult>;
 
 type index_AskQuestionsOptions = AskQuestionsOptions;
 type index_AskQuestionsResult = AskQuestionsResult;

package/dist/index.d.ts

@@ -2,14 +2,51 @@ import { W as WorkflowCredentials, S as StoragePutObjectInput, a as StoragePresi
 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 './shots-BFYOfBgN.js';
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
 export { i as primitives } from './index-CuBu_u5-.js';
-export { i as workflows } from './index-BeX_4DL7.js';
+export { i as workflows } from './index-yn3fUDgv.js';
 import '@mux/mux-node';
 import 'zod';
 import '@ai-sdk/anthropic';
 import '@ai-sdk/google';
 import '@ai-sdk/openai';
 
-var version = "0.13.1";
+var version = "0.15.1";
+
+type MuxAiErrorType = "validation_error" | "processing_error" | "timeout_error";
+/**
+ * An error whose message is safe to surface verbatim to the customer.
+ *
+ * Uses a structural brand (`__robots_error = true`) so that downstream
+ * consumers can identify customer-safe errors via duck typing — no
+ * shared dependency required. Errors from @mux/ai that DON'T carry
+ * this brand (unexpected SDK failures, upstream provider errors, etc.)
+ * should be treated as internal and obfuscated.
+ *
+ * Own properties (`publicMessage`, `publicType`, `retryable`) survive
+ * JSON serialization across workflow step boundaries, unlike inherited
+ * `Error.message`.
+ */
+declare class MuxAiError extends Error {
+    /** Structural brand for duck-type identification. */
+    readonly __robots_error = true;
+    /** Error category shown in the API response. */
+    readonly publicType: MuxAiErrorType;
+    /** Customer-facing message. Must be safe to show verbatim. */
+    readonly publicMessage: string;
+    /** Whether the customer should retry the job. */
+    readonly retryable: boolean;
+    constructor(message: string, opts?: {
+        type?: MuxAiErrorType;
+        retryable?: boolean;
+    });
+}
+/**
+ * Re-throws {@link MuxAiError} instances to preserve the structural brand,
+ * wraps everything else in a plain `Error` with a contextual message.
+ *
+ * Use this in catch blocks that re-throw so a customer-safe error from a
+ * callee isn't accidentally converted into an internal error.
+ */
+declare function wrapError(error: unknown, message: string): never;
 
 /**
  * A function that returns workflow credentials, either synchronously or asynchronously.
@@ -45,4 +82,4 @@ declare class WorkflowStorageClient {
 }
 declare function createWorkflowStorageClient(options?: WorkflowStorageClientOptions): WorkflowStorageClient;
 
-export { StoragePresignGetObjectInput, StoragePutObjectInput, WorkflowCredentials, type WorkflowCredentialsProvider, WorkflowStorageClient, createWorkflowStorageClient, setWorkflowCredentialsProvider, version };
+export { MuxAiError, type MuxAiErrorType, StoragePresignGetObjectInput, StoragePutObjectInput, WorkflowCredentials, type WorkflowCredentialsProvider, WorkflowStorageClient, createWorkflowStorageClient, setWorkflowCredentialsProvider, version, wrapError };