@mux/ai 0.52.0 → 0.54.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mux/ai",
   "type": "module",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "AI library for Mux",
   "author": "Mux",
   "license": "Apache-2.0",
@@ -113,7 +113,7 @@
     "example:translate-audio": "npx tsx examples/translate-audio/basic-example.ts",
     "evalite:post-results:dev": "npx tsx scripts/export-evalite-results.ts --model-set all && npx tsx scripts/post-evalite-results.ts -d -k",
     "evalite:post-results:production": "npx tsx scripts/export-evalite-results.ts --model-set all && npx tsx scripts/post-evalite-results.ts",
-    "prepare": "husky"
+    "prepare": "husky || true; npm run build"
   },
   "peerDependencies": {
     "workflow": ">=4.2.4"

package/dist/index-nu1UOAMW.d.ts

@@ -1,387 +0,0 @@
-import { l as WorkflowCredentialsInput, n as WorkflowScope, A as AssetTextTrack, M as MuxAsset, T as TextChunk, b as ChunkingStrategy, q as CompletedShotsResult, D as DeletedShotsResult, r as ErroredShotsResult, H as Hotspot, s as HotspotOptions, t as HotspotResponse, u as PendingShotsResult, v as Shot, w as ShotRequestOptions, x as ShotsResult, y as SkippedShotsResult, z as WaitForShotsOptions, B as getHotspotsForAsset, F as getHotspotsForPlaybackId, G as getHotspotsForVideo, J as getShotsForAsset, K as requestShotsForAsset, L as waitForShotsForAsset } from './shots-3wmvZnUV.js';
-
-interface HeatmapOptions {
-    /** Time window for results, e.g., '7:days' (default: '7:days') */
-    timeframe?: string;
-    /** Optional workflow credentials */
-    credentials?: WorkflowCredentialsInput;
-}
-interface HeatmapResponse {
-    assetId?: string;
-    videoId?: string;
-    playbackId?: string;
-    /** Engagement values across the video timeline, one per equal slice (currently 100) */
-    heatmap: number[];
-    timeframe: [number, number];
-}
-/**
- * Fetches engagement heatmap for a Mux asset.
- * Returns an array where each value represents how many times
- * that slice of the video was watched.
- *
- * @param assetId - The Mux asset ID
- * @param options - Heatmap query options
- * @returns Heatmap data with per-bucket engagement values
- */
-declare function getHeatmapForAsset(assetId: string, options?: HeatmapOptions): Promise<HeatmapResponse>;
-/**
- * Fetches engagement heatmap for a Mux video ID.
- * Returns an array where each value represents how many times
- * that slice of the video was watched.
- *
- * @param videoId - The Mux video ID
- * @param options - Heatmap query options
- * @returns Heatmap data with per-bucket engagement values
- */
-declare function getHeatmapForVideo(videoId: string, options?: HeatmapOptions): Promise<HeatmapResponse>;
-/**
- * Fetches engagement heatmap for a Mux playback ID.
- * Returns an array where each value represents how many times
- * that slice of the video was watched.
- *
- * @param playbackId - The Mux playback ID
- * @param options - Heatmap query options
- * @returns Heatmap data with per-bucket engagement values
- */
-declare function getHeatmapForPlaybackId(playbackId: string, options?: HeatmapOptions): Promise<HeatmapResponse>;
-
-declare const DEFAULT_STORYBOARD_WIDTH = 640;
-/**
- * Generates a storyboard URL for the given playback ID.
- * 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 shouldSign - Flag for whether or not to use signed playback IDs (default: false)
- * @param credentials - Optional workflow credentials used for signing
- * @param scope - Optional asset-relative range for storyboard tiles
- * @returns Storyboard URL (signed if shouldSign is true)
- */
-declare function getStoryboardUrl(playbackId: string, width?: number, shouldSign?: boolean, credentials?: WorkflowCredentialsInput, scope?: WorkflowScope): Promise<string>;
-
-/** A single cue from a VTT file with timing info. */
-interface VTTCue {
-    startTime: number;
-    endTime: number;
-    text: string;
-}
-interface TranscriptFetchOptions {
-    languageCode?: string;
-    cleanTranscript?: boolean;
-    /** Optional asset-relative time range used to filter transcript cues. */
-    scope?: WorkflowScope;
-    /** Optional signing context for signed playback IDs */
-    shouldSign?: boolean;
-    credentials?: WorkflowCredentialsInput;
-    /**
-     * When true, throws if no usable transcript can be retrieved (no ready text track,
-     * missing track id, fetch error, or empty transcript).
-     *
-     * Default behavior is non-fatal and returns an empty `transcriptText`.
-     */
-    required?: boolean;
-}
-interface TranscriptResult {
-    transcriptText: string;
-    transcriptUrl?: string;
-    track?: AssetTextTrack;
-}
-declare function getReadyTextTracks(asset: MuxAsset): AssetTextTrack[];
-declare function findCaptionTrack(asset: MuxAsset, languageCode?: string): AssetTextTrack | undefined;
-/**
- * Default minimum auto-detection confidence required to trust a track's language code.
- * Below this threshold, the language is treated as undetermined.
- */
-declare const LOW_CONFIDENCE_THRESHOLD = 0.5;
-/**
- * Extracts a trustworthy language code from a track, returning `undefined`
- * when the language metadata shouldn't be used as an LLM output language.
- *
- * Returns `undefined` when:
- * - The track or its language code is missing
- * - The language code is undetermined (`und`, `mul`, `mis`, `zxx`)
- * - The language was auto-detected with confidence below the threshold
- *
- * Trusts the language code when:
- * - `auto_language_confidence` is absent (manually set or non-auto tracks)
- * - `auto_language_confidence` meets the threshold
- *
- * @param track - The text track to inspect
- * @param confidenceThreshold - Minimum confidence to trust auto-detected language (default: {@link LOW_CONFIDENCE_THRESHOLD})
- */
-declare function getReliableLanguageCode(track: AssetTextTrack | undefined, confidenceThreshold?: number): string | undefined;
-/**
- * Sanitise untrusted text (typically a VTT cue or joined transcript)
- * before it is interpolated into a prompt. Thin wrapper around the
- * shared {@link normalizeUntrustedUnicode} helper, with a null/empty
- * guard for convenience.
- */
-declare function sanitizeUntrustedText(value: string): string;
-/**
- * Upper bound on individual cue text length before we consider the cue
- * adversarial and truncate it.
- *
- * Legitimate captions are short — a long monologue cue rarely exceeds
- * 500 characters, and most captioning standards recommend well under
- * that for readability. We set the cap at 2000 to give comfortable
- * headroom for edge cases (stage directions, speaker identification,
- * multi-line blocks) while making "hide a multi-kilobyte injection
- * payload inside a single cue" mechanically infeasible.
- */
-declare const MAX_CUE_TEXT_CHARS = 2000;
-/**
- * Strip VTT metadata blocks that are never rendered by players but can
- * still carry text through to an LLM when the raw VTT is used in a prompt:
- *
- * - NOTE blocks (VTT comments)
- * - STYLE blocks (CSS for cue styling)
- * - REGION blocks (positioning definitions)
- *
- * Viewers never see the contents of these blocks. That makes them an
- * ideal hiding spot for prompt-injection payloads — an attacker-controlled
- * caption file can carry hundreds of bytes of "NOTE ignore previous
- * instructions…" that will be stripped from any player but will reach the
- * model if the raw VTT is passed through. Removing them before sending
- * the VTT to the model closes that channel without changing what the
- * model sees for legitimate cue content.
- *
- * Cue identifiers, timing lines, and cue payload text are preserved.
- * In particular: a cue whose first payload line happens to start with
- * `NOTE `/`STYLE `/`REGION ` (plausible in legitimate captions — e.g.
- * `"NOTE THAT..."`, `"STYLE GUIDE"`, `"NOTE how the villain plots..."`)
- * is NOT treated as a metadata block. The scanner tracks cue-payload
- * state: metadata headers are only recognised between cues (i.e. when
- * the previous non-blank line was not a timing line).
- *
- * Example input:
- *
- *     WEBVTT
- *
- *     NOTE This is a comment with hidden instructions
- *     that span multiple lines until a blank line appears.
- *
- *     STYLE
- *     ::cue(b) { font-weight: bold; }
- *
- *     00:00:01.000 --> 00:00:04.000
- *     Legitimate caption text
- *
- *     00:00:05.000 --> 00:00:08.000
- *     NOTE THAT the hero wins
- *
- * Returns:
- *
- *     WEBVTT
- *
- *     00:00:01.000 --> 00:00:04.000
- *     Legitimate caption text
- *
- *     00:00:05.000 --> 00:00:08.000
- *     NOTE THAT the hero wins
- */
-declare function stripVttMetadataBlocks(vttContent: string): string;
-declare function extractTextFromVTT(vttContent: string): string;
-declare function vttTimestampToSeconds(timestamp: string): number;
-/**
- * Converts seconds to a human-readable timestamp.
- * Returns M:SS for durations under an hour, H:MM:SS for an hour or more.
- *
- * @param seconds - The number of seconds to convert
- * @returns A formatted timestamp string (e.g., "2:05" or "01:02:05")
- */
-declare function secondsToTimestamp(seconds: number): string;
-declare function extractTimestampedTranscript(vttContent: string): string;
-/**
- * Parses VTT content into structured cues with timing.
- *
- * @param vttContent - Raw VTT file content
- * @returns Array of VTT cues with start/end times and text
- */
-declare function parseVTTCues(vttContent: string): VTTCue[];
-/**
- * Keeps only VTT cues that overlap an asset-relative time range.
- *
- * Cue timestamps remain relative to the original asset; they are not rebased
- * to the start of the scope.
- */
-declare function filterVttByScope(vttContent: string, scope: WorkflowScope | undefined): string;
-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.
- *
- * @param playbackId - The Mux playback ID
- * @param trackId - The text track ID
- * @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, 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.
- * This approximation is generally close enough for chunking purposes (1 token ≈ 0.75 words).
- */
-declare function estimateTokenCount(text: string): number;
-/**
- * Chunks text into overlapping segments based on token count.
- *
- * @param text - The text to chunk
- * @param maxTokens - Maximum tokens per chunk
- * @param overlapTokens - Number of tokens to overlap between chunks
- * @returns Array of text chunks with metadata
- */
-declare function chunkByTokens(text: string, maxTokens: number, overlapTokens?: number): TextChunk[];
-/**
- * Chunks VTT cues into groups that respect natural cue boundaries.
- * Splits at cue boundaries rather than mid-sentence, preserving accurate timestamps.
- *
- * @param cues - Array of VTT cues to chunk
- * @param maxTokens - Maximum tokens per chunk
- * @param overlapCues - Number of cues to overlap between chunks (default: 2)
- * @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.
- *
- * @param text - The text to chunk
- * @param strategy - The chunking strategy to use
- * @returns Array of text chunks
- */
-declare function chunkText(text: string, strategy: ChunkingStrategy): TextChunk[];
-
-interface ThumbnailOptions {
-    /** Interval between thumbnails in seconds (default: 10) */
-    interval?: number;
-    /** Width of the thumbnail in pixels (default: 640) */
-    width?: number;
-    /** Flag for whether or not to use signed playback IDs (default: false) */
-    shouldSign?: boolean;
-    /** Maximum number of thumbnails to generate. When set, samples are evenly distributed with first and last frames pinned. */
-    maxSamples?: number;
-    /** Workflow credentials for signing (optional). */
-    credentials?: WorkflowCredentialsInput;
-    /** Optional asset-relative range from which thumbnails should be sampled. */
-    scope?: WorkflowScope;
-}
-/**
- * Generates thumbnail URLs at regular intervals based on video duration.
- * 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 objects containing the thumbnail URL and its time in seconds
- */
-declare function getThumbnailUrls(playbackId: string, duration: number, options?: ThumbnailOptions): Promise<Array<{
-    url: string;
-    time: number;
-}>>;
-
-declare const index_CompletedShotsResult: typeof CompletedShotsResult;
-declare const index_DEFAULT_STORYBOARD_WIDTH: typeof DEFAULT_STORYBOARD_WIDTH;
-declare const index_DeletedShotsResult: typeof DeletedShotsResult;
-declare const index_ErroredShotsResult: typeof ErroredShotsResult;
-type index_HeatmapOptions = HeatmapOptions;
-type index_HeatmapResponse = HeatmapResponse;
-declare const index_Hotspot: typeof Hotspot;
-declare const index_HotspotOptions: typeof HotspotOptions;
-declare const index_HotspotResponse: typeof HotspotResponse;
-declare const index_LOW_CONFIDENCE_THRESHOLD: typeof LOW_CONFIDENCE_THRESHOLD;
-declare const index_MAX_CUE_TEXT_CHARS: typeof MAX_CUE_TEXT_CHARS;
-declare const index_PendingShotsResult: typeof PendingShotsResult;
-declare const index_Shot: typeof Shot;
-declare const index_ShotRequestOptions: typeof ShotRequestOptions;
-declare const index_ShotsResult: typeof ShotsResult;
-declare const index_SkippedShotsResult: typeof SkippedShotsResult;
-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;
-declare const index_WaitForShotsOptions: typeof 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;
-declare const index_fetchTranscriptForAsset: typeof fetchTranscriptForAsset;
-declare const index_filterVttByScope: typeof filterVttByScope;
-declare const index_findCaptionTrack: typeof findCaptionTrack;
-declare const index_getHeatmapForAsset: typeof getHeatmapForAsset;
-declare const index_getHeatmapForPlaybackId: typeof getHeatmapForPlaybackId;
-declare const index_getHeatmapForVideo: typeof getHeatmapForVideo;
-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_getReliableLanguageCode: typeof getReliableLanguageCode;
-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_sanitizeUntrustedText: typeof sanitizeUntrustedText;
-declare const index_secondsToTimestamp: typeof secondsToTimestamp;
-declare const index_splitVttPreambleAndCueBlocks: typeof splitVttPreambleAndCueBlocks;
-declare const index_stripVttMetadataBlocks: typeof stripVttMetadataBlocks;
-declare const index_vttTimestampToSeconds: typeof vttTimestampToSeconds;
-declare const index_waitForShotsForAsset: typeof waitForShotsForAsset;
-declare namespace index {
-  export { index_CompletedShotsResult as CompletedShotsResult, index_DEFAULT_STORYBOARD_WIDTH as DEFAULT_STORYBOARD_WIDTH, index_DeletedShotsResult as DeletedShotsResult, index_ErroredShotsResult as ErroredShotsResult, type index_HeatmapOptions as HeatmapOptions, type index_HeatmapResponse as HeatmapResponse, index_Hotspot as Hotspot, index_HotspotOptions as HotspotOptions, index_HotspotResponse as HotspotResponse, index_LOW_CONFIDENCE_THRESHOLD as LOW_CONFIDENCE_THRESHOLD, index_MAX_CUE_TEXT_CHARS as MAX_CUE_TEXT_CHARS, index_PendingShotsResult as PendingShotsResult, index_Shot as Shot, index_ShotRequestOptions as ShotRequestOptions, index_ShotsResult as ShotsResult, index_SkippedShotsResult as SkippedShotsResult, 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, 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_filterVttByScope as filterVttByScope, 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_getReliableLanguageCode as getReliableLanguageCode, 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_sanitizeUntrustedText as sanitizeUntrustedText, index_secondsToTimestamp as secondsToTimestamp, index_splitVttPreambleAndCueBlocks as splitVttPreambleAndCueBlocks, index_stripVttMetadataBlocks as stripVttMetadataBlocks, index_vttTimestampToSeconds as vttTimestampToSeconds, index_waitForShotsForAsset as waitForShotsForAsset };
-}
-
-export { getReliableLanguageCode as A, getStoryboardUrl as B, getThumbnailUrls as C, DEFAULT_STORYBOARD_WIDTH as D, parseVTTCues as E, replaceCueText as F, sanitizeUntrustedText as G, type HeatmapOptions as H, secondsToTimestamp as I, splitVttPreambleAndCueBlocks as J, stripVttMetadataBlocks as K, LOW_CONFIDENCE_THRESHOLD as L, MAX_CUE_TEXT_CHARS as M, vttTimestampToSeconds as N, type ThumbnailOptions as T, type VTTCue as V, type HeatmapResponse as a, type TranscriptFetchOptions as b, type TranscriptResult as c, type VTTCueBudgetChunkingOptions as d, type VTTDurationChunk as e, type VTTDurationChunkingOptions as f, buildTranscriptUrl as g, buildVttFromCueBlocks as h, index as i, buildVttFromTranslatedCueBlocks as j, chunkByTokens as k, chunkText as l, chunkVTTCues as m, chunkVTTCuesByBudget as n, chunkVTTCuesByDuration as o, concatenateVttSegments as p, estimateTokenCount as q, extractTextFromVTT as r, extractTimestampedTranscript as s, fetchTranscriptForAsset as t, filterVttByScope as u, findCaptionTrack as v, getHeatmapForAsset as w, getHeatmapForPlaybackId as x, getHeatmapForVideo as y, getReadyTextTracks as z };