@mux/ai 0.52.0 → 0.54.0

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.52.0";
+var version = "0.54.0";
 
 // src/lib/language-codes.ts
 var ISO639_1_TO_3 = {
@@ -704,6 +704,9 @@ var MuxAiError = class extends Error {
     super(message);
     /** Structural brand for duck-type identification. */
     this.__robots_error = true;
+    if (opts?.cause !== void 0) {
+      Object.defineProperty(this, "cause", { value: opts.cause, writable: true, configurable: true });
+    }
     this.name = "FatalError";
     this.publicType = opts?.type ?? "processing_error";
     this.publicMessage = message;
@@ -1814,6 +1817,7 @@ __export(primitives_exports, {
   estimateTokenCount: () => estimateTokenCount,
   extractTextFromVTT: () => extractTextFromVTT,
   extractTimestampedTranscript: () => extractTimestampedTranscript,
+  fetchTranscriptDataForUrl: () => fetchTranscriptDataForUrl,
   fetchTranscriptForAsset: () => fetchTranscriptForAsset,
   filterVttByScope: () => filterVttByScope,
   findCaptionTrack: () => findCaptionTrack,
@@ -3128,9 +3132,10 @@ function extractTimestampedTranscript(vttContent) {
     segments.map((segment) => `[${Math.floor(segment.time)}s] ${segment.text}`).join("\n")
   );
 }
-function parseVTTCues(vttContent) {
+function parseVTTCues(vttContent, options = {}) {
   if (!vttContent.trim())
     return [];
+  const { capCueText = true } = options;
   const lines = vttContent.split("\n");
   const cues = [];
   let previousCueIdentifier = null;
@@ -3162,15 +3167,16 @@ function parseVTTCues(vttContent) {
       }
       const textLines = rawTextLines.map((textLine) => textLine.replace(/<[^>]*>/g, "")).filter(Boolean);
       if (textLines.length > 0) {
+        const sanitized = sanitizeUntrustedText(textLines.join(" "));
         cues.push({
           startTime,
           endTime,
           // Sanitize at the cue boundary so every downstream consumer
           // (engagement-insights, translate-captions chunked path, etc.)
           // receives text free of invisible / bidi obfuscation. Length-
-          // cap the result so an adversarially oversized cue cannot
-          // smuggle a large injection payload into the prompt.
-          text: capCueTextLength(sanitizeUntrustedText(textLines.join(" ")))
+          // cap the result by default so an adversarially oversized cue
+          // cannot smuggle a large injection payload into a prompt.
+          text: capCueText ? capCueTextLength(sanitized) : sanitized
         });
       }
       previousCueIdentifier = currentCueIdentifier;
@@ -3294,16 +3300,32 @@ async function buildTranscriptUrl(playbackId, trackId, shouldSign = false, crede
   }
   return baseUrl;
 }
-async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
+async function fetchTranscriptDataForUrl(transcriptUrl, options = {}) {
   "use step";
-  const {
-    languageCode,
-    cleanTranscript = true,
-    scope,
-    shouldSign,
-    credentials,
-    required = false
-  } = options;
+  const { cleanTranscript = true, scope } = options;
+  try {
+    const response = await fetch(transcriptUrl);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch transcript (HTTP ${response.status})`);
+    }
+    const rawVtt = await response.text();
+    const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+    const scopedVtt = filterVttByScope(rawVtt, effectiveScope);
+    const transcriptText = cleanTranscript ? extractTextFromVTT(scopedVtt) : scopedVtt;
+    const hasScopedCues = !effectiveScope || parseVTTCues(scopedVtt).length > 0;
+    if (!transcriptText.trim() || !hasScopedCues) {
+      return {
+        transcriptText,
+        emptyReason: hasScopedCues ? "empty_body" : "no_scoped_cues"
+      };
+    }
+    return { transcriptText };
+  } catch (error) {
+    wrapError(error, "Failed to fetch transcript");
+  }
+}
+async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
+  const { required = false, languageCode, cleanTranscript, scope, shouldSign, credentials } = options;
   const track = findCaptionTrack(asset, languageCode);
   if (!track) {
     if (required) {
@@ -3322,33 +3344,25 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
     return { transcriptText: "", track };
   }
   const transcriptUrl = await buildTranscriptUrl(playbackId, track.id, shouldSign, credentials);
+  let result;
   try {
-    const response = await fetch(transcriptUrl);
-    if (!response.ok) {
-      if (required) {
-        throw new Error(`Failed to fetch transcript (HTTP ${response.status})`);
-      }
-      return { transcriptText: "", transcriptUrl, track };
-    }
-    const rawVtt = await response.text();
-    const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
-    const scopedVtt = filterVttByScope(rawVtt, effectiveScope);
-    const transcriptText = cleanTranscript ? extractTextFromVTT(scopedVtt) : scopedVtt;
-    const hasScopedCues = !effectiveScope || parseVTTCues(scopedVtt).length > 0;
-    if (required && (!transcriptText.trim() || !hasScopedCues)) {
-      throw new MuxAiError(
-        effectiveScope ? "Transcript has no cues in the requested scope." : "Transcript is empty.",
-        { type: "validation_error" }
-      );
-    }
-    return { transcriptText, transcriptUrl, track };
+    result = await fetchTranscriptDataForUrl(transcriptUrl, { cleanTranscript, scope });
   } catch (error) {
     if (required) {
-      wrapError(error, "Failed to fetch transcript");
+      throw error;
     }
     console.warn("Failed to fetch transcript:", error);
     return { transcriptText: "", transcriptUrl, track };
   }
+  if (!required || !result.emptyReason) {
+    return { transcriptText: result.transcriptText, transcriptUrl, track };
+  }
+  switch (result.emptyReason) {
+    case "no_scoped_cues":
+      throw new MuxAiError("Transcript has no cues in the requested scope.", { type: "validation_error" });
+    case "empty_body":
+      throw new MuxAiError("Transcript is empty.", { type: "validation_error" });
+  }
 }
 
 // src/workflows/index.ts
@@ -3361,6 +3375,7 @@ __export(workflows_exports, {
   DEFAULT_DESCRIPTION_LENGTH: () => DEFAULT_DESCRIPTION_LENGTH,
   DEFAULT_SUMMARY_KEYWORD_LIMIT: () => DEFAULT_SUMMARY_KEYWORD_LIMIT,
   DEFAULT_TITLE_LENGTH: () => DEFAULT_TITLE_LENGTH,
+  DEFAULT_TRANSCRIPT_WINDOWING: () => DEFAULT_TRANSCRIPT_WINDOWING,
   GENERATE_TEXT_CALLS_TO_ACTION: () => GENERATE_TEXT_CALLS_TO_ACTION,
   GENERATE_TEXT_CHANNELS: () => GENERATE_TEXT_CHANNELS,
   GENERATE_TEXT_CHANNEL_CEILINGS: () => GENERATE_TEXT_CHANNEL_CEILINGS,
@@ -3386,6 +3401,7 @@ __export(workflows_exports, {
   applyTextRepair: () => applyTextRepair,
   askQuestions: () => askQuestions,
   buildReplacementRegex: () => buildReplacementRegex,
+  buildTranscriptWindows: () => buildTranscriptWindows,
   burnedInCaptionsSchema: () => burnedInCaptionsSchema,
   censorVttContent: () => censorVttContent,
   chapterSchema: () => chapterSchema,
@@ -7277,10 +7293,27 @@ ${renderSection({ tag: "revision_request", content: "The previous draft was empt
   usages.push(...repaired.attempts.flatMap((item) => item.call.usage ? [item.call.usage] : []));
   if (repaired.status !== "valid") {
     const cause = repaired.attempts.at(-1)?.call.errorCause;
-    const failure = isIncompleteGenerationError(cause) ? new IncompleteGenerationError(cause.finishReason, cause.rawFinishReason) : MuxAiError.is(cause) ? new MuxAiError(cause.publicMessage, { type: cause.publicType, retryable: cause.retryable }) : new MuxAiError(`Bounded text repair failed: ${repaired.reason}`, {
-      type: "processing_error",
-      retryable: APICallError3.isInstance(cause) ? cause.isRetryable : true
-    });
+    let failure;
+    if (isIncompleteGenerationError(cause)) {
+      failure = new IncompleteGenerationError(cause.finishReason, cause.rawFinishReason);
+    } else if (MuxAiError.is(cause)) {
+      failure = new MuxAiError(cause.publicMessage, { type: cause.publicType, retryable: cause.retryable });
+    } else {
+      const apiError = APICallError3.isInstance(cause) ? cause : void 0;
+      console.warn("[@mux/ai] Bounded text repair failed.", {
+        provider: args.provider,
+        modelId: args.modelId,
+        reason: repaired.reason,
+        errorName: cause instanceof Error ? cause.name : void 0,
+        statusCode: apiError?.statusCode,
+        requestId: apiError?.responseHeaders?.["x-request-id"] ?? apiError?.responseHeaders?.["request-id"]
+      });
+      failure = new MuxAiError("Unable to complete text generation.", {
+        type: "processing_error",
+        retryable: apiError?.isRetryable ?? true,
+        cause
+      });
+    }
     rethrowWithTokenUsage(failure, usages);
   }
   return { content: repaired.content, usages, unexpectedKeys };
@@ -7458,6 +7491,9 @@ async function generateTextInternal(assetId, rawOptions, collectedUsage) {
   };
 }
 
+// src/workflows/moderation.ts
+import { z as z9 } from "zod";
+
 // src/lib/sampling-plan.ts
 var DEFAULT_FPS = 30;
 function roundToNearestFrameMs(tsMs, fps = DEFAULT_FPS) {
@@ -7530,6 +7566,15 @@ var OPENAI_MODERATION_BASE_DELAY_MS = 750;
 var OPENAI_MODERATION_MAX_DELAY_MS = 3e3;
 var MIN_SAMPLE_COVERAGE_FOR_CONFIDENT_THRESHOLDING = 0.5;
 var MIN_SUCCESSFUL_THUMBNAILS_FOR_CONFIDENT_THRESHOLDING = 3;
+var DEFAULT_TRANSCRIPT_WINDOWING = {
+  targetWindowCount: 40,
+  minWindowSeconds: 20,
+  maxWindowSeconds: 120,
+  overlapFraction: 0.15,
+  minOverlapSeconds: 5
+};
+var TRANSCRIPT_BATCH_MAX_UTF16_CODE_UNITS = 1e5;
+var TRANSCRIPT_BATCH_MAX_ITEMS = 100;
 var GOOGLE_VISION_ENDPOINT = "https://vision.googleapis.com/v1/images:annotate";
 var GOOGLE_VISION_LIKELIHOOD_TO_SCORE = {
   UNKNOWN: 0,
@@ -7597,6 +7642,14 @@ function parseOpenAIModerationResponse(bodyText, status, statusText) {
     );
   }
 }
+var OpenAIModerationResponseSchema = z9.object({
+  results: z9.array(z9.object({
+    category_scores: z9.object({
+      sexual: z9.number().finite().nullish(),
+      violence: z9.number().finite().nullish()
+    })
+  }))
+});
 async function callOpenAIModerationApi({
   model,
   input,
@@ -7636,7 +7689,21 @@ async function callOpenAIModerationApi({
           }
         );
       }
-      return json;
+      const parsed = OpenAIModerationResponseSchema.safeParse(json);
+      if (!parsed.success) {
+        throw new OpenAIModerationRequestError(
+          `OpenAI moderation returned an unexpected response shape: ${compactBodySnippet(bodyText)}`,
+          { status: res.status, retriable: false }
+        );
+      }
+      const expectedResultCount = Array.isArray(input) ? input.length : 1;
+      if (parsed.data.results.length !== expectedResultCount) {
+        throw new OpenAIModerationRequestError(
+          `OpenAI moderation returned ${parsed.data.results.length} result(s) for ${expectedResultCount} input(s).`,
+          { status: res.status, retriable: false }
+        );
+      }
+      return parsed.data;
     },
     {
       maxRetries: OPENAI_MODERATION_MAX_RETRIES,
@@ -7660,7 +7727,7 @@ async function processConcurrently(items, processor, maxConcurrent = 5) {
 async function moderateImageWithOpenAI(entry) {
   "use step";
   try {
-    const json = await callOpenAIModerationApi({
+    const { results } = await callOpenAIModerationApi({
       model: entry.model,
       input: [
         {
@@ -7672,12 +7739,12 @@ async function moderateImageWithOpenAI(entry) {
       ],
       credentials: entry.credentials
     });
-    const categoryScores = json.results?.[0]?.category_scores || {};
+    const [result] = results;
     return {
       url: entry.url,
       time: entry.time,
-      sexual: categoryScores.sexual || 0,
-      violence: categoryScores.violence || 0,
+      sexual: result.category_scores.sexual ?? 0,
+      violence: result.category_scores.violence ?? 0,
       error: false
     };
   } catch (error) {
@@ -7701,65 +7768,187 @@ async function requestOpenAIModeration(images, model, maxConcurrent = 5, submiss
   ) : images.map((img) => ({ url: img.url, time: img.time, image: img.url, model, credentials }));
   return processConcurrently(targetUrls, moderateImageWithOpenAI, maxConcurrent);
 }
-async function requestOpenAITextModeration(text, model, url, credentials) {
-  "use step";
-  try {
-    const json = await callOpenAIModerationApi({
-      model,
-      input: text,
-      credentials
+var TRANSCRIPT_WINDOW_MAX_UTF16_CODE_UNITS = 1e4;
+function describeSurfaceFailure(itemLabel, scores) {
+  const messages = Array.from(new Set(scores.map((s) => s.errorMessage || "Unknown error")));
+  return `All ${scores.length} ${itemLabel}(s) failed to moderate: ${messages.join("; ")}`;
+}
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+function splitCuesUnderCharCeiling(cues, maxUnits = TRANSCRIPT_WINDOW_MAX_UTF16_CODE_UNITS) {
+  const windows = [];
+  let current = [];
+  let currentLength = 0;
+  const flush = () => {
+    if (current.length === 0) {
+      return;
+    }
+    windows.push({
+      startTime: Math.min(...current.map((cue) => cue.startTime)),
+      endTime: Math.max(...current.map((cue) => cue.endTime)),
+      text: current.map((cue) => cue.text).join(" ")
     });
-    const categoryScores = json.results?.[0]?.category_scores || {};
-    return {
-      url,
-      sexual: categoryScores.sexual || 0,
-      violence: categoryScores.violence || 0,
-      error: false
-    };
-  } catch (error) {
-    console.error("OpenAI text moderation failed:", error);
-    return {
-      url,
-      sexual: 0,
-      violence: 0,
-      error: true,
-      errorMessage: error instanceof Error ? error.message : String(error)
-    };
+    current = [];
+    currentLength = 0;
+  };
+  for (const cue of cues) {
+    const cueText = cue.text;
+    const addedLength = currentLength === 0 ? cueText.length : currentLength + 1 + cueText.length;
+    if (current.length > 0 && addedLength > maxUnits) {
+      flush();
+    }
+    current.push(cue);
+    currentLength = current.length === 1 ? cueText.length : currentLength + 1 + cueText.length;
   }
+  flush();
+  return windows;
 }
-function chunkTextByUtf16CodeUnits(text, maxUnits) {
-  if (!text.trim()) {
+function buildTranscriptWindows(cues, duration) {
+  const usableCues = cues.filter((cue) => cue.text.trim().length > 0).slice().sort((a, b) => a.startTime - b.startTime);
+  if (usableCues.length === 0) {
     return [];
   }
-  if (text.length <= maxUnits) {
-    return [text];
+  const lastCueEnd = Math.max(...usableCues.map((cue) => cue.endTime));
+  const effectiveDuration = duration && duration > 0 ? duration : lastCueEnd;
+  const { targetWindowCount, minWindowSeconds, maxWindowSeconds, overlapFraction, minOverlapSeconds } = DEFAULT_TRANSCRIPT_WINDOWING;
+  const windowSeconds = clamp(
+    effectiveDuration / targetWindowCount,
+    minWindowSeconds,
+    maxWindowSeconds
+  );
+  const overlapSeconds = Math.max(
+    minOverlapSeconds,
+    windowSeconds * overlapFraction
+  );
+  const stride = Math.max(windowSeconds - overlapSeconds, 1);
+  const rawWindows = [];
+  for (let k = 0; ; k++) {
+    const windowStart = k * stride;
+    if (windowStart > lastCueEnd) {
+      break;
+    }
+    const windowEnd = windowStart + windowSeconds;
+    const windowCues = usableCues.filter(
+      (cue) => cue.startTime < windowEnd && cue.endTime > windowStart
+    );
+    if (windowCues.length > 0) {
+      rawWindows.push(windowCues);
+    }
+    if (stride <= 0) {
+      break;
+    }
   }
-  const chunks = [];
-  for (let i = 0; i < text.length; i += maxUnits) {
-    const chunk = text.slice(i, i + maxUnits).trim();
-    if (chunk) {
-      chunks.push(chunk);
+  const dedupedCueGroups = [];
+  const cueGroupKey = (group) => group.map((cue) => `${cue.startTime}:${cue.endTime}`).join("|");
+  let previousKey;
+  for (const group of rawWindows) {
+    const key = cueGroupKey(group);
+    if (key === previousKey) {
+      continue;
     }
+    dedupedCueGroups.push(group);
+    previousKey = key;
   }
-  return chunks;
+  const windows = [];
+  for (const group of dedupedCueGroups) {
+    const joinedLength = group.reduce(
+      (sum, cue, index) => sum + cue.text.length + (index === 0 ? 0 : 1),
+      0
+    );
+    if (joinedLength > TRANSCRIPT_WINDOW_MAX_UTF16_CODE_UNITS) {
+      windows.push(...splitCuesUnderCharCeiling(group));
+    } else {
+      windows.push({
+        startTime: Math.min(...group.map((cue) => cue.startTime)),
+        endTime: Math.max(...group.map((cue) => cue.endTime)),
+        text: group.map((cue) => cue.text).join(" ")
+      });
+    }
+  }
+  return windows;
+}
+function packWindowsIntoBatches(windows) {
+  const batches = [];
+  let current = [];
+  let currentLength = 0;
+  for (const window of windows) {
+    const wouldExceedChars = current.length > 0 && currentLength + window.text.length > TRANSCRIPT_BATCH_MAX_UTF16_CODE_UNITS;
+    const wouldExceedItems = current.length >= TRANSCRIPT_BATCH_MAX_ITEMS;
+    if (wouldExceedChars || wouldExceedItems) {
+      batches.push(current);
+      current = [];
+      currentLength = 0;
+    }
+    current.push(window);
+    currentLength += window.text.length;
+  }
+  if (current.length > 0) {
+    batches.push(current);
+  }
+  return batches;
+}
+function transcriptErrorScore(window, error) {
+  return {
+    startTime: window.startTime,
+    endTime: window.endTime,
+    sexual: 0,
+    violence: 0,
+    error: true,
+    errorMessage: error instanceof Error ? error.message : String(error)
+  };
 }
-async function requestOpenAITranscriptModeration(transcriptText, model, maxConcurrent = 5, credentials) {
+async function moderateTranscriptBatchWithOpenAI(batch) {
   "use step";
-  const chunks = chunkTextByUtf16CodeUnits(transcriptText, 1e4);
-  if (!chunks.length) {
-    return [
-      { url: "transcript:0", sexual: 0, violence: 0, error: true, errorMessage: "No transcript chunks to moderate" }
-    ];
-  }
-  const targets = chunks.map((chunk, idx) => ({
-    chunk,
-    url: `transcript:${idx}`
-  }));
-  return processConcurrently(
-    targets,
-    async (entry) => requestOpenAITextModeration(entry.chunk, model, entry.url, credentials),
+  const { windows, model, credentials } = batch;
+  if (windows.length === 0) {
+    return [];
+  }
+  try {
+    const { results } = await callOpenAIModerationApi({
+      model,
+      input: windows.map((window) => window.text),
+      credentials
+    });
+    return windows.map((window, index) => {
+      const result = results[index];
+      return {
+        startTime: window.startTime,
+        endTime: window.endTime,
+        sexual: result.category_scores.sexual ?? 0,
+        violence: result.category_scores.violence ?? 0,
+        error: false
+      };
+    });
+  } catch (error) {
+    const status = error instanceof OpenAIModerationRequestError ? error.status : void 0;
+    if (status === 400 && windows.length > 1) {
+      const mid = Math.ceil(windows.length / 2);
+      const [left, right] = await Promise.all([
+        moderateTranscriptBatchWithOpenAI({ windows: windows.slice(0, mid), model, credentials }),
+        moderateTranscriptBatchWithOpenAI({ windows: windows.slice(mid), model, credentials })
+      ]);
+      return [...left, ...right];
+    }
+    console.error("OpenAI transcript moderation failed:", error);
+    return windows.map((window) => transcriptErrorScore(window, error));
+  }
+}
+async function requestOpenAITranscriptModeration(cues, duration, model, maxConcurrent = 5, credentials) {
+  "use step";
+  const windows = buildTranscriptWindows(cues, duration);
+  if (!windows.length) {
+    return [];
+  }
+  const batches = packWindowsIntoBatches(windows).map(
+    (windowBatch) => ({ windows: windowBatch, model, credentials })
+  );
+  const batchResults = await processConcurrently(
+    batches,
+    moderateTranscriptBatchWithOpenAI,
     maxConcurrent
   );
+  return batchResults.flat();
 }
 function getHiveCategoryScores(classes, categoryNames) {
   const scoreMap = Object.fromEntries(
@@ -7982,12 +8171,35 @@ async function getThumbnailUrlsFromTimestamps(playbackId, timestampsMs, options)
   });
   return Promise.all(urlPromises);
 }
+async function requestThumbnailModeration(provider, thumbnailUrls, options) {
+  const { model, maxConcurrent, imageSubmissionMode, imageDownloadOptions, credentials } = options;
+  switch (provider) {
+    case "openai":
+      return requestOpenAIModeration(
+        thumbnailUrls,
+        model || "omni-moderation-latest",
+        maxConcurrent,
+        imageSubmissionMode,
+        imageDownloadOptions,
+        credentials
+      );
+    case "hive":
+      return requestHiveModeration(thumbnailUrls, maxConcurrent, imageSubmissionMode, imageDownloadOptions, credentials);
+    case "google-vision-api":
+      return requestGoogleVisionModeration(thumbnailUrls, maxConcurrent, imageSubmissionMode, imageDownloadOptions, credentials);
+    default: {
+      const exhaustiveCheck = provider;
+      throw new Error(`Unsupported moderation provider: ${exhaustiveCheck}`);
+    }
+  }
+}
 async function getModerationScores(assetId, options = {}) {
   "use workflow";
   const {
     provider = DEFAULT_PROVIDER2,
     model = provider === "openai" ? "omni-moderation-latest" : void 0,
     languageCode,
+    includeTranscript = true,
     thresholds = DEFAULT_THRESHOLDS,
     thumbnailInterval = 10,
     thumbnailWidth = 640,
@@ -8014,47 +8226,31 @@ async function getModerationScores(assetId, options = {}) {
     startTime: Math.min(resolvedScope.startTime, duration),
     endTime: Math.min(resolvedScope.endTime, duration)
   } : void 0;
-  if (!isAudioOnly && renderableScope && renderableScope.startTime >= renderableScope.endTime) {
-    throw new Error("The requested scope does not include any renderable video.");
-  }
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
     throw new Error(
       "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables."
     );
   }
-  let thumbnailScores;
-  let mode = "thumbnails";
-  let thumbnailCount;
+  let thumbnailModeration = { status: "completed" };
+  let thumbnailUrls = [];
+  let shouldRunThumbnails = false;
   if (isAudioOnly) {
-    mode = "transcript";
-    const transcriptResult = await fetchTranscriptForAsset(asset, playbackId, {
-      languageCode,
-      cleanTranscript: true,
-      shouldSign: policy === "signed",
-      credentials,
-      required: true,
-      scope: effectiveScope
-    });
-    if (provider === "openai") {
-      thumbnailScores = await requestOpenAITranscriptModeration(
-        transcriptResult.transcriptText,
-        model || "omni-moderation-latest",
-        maxConcurrent,
-        credentials
-      );
-    } else if (provider === "hive") {
-      throw new Error("Hive does not support transcript moderation in this workflow. Use provider: 'openai' for audio-only assets.");
-    } else if (provider === "google-vision-api") {
-      throw new Error("google-vision-api is image-only and does not support transcript moderation. Use provider: 'openai' for audio-only assets.");
-    } else {
-      const exhaustiveCheck = provider;
-      throw new Error(`Unsupported moderation provider: ${exhaustiveCheck}`);
-    }
+    thumbnailModeration = {
+      status: "skipped",
+      skipReason: "no_video_track",
+      skipMessage: "Asset has no video track, so there are no thumbnails to moderate."
+    };
+  } else if (renderableScope && renderableScope.startTime >= renderableScope.endTime) {
+    thumbnailModeration = {
+      status: "skipped",
+      skipReason: "no_video_in_scope",
+      skipMessage: "The requested scope does not include any renderable video, so there are no thumbnails to moderate."
+    };
   } else {
     const scopedDuration = renderableScope ? renderableScope.endTime - renderableScope.startTime : duration;
     const estimatedIntervalCount = scopedDuration <= 50 ? 5 : Math.ceil(scopedDuration / thumbnailInterval);
-    const thumbnailUrls = maxSamples !== void 0 && estimatedIntervalCount > maxSamples ? await getThumbnailUrlsFromTimestamps(
+    thumbnailUrls = maxSamples !== void 0 && estimatedIntervalCount > maxSamples ? await getThumbnailUrlsFromTimestamps(
       playbackId,
       filterTimestampsWithinExclusiveScope(
         planSamplingTimestamps({
@@ -8079,70 +8275,148 @@ async function getModerationScores(assetId, options = {}) {
       credentials,
       scope: renderableScope
     });
-    thumbnailCount = thumbnailUrls.length;
-    if (provider === "openai") {
-      thumbnailScores = await requestOpenAIModeration(
-        thumbnailUrls,
-        model || "omni-moderation-latest",
-        maxConcurrent,
-        imageSubmissionMode,
-        imageDownloadOptions,
-        credentials
-      );
-    } else if (provider === "hive") {
-      thumbnailScores = await requestHiveModeration(
-        thumbnailUrls,
-        maxConcurrent,
-        imageSubmissionMode,
-        imageDownloadOptions,
-        credentials
-      );
-    } else if (provider === "google-vision-api") {
-      thumbnailScores = await requestGoogleVisionModeration(
-        thumbnailUrls,
-        maxConcurrent,
-        imageSubmissionMode,
-        imageDownloadOptions,
-        credentials
-      );
+    shouldRunThumbnails = true;
+  }
+  let transcriptModeration = { status: "completed" };
+  let transcriptCues = [];
+  let shouldRunTranscript = false;
+  const transcriptEnabled = includeTranscript || isAudioOnly;
+  const captionTrack = transcriptEnabled && provider === "openai" ? findCaptionTrack(asset, languageCode) : void 0;
+  if (!transcriptEnabled) {
+    transcriptModeration = {
+      status: "skipped",
+      skipReason: "disabled",
+      skipMessage: "Transcript moderation was disabled with includeTranscript: false."
+    };
+  } else if (provider !== "openai") {
+    transcriptModeration = {
+      status: "skipped",
+      skipReason: "unsupported_provider",
+      skipMessage: `Provider '${provider}' is image-only and cannot moderate transcript text; use provider 'openai'.`
+    };
+  } else if (!captionTrack) {
+    transcriptModeration = {
+      status: "skipped",
+      skipReason: "no_ready_text_track",
+      skipMessage: languageCode ? `No ready caption/subtitle track found for language '${languageCode}'.` : "No ready caption/subtitle track found for this asset."
+    };
+  } else {
+    if (!captionTrack.id) {
+      throw new MuxAiError("Transcript track is missing an id.", { type: "validation_error" });
+    }
+    const transcriptUrl = await buildTranscriptUrl(playbackId, captionTrack.id, policy === "signed", credentials);
+    const { transcriptText, emptyReason } = await fetchTranscriptDataForUrl(transcriptUrl, {
+      cleanTranscript: false,
+      scope: effectiveScope
+    });
+    if (emptyReason) {
+      transcriptModeration = {
+        status: "skipped",
+        skipReason: "no_cues",
+        skipMessage: emptyReason === "no_scoped_cues" ? "Transcript has no cues in the requested scope." : "Transcript is empty."
+      };
     } else {
-      const exhaustiveCheck = provider;
-      throw new Error(`Unsupported moderation provider: ${exhaustiveCheck}`);
+      transcriptCues = parseVTTCues(transcriptText, { capCueText: false });
+      const windows = transcriptCues.length === 0 ? [] : buildTranscriptWindows(transcriptCues, duration);
+      if (windows.length === 0) {
+        transcriptModeration = {
+          status: "skipped",
+          skipReason: "no_cues",
+          skipMessage: "Caption track had no parseable cues."
+        };
+      } else {
+        shouldRunTranscript = true;
+      }
     }
   }
-  const failed = thumbnailScores.filter((s) => s.error);
-  const successful = thumbnailScores.filter((s) => !s.error);
+  if (!shouldRunThumbnails && !shouldRunTranscript) {
+    throw new MuxAiError(
+      `Nothing to moderate. Thumbnails skipped: ${thumbnailModeration.skipMessage} Transcript skipped: ${transcriptModeration.skipMessage}`,
+      { type: "validation_error" }
+    );
+  }
+  const [thumbnailScores, transcriptScores] = await Promise.all([
+    shouldRunThumbnails ? requestThumbnailModeration(provider, thumbnailUrls, {
+      model,
+      maxConcurrent,
+      imageSubmissionMode,
+      imageDownloadOptions,
+      credentials
+    }) : Promise.resolve([]),
+    shouldRunTranscript ? requestOpenAITranscriptModeration(
+      transcriptCues,
+      duration,
+      model || "omni-moderation-latest",
+      maxConcurrent,
+      credentials
+    ) : Promise.resolve([])
+  ]);
+  const mode = shouldRunThumbnails && shouldRunTranscript ? "combined" : shouldRunTranscript ? "transcript" : "thumbnails";
+  const thumbnailCount = shouldRunThumbnails ? thumbnailUrls.length : void 0;
+  const allScores = [
+    ...thumbnailScores.map((s) => ({ ...s, label: s.url })),
+    ...transcriptScores.map((s) => ({ ...s, error: s.error ?? false, label: `transcript window ${s.startTime}-${s.endTime}s` }))
+  ];
+  const failed = allScores.filter((s) => s.error);
+  const successful = allScores.filter((s) => !s.error);
   if (successful.length === 0) {
-    const details = failed.map((s) => `${s.url}: ${s.errorMessage || "Unknown error"}`).join("; ");
+    const details = failed.map((s) => `${s.label}: ${s.errorMessage || "Unknown error"}`).join("; ");
     throw new Error(
-      `Moderation failed for all ${thumbnailScores.length} sample(s): ${details}`
+      `Moderation failed for all ${allScores.length} sample(s): ${details}`
     );
   }
   if (failed.length > 0) {
     console.warn(
-      `Moderation had partial failures (${failed.length}/${thumbnailScores.length}); continuing with successful samples.`
+      `Moderation had partial failures (${failed.length}/${allScores.length}); continuing with successful samples.`
     );
   }
+  const thumbnailsFailed = shouldRunThumbnails && thumbnailScores.length > 0 && thumbnailScores.every((s) => s.error);
+  const transcriptFailed = shouldRunTranscript && transcriptScores.length > 0 && transcriptScores.every((s) => s.error);
+  if (thumbnailsFailed) {
+    thumbnailModeration = {
+      status: "failed",
+      errorMessage: describeSurfaceFailure("thumbnail", thumbnailScores)
+    };
+  }
+  if (transcriptFailed) {
+    transcriptModeration = {
+      status: "failed",
+      errorMessage: describeSurfaceFailure("transcript window", transcriptScores)
+    };
+  }
   const maxSexual = Math.max(...successful.map((s) => s.sexual));
   const maxViolence = Math.max(...successful.map((s) => s.violence));
   const finalThresholds = { ...DEFAULT_THRESHOLDS, ...thresholds };
-  const requestedSampleCount = thumbnailScores.length;
-  const successfulSampleCount = successful.length;
-  const failedSampleCount = failed.length;
-  const sampleCoverage = successfulSampleCount / requestedSampleCount;
-  const hasEnoughSuccessfulSamples = mode === "transcript" || successfulSampleCount >= MIN_SUCCESSFUL_THUMBNAILS_FOR_CONFIDENT_THRESHOLDING;
-  const isLowConfidence = sampleCoverage < MIN_SAMPLE_COVERAGE_FOR_CONFIDENT_THRESHOLDING || !hasEnoughSuccessfulSamples;
+  const coverageScores = thumbnailScores;
+  const coverageFailed = coverageScores.filter((s) => s.error);
+  const coverageSuccessful = coverageScores.filter((s) => !s.error);
+  const requestedSampleCount = coverageScores.length;
+  const successfulSampleCount = coverageSuccessful.length;
+  const failedSampleCount = coverageFailed.length;
+  const sampleCoverage = requestedSampleCount > 0 ? successfulSampleCount / requestedSampleCount : 0;
+  const hasThumbnails = requestedSampleCount > 0;
+  const hasSuccessfulTranscript = transcriptScores.some((s) => !s.error);
+  let isLowConfidence;
+  if (!hasThumbnails) {
+    isLowConfidence = !hasSuccessfulTranscript;
+  } else {
+    const hasEnoughSuccessfulSamples = successfulSampleCount >= MIN_SUCCESSFUL_THUMBNAILS_FOR_CONFIDENT_THRESHOLDING;
+    isLowConfidence = sampleCoverage < MIN_SAMPLE_COVERAGE_FOR_CONFIDENT_THRESHOLDING || !hasEnoughSuccessfulSamples || transcriptFailed;
+  }
   return {
     assetId,
     mode,
     isAudioOnly,
     thumbnailScores,
+    transcriptScores,
+    thumbnailModeration,
+    transcriptModeration,
     coverage: {
       requestedSampleCount,
       successfulSampleCount,
       failedSampleCount,
       sampleCoverage,
-      isPartial: failedSampleCount > 0,
+      isPartial: failed.length > 0,
       isLowConfidence
     },
     usage: {
@@ -8162,7 +8436,7 @@ async function getModerationScores(assetId, options = {}) {
 
 // src/workflows/summarization.ts
 import { generateText as generateText8, Output as Output8 } from "ai";
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 
 // src/lib/markdown-normalization.ts
 var ESCAPED_LINE_BREAK_REGEX = /\\r\\n|\\n|\\r/g;
@@ -8307,17 +8581,17 @@ function createSummarizationGuidance({
 }
 
 // src/workflows/summarization.ts
-var summarySchema = z9.object({
-  keywords: z9.array(z9.string().max(200)),
-  title: z9.string().max(500),
-  description: z9.string().max(1e4)
+var summarySchema = z10.object({
+  keywords: z10.array(z10.string().max(200)),
+  title: z10.string().max(500),
+  description: z10.string().max(1e4)
 });
 function buildSummarySchema(descriptionLength) {
   const descriptionMaxChars = Math.max(2e3, descriptionLength * 15);
-  return z9.object({
-    keywords: z9.array(z9.string().max(200)),
-    title: z9.string().max(500),
-    description: z9.string().max(descriptionMaxChars)
+  return z10.object({
+    keywords: z10.array(z10.string().max(200)),
+    title: z10.string().max(500),
+    description: z10.string().max(descriptionMaxChars)
   });
 }
 var VALID_TONES = ["neutral", "playful", "professional"];
@@ -9436,9 +9710,9 @@ import {
   RetryError as RetryError2,
   TypeValidationError
 } from "ai";
-import { z as z10 } from "zod";
-var translationSchema = z10.object({
-  translation: z10.string()
+import { z as z11 } from "zod";
+var translationSchema = z11.object({
+  translation: z11.string()
 });
 var SYSTEM_PROMPT5 = promptDedent`
   You are a subtitle translation expert. Translate VTT subtitle files to the target language specified by the user.
@@ -9817,8 +10091,8 @@ async function translateCueChunkWithAI({
 }) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const schema = z10.object({
-    translations: z10.array(z10.string().min(1).max(2e3)).length(cues.length)
+  const schema = z11.object({
+    translations: z11.array(z11.string().min(1).max(2e3)).length(cues.length)
   });
   const cuePayload = cues.map((cue, index) => ({
     index,