Skip to content

Presentation Video Step 3 Change Breakdown

Created: 2026-05-26 02:46 UTC

Summary

This change updates the Step 3 scene editor so scene-level timing, voiceover, visual overrides, and preview recompilation behave as a single coherent authoring loop. The main outcomes are:

  • expose editable pauseSeconds per scene
  • regenerate and replace ElevenLabs voiceover audio from the scene voiceover editor
  • keep PresentationConfig.json timing and word-level metadata in sync after audio generation
  • ensure scene visual override changes are reflected when Generate Slides Preview recompiles the config
  • remove Why This Visual
  • restyle the scene editor to match the new desktop layout and a vertical mobile flow with a sticky preview visual

The current implementation already has most of the primitives, but they are split across client state, scene documents, and compilation steps. The requested behavior requires tightening those boundaries so Step 3 edits reliably flow into the latest compiled presentation state.

Target Flow

flowchart TD
  select["Select scene"] --> preview["Preview visual"]
  preview --> pause["Edit pauseSeconds"]
  preview --> text["Review voiceover and caption"]
  text --> popup["Edit Voiceover popup"]
  popup --> regen["Generate Audio from current draft"]
  regen --> play["Play regenerated clip in popup"]
  play --> done{"Done?"}
  done -->|Yes| persist["Persist new text/audio to scene"]
  done -->|No| discard["Keep previous saved scene state"]

  persist --> previewCompile["Generate Slides Preview"]
  visual["Select or upload scene visual override"] --> previewCompile
  pause --> previewCompile
  text --> previewCompile
  previewCompile --> config["Recompile PresentationConfig.json"]
  config --> synced["Updated scene timing, duration, words, and overrides"]

  synced --> deferred["Generate VO Audio for dirty or missing scenes"]
  deferred --> config

Current Touchpoints

  • src/components/anuvax/presentation-video/presentation-video-page.tsx Owns the Step 3 scene list, desktop/mobile editor layouts, voiceover dialog, preview buttons, scene visual override actions, and client dirty-state tracking.
  • src/app/(frontend)/app/presentation/actions.ts Owns scene persistence, scene-level voiceover refinement, scene-level audio generation, preview recompilation, deferred audio generation, and public config compilation.
  • src/lib/presentation-config/schema.ts Defines the public config timing and voiceover schema, including pauseSeconds and audio duration fields.
  • src/lib/render-worker/service.ts Consumes compiled timing and audio duration data during render duration calculations.
  • tests/integration/helpers/mock-runtime.ts, tests/integration/render-worker-api.integration.test.ts, tests/unit/anuva-orchestration-service.test.ts Already encode assumptions around pauseSeconds, duration, and stale-preview behavior that will likely need updates or extension.

Current Behavior Snapshot

  • The scene UI already carries pauseSeconds in client state, but Step 3 does not expose any editable input for it.
  • Generate Slides Preview calls previewPresentationConfig, which recomputes camera/scene timing and creates a new compilation from persisted scene data.
  • Generate VO Audio currently queues bulk audio generation for missing or dirty scene audio and then refreshes the compilation snapshot before video generation.
  • The Edit Voiceover dialog currently lets the user change local text and click Generate Audio, but the current generate-audio action reads the saved scene text, not the unsaved dialog draft.
  • The popup includes a Play button visually, but the current dialog wiring does not yet provide the full replace-and-preview workflow requested.
  • Scene visual overrides already mark the scene compiler state dirty, but the breakdown needs to preserve that behavior explicitly when preview recompiles.
  • Why this visual? still renders on both desktop and mobile when selectedScene.explainability exists.

Grouped Changes

1. Scene timing controls

Expose pauseSeconds as an editable float field in the scene editor for each scene.

Explanation:

The client scene model already tracks pauseSeconds, playback uses it when auto-advancing scenes, and the public config schema supports it. What is missing is Step 3 editing, persistence, validation, and a clear rule for how pause changes mark a scene and preview as stale.

Likely affected code:

  • src/components/anuvax/presentation-video/presentation-video-page.tsx
  • src/app/(frontend)/app/presentation/actions.ts
  • src/lib/presentation-config/schema.ts
  • tests/integration/helpers/mock-runtime.ts

2. Post-audio timing and word-sync refresh

Ensure PresentationConfig.json reflects actual post-TTS metadata after ElevenLabs generation, including:

  • scenes.timing.start
  • scenes.timing.end
  • scenes.voiceover.audio.durationSeconds
  • scenes.voiceover.words
  • scenes.voiceover.words.start
  • scenes.voiceover.words.end

Explanation:

The server already stores actual word timings and scene audio assets, and preview compilation already rebuilds the public config from scene records. The gap is that scene-level and bulk audio generation do not yet guarantee an immediate, user-visible refresh of compiled timing metadata at the moments described in the request. The implementation plan will need to define when recompilation happens automatically versus when Step 3 remains dirty until Generate Slides Preview is clicked.

Likely affected code:

  • src/app/(frontend)/app/presentation/actions.ts Relevant areas: buildPublicConfig, previewPresentationConfig, queuePresentationAudioGeneration, generatePresentationSceneAudio, generatePresentationVideo
  • src/lib/render-worker/service.ts
  • tests/integration/render-worker-api.integration.test.ts

3. Voiceover editor popup regeneration workflow

Make the Edit Voiceover popup the source of truth for draft voiceover edits, audio regeneration, audio preview, clip replacement, and final commit on Done.

Explanation:

The requested behavior is stronger than the current flow. Right now the dialog can edit local text, but the audio-generation action still operates on the saved scene text, and the replacement lifecycle for prior clips is not clearly modeled. The change likely needs a draft-aware server action or a two-phase commit model so the popup can generate audio from the unsaved text, play the new clip immediately, and only promote the clip to the saved scene state when the user confirms.

Likely affected code:

  • src/components/anuvax/presentation-video/presentation-video-page.tsx
  • src/app/(frontend)/app/presentation/actions.ts Relevant areas: updatePresentationScene, refinePresentationSceneVoiceover, generatePresentationSceneAudio
  • Possible cleanup logic for replaced voiceover_audio_assets
  • Integration coverage around save/cancel/regenerate flows

4. Scene visual override persistence and preview recompilation

Ensure scene image override uploads and selections are reflected in PresentationConfig.json once the user clicks Generate Slides Preview, and ensure preview recompilation includes all scene-related edits together.

Explanation:

The current updatePresentationScene action already flips the scene compiler state to dirty for image/video override changes. The implementation work here is less about adding a new concept and more about making the preview recompilation contract explicit and reliable for all scene edits, including caption, voiceover, pause timing, and override changes in one pass.

Likely affected code:

  • src/components/anuvax/presentation-video/presentation-video-page.tsx
  • src/app/(frontend)/app/presentation/actions.ts Relevant areas: updatePresentationScene, previewPresentationConfig, markPresentationPreviewStale
  • docs/core/PresentationConfig.md
  • docs/core/PresentationVideoWorkflow.md

5. Scene editor layout refresh and explainability removal

Rework the Step 3 layout to match the supplied mockup and remove Why This Visual from both desktop and mobile.

Explanation:

The current Step 3 view is still built as separate desktop and mobile layouts with a relatively short mobile preview and bottom action stack. The requested layout keeps the preview visual more central, aligns the form content vertically beside it on desktop, and shifts mobile to a vertical authoring flow with a sticky preview visual. The removal of Why This Visual should be handled as both a UI cleanup and a signal that explainability text is no longer part of the Step 3 authoring surface.

Likely affected code:

  • src/components/anuvax/presentation-video/presentation-video-page.tsx
  • Possibly shared scene-editor styling in related UI primitives
  • Route-level or interaction tests for mobile layout and visible controls

Affected Product Surfaces

  • Presentation Step 3 scene editor UI
  • Scene-level voiceover editing popup
  • Scene-level visual override flow
  • Scene preview compilation and stale-state handling
  • Deferred bulk voiceover generation
  • Render timing that depends on compiled voiceover duration and pause values

Likely Affected Docs

  • docs/core/PresentationVideoWorkflow.md
  • docs/core/PresentationConfig.md
  • docs/state/CurrentImplementationMap.md
  • docs/state/ServerActionsMap.md
  • docs/state/WorkflowMap.md
  • docs/state/KnownGaps.md
  • docs/changes/2026-05-26-0246-presentation-video-step-3/ImplementationPlan.md
  • docs/changes/2026-05-26-0246-presentation-video-step-3/ImplementationLog.md

Risks And Dependencies

  • Popup-generated voiceover audio currently does not have a clean draft-versus-saved lifecycle. Without a clear commit/discard model, the UI can easily orphan audio assets or persist text/audio mismatches.
  • voiceoverDurationSec is currently derived with an estimator even after ElevenLabs generation in some paths. If actual timing should become authoritative, the plan must define how duration is sourced and normalized.
  • Recompiling after audio generation can create more compilation records and status churn than the current flow. The plan should define whether every scene-level audio regeneration creates a new compilation or only updates scene state until preview is regenerated.
  • Exposing pauseSeconds as a float requires validation and UX decisions around precision, minimum/maximum values, and whether the last scene pause matters.
  • The current Step 3 component has separate desktop/mobile trees. Layout changes can drift if both branches are updated inconsistently.
  • Removing Why This Visual from the UI should not accidentally break any downstream logic that still uses whyThisVisual internally for generated images or audit trails.

Out Of Scope

  • Changing the Step 1 or Step 2 presentation setup flow
  • Redesigning the final video player, render worker, or YouTube upload flow
  • Reworking narrative generation, scene generation, or non-Step-3 Mastra workflows beyond what is needed to keep compiled scene data in sync
  • Replacing the scene caption AI assistant pattern
  • Broad Payload schema redesign unless the implementation plan proves new temporary draft persistence is unavoidable

Open Questions

Q1. Should pauseSeconds be editable for every scene including the final scene, or should the last scene ignore pause because no next scene follows it?

Answer: Make it editable for for every scene including the final scene

Q2. When the user clicks Generate Audio inside the popup, should the regenerated clip remain a temporary draft until Done, or should it immediately replace the saved scene audio even before confirmation?

Answer: The regenerated clip should remain a temporary draft until Done

Q3. If the user generates a new clip in the popup and then clicks Cancel, should the previous saved clip remain active and the newly generated draft clip be discarded?

Answer: Yes, the previous saved clip should remain active and the newly generated draft clip should be discarded

Q4. After a successful popup audio regeneration and Done, should the app immediately create a fresh compilation snapshot, or should it only mark the scene dirty and wait for Generate Slides Preview to recompile?

Answer: It should only mark the scene dirty and wait for Generate Slides Preview to recompile

Q5. For the bulk Generate VO Audio button, should it regenerate only scenes with missing/dirty audio, or should it force-regenerate all scene audio after any scene edit?

Answer: It should regenerate only scenes with missing/dirty audio

Q6. On mobile, should the sticky preview visual stay pinned at the top of the scrolling editor form, or should it only remain sticky within the visible Step 3 editor pane beneath the scene list?

Answer: It should stay pinned at the top of the scrolling editor form

Q7. Is the intended desktop layout in the mockup a strict visual target, including the scene list width, preview width, and right-hand form grouping, or should it be treated as directional while preserving existing spacing tokens and components?

Answer: It should be treated as directional while preserving existing spacing tokens and components