Skip to content

Presentation Video Workflow

Last refreshed: 2026-07-28

Current User Flow

The active product flow lives under src/app/(frontend)/app/create/presentation, src/app/(frontend)/app/videos, and src/app/(frontend)/app/videos/[id].

Server-side behavior is concentrated in src/app/(frontend)/app/presentation/actions.ts, with list/detail helpers in src/app/(frontend)/app/videos/actions.ts.

flowchart LR
  setup["🧾 Create presentation"] --> voPreview["🎙️ Generate VO preview via narrativeWorkflow"]
  voPreview --> review["Human review boundary"]
  review --> scenes["🎞️ Go To Scene Details"]
  scenes --> preview["👁️ Preview config"]
  scenes --> imageQueue["🖼️ Queue scene image generation"]
  imageQueue --> worker["⚙️ presentation-worker"]
  worker --> preview["👁️ Preview config"]
  preview --> sceneEdits["✏️ Edit scenes"]
  sceneEdits --> editAgents["editAgent / visualAgent helpers"]
  editAgents --> sceneEdits
  sceneEdits --> preview
  preview --> audio["🔊 Queue or generate audio"]
  audio --> final["📤 Generate final video handoff"]

Main Server Actions

  • generatePresentationDescription: creates an initial setup-ready brief using code-owned prompt builders.
  • generatePresentationNarrativePreview: starts presentationVideoWorkflow through the preview-only narrative path, persists transient review metadata, and returns the VO script preview plus the approved preview script artifact.
  • continuePresentationFromNarrative: resumes the suspended workflow after VO review and selected visual identity, runs post-approval narrative expansion, then continues into visuals, slides, direction, compile, persistence, job creation, and optional audio.
  • generatePresentationConfig: compatibility scene/config generation path with code-owned prompt builders.
  • generatePresentationVideoScenesWithWorkflow: compatibility workflow-backed scene generation path that auto-approves the narrative boundary for older callers.
  • queuePresentationAudioGeneration: queues or prepares scene audio work.
  • previewPresentationConfig: rebuilds preview config and readiness state.
  • generatePresentationVideo: creates final generation/render handoff.
  • updatePresentationScene: edits persisted scene data.
  • generatePresentationSceneAudioDraft: creates temporary draft TTS audio for the Step 3 voiceover popup without mutating the scene.
  • discardPresentationSceneVoiceoverDraft: deletes abandoned temporary popup audio.
  • commitPresentationSceneVoiceoverDraft: commits popup draft text/audio into the persisted scene and marks preview stale.
  • listPresentationSceneVisualOptions: returns selectable visual options.
  • refinePresentationSceneVoiceover, refinePresentationSceneCaption, regeneratePresentationSceneImage, generatePresentationSceneAudio: per-scene assistants backed by editAgent, visualAgent, or deterministic TTS/audio helpers.

Presentation Video no longer reads prompt text from Payload prompt records. Prompt ownership is in Mastra agent definitions, workflow prompt builders, and src/mastra/tools/presentation/prompt-builders.ts.

Scene visuals follow an image-generation-first path. Scene generation persists visualGenerationPrompt for image-capable scenes, queues presentation_generation_jobs, and the presentation worker calls the Image Gen model asynchronously. Setup-stage visual upload/select is not part of the create flow. Uploaded visuals remain available for manual replacement in Scene Editor.

Mastra Workflow Sequence

src/mastra/workflows/presentationvideo.workflow.ts defines presentationVideoWorkflow.

Current sequence:

  1. prepare-presentation-run: creates or updates Payload presentation state and ingests external web source descriptions.
  2. intake: either skips IntentAgent and derives a deterministic VideoDescriptionBrief from explicit setup inputs, or runs IntentAgent when the request still needs interpretation.
  3. ragWorkflow: either skips KnowledgeOrchestrator for uploaded-only runs or plans and collects knowledge for mixed/remote source sets.
  4. persisted-rag-context: merges persisted Payload RAG chunks.
  5. narrativePreviewWorkflow: generates and normalizes a preview-only VoiceoverScriptJson.
  6. narrative-review: persists presentationStatusJson.setup.narrativeReview with the approved preview script and suspends for user approval.
  7. narrativeExpansionWorkflow: expands the approved preview script into NarrativeSceneDetails after resume.
  8. visualsWorkflow: creates generated-image visual strategy, including recommendedVisualType and visualGenerationPrompt.
  9. slidesWorkflow: analyzes narrative and builds typed, complementary Main, Companion, and Emphasis plans.
  10. directionWorkflow: applies deterministic camera direction and optional refinement.
  11. compile: compiles the validated PresentationConfig v2 workflow input.
  12. persist-scenes: writes presentation_scenes.
  13. assign-visuals: queues generated images for scenes that need visuals.
  14. persist-compilation: validates and appends an immutable Bento aggregate revision.
  15. audio: returns deferred audio plan or generates TTS.
  16. finalize: saves final handoff and queues presentation_generation_jobs.
flowchart TD
  prepare["prepare-presentation-run"] --> intake["intake"]
  intake --> intakeGate{"Skip IntentAgent?"}
  intakeGate -->|Yes| rag["ragWorkflow"]
  intakeGate -->|No| intent["intent-agent"]
  intent --> rag
  rag --> persistedRag["persisted-rag-context"]
  persistedRag --> preview["narrativePreviewWorkflow"]
  preview --> review["narrative-review suspend"]
  review --> uiPreview["VO Script Preview"]
  uiPreview --> resume["Go To Scene Details resume"]
  resume --> expand["narrativeExpansionWorkflow"]
  expand --> visuals["visualsWorkflow"]
  visuals --> slides["slidesWorkflow"]
  slides --> direction["directionWorkflow"]
  direction --> compile["compile"]
  compile --> persistScenes["persist-scenes"]
  persistScenes --> assignVisuals["assign-visuals / queue image prompts"]
  assignVisuals --> imageWorker["presentation-worker Image Gen"]
  assignVisuals --> persistCompilation["persist-compilation"]
  imageWorker --> sceneImages["generated scene images"]
  persistCompilation --> audio["audio"]
  audio --> finalize["finalize"]

Generated Artifacts

Canonical workflow artifact names are in src/lib/anuva/workflow-graph.ts:

  • intentBrief
  • knowledgeContext
  • sceneModels
  • visualStrategy
  • slidePlan
  • slideDeck
  • sceneDirection
  • compiledConfig
  • voiceoverAudio
  • renderJob
  • finalPresentation

Human-In-The-Loop Boundaries

narrative-review is the first explicit HITL boundary in the create flow. Users review a preview-only VoiceoverScriptJson before downstream scene-detail generation runs. Newly persisted review state now stores the approved preview script instead of a richer semantic scene package, and post-approval expansion treats the approved sentences as hard input. Scene edits can still mark preview and audio state stale. Users must regenerate the relevant preview/audio artifacts before final video generation becomes valid again. This behavior is covered by integration and e2e tests.

Step 3 Edit Loop

Step 3 now treats popup voiceover regeneration as a temporary draft flow instead of mutating the scene immediately.

Step 3 also exposes the exact Bento editor after simple scene edits have been compiled. The host loads the full latest accepted aggregate, focuses the selected scene's stable Main slide, and preserves all three surface documents in one session. Manual save and debounced autosave append immutable revisions; dirty or conflicted editor state remains a user-scoped recoverable draft.

The saved-revision preview uses three exact-player iframes driven by one absolute clock. It never previews an unaccepted editor draft. Generating slides from scene-plan controls is disabled while local simple edits are pending; a future generated recompilation over an editor-authored revision must retain an explicit replacement warning rather than silently discarding Bento work.

  • Voiceover text edits inside the popup remain local until Done.
  • Generate Audio in the popup creates a temporary ElevenLabs clip from the current draft text.
  • Re-generating inside the popup discards the previous temporary clip and replaces it.
  • Canceling the popup discards the temporary clip and preserves the previously committed scene.
  • Clicking Done commits the new text/audio to the scene, marks preview stale, and defers config recompilation until Generate Slides Preview.
  • Generate VO Audio still regenerates only missing or dirty scenes, but scene timing now prefers actual TTS word timings when available and appends a new compilation revision.
flowchart TD
  sceneEditor["Step 3 scene editor"] --> popup["Edit Voiceover popup"]
  popup --> draftAudio["Temporary ElevenLabs audio draft"]
  draftAudio --> cancel["Cancel: discard temp clip"]
  draftAudio --> done["Done: commit scene text/audio"]
  done --> stale["presentationStatusJson.previewReady = false"]
  stale --> preview["Generate Slides Preview"]
  preview --> config["immutable presentation_compilations revision"]
  config --> deferred["Generate VO Audio for dirty or missing scenes"]

Readiness Rules

Final generation depends on current persisted scene state, preview compilation state, and audio readiness. The UI must not treat stale scenes as render-ready.

Before final handoff, the current aggregate is revalidated against the vendored Bento contract and exact CMS consumer compatibility. The render job snapshots that revision and its render settings. Package-relative content-addressed assets remain immutable; signed worker download URLs are issued separately.