@mux/ai 0.7.3 → 0.7.4

package/README.md

@@ -1,210 +1,40 @@
-# `@mux/ai` 📼 🤝 🤖
+# `@mux/ai`
 
 [![npm version](https://badge.fury.io/js/@mux%2Fai.svg)](https://www.npmjs.com/package/@mux/ai)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-> **A TypeScript toolkit for building AI-driven video workflows on the server, powered by [Mux](https://www.mux.com)!**
+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).
 
-`@mux/ai` does this by providing:
-
-Easy to use, purpose-driven, cost effective, configurable **_workflow functions_** that integrate with a variety of 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)
 - Workflows automatically ship with `"use workflow"` [compatability with Workflow DevKit](#compatability-with-workflow-devkit)
 
-Convenient, parameterized, commonly needed **_primitive functions_** backed by [Mux Video](https://www.mux.com/video-api) for building your own media-based AI workflows and integrations.
-- **Examples:** `getStoryboardUrl`, `chunkVTTCues`, `fetchTranscriptForAsset`
-
-# Usage
-
-```ts
-import { getSummaryAndTags } from "@mux/ai/workflows";
-
-const result = await getSummaryAndTags("your-asset-id", {
-  provider: "openai",
-  tone: "professional",
-  includeTranscript: true
-});
-
-console.log(result.title);        // "Getting Started with TypeScript"
-console.log(result.description);  // "A comprehensive guide to..."
-console.log(result.tags);         // ["typescript", "tutorial", "programming"]
-```
-
-> **⚠️ Important:** Many workflows rely on video transcripts for best results. Consider enabling [auto-generated captions](https://www.mux.com/docs/guides/add-autogenerated-captions-and-use-transcripts) on your Mux assets to unlock the full potential of transcript-based workflows like summarization, chapters, and embeddings.
-
-# Quick Start
-
-## Prerequisites
+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.
 
-- [Node.js](https://nodejs.org/en/download) (≥ 21.0.0)
-- A Mux account and necessary [credentials](#credentials---mux) for your environment (sign up [here](https://dashboard.mux.com/signup) for free!)
-- Accounts and [credentials](#credentials---ai-providers) for any AI providers you intend to use for your workflows
-- (For some workflows only) AWS S3 and [other credentials](#credentials---other)
+## Quick Start
 
-
-## Installation
+### Install
 
 ```bash
 npm install @mux/ai
 ```
 
-## Configuration
+### Configure
 
-We support [dotenv](https://www.npmjs.com/package/dotenv), so you can simply add the following environment variables to your `.env` file:
+Add your credentials to a `.env` file (we support [dotenv](https://www.npmjs.com/package/dotenv)):
 
 ```bash
-# Required
 MUX_TOKEN_ID=your_mux_token_id
 MUX_TOKEN_SECRET=your_mux_token_secret
-
-# Needed if your assets _only_ have signed playback IDs
-MUX_SIGNING_KEY=your_signing_key_id
-MUX_PRIVATE_KEY=your_base64_encoded_private_key
-
-# You only need to configure API keys for the AI platforms and workflows you're using
-OPENAI_API_KEY=your_openai_api_key
-ANTHROPIC_API_KEY=your_anthropic_api_key
-GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key
-ELEVENLABS_API_KEY=your_elevenlabs_api_key
-
-# S3-Compatible Storage (required for translation & audio dubbing)
-S3_ENDPOINT=https://your-s3-endpoint.com
-S3_REGION=auto
-S3_BUCKET=your-bucket-name
-S3_ACCESS_KEY_ID=your-access-key
-S3_SECRET_ACCESS_KEY=your-secret-key
+OPENAI_API_KEY=your_openai_api_key          # or ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY
 ```
 
-> **💡 Tip:** If you're using `.env` in a repository or version tracking system, make sure you add this file to your `.gitignore` or equivalent to avoid unintentionally committing secure credentials.
-
-# Workflows
-
-## Available pre-built workflows
-
-| Workflow                                                                 | Description                                                       | Providers                 | Default Models                                                     | Mux Asset Requirements | Cloud Infrastructure Requirements |
-| ------------------------------------------------------------------------ | ----------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------ | ---------------------- | --------------------------------- |
-| [`getSummaryAndTags`](./docs/WORKFLOWS.md#video-summarization)<br/>[API](./docs/API.md#getsummaryandtagsassetid-options) · [Source](./src/workflows/summarization.ts) | Generate titles, descriptions, and tags for an asset              | OpenAI, Anthropic, Google | `gpt-5.1` (OpenAI), `claude-sonnet-4-5` (Anthropic), `gemini-3-flash-preview` (Google) | Video (required), Captions (optional) | None |
-| [`getModerationScores`](./docs/WORKFLOWS.md#content-moderation)<br/>[API](./docs/API.md#getmoderationscoresassetid-options) · [Source](./src/workflows/moderation.ts) | Detect inappropriate (sexual or violent) content in an asset      | OpenAI, Hive              | `omni-moderation-latest` (OpenAI) or Hive visual moderation task   | Video (required) | None |
-| [`hasBurnedInCaptions`](./docs/WORKFLOWS.md#burned-in-caption-detection)<br/>[API](./docs/API.md#hasburnedincaptionsassetid-options) · [Source](./src/workflows/burned-in-captions.ts) | Detect burned-in captions (hardcoded subtitles) in an asset       | OpenAI, Anthropic, Google | `gpt-5.1` (OpenAI), `claude-sonnet-4-5` (Anthropic), `gemini-3-flash-preview` (Google) | Video (required) | None |
-| [`askQuestions`](./docs/WORKFLOWS.md#ask-questions)<br/>[API](./docs/API.md#askquestionsassetid-questions-options) · [Source](./src/workflows/ask-questions.ts) | Answer yes/no questions about an asset's content                  | OpenAI, Anthropic, Google | `gpt-5.1` (OpenAI), `claude-sonnet-4-5` (Anthropic), `gemini-3-flash-preview` (Google) | Video (required), Captions (optional) | None |
-| [`generateChapters`](./docs/WORKFLOWS.md#chapter-generation)<br/>[API](./docs/API.md#generatechaptersassetid-languagecode-options) · [Source](./src/workflows/chapters.ts) | Generate chapter markers for an asset using the transcript        | OpenAI, Anthropic, Google | `gpt-5.1` (OpenAI), `claude-sonnet-4-5` (Anthropic), `gemini-3-flash-preview` (Google) | Video or audio-only, Captions/Transcripts (required) | None |
-| [`generateEmbeddings`](./docs/WORKFLOWS.md#embeddings)<br/>[API](./docs/API.md#generateembeddingsassetid-options) · [Source](./src/workflows/embeddings.ts) | Generate vector embeddings for an asset's transcript chunks       | OpenAI, Google            | `text-embedding-3-small` (OpenAI), `gemini-embedding-001` (Google) | Video or audio-only, Captions/Transcripts (required) | None |
-| [`translateCaptions`](./docs/WORKFLOWS.md#caption-translation)<br/>[API](./docs/API.md#translatecaptionsassetid-fromlanguagecode-tolanguagecode-options) · [Source](./src/workflows/translate-captions.ts) | Translate an asset's captions into different languages            | OpenAI, Anthropic, Google | `gpt-5.1` (OpenAI), `claude-sonnet-4-5` (Anthropic), `gemini-3-flash-preview` (Google) | Video or audio-only, Captions/Transcripts (required) | AWS S3 (if `uploadToMux=true`) |
-| [`translateAudio`](./docs/WORKFLOWS.md#audio-dubbing)<br/>[API](./docs/API.md#translateaudioassetid-tolanguagecode-options) · [Source](./src/workflows/translate-audio.ts) | Create AI-dubbed audio tracks in different languages for an asset | ElevenLabs only           | ElevenLabs Dubbing API                                             | Video or audio-only, Audio (required) | AWS S3 (if `uploadToMux=true`) |
+You only need credentials for the AI provider you're using. See the [Credentials guide](./docs/CREDENTIALS.md) for full setup details including signed playback, S3 storage, and all supported providers.
 
-## Compatability with Workflow DevKit
+For multi-tenant apps or cases where you need to provide API keys at runtime rather than through environment variables, every workflow accepts a `credentials` option. You can also register a global credentials provider with `setWorkflowCredentialsProvider()` for dynamic key resolution (e.g. per-tenant secrets). When using [Workflow DevKit](https://useworkflow.dev), credentials can be [encrypted](./docs/WORKFLOW-ENCRYPTION.md) before crossing workflow boundaries so plaintext secrets never appear in serialized payloads.
 
-All workflows are compatible with [Workflow DevKit](https://useworkflow.dev). The workflows in this SDK are exported with `"use workflow"` directives and `"use step"` directives in the code.
-
-Workflow DevKit serializes workflow inputs/outputs for observability. To avoid sending plaintext secrets through `start(...)`, encrypt credentials in the trigger host and decrypt them in workflow steps.
-See the dedicated [Workflow Encryption guide](./docs/WORKFLOW-ENCRYPTION.md) for full setup and patterns.
-
-If you are using Workflow DevKit in your project, then you must call workflow functions like this:
+### Run Your First Workflow
 
 ```ts
-import { start } from 'workflow/api';
-import { getSummaryAndTags } from '@mux/ai/workflows';
-
-const assetId = 'YOUR_ASSET_ID';
-const run = await start(getSummaryAndTags, [assetId]);
-
-// optionally, wait for the workflow run return value:
-// const result = await run.returnValue
-```
-
-### Multi-tenant credentials with Workflow Dev Kit
-
-Set a shared workflow secret key (base64-encoded 32-byte value) in your environment:
-
-```bash
-MUX_AI_WORKFLOW_SECRET_KEY=your_base64_32_byte_key
-```
-
-Then encrypt credentials before calling `start()`:
-
-```ts
-import { start } from "workflow/api";
-import { encryptForWorkflow } from "@mux/ai";
-import { getSummaryAndTags } from "@mux/ai/workflows";
-
-const workflowKey = process.env.MUX_AI_WORKFLOW_SECRET_KEY!;
-const encryptedCredentials = await encryptForWorkflow(
-  {
-    muxTokenId: "mux-token-id",
-    muxTokenSecret: "mux-token-secret",
-    openaiApiKey: "openai-api-key",
-  },
-  workflowKey,
-);
-
-const run = await start(getSummaryAndTags, [
-  "your-asset-id",
-  {
-    provider: "openai",
-    credentials: encryptedCredentials,
-  },
-]);
-```
-
-For Mux tokens specifically, `setWorkflowCredentialsProvider(...)` (or environment variables) is still recommended so raw Mux secrets are never embedded in workflow input payloads.
-
-You can also register a credential provider on the execution host to resolve secrets inside steps.
-This is useful for dynamic key resolution, e.g. rotating keys or per-tenant secrets:
-
-```ts
-import {
-  setWorkflowCredentialsProvider,
-} from "@mux/ai";
-
-setWorkflowCredentialsProvider(async () => ({
-  muxTokenId: "mux-token-id",
-  muxTokenSecret: "mux-token-secret",
-  openaiApiKey: await getOpenAIKeyForTenant(),
-}));
-```
-
-### Features of Workflow DevKit
-
-- [Observability Dashboard](https://useworkflow.dev/docs/observability)
-- [Control Flow Patterns](https://useworkflow.dev/docs/foundations/control-flow-patterns) like Parallel Execution.
-- [Errors and Retrying](https://useworkflow.dev/docs/foundations/errors-and-retries)
-- [Hooks and Webhooks](https://useworkflow.dev/docs/foundations/hooks)
-- Patterns for building Agents with [Human in the Loop](https://useworkflow.dev/docs/ai/human-in-the-loop)
-
-**Workflows can be nested**
-
-```ts
-import { start } from "workflow/api";
-import { getSummaryAndTags } from '@mux/ai/workflows';
-
-async function processVideoSummary (assetId: string) {
-  'use workflow'
-
-  const summary = await getSummaryAndTags(assetId);
-  const emailResp = await emailSummaryToAdmins(summary: summary);
-
-  return { assetId, summary, emailResp }
-}
-
-async function emailSummaryToAdmins (assetId: string) {
-  'use step';
-  return { sent: true }
-}
-
-//
-// this will call the processVideoSummary workflow that is defined above
-// in that workflow, it calls `getSummaryAndTags()` workflow
-//
-const run = await start(processVideoSummary, [assetId]);
-```
-
-## Example Workflows
-
-### Video Summarization
-
-Generate SEO-friendly titles, descriptions, and tags from your video content:
-
-```typescript
 import { getSummaryAndTags } from "@mux/ai/workflows";
 
 const result = await getSummaryAndTags("your-asset-id", {
@@ -218,11 +48,42 @@ console.log(result.description);  // "A comprehensive guide to..."
 console.log(result.tags);         // ["typescript", "tutorial", "programming"]
 ```
 
-### Content Moderation
+> **⚠️ Note:** Many workflows rely on transcripts for best results. Consider enabling [auto-generated captions](https://www.mux.com/docs/guides/add-autogenerated-captions-and-use-transcripts) on your Mux assets to unlock the full potential of transcript-based workflows like summarization, chapters, and embeddings. This applies to both video and audio-only assets.
+
+## Why `@mux/ai`?
 
-Automatically detect inappropriate content in videos (or audio-only assets with transcripts):
+- **Pre-built workflows for media AI tasks.** Common multi-step operations (transcript access, frame analysis, LLM calls, and structured parsing) are available as high-level functions.
+- **Support for video and audio assets.** The same workflows work with video and [audio-only assets](./docs/AUDIO-ONLY.md), including summarization, moderation, chaptering, and more.
+- **Provider-flexible API.** Choose OpenAI, Anthropic, or Google through workflow options while keeping the same workflow interface.
+- **Published evaluation coverage.** Workflows include [evals](./docs/EVALS.md) for quality, latency, and cost, with results [published publicly](https://evaluating-mux-ai.vercel.app/) on pushes to `main`.
+- **Sensible default models.** Defaults (`gpt-5.1`, `claude-sonnet-4-5`, `gemini-3-flash-preview`) are selected to balance output quality and runtime cost.
+- **Typed end-to-end.** Workflow inputs, options, and outputs are fully typed in TypeScript.
+- **Operational defaults included.** Retry handling, error handling, signed playback support, and [Workflow DevKit](https://useworkflow.dev) compatibility are built in.
+- **Prompt customization support.** Use `promptOverrides` to adjust sections of workflow prompts for your domain or product requirements.
+- **Composable abstractions.** Start with full workflows and drop down to lower-level primitives when you need more control.
+
+## Workflows
 
-```typescript
+Workflows are high-level functions that handle complete media AI tasks end-to-end — fetching data from Mux, calling AI providers, and returning structured results. Most workflows support both video and audio-only assets.
+
+| Workflow | What it does | Providers | Audio-only |
+| --- | --- | --- | :---: |
+| [`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 | — |
+| [`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 |
+| [`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.
+
+### Quick Examples
+
+**Content moderation:**
+
+```ts
 import { getModerationScores } from "@mux/ai/workflows";
 
 const result = await getModerationScores("your-asset-id", {
@@ -232,268 +93,130 @@ const result = await getModerationScores("your-asset-id", {
 
 if (result.exceedsThreshold) {
   console.log("Content flagged for review");
-  console.log(`Max scores: ${result.maxScores}`);
 }
 ```
 
-### Chapter Generation
-
-Create automatic chapter markers for better video navigation:
+**Chapter generation:**
 
-```typescript
+```ts
 import { generateChapters } from "@mux/ai/workflows";
 
 const result = await generateChapters("your-asset-id", "en", {
   provider: "anthropic"
 });
 
-// Use with Mux Player
-player.addChapters(result.chapters);
-// [
-//   { startTime: 0, title: "Introduction" },
-//   { startTime: 45, title: "Main Content" },
-//   { startTime: 120, title: "Conclusion" }
-// ]
+// [{ startTime: 0, title: "Introduction" }, { startTime: 45, title: "Main Content" }, ...]
 ```
 
-### Search with Embeddings
-
-Generate embeddings for semantic search over transcripts:
+**Semantic search embeddings:**
 
-```typescript
+```ts
 import { generateEmbeddings } from "@mux/ai/workflows";
 
 const result = await generateEmbeddings("your-asset-id", {
   provider: "openai",
-  languageCode: "en",
-  chunkingStrategy: {
-    type: "token",
-    maxTokens: 500,
-    overlap: 100
-  }
+  chunkingStrategy: { type: "token", maxTokens: 500, overlap: 100 }
 });
 
-// Store embeddings in your vector database
 for (const chunk of result.chunks) {
-  await vectorDB.insert({
-    embedding: chunk.embedding,
-    metadata: {
-      assetId: result.assetId,
-      startTime: chunk.metadata.startTime,
-      endTime: chunk.metadata.endTime
-    }
-  });
+  await vectorDB.insert({ embedding: chunk.embedding, startTime: chunk.metadata.startTime });
 }
 ```
 
-# Key Features
-
-- **Cost-Effective by Default**: Uses affordable frontier models like `gpt-5.1`, `claude-sonnet-4-5`, and `gemini-3-flash-preview` to keep analysis costs low while maintaining high quality results
-- **Multi-modal Analysis**: Combines storyboard images with video transcripts for richer understanding
-- **Tone Control**: Choose between neutral, playful, or professional analysis styles for summarization
-- **Prompt Customization**: Override specific prompt sections to tune workflows to your exact use case
-- **Configurable Thresholds**: Set custom sensitivity levels for content moderation
-- **Full TypeScript Support**: Comprehensive types for excellent developer experience and IDE autocomplete
-- **Provider Flexibility**: Switch between OpenAI, Anthropic, Google, and other providers based on your needs
-- **Composable Building Blocks**: Use primitives to fetch transcripts, thumbnails, and storyboards for custom workflows
-- **Universal Language Support**: Automatic language name detection using `Intl.DisplayNames` for all ISO 639-1 codes
-- **Production Ready**: Built-in retry logic, error handling, and edge case management
-
-# Core Concepts
-
-`@mux/ai` is built around two complementary abstractions:
-
-## Workflows
-
-**Workflows** are functions that handle complete video AI tasks end-to-end. Each workflow orchestrates the entire process: fetching video data from Mux (transcripts, thumbnails, storyboards), formatting it for AI providers, and returning structured results.
-
-```typescript
-import { getSummaryAndTags } from "@mux/ai/workflows";
-
-const result = await getSummaryAndTags("asset-id", { provider: "openai" });
-```
-
-Use workflows when you need battle-tested solutions for common tasks like summarization, content moderation, chapter generation, or translation.
-
-## Primitives
-
-**Primitives** are low-level building blocks that give you direct access to Mux video data and utilities. They provide functions for fetching transcripts, storyboards, thumbnails, and processing text—perfect for building custom workflows.
-
-```typescript
-import { fetchTranscriptForAsset, getStoryboardUrl } from "@mux/ai/primitives";
-
-const transcript = await fetchTranscriptForAsset("asset-id", "en");
-const storyboard = getStoryboardUrl("playback-id", { width: 640 });
-```
-
-Use primitives when you need complete control over your AI prompts or want to build custom workflows not covered by the pre-built options.
-
-## Package Structure
-
-```typescript
-// Import workflows
-import { generateChapters } from "@mux/ai/workflows";
-
-// Import primitives
-import { fetchTranscriptForAsset } from "@mux/ai/primitives";
-
-// Or import everything
-import { workflows, primitives } from "@mux/ai";
-```
-
-# Credentials
-
-You'll need to set up credentials for Mux as well as any AI provider you want to use for a particular workflow. In addition, some workflows will need other cloud-hosted access (e.g. cloud storage via AWS S3).
-
-## Credentials - Mux
-
-### Access Token (required)
-
-All workflows require a Mux API access token to interact with your video assets. If you're already logged into the dashboard, you can [create a new access token here](https://dashboard.mux.com/settings/access-tokens).
-
-**Required Permissions:**
-- **Mux Video**: Read + Write access
-- **Mux Data**: Read access
-
-These permissions cover all current workflows. You can set these when creating your token in the dashboard.
-
-> **💡 Tip:** For security reasons, consider creating a dedicated access token specifically for your AI workflows rather than reusing existing tokens.
-
-### Signing Key (conditionally required)
-
-If your Mux assets use [signed playback URLs](https://docs.mux.com/guides/secure-video-playback) for security, you'll need to provide signing credentials so `@mux/ai` can access the video data.
-
-**When needed:** Only if your assets have signed playback policies enabled and no public playback ID.
-
-**How to get:**
-1. Go to [Settings > Signing Keys](https://dashboard.mux.com/settings/signing-keys) in your Mux dashboard
-2. Create a new signing key or use an existing one
-3. Save both the **Signing Key ID** and the **Base64-encoded Private Key**
-
-**Configuration:**
-```bash
-MUX_SIGNING_KEY=your_signing_key_id
-MUX_PRIVATE_KEY=your_base64_encoded_private_key
-```
-
-## Credentials - AI Providers
-
-Different workflows support various AI providers. You only need to configure API keys for the providers you plan to use.
-
-### OpenAI
+## Prompt Customization
 
-**Used by:** `getSummaryAndTags`, `getModerationScores`, `hasBurnedInCaptions`, `generateChapters`, `generateEmbeddings`, `translateCaptions`
+Every workflow prompt is built from a structured template of named sections. The `promptOverrides` option lets you swap out individual sections with your own instructions while keeping the battle-tested defaults for everything else — no need to rewrite entire prompts.
 
-**Get your API key:** [OpenAI API Keys](https://platform.openai.com/api-keys)
-
-```bash
-OPENAI_API_KEY=your_openai_api_key
+```ts
+const result = await getSummaryAndTags(assetId, {
+  provider: "openai",
+  promptOverrides: {
+    title: "Create a search-optimized title (50-60 chars) with the primary keyword front-loaded.",
+    keywords: "Focus on high search volume terms and long-tail keyword phrases.",
+    // task, description, qualityGuidelines → keep defaults
+  },
+});
 ```
 
-### Anthropic
+This works with `getSummaryAndTags`, `generateChapters`, and `hasBurnedInCaptions`. The [Prompt Customization guide](./docs/PROMPT-CUSTOMIZATION.md) has ready-to-use presets for SEO, social media, e-commerce, and technical analysis, along with tips for writing effective overrides.
 
-**Used by:** `getSummaryAndTags`, `hasBurnedInCaptions`, `generateChapters`, `translateCaptions`
+## Evaluations
 
-**Get your API key:** [Anthropic Console](https://console.anthropic.com/)
+Choosing between OpenAI, Anthropic, and Google for a given workflow isn't guesswork. Every workflow in `@mux/ai` ships with eval coverage that benchmarks providers and models against three dimensions:
 
-```bash
-ANTHROPIC_API_KEY=your_anthropic_api_key
-```
-
-### Google Generative AI
+- **Efficacy** — Does it produce accurate, high-quality results?
+- **Efficiency** — How fast is it and how many tokens does it consume?
+- **Expense** — What does each request cost?
 
-**Used by:** `getSummaryAndTags`, `hasBurnedInCaptions`, `generateChapters`, `generateEmbeddings`, `translateCaptions`
+Evals run automatically on every push to `main` and results are published to a **[public dashboard](https://evaluating-mux-ai.vercel.app/)** so you can compare providers side-by-side before choosing one for your use case.
 
-**Get your API key:** [Google AI Studio](https://aistudio.google.com/app/apikey)
+You can also run evals locally against your own assets:
 
 ```bash
-GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key
+npm run test:eval
 ```
 
-### ElevenLabs
-
-**Used by:** `translateAudio` (audio dubbing)
-
-**Get your API key:** [ElevenLabs API Keys](https://elevenlabs.io/app/settings/api-keys)
+See the [Evaluations guide](./docs/EVALS.md) for details on the 3 E's framework, adding your own evals, and cross-provider testing.
 
-**Note:** Requires a Creator plan or higher for dubbing features.
-
-```bash
-ELEVENLABS_API_KEY=your_elevenlabs_api_key
-```
-
-### Hive
+## Primitives
 
-**Used by:** `getModerationScores` (alternative to OpenAI moderation)
+Primitives are low-level building blocks that give you direct access to Mux media data — transcripts, storyboards, thumbnails, and text chunking utilities. Use them when you need full control over your AI prompts or want to build custom workflows.
 
-**Get your API key:** [Hive Console](https://thehive.ai/)
+```ts
+import { fetchTranscriptForAsset, getStoryboardUrl } from "@mux/ai/primitives";
 
-```bash
-HIVE_API_KEY=your_hive_api_key
+const transcript = await fetchTranscriptForAsset(asset, playbackId, { languageCode: "en" });
+const storyboard = getStoryboardUrl(playbackId, 640);
 ```
 
-## Credentials - Cloud Infrastructure
+All pre-built workflows are composed from these primitives internally, so you can always drop down a level when you need to customize behavior.
 
-### AWS S3 (or S3-compatible storage)
+See the [Primitives guide](./docs/PRIMITIVES.md) for the full list of available functions and examples of building custom workflows.
 
-**Required for:** `translateCaptions`, `translateAudio` (only if `uploadToMux` is true, which is the default)
-
-Translation workflows need temporary storage to upload translated files before attaching them to your Mux assets. Any S3-compatible storage service works (AWS S3, Cloudflare R2, DigitalOcean Spaces, etc.).
+## Package Structure
 
-**AWS S3 Setup:**
-1. [Create an S3 bucket](https://s3.console.aws.amazon.com/s3/home)
-2. [Create an IAM user](https://console.aws.amazon.com/iam/) with programmatic access
-3. Attach a policy with `s3:PutObject`, `s3:GetObject`, and `s3:PutObjectAcl` permissions for your bucket
+```ts
+// Import specific workflows
+import { getSummaryAndTags, generateChapters } from "@mux/ai/workflows";
 
-**Configuration:**
-```bash
-S3_ENDPOINT=https://s3.amazonaws.com  # Or your S3-compatible endpoint
-S3_REGION=us-east-1                   # Your bucket region
-S3_BUCKET=your-bucket-name
-S3_ACCESS_KEY_ID=your-access-key
-S3_SECRET_ACCESS_KEY=your-secret-key
-```
+// Import specific primitives
+import { fetchTranscriptForAsset, getStoryboardUrl } from "@mux/ai/primitives";
 
-**Cloudflare R2 Example:**
-```bash
-S3_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
-S3_REGION=auto
-S3_BUCKET=your-bucket-name
-S3_ACCESS_KEY_ID=your-r2-access-key
-S3_SECRET_ACCESS_KEY=your-r2-secret-key
+// Or import everything via namespace
+import { workflows, primitives } from "@mux/ai";
 ```
 
-# Documentation
-
-## Full Documentation
-
-- **[Workflows Guide](./docs/WORKFLOWS.md)** - Detailed guide to each pre-built workflow with examples
-- **[API Reference](./docs/API.md)** - Complete API documentation for all functions, parameters, and return types
-- **[Workflow Encryption](./docs/WORKFLOW-ENCRYPTION.md)** - Encrypting credentials across Workflow DevKit boundaries
-- **[Storage Adapters](./docs/STORAGE-ADAPTERS.md)** - Using custom storage SDKs (AWS, Cloudflare R2, MinIO)
-- **[Primitives Guide](./docs/PRIMITIVES.md)** - Low-level building blocks for custom workflows
-- **[Examples](./docs/EXAMPLES.md)** - Running examples from the repository
+## Prerequisites
 
-## Additional Resources
+- [Node.js](https://nodejs.org/en/download) (>= 21.0.0)
+- A [Mux](https://dashboard.mux.com/signup) account (free to sign up)
+- An API key for at least one supported AI provider
 
-- **[Mux Video API Docs](https://docs.mux.com/guides/video)** - Learn about Mux Video features
-- **[Auto-generated Captions](https://www.mux.com/docs/guides/add-autogenerated-captions-and-use-transcripts)** - Enable transcripts for your assets
-- **[GitHub Repository](https://github.com/muxinc/ai)** - Source code, issues, and contributions
-- **[npm Package](https://www.npmjs.com/package/@mux/ai)** - Package page and version history
+## Documentation
 
-# Contributing
+| Guide | Description |
+| --- | --- |
+| [Workflows](./docs/WORKFLOWS.md) | Detailed guide for each pre-built workflow with examples and options |
+| [API Reference](./docs/API.md) | Complete API docs — all function signatures, parameters, and return types |
+| [Primitives](./docs/PRIMITIVES.md) | Low-level building blocks for custom workflows |
+| [Prompt Customization](./docs/PROMPT-CUSTOMIZATION.md) | Overriding prompt sections with `promptOverrides` for custom use cases |
+| [Credentials](./docs/CREDENTIALS.md) | Setting up Mux, AI provider, and cloud storage credentials |
+| [Workflow DevKit](./docs/WORKFLOW-DEVKIT.md) | Integration with Workflow DevKit for observability and orchestration |
+| [Workflow Encryption](./docs/WORKFLOW-ENCRYPTION.md) | Encrypting credentials across Workflow DevKit boundaries |
+| [Storage Adapters](./docs/STORAGE-ADAPTERS.md) | Using custom storage SDKs (AWS, Cloudflare R2, MinIO) |
+| [Audio-Only Workflows](./docs/AUDIO-ONLY.md) | Working with audio-only assets (no video track) |
+| [Evaluations](./docs/EVALS.md) | AI eval testing with the 3 E's framework — [public dashboard](https://evaluating-mux-ai.vercel.app/) |
+| [Examples](./docs/EXAMPLES.md) | Running the example scripts from the repository |
 
-We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, we'd love your help.
+### Additional Resources
 
-Please see our **[Contributing Guide](./CONTRIBUTING.md)** for details on:
+- [Mux Video API Docs](https://docs.mux.com/guides/video) — Learn about Mux Video features
+- [Auto-generated Captions](https://www.mux.com/docs/guides/add-autogenerated-captions-and-use-transcripts) — Enable transcripts for your assets
+- [npm Package](https://www.npmjs.com/package/@mux/ai) — Package page and version history
 
-- Setting up your development environment
-- Running examples and tests
-- Code style and conventions
-- Submitting pull requests
-- Reporting issues
+## Contributing
 
-> **Note on integration tests:** The integration suite runs against real Mux assets. If you want to run `npm run test:integration` with your own Mux credentials, you’ll also need to set Mux test asset IDs (see `env.test.example`, the “Integration test assets (Mux)” section in `CONTRIBUTING.md`, and `tests/helpers/mux-test-assets.ts` for the expected test asset IDs).
+We welcome contributions! Please see the [Contributing Guide](./CONTRIBUTING.md) for details on setting up your development environment, running tests, and submitting pull requests.
 
 For questions or discussions, feel free to [open an issue](https://github.com/muxinc/ai/issues).
 

package/dist/{index-BMqnP1RV.d.ts → index-Bavk1Y8-.d.ts}

@@ -639,6 +639,12 @@ interface AudioTranslationResult {
 interface AudioTranslationOptions extends MuxAIOptions {
     /** Audio dubbing provider (currently ElevenLabs only). */
     provider?: "elevenlabs";
+    /**
+     * Optional source language code for ElevenLabs `source_lang`.
+     * Accepts ISO 639-1 (e.g. "en") or ISO 639-3 (e.g. "eng").
+     * Defaults to auto-detect when omitted.
+     */
+    fromLanguageCode?: string;
     /** Number of speakers supplied to ElevenLabs (0 = auto-detect, default). */
     numSpeakers?: number;
     /** Optional override for the S3-compatible endpoint used for uploads. */

package/dist/index.d.ts

@@ -2,14 +2,14 @@ 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 './types-BQVi_wnh.js';
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
 export { i as primitives } from './index-DZlygsvb.js';
-export { i as workflows } from './index-BMqnP1RV.js';
+export { i as workflows } from './index-Bavk1Y8-.js';
 import '@mux/mux-node';
 import 'zod';
 import '@ai-sdk/anthropic';
 import '@ai-sdk/google';
 import '@ai-sdk/openai';
 
-var version = "0.7.3";
+var version = "0.7.4";
 
 /**
  * A function that returns workflow credentials, either synchronously or asynchronously.