video_translate/docs/plans/2026-03-17-export-preview-parity.md

Export Preview Parity Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Make exported videos match the editor preview for audio behavior, subtitle timing, and visible subtitle styling.

Architecture: Keep the editor preview as the source of truth and teach the export pipeline to consume the same state explicitly. Extract pure helpers for export payload building, subtitle timeline normalization, audio mix planning, and ASS subtitle generation so we can lock parity with tests before wiring FFmpeg.

Tech Stack: React 19, TypeScript, Express, FFmpeg, Vitest.

---

Task 1: Add Export Payload Builder Coverage

Files:

• Create: E:\Downloads\ai-video-dubbing-&-translation\src\lib\exportPayload.ts
• Create: E:\Downloads\ai-video-dubbing-&-translation\src\lib\exportPayload.test.ts
• Modify: E:\Downloads\ai-video-dubbing-&-translation\src\components\ExportModal.tsx
• Modify: E:\Downloads\ai-video-dubbing-&-translation\src\components\EditorScreen.tsx

Step 1: Write the failing test

Cover that export payloads include subtitle audio volume and global text styles.

Step 2: Run test to verify it fails

Run: node .\node_modules\vitest\vitest.mjs run src/lib/exportPayload.test.ts Expected: FAIL because the helper does not exist yet.

Step 3: Write minimal implementation

Create a small pure builder and wire ExportModal to use it. Pass textStyles from EditorScreen.

Step 4: Run test to verify it passes

Run: node .\node_modules\vitest\vitest.mjs run src/lib/exportPayload.test.ts Expected: PASS.

Task 2: Add Export Backend Planning Helpers

Files:

• Create: E:\Downloads\ai-video-dubbing-&-translation\src\server\exportVideo.ts
• Create: E:\Downloads\ai-video-dubbing-&-translation\src\server\exportVideo.test.ts

Step 1: Write the failing test

Cover:

1. Subtitle times shift by trimRange.start for export.
2. Original source audio is excluded when BGM is present.
3. Original source audio is kept at preview volume when BGM is absent.
4. ASS subtitle output reflects selected styles.

Step 2: Run test to verify it fails

Run: node .\node_modules\vitest\vitest.mjs run src/server/exportVideo.test.ts Expected: FAIL because helper module does not exist yet.

Step 3: Write minimal implementation

Implement pure helpers for:

1. Subtitle timeline normalization
2. Audio mix planning
3. ASS subtitle generation

Step 4: Run test to verify it passes

Run: node .\node_modules\vitest\vitest.mjs run src/server/exportVideo.test.ts Expected: PASS.

Task 3: Wire Backend Export Route to Helpers

Files:

• Modify: E:\Downloads\ai-video-dubbing-&-translation\server.ts

Step 1: Write the failing integration-leaning test

Extend src/server/exportVideo.test.ts if needed to assert the route-facing helper contract.

Step 2: Run test to verify it fails

Run: node .\node_modules\vitest\vitest.mjs run src/server/exportVideo.test.ts Expected: FAIL because current route behavior still assumes SRT/default mixing.

Step 3: Write minimal implementation

Update the route to:

1. Parse textStyles
2. Use normalized subtitle times for export
3. Generate .ass instead of .srt
4. Apply preview-equivalent audio mix rules

Step 4: Run test to verify it passes

Run: node .\node_modules\vitest\vitest.mjs run src/server/exportVideo.test.ts Expected: PASS.

Task 4: Verify End-to-End Regressions

Files:

• Modify if needed: E:\Downloads\ai-video-dubbing-&-translation\src\services\geminiService.test.ts
• Modify if needed: E:\Downloads\ai-video-dubbing-&-translation\src\server\minimaxTts.test.ts

Step 1: Run focused regression suite

Run:

node .\node_modules\vitest\vitest.mjs run src/lib/exportPayload.test.ts src/server/exportVideo.test.ts src/services/geminiService.test.ts src/server/minimaxTts.test.ts

Expected: PASS.

Step 2: Run TypeScript check

Run: node .\node_modules\typescript\bin\tsc --noEmit Expected: Existing baseline errors may remain; no new export-parity errors should appear.

Step 3: Smoke-check the running app

1. Restart the local server.
2. Export a trimmed clip with BGM and TTS.
3. Confirm the exported audio and subtitle timing now match preview expectations.

Plan complete and saved to docs/plans/2026-03-17-export-preview-parity.md. Defaulting to execution in this session using the plan directly.