@mux/ai 0.2.0 → 0.3.0

package/README.md

@@ -3,13 +3,16 @@
 [![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 SDK for building AI-driven video workflows on the server, powered by [Mux](https://www.mux.com)!**
+> **A TypeScript toolkit for building AI-driven video workflows on the server, powered by [Mux](https://www.mux.com)!**
 
 `@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:** [`generateChapters`](#chapter-generation), [`getModerationScores`](#content-moderation), [`generateVideoEmbeddings`](#video-search-with-embeddings), [`getSummaryAndTags`](#video-summarization)
-- 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`
+
+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), [`generateVideoEmbeddings`](#video-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
 
@@ -72,16 +75,6 @@ S3_ACCESS_KEY_ID=your-access-key
 S3_SECRET_ACCESS_KEY=your-secret-key
 ```
 
-Or pass credentials directly to each function:
-
-```typescript
-const result = await getSummaryAndTags(assetId, {
-  muxTokenId: "your-token-id",
-  muxTokenSecret: "your-token-secret",
-  openaiApiKey: "your-openai-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
@@ -98,6 +91,58 @@ const result = await getSummaryAndTags(assetId, {
 | [`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-2.5-flash` (Google) | Video (required), Captions (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 (required), Audio (required) | AWS S3 (if `uploadToMux=true`) |
 
+## Compatability with Workflow DevKit
+
+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.
+
+If you are using Workflow DevKit in your project, then you must call workflow functions like this:
+
+```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
+```
+
+### 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
@@ -190,7 +235,7 @@ for (const chunk of result.chunks) {
 
 - **Cost-Effective by Default**: Uses affordable frontier models like `gpt-5.1`, `claude-sonnet-4-5`, and `gemini-2.5-flash` 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 normal, sassy, or professional analysis styles for summarization
+- **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

package/dist/{index-DyTSka2R.d.ts → index-BcNDGOI6.d.ts}

@@ -1,28 +1,16 @@
-import { A as AssetTextTrack, b as MuxAsset, e as TextChunk, C as ChunkingStrategy } from './types-ktXDZ93V.js';
-
-/**
- * Context required to sign URLs for signed playback IDs.
- */
-interface SigningContext {
-    /** The signing key ID from Mux dashboard. */
-    keyId: string;
-    /** The base64-encoded private key from Mux dashboard. */
-    keySecret: string;
-    /** Token expiration time (e.g. '1h', '1d'). Defaults to '1h'. */
-    expiration?: string;
-}
+import { A as AssetTextTrack, a as MuxAsset, d as TextChunk, C as ChunkingStrategy } from './types-DzOQNn9R.js';
 
 declare const DEFAULT_STORYBOARD_WIDTH = 640;
 /**
  * Generates a storyboard URL for the given playback ID.
- * If a signing context is provided, the URL will be signed with a token.
+ * If shouldSign is true, the URL will be signed with a token using credentials from environment variables.
  *
  * @param playbackId - The Mux playback ID
  * @param width - Width of the storyboard in pixels (default: 640)
- * @param signingContext - Optional signing context for signed playback IDs
- * @returns Storyboard URL (signed if context provided)
+ * @param shouldSign - Flag for whether or not to use signed playback IDs (default: false)
+ * @returns Storyboard URL (signed if shouldSign is true)
  */
-declare function getStoryboardUrl(playbackId: string, width?: number, signingContext?: SigningContext): Promise<string>;
+declare function getStoryboardUrl(playbackId: string, width?: number, shouldSign?: boolean): Promise<string>;
 
 /** A single cue from a VTT file with timing info. */
 interface VTTCue {
@@ -34,7 +22,7 @@ interface TranscriptFetchOptions {
     languageCode?: string;
     cleanTranscript?: boolean;
     /** Optional signing context for signed playback IDs */
-    signingContext?: SigningContext;
+    shouldSign?: boolean;
 }
 interface TranscriptResult {
     transcriptText: string;
@@ -59,10 +47,10 @@ declare function parseVTTCues(vttContent: string): VTTCue[];
  *
  * @param playbackId - The Mux playback ID
  * @param trackId - The text track ID
- * @param signingContext - Optional signing context for signed playback IDs
+ * @param shouldSign - Flag for whether or not to use signed playback IDs
  * @returns Transcript URL (signed if context provided)
  */
-declare function buildTranscriptUrl(playbackId: string, trackId: string, signingContext?: SigningContext): Promise<string>;
+declare function buildTranscriptUrl(playbackId: string, trackId: string, shouldSign?: boolean): Promise<string>;
 declare function fetchTranscriptForAsset(asset: MuxAsset, playbackId: string, options?: TranscriptFetchOptions): Promise<TranscriptResult>;
 
 /**
@@ -104,17 +92,17 @@ interface ThumbnailOptions {
     interval?: number;
     /** Width of the thumbnail in pixels (default: 640) */
     width?: number;
-    /** Optional signing context for signed playback IDs */
-    signingContext?: SigningContext;
+    /** Flag for whether or not to use signed playback IDs (default: false) */
+    shouldSign?: boolean;
 }
 /**
  * Generates thumbnail URLs at regular intervals based on video duration.
- * If a signing context is provided, the URLs will be signed with tokens.
+ * If shouldSign is true, the URLs will be signed with tokens using credentials from environment variables.
  *
  * @param playbackId - The Mux playback ID
  * @param duration - Video duration in seconds
  * @param options - Thumbnail generation options
- * @returns Array of thumbnail URLs (signed if context provided)
+ * @returns Array of thumbnail URLs (signed if shouldSign is true)
  */
 declare function getThumbnailUrls(playbackId: string, duration: number, options?: ThumbnailOptions): Promise<string[]>;
 

package/dist/{index-CMZYZcj6.d.ts → index-D3fZHu0h.d.ts}

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { createAnthropic } from '@ai-sdk/anthropic';
 import { createGoogleGenerativeAI } from '@ai-sdk/google';
 import { createOpenAI } from '@ai-sdk/openai';
-import { h as TokenUsage, a as MuxAIOptions, I as ImageSubmissionMode, C as ChunkingStrategy, g as VideoEmbeddingsResult, T as ToneType } from './types-ktXDZ93V.js';
+import { g as TokenUsage, M as MuxAIOptions, I as ImageSubmissionMode, C as ChunkingStrategy, f as VideoEmbeddingsResult, T as ToneType } from './types-DzOQNn9R.js';
 import { Buffer } from 'node:buffer';
 
 interface ImageDownloadOptions {
@@ -339,7 +339,7 @@ interface SummarizationOptions extends MuxAIOptions {
     provider?: SupportedProvider;
     /** Provider-specific chat model identifier. */
     model?: ModelIdByProvider[SupportedProvider];
-    /** Prompt tone shim applied to the system instruction (defaults to 'normal'). */
+    /** 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). */
     includeTranscript?: boolean;
@@ -478,10 +478,6 @@ interface AudioTranslationOptions extends MuxAIOptions {
     s3Region?: string;
     /** Bucket that will store dubbed audio files. */
     s3Bucket?: string;
-    /** Access key ID used for uploads. */
-    s3AccessKeyId?: string;
-    /** Secret access key used for uploads. */
-    s3SecretAccessKey?: string;
     /**
      * When true (default) the dubbed audio file is uploaded to the configured
      * bucket and attached to the Mux asset.
@@ -528,10 +524,6 @@ interface TranslationOptions<P extends SupportedProvider = SupportedProvider> ex
     s3Region?: string;
     /** Bucket that will store translated VTT files. */
     s3Bucket?: string;
-    /** Access key ID used for uploads. */
-    s3AccessKeyId?: string;
-    /** Secret access key used for uploads. */
-    s3SecretAccessKey?: string;
     /**
      * When true (default) the translated VTT is uploaded to the configured
      * bucket and attached to the Mux asset.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { i as primitives } from './index-DyTSka2R.js';
-export { A as AssetTextTrack, f as ChunkEmbedding, C as ChunkingStrategy, I as ImageSubmissionMode, M as MuxAIConfig, a as MuxAIOptions, b as MuxAsset, c as PlaybackAsset, P as PlaybackPolicy, e as TextChunk, d as TokenChunkingConfig, h as TokenUsage, T as ToneType, V as VTTChunkingConfig, g as VideoEmbeddingsResult } from './types-ktXDZ93V.js';
-export { i as workflows } from './index-CMZYZcj6.js';
+export { i as primitives } from './index-BcNDGOI6.js';
+export { A as AssetTextTrack, e as ChunkEmbedding, C as ChunkingStrategy, I as ImageSubmissionMode, M as MuxAIOptions, a as MuxAsset, b as PlaybackAsset, P as PlaybackPolicy, d as TextChunk, c as TokenChunkingConfig, g as TokenUsage, T as ToneType, V as VTTChunkingConfig, f as VideoEmbeddingsResult } from './types-DzOQNn9R.js';
+export { i as workflows } from './index-D3fZHu0h.js';
 import '@mux/mux-node';
 import 'zod';
 import '@ai-sdk/anthropic';