@mux/ai 0.12.1 → 0.13.0

package/dist/workflows/index.js

@@ -1081,6 +1081,16 @@ function vttTimestampToSeconds(timestamp) {
   const seconds = Number.parseFloat(parts[2]) || 0;
   return hours * 3600 + minutes * 60 + seconds;
 }
+function secondsToTimestamp(seconds) {
+  const rounded = Math.max(0, Math.floor(seconds));
+  const hours = Math.floor(rounded / 3600);
+  const minutes = Math.floor(rounded % 3600 / 60);
+  const remainingSeconds = rounded % 60;
+  if (hours > 0) {
+    return `${hours.toString().padStart(2, "0")}:${minutes.toString().padStart(2, "0")}:${remainingSeconds.toString().padStart(2, "0")}`;
+  }
+  return `${minutes}:${remainingSeconds.toString().padStart(2, "0")}`;
+}
 function extractTimestampedTranscript(vttContent) {
   if (!vttContent.trim()) {
     return "";
@@ -1368,17 +1378,23 @@ var SYSTEM_PROMPT = dedent`
   </answer_guidelines>
 
   <relevance_filtering>
-    Before answering each question, assess whether it can be meaningfully
-    answered based on the video storyboard and/or transcript. A question is
-    relevant if it asks about something observable or inferable from the
-    video content (visuals, audio, dialogue, setting, subjects, actions, etc.).
+    IMPORTANT: Evaluate each question INDEPENDENTLY for relevance to the video
+    content. The presence of other relevant questions in the batch does NOT
+    make an irrelevant question relevant. Assess every question on its own merits.
+
+    A question is relevant if it asks about something observable or inferable
+    from the video content (visuals, audio, dialogue, setting, subjects,
+    actions, etc.).
 
     Mark a question as skipped (skipped: true) if it:
-    - Is completely unrelated to video content (e.g., math, trivia, personal questions)
+    - Is completely unrelated to the content of the video or audio (e.g., math, trivia, personal questions)
     - Asks about information that cannot be determined from storyboard frames or transcript
     - Is a general knowledge question with no connection to what is shown or said in the video
     - Attempts to use the system for non-video-analysis purposes
 
+    CRITICAL: Do NOT answer irrelevant questions with any of the allowed answers.
+    Answering an irrelevant question is WRONG — you MUST skip it instead.
+
     For skipped questions:
     - Set skipped to true
     - Set answer to "${SKIP_SENTINEL}"
@@ -3236,6 +3252,594 @@ async function generateVideoEmbeddings(assetId, options = {}) {
   return generateEmbeddingsInternal(assetId, options);
 }
 
+// src/workflows/engagement-insights.ts
+import { generateText as generateText5, Output as Output5 } from "ai";
+import dedent5 from "dedent";
+import { z as z6 } from "zod";
+
+// src/primitives/heatmap.ts
+async function getHeatmapForAsset(assetId, options = {}) {
+  "use step";
+  return fetchHeatmap("assets", assetId, options);
+}
+function transformHeatmapResponse(response) {
+  return {
+    assetId: response.data.asset_id,
+    videoId: response.data.video_id,
+    playbackId: response.data.playback_id,
+    heatmap: response.data.heatmap,
+    timeframe: response.timeframe
+  };
+}
+async function fetchHeatmap(identifierType, id, options) {
+  "use step";
+  const { timeframe = "7:days", credentials } = options;
+  const muxClient = await getMuxClientFromEnv(credentials);
+  const mux = await muxClient.createClient();
+  const queryParams = new URLSearchParams();
+  queryParams.append("timeframe[]", timeframe);
+  const path = `/data/v1/engagement/${identifierType}/${id}/heatmap?${queryParams.toString()}`;
+  const response = await mux.get(path);
+  return transformHeatmapResponse(response);
+}
+
+// src/primitives/hotspots.ts
+async function getHotspotsForAsset(assetId, options = {}) {
+  "use step";
+  const response = await fetchHotspots("assets", assetId, options);
+  return response.hotspots;
+}
+function transformHotspotResponse(response) {
+  return {
+    assetId: response.data.asset_id,
+    videoId: response.data.video_id,
+    playbackId: response.data.playback_id,
+    hotspots: response.data.hotspots.map((h) => ({
+      startMs: h.start_ms,
+      endMs: h.end_ms,
+      score: h.score
+    }))
+  };
+}
+async function fetchHotspots(identifierType, id, options) {
+  "use step";
+  const {
+    limit = 5,
+    orderDirection = "desc",
+    orderBy = "score",
+    timeframe = "7:days",
+    credentials
+  } = options;
+  const muxClient = await getMuxClientFromEnv(credentials);
+  const mux = await muxClient.createClient();
+  const queryParams = new URLSearchParams();
+  queryParams.append("limit", String(limit));
+  queryParams.append("order_direction", orderDirection);
+  queryParams.append("order_by", orderBy);
+  queryParams.append("timeframe[]", timeframe);
+  const path = `/data/v1/engagement/${identifierType}/${id}/hotspots?${queryParams.toString()}`;
+  const response = await mux.get(path);
+  return transformHotspotResponse(response);
+}
+
+// src/primitives/shots.ts
+function getShotsPath(assetId) {
+  return `/video/v1/assets/${assetId}/shots`;
+}
+function mapManifestShots(shots) {
+  return shots.map((shot, index) => {
+    const { startTime, imageUrl } = shot;
+    if (typeof startTime !== "number" || !Number.isFinite(startTime)) {
+      throw new TypeError(`Invalid shot startTime in shots manifest at index ${index}`);
+    }
+    if (typeof imageUrl !== "string" || imageUrl.length === 0) {
+      throw new TypeError(`Invalid shot imageUrl in shots manifest at index ${index}`);
+    }
+    return {
+      startTime,
+      imageUrl
+    };
+  });
+}
+async function fetchShotsFromManifest(shotsManifestUrl) {
+  const response = await fetch(shotsManifestUrl);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch shots manifest: ${response.status} ${response.statusText}`
+    );
+  }
+  const manifest = await response.json();
+  if (!Array.isArray(manifest.shots)) {
+    throw new TypeError("Invalid shots manifest response: missing shots array");
+  }
+  return mapManifestShots(manifest.shots);
+}
+async function transformShotsResponse(response) {
+  switch (response.data.status) {
+    case "pending":
+      return {
+        status: "pending",
+        createdAt: response.data.created_at
+      };
+    case "errored":
+      return {
+        status: "errored",
+        createdAt: response.data.created_at,
+        error: response.data.error
+      };
+    case "completed":
+      return {
+        status: "completed",
+        createdAt: response.data.created_at,
+        shots: await fetchShotsFromManifest(response.data.shots_manifest_url)
+      };
+    default: {
+      const exhaustiveCheck = response.data;
+      throw new Error(`Unsupported shots response: ${JSON.stringify(exhaustiveCheck)}`);
+    }
+  }
+}
+async function getShotsForAsset(assetId, options = {}) {
+  "use step";
+  const { credentials } = options;
+  const muxClient = await getMuxClientFromEnv(credentials);
+  const mux = await muxClient.createClient();
+  const response = await mux.get(
+    getShotsPath(assetId)
+  );
+  return await transformShotsResponse(response);
+}
+
+// src/workflows/engagement-insights.ts
+var aiMomentInsightSchema = z6.object({
+  hotspotIndex: z6.number(),
+  startMs: z6.number(),
+  endMs: z6.number(),
+  timestamp: z6.string(),
+  engagementScore: z6.number(),
+  insight: z6.string()
+});
+var aiOverallInsightSchema = z6.object({
+  summary: z6.string(),
+  trends: z6.array(z6.string())
+});
+var engagementInsightsSchema = z6.object({
+  momentInsights: z6.array(aiMomentInsightSchema),
+  overallInsight: aiOverallInsightSchema
+});
+var SYSTEM_PROMPT4 = dedent5`
+  <role>
+    You are a video engagement analyst specializing in understanding viewer behavior.
+    Your job is to explain why specific moments in videos have high or low engagement
+    based on visual content, audio/dialogue, and viewer watch patterns.
+  </role>
+
+  <context>
+    You will receive:
+    - Engagement data showing which segments are most/least re-watched (hotspots)
+    - Images at key timestamps (shot frames or thumbnails)
+    - Transcript with timestamps (if available)
+    - Overall engagement curve statistics
+
+    Engagement scores are normalized (0-1) where higher values indicate more re-watching.
+  </context>
+
+  <task>
+    For each engagement moment (hotspot), analyze:
+    1. What visual or audio content is present
+    2. Why viewers might find it engaging (or disengaging)
+    3. Observable patterns that correlate with engagement
+
+    Base your insights on OBSERVABLE EVIDENCE from visuals and transcript.
+  </task>
+
+  <constraints>
+    - Only describe what you can see in images or read in transcripts
+    - Do not fabricate details or make unsupported assumptions
+    - Correlate engagement scores with observable content
+    - Return structured data matching the requested schema exactly
+    - Each momentInsight MUST include the hotspotIndex from the input data
+  </constraints>
+
+  <quality_guidelines>
+    - Be specific: cite timestamps, visual elements, or transcript quotes
+    - Focus on patterns: "demonstration moments", "pacing changes", etc.
+    - Avoid generic statements like "interesting content"
+    - Connect engagement data to content features
+  </quality_guidelines>
+`;
+var AUDIO_ONLY_SYSTEM_PROMPT = dedent5`
+  <role>
+    You are a video engagement analyst specializing in understanding viewer behavior for audio content.
+    Your job is to explain why specific moments have high or low engagement based on audio/dialogue and viewer watch patterns.
+  </role>
+
+  <context>
+    You will receive:
+    - Engagement data showing which segments are most/least re-watched (hotspots)
+    - Transcript with timestamps
+    - Overall engagement curve statistics
+
+    Note: This is audio-only content with no visual elements.
+    Engagement scores are normalized (0-1) where higher values indicate more re-watching.
+  </context>
+
+  <task>
+    For each engagement moment (hotspot), analyze:
+    1. What audio content or dialogue is present
+    2. Why listeners might find it engaging (or disengaging)
+    3. Observable patterns that correlate with engagement
+
+    Base your insights on OBSERVABLE EVIDENCE from the transcript.
+  </task>
+
+  <constraints>
+    - Only describe what you can read in the transcript
+    - Do not fabricate details or make unsupported assumptions
+    - Correlate engagement scores with observable content
+    - Return structured data matching the requested schema exactly
+    - Each momentInsight MUST include the hotspotIndex from the input data
+  </constraints>
+
+  <quality_guidelines>
+    - Be specific: cite timestamps or transcript quotes
+    - Focus on patterns: "topic changes", "pacing", "dialogue style", etc.
+    - Avoid generic statements like "interesting content"
+    - Connect engagement data to content features
+  </quality_guidelines>
+`;
+var INSIGHT_GUIDELINES = dedent5`
+  Provide explanatory insights that describe WHY moments are engaging.
+  Focus on observable patterns and viewer behavior correlation.
+  Example: "The cooking demonstration at 2:15 has 3x average engagement
+  because it shows the key technique viewers are searching for."
+`;
+var engagementInsightsPromptBuilder = createPromptBuilder({
+  template: {
+    task: {
+      tag: "task",
+      content: "Analyze the engagement data and visual/audio content to generate insights."
+    },
+    insightGuidelines: {
+      tag: "insight_guidelines",
+      content: INSIGHT_GUIDELINES
+    },
+    outputFormat: {
+      tag: "output_format",
+      content: dedent5`
+        Return valid JSON matching the provided schema.
+        Include insights for each hotspot and overall engagement trends.
+        Each momentInsight must include the hotspotIndex matching the input.
+      `
+    },
+    visualContext: {
+      tag: "visual_context",
+      content: dedent5`
+        Images are provided for each hotspot timestamp.
+        A storyboard overview image may also be included showing the full video timeline.
+        Use visual evidence from these images to support your engagement analysis.
+      `
+    }
+  },
+  sectionOrder: ["task", "insightGuidelines", "visualContext", "outputFormat"]
+});
+function buildUserPrompt4(hotspots, transcriptSegments, heatmap, isAudioOnly) {
+  const hotspotData = hotspots.map((h, idx) => {
+    const transcript = transcriptSegments[idx]?.text || "(no transcript)";
+    const startTimestamp = secondsToTimestamp(h.startMs / 1e3);
+    const endTimestamp = secondsToTimestamp(h.endMs / 1e3);
+    return dedent5`
+        Hotspot ${idx} (hotspotIndex: ${idx}):
+        - Time Range: ${startTimestamp} - ${endTimestamp}
+        - Engagement Score: ${h.score.toFixed(2)} (0=low, 1=high)
+        - Transcript: "${transcript}"
+      `;
+  }).join("\n\n");
+  const heatmapData = dedent5`
+    Engagement Heatmap (${heatmap.length} values, each representing 1/${heatmap.length}th of the video, higher = more re-watches):
+    [${heatmap.map((v) => v.toFixed(2)).join(", ")}]
+  `;
+  const contextSections = [
+    {
+      tag: "engagement_hotspots",
+      content: hotspotData
+    },
+    {
+      tag: "heatmap_analysis",
+      content: heatmapData
+    }
+  ];
+  const visualContextOverride = isAudioOnly ? { visualContext: "" } : {};
+  return engagementInsightsPromptBuilder.buildWithContext(
+    { ...visualContextOverride },
+    contextSections
+  );
+}
+function extractTranscriptSegmentsForHotspots(vttContent, hotspots) {
+  if (!vttContent.trim()) {
+    return [];
+  }
+  const cues = parseVTTCues(vttContent);
+  return hotspots.map((hotspot) => {
+    const startSec = hotspot.startMs / 1e3;
+    const endSec = hotspot.endMs / 1e3;
+    const relevantCues = cues.filter(
+      (cue) => cue.startTime < endSec && cue.endTime > startSec
+    );
+    const text = relevantCues.map((c) => c.text).join(" ");
+    return {
+      startMs: hotspot.startMs,
+      endMs: hotspot.endMs,
+      text,
+      timestamp: secondsToTimestamp(startSec)
+    };
+  });
+}
+function mapShotsToHotspots(shots, hotspots) {
+  const validShots = shots.filter((s) => s.imageUrl);
+  if (validShots.length === 0) {
+    return [];
+  }
+  return hotspots.map((hotspot) => {
+    const startSec = hotspot.startMs / 1e3;
+    const endSec = hotspot.endMs / 1e3;
+    const midpoint = (startSec + endSec) / 2;
+    const inRange = validShots.filter(
+      (s) => s.startTime >= startSec && s.startTime <= endSec
+    );
+    if (inRange.length > 0) {
+      const closest = inRange.reduce(
+        (best, s) => Math.abs(s.startTime - midpoint) < Math.abs(best.startTime - midpoint) ? s : best
+      );
+      return closest.imageUrl;
+    }
+    const nearest = validShots.reduce(
+      (best, s) => Math.abs(s.startTime - startSec) < Math.abs(best.startTime - startSec) ? s : best
+    );
+    return nearest.imageUrl;
+  });
+}
+async function getThumbnailUrlsForHotspots(playbackId, hotspots, options = {}) {
+  const { width = 640, shouldSign = false, credentials } = options;
+  const baseUrl = getMuxThumbnailBaseUrl(playbackId);
+  const urlPromises = hotspots.map(async (h) => {
+    const time = Math.floor(h.startMs / 1e3);
+    if (shouldSign) {
+      return signUrl(baseUrl, playbackId, "thumbnail", { time, width }, credentials);
+    }
+    return `${baseUrl}?time=${time}&width=${width}`;
+  });
+  return Promise.all(urlPromises);
+}
+async function fetchEngagementData(assetId, options) {
+  "use step";
+  const { hotspotLimit, timeframe, credentials } = options;
+  const [peaks, valleys, heatmap] = await Promise.all([
+    getHotspotsForAsset(assetId, {
+      limit: hotspotLimit,
+      orderDirection: "desc",
+      timeframe,
+      credentials
+    }),
+    getHotspotsForAsset(assetId, {
+      limit: hotspotLimit,
+      orderDirection: "asc",
+      timeframe,
+      credentials
+    }),
+    getHeatmapForAsset(assetId, {
+      timeframe,
+      credentials
+    })
+  ]);
+  const allHotspots = [...peaks, ...valleys].sort((a, b) => a.startMs - b.startMs);
+  return {
+    hotspots: allHotspots,
+    heatmap
+  };
+}
+async function generateInsightsWithAI(provider, modelId, systemPrompt, userPrompt, imageUrls, credentials) {
+  "use step";
+  const model = await createLanguageModelFromConfig(provider, modelId, credentials);
+  const response = await withRetry(
+    () => generateText5({
+      model,
+      output: Output5.object({ schema: engagementInsightsSchema }),
+      experimental_telemetry: { isEnabled: true },
+      messages: [
+        {
+          role: "system",
+          content: systemPrompt
+        },
+        {
+          role: "user",
+          content: [
+            { type: "text", text: userPrompt },
+            ...imageUrls.map((url) => ({ type: "image", image: url }))
+          ]
+        }
+      ]
+    })
+  );
+  if (!response.output) {
+    throw new Error("AI returned empty or unparseable response");
+  }
+  return {
+    result: response.output,
+    usage: {
+      inputTokens: response.usage.inputTokens,
+      outputTokens: response.usage.outputTokens,
+      totalTokens: response.usage.totalTokens,
+      reasoningTokens: response.usage.reasoningTokens,
+      cachedInputTokens: response.usage.cachedInputTokens
+    }
+  };
+}
+async function generateEngagementInsights(assetId, options = {}) {
+  "use workflow";
+  const {
+    provider = "openai",
+    model,
+    hotspotLimit = 5,
+    timeframe = "7:days",
+    credentials,
+    skipShots = false
+  } = options;
+  if (!Number.isInteger(hotspotLimit) || hotspotLimit < 1 || hotspotLimit > 10) {
+    throw new Error("hotspotLimit must be an integer between 1 and 10");
+  }
+  const modelConfig = resolveLanguageModelConfig({
+    ...options,
+    model,
+    provider
+  });
+  const { asset, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
+  const assetDurationSeconds = getAssetDurationSecondsFromAsset(asset);
+  if (!assetDurationSeconds) {
+    throw new Error(`Asset ${assetId} has no valid duration`);
+  }
+  const audioOnly = isAudioOnlyAsset(asset);
+  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."
+    );
+  }
+  const shouldSign = policy === "signed";
+  const shouldFetchShots = !skipShots && !audioOnly;
+  let shotsPromise;
+  if (shouldFetchShots) {
+    shotsPromise = getShotsForAsset(assetId, { credentials });
+  } else {
+    shotsPromise = Promise.resolve(null);
+  }
+  let storyboardPromise;
+  if (!audioOnly) {
+    storyboardPromise = getStoryboardUrl(playbackId, 640, shouldSign, credentials);
+  } else {
+    storyboardPromise = Promise.resolve(null);
+  }
+  const [engagementResult, shotsResult, transcriptResult, storyboardResult] = await Promise.allSettled([
+    fetchEngagementData(assetId, { hotspotLimit, timeframe, credentials }),
+    shotsPromise,
+    fetchTranscriptForAsset(asset, playbackId, {
+      cleanTranscript: false,
+      shouldSign,
+      credentials
+    }),
+    storyboardPromise
+  ]);
+  if (engagementResult.status === "rejected") {
+    throw new Error(
+      `Failed to fetch engagement data for asset ${assetId}: ${engagementResult.reason}`
+    );
+  }
+  const { hotspots, heatmap } = engagementResult.value;
+  if (hotspots.length === 0) {
+    throw new Error(
+      `No engagement data available for asset ${assetId} in timeframe ${timeframe}. Video may not have been viewed yet or engagement tracking is not enabled.`
+    );
+  }
+  let transcriptText = "";
+  if (transcriptResult.status === "fulfilled") {
+    transcriptText = transcriptResult.value.transcriptText || "";
+  }
+  if (!transcriptText.trim()) {
+    console.warn(
+      `No transcript available for asset ${assetId}. Insights will be based solely on visual analysis and engagement patterns.`
+    );
+  }
+  const transcriptSegments = extractTranscriptSegmentsForHotspots(transcriptText, hotspots);
+  let imageUrls = [];
+  if (audioOnly) {
+    console.warn(
+      `Asset ${assetId} is audio-only. Insights will be based solely on transcript and engagement data without visual analysis.`
+    );
+  } else {
+    if (shotsResult.status === "fulfilled" && shotsResult.value?.status === "completed") {
+      const shotImageUrls = mapShotsToHotspots(shotsResult.value.shots, hotspots);
+      if (shotImageUrls.length > 0) {
+        imageUrls = shotImageUrls;
+      }
+    }
+    if (imageUrls.length === 0) {
+      if (shouldFetchShots && shotsResult.status === "fulfilled" && shotsResult.value?.status !== "completed") {
+        console.warn(
+          `Shots not ready for asset ${assetId} (status: ${shotsResult.value?.status}). Falling back to thumbnails.`
+        );
+      } else if (shouldFetchShots && shotsResult.status === "rejected") {
+        console.warn(
+          `Shots fetch failed for asset ${assetId}. Falling back to thumbnails.`
+        );
+      }
+      imageUrls = await getThumbnailUrlsForHotspots(playbackId, hotspots, {
+        shouldSign,
+        credentials
+      });
+    }
+    if (storyboardResult.status === "fulfilled" && storyboardResult.value) {
+      imageUrls.push(storyboardResult.value);
+    }
+  }
+  const systemPrompt = audioOnly ? AUDIO_ONLY_SYSTEM_PROMPT : SYSTEM_PROMPT4;
+  const userPrompt = buildUserPrompt4(
+    hotspots,
+    transcriptSegments,
+    heatmap.heatmap,
+    audioOnly
+  );
+  const { result: aiInsights, usage } = await generateInsightsWithAI(
+    modelConfig.provider,
+    modelConfig.modelId,
+    systemPrompt,
+    userPrompt,
+    imageUrls,
+    credentials
+  );
+  if (!aiInsights.momentInsights || aiInsights.momentInsights.length === 0) {
+    throw new Error("Failed to generate insights from AI response");
+  }
+  const momentInsights = [];
+  for (const aiMoment of aiInsights.momentInsights) {
+    const idx = aiMoment.hotspotIndex;
+    if (idx < 0 || idx >= hotspots.length) {
+      console.warn(
+        `AI returned hotspotIndex ${idx} which is out of range (0-${hotspots.length - 1}). Skipping.`
+      );
+      continue;
+    }
+    const hotspot = hotspots[idx];
+    momentInsights.push({
+      startMs: hotspot.startMs,
+      endMs: hotspot.endMs,
+      timestamp: secondsToTimestamp(hotspot.startMs / 1e3),
+      engagementScore: hotspot.score,
+      insight: aiMoment.insight
+    });
+  }
+  if (momentInsights.length === 0) {
+    throw new Error(
+      "AI returned insights but none matched valid hotspot indices. This may indicate a prompt or model issue."
+    );
+  }
+  const usageWithMetadata = {
+    ...usage,
+    metadata: {
+      assetDurationSeconds,
+      thumbnailCount: imageUrls.length
+    }
+  };
+  return {
+    assetId,
+    momentInsights,
+    overallInsight: {
+      summary: aiInsights.overallInsight.summary,
+      trends: aiInsights.overallInsight.trends
+    },
+    usage: usageWithMetadata
+  };
+}
+
 // src/lib/sampling-plan.ts
 var DEFAULT_FPS = 30;
 function roundToNearestFrameMs(tsMs, fps = DEFAULT_FPS) {
@@ -3763,18 +4367,18 @@ async function getModerationScores(assetId, options = {}) {
 }
 
 // src/workflows/summarization.ts
-import { generateText as generateText5, Output as Output5 } from "ai";
-import dedent5 from "dedent";
-import { z as z6 } from "zod";
+import { generateText as generateText6, Output as Output6 } from "ai";
+import dedent6 from "dedent";
+import { z as z7 } from "zod";
 var DEFAULT_SUMMARY_KEYWORD_LIMIT = 10;
 var DEFAULT_TITLE_LENGTH = 10;
 var DEFAULT_DESCRIPTION_LENGTH = 50;
-var summarySchema = z6.object({
-  keywords: z6.array(z6.string()),
-  title: z6.string(),
-  description: z6.string()
+var summarySchema = z7.object({
+  keywords: z7.array(z7.string()),
+  title: z7.string(),
+  description: z7.string()
 }).strict();
-var SUMMARY_OUTPUT = Output5.object({
+var SUMMARY_OUTPUT = Output6.object({
   name: "summary_metadata",
   description: "Structured summary with title, description, and keywords.",
   schema: summarySchema
@@ -3790,36 +4394,36 @@ var DESCRIPTION_LENGTH_THRESHOLD_LARGE = 100;
 function buildDescriptionGuidance(wordCount, contentType) {
   if (wordCount < DESCRIPTION_LENGTH_THRESHOLD_SMALL) {
     if (contentType === "video") {
-      return dedent5`A brief summary of the video in no more than ${wordCount} words. Shorter is fine.
+      return dedent6`A brief summary of the video in no more than ${wordCount} words. Shorter is fine.
         Focus on the single most important subject or action.
         Write in present tense.`;
     }
-    return dedent5`A brief summary of the audio content in no more than ${wordCount} words. Shorter is fine.
+    return dedent6`A brief summary of the audio content in no more than ${wordCount} words. Shorter is fine.
       Focus on the single most important topic or theme.
       Write in present tense.`;
   }
   if (wordCount > DESCRIPTION_LENGTH_THRESHOLD_LARGE) {
     if (contentType === "video") {
-      return dedent5`A detailed summary that describes what happens across the video.
+      return dedent6`A detailed summary that describes what happens across the video.
         Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
         Be thorough: cover subjects, actions, setting, progression, and any notable details visible across frames.
         Write in present tense. Be specific about observable details rather than making assumptions.
         If the transcript provides dialogue or narration, incorporate key points but prioritize visual content.`;
     }
-    return dedent5`A detailed summary that describes the audio content.
+    return dedent6`A detailed summary that describes the audio content.
       Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
       Be thorough: cover topics, speakers, themes, progression, and any notable insights.
       Write in present tense. Be specific about what is discussed or presented rather than making assumptions.
       Focus on the spoken content and any key insights, dialogue, or narrative elements.`;
   }
   if (contentType === "video") {
-    return dedent5`A summary that describes what happens across the video.
+    return dedent6`A summary that describes what happens across the video.
       Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
       Cover the main subjects, actions, setting, and any notable progression visible across frames.
       Write in present tense. Be specific about observable details rather than making assumptions.
       If the transcript provides dialogue or narration, incorporate key points but prioritize visual content.`;
   }
-  return dedent5`A summary that describes the audio content.
+  return dedent6`A summary that describes the audio content.
     Never exceed ${wordCount} words, but shorter is perfectly fine. You may use multiple sentences.
     Cover the main topics, speakers, themes, and any notable progression in the discussion or narration.
     Write in present tense. Be specific about what is discussed or presented rather than making assumptions.
@@ -3836,7 +4440,7 @@ function createSummarizationBuilder({ titleLength, descriptionLength, tagCount }
       },
       title: {
         tag: "title_requirements",
-        content: dedent5`
+        content: dedent6`
           A concise, label-style title — not a sentence or description.
           Never exceed ${titleLimit} words, but shorter is better.
           Think of how a video card title, playlist entry, or file name would read — e.g. "Predator: Badlands Trailer" or "Chef Prepares Holiday Feast".
@@ -3849,7 +4453,7 @@ function createSummarizationBuilder({ titleLength, descriptionLength, tagCount }
       },
       keywords: {
         tag: "keywords_requirements",
-        content: dedent5`
+        content: dedent6`
           Specific, searchable terms (up to ${keywordLimit}) that capture:
           - Primary subjects (people, animals, objects)
           - Actions and activities being performed
@@ -3861,7 +4465,7 @@ function createSummarizationBuilder({ titleLength, descriptionLength, tagCount }
       },
       qualityGuidelines: {
         tag: "quality_guidelines",
-        content: dedent5`
+        content: dedent6`
           - Examine all frames to understand the full context and progression
           - Be precise: "golden retriever" is better than "dog" when identifiable
           - Capture the narrative: what begins, develops, and concludes
@@ -3882,7 +4486,7 @@ function createAudioOnlyBuilder({ titleLength, descriptionLength, tagCount } = {
       },
       title: {
         tag: "title_requirements",
-        content: dedent5`
+        content: dedent6`
           A concise, label-style title — not a sentence or description.
           Never exceed ${titleLimit} words, but shorter is better.
           Think of how a podcast episode title or playlist entry would read — e.g. "Weekly News Roundup" or "Interview with Dr. Smith".
@@ -3895,7 +4499,7 @@ function createAudioOnlyBuilder({ titleLength, descriptionLength, tagCount } = {
       },
       keywords: {
         tag: "keywords_requirements",
-        content: dedent5`
+        content: dedent6`
           Specific, searchable terms (up to ${keywordLimit}) that capture:
           - Primary topics and themes
           - Speakers or presenters (if named)
@@ -3907,7 +4511,7 @@ function createAudioOnlyBuilder({ titleLength, descriptionLength, tagCount } = {
       },
       qualityGuidelines: {
         tag: "quality_guidelines",
-        content: dedent5`
+        content: dedent6`
           - Analyze the full transcript to understand context and themes
           - Be precise: use specific terminology when mentioned
           - Capture the narrative: what is introduced, discussed, and concluded
@@ -3917,7 +4521,7 @@ function createAudioOnlyBuilder({ titleLength, descriptionLength, tagCount } = {
     sectionOrder: ["task", "title", "description", "keywords", "qualityGuidelines"]
   });
 }
-var SYSTEM_PROMPT4 = dedent5`
+var SYSTEM_PROMPT5 = dedent6`
   <role>
     You are a video content analyst specializing in storyboard interpretation and multimodal analysis.
   </role>
@@ -3974,7 +4578,7 @@ var SYSTEM_PROMPT4 = dedent5`
 
     Write as if describing reality, not describing a recording of reality.
   </language_guidelines>`;
-var AUDIO_ONLY_SYSTEM_PROMPT = dedent5`
+var AUDIO_ONLY_SYSTEM_PROMPT2 = dedent6`
   <role>
     You are an audio content analyst specializing in transcript analysis and metadata generation.
   </role>
@@ -4028,7 +4632,7 @@ var AUDIO_ONLY_SYSTEM_PROMPT = dedent5`
 
     Write as if describing reality, not describing a recording of reality.
   </language_guidelines>`;
-function buildUserPrompt4({
+function buildUserPrompt5({
   tone,
   transcriptText,
   isCleanTranscript = true,
@@ -4059,7 +4663,7 @@ function buildUserPrompt4({
 async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, systemPrompt, credentials) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const response = await generateText5({
+  const response = await generateText6({
     model,
     output: SUMMARY_OUTPUT,
     messages: [
@@ -4094,7 +4698,7 @@ async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, s
 async function analyzeAudioOnly(provider, modelId, userPrompt, systemPrompt, credentials) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const response = await generateText5({
+  const response = await generateText6({
     model,
     output: SUMMARY_OUTPUT,
     messages: [
@@ -4197,7 +4801,7 @@ async function getSummaryAndTags(assetId, options) {
   const transcriptText = transcriptResult?.transcriptText ?? "";
   const resolvedLanguageCode = outputLanguageCode && outputLanguageCode !== "auto" ? outputLanguageCode : transcriptResult?.track?.language_code ?? getReadyTextTracks(assetData)[0]?.language_code;
   const languageName = resolvedLanguageCode ? getLanguageName(resolvedLanguageCode) : void 0;
-  const userPrompt = buildUserPrompt4({
+  const userPrompt = buildUserPrompt5({
     tone,
     transcriptText,
     isCleanTranscript: cleanTranscript,
@@ -4210,7 +4814,7 @@ async function getSummaryAndTags(assetId, options) {
   });
   let analysisResponse;
   let imageUrl;
-  const systemPrompt = isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT : SYSTEM_PROMPT4;
+  const systemPrompt = isAudioOnly ? AUDIO_ONLY_SYSTEM_PROMPT2 : SYSTEM_PROMPT5;
   try {
     if (isAudioOnly) {
       analysisResponse = await analyzeAudioOnly(
@@ -4683,24 +5287,24 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
 // src/workflows/translate-captions.ts
 import {
   APICallError,
-  generateText as generateText6,
+  generateText as generateText7,
   NoObjectGeneratedError,
-  Output as Output6,
+  Output as Output7,
   RetryError,
   TypeValidationError
 } from "ai";
-import dedent6 from "dedent";
-import { z as z7 } from "zod";
-var translationSchema = z7.object({
-  translation: z7.string()
+import dedent7 from "dedent";
+import { z as z8 } from "zod";
+var translationSchema = z8.object({
+  translation: z8.string()
 });
-var SYSTEM_PROMPT5 = dedent6`
+var SYSTEM_PROMPT6 = dedent7`
   You are a subtitle translation expert. Translate VTT subtitle files to the target language specified by the user.
   You may receive either a full VTT file or a chunk from a larger VTT.
   Preserve all timestamps, cue ordering, and VTT formatting exactly as they appear.
   Return JSON with a single key "translation" containing the translated VTT content.
 `;
-var CUE_TRANSLATION_SYSTEM_PROMPT = dedent6`
+var CUE_TRANSLATION_SYSTEM_PROMPT = dedent7`
   You are a subtitle translation expert.
   You will receive a sequence of subtitle cues extracted from a VTT file.
   Translate the cues to the requested target language while preserving their original order.
@@ -4872,13 +5476,13 @@ async function translateVttWithAI({
 }) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const response = await generateText6({
+  const response = await generateText7({
     model,
-    output: Output6.object({ schema: translationSchema }),
+    output: Output7.object({ schema: translationSchema }),
     messages: [
       {
         role: "system",
-        content: SYSTEM_PROMPT5
+        content: SYSTEM_PROMPT6
       },
       {
         role: "user",
@@ -4909,8 +5513,8 @@ async function translateCueChunkWithAI({
 }) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const schema = z7.object({
-    translations: z7.array(z7.string().min(1)).length(cues.length)
+  const schema = z8.object({
+    translations: z8.array(z8.string().min(1)).length(cues.length)
   });
   const cuePayload = cues.map((cue, index) => ({
     index,
@@ -4918,9 +5522,9 @@ async function translateCueChunkWithAI({
     endTime: cue.endTime,
     text: cue.text
   }));
-  const response = await generateText6({
+  const response = await generateText7({
     model,
-    output: Output6.object({ schema }),
+    output: Output7.object({ schema }),
     messages: [
       {
         role: "system",
@@ -5271,12 +5875,15 @@ export {
   chaptersSchema,
   createReplacer,
   editCaptions,
+  extractTranscriptSegmentsForHotspots,
   generateChapters,
   generateEmbeddings,
+  generateEngagementInsights,
   generateVideoEmbeddings,
   getModerationScores,
   getSummaryAndTags,
   hasBurnedInCaptions,
+  mapShotsToHotspots,
   profanityDetectionSchema,
   questionAnswerSchema,
   shouldSplitChunkTranslationError,