# MentorAI 2026-06-21 Demo Execution Plan

Demo date: 2026-06-21

Objective: show a working MentorAI teaching-video workflow that turns a reference lecture into an original blackboard-style lesson video with authorized teacher voice support.

## Demo Definition Of Done

The demo is ready only when all of these are true:

- A playable MP4 exists for `兒時記趣` V1 blackboard teaching style.
- The video uses the rewritten teaching script, not copied reference-video wording.
- The audio path is one of:
  - authorized teacher voice MP3s, or
  - documented Edge-TTS fallback if the provider is not ready.
- The demo can show the production workflow from:
  - reference video analysis,
  - transcript,
  - storyboard/script,
  - character design,
  - voice asset/consent record,
  - generated slides,
  - final MP4.
- A backup video exists by 2026-06-19, even if final voice clone quality is still being improved.
- All demo commands and file paths are documented.

## Current State

Already available:

- Reference video assets: `storage/research/v2EN9GVEeMc/`
- Reference transcript: `storage/research/v2EN9GVEeMc/transcript.txt`
- Reference analysis: `docs/research/v1-reference-liuxin-video-analysis.md`
- Teaching-video workflow: `docs/research/v1-teaching-video-production-workflow.md`
- Authorized voice adapter spec: `docs/research/authorized-voice-generation-adapter.md`
- Authorized voice asset folder: `storage/voice-rights/teacher-liu-authorized/`
- Cleaned voice source WAV: `storage/voice-rights/teacher-liu-authorized/cleaned-audio/reference-youtube-v2EN9GVEeMc-clean.wav`
- V1 generation script: `apps/api/src/scripts/produceChildhoodWonderVideo.ts`
- Existing old V1 output: `storage/childhood-wonder-video/childhood-wonder-full.mp4`

Main gaps:

- Choose and configure the actual authorized voice generation provider.
- Generate `segment-01-audio.mp3` through `segment-08-audio.mp3` in the authorized voice.
- Re-run V1 after the blackboard/script changes.
- Verify the new MP4 visually and aurally.
- Prepare a concise demo walkthrough.

## Demo Scope

In scope for 2026-06-21:

- One polished lesson demo for `兒時記趣`.
- V1 blackboard-style generation pipeline.
- Authorized voice path prepared and used if provider is ready.
- Fallback voice video ready for demo safety.
- Clear workflow explanation for how this generalizes to other lessons.

Out of scope for this demo:

- Full studio2 product UI.
- Fully automated multi-subject course generation.
- Real-time editing interface.
- Perfect avatar lip-sync across the whole lesson.
- Large-scale provider cost optimization.

## Daily Plan

### 2026-06-14: Plan And Asset Lock

Deliverables:

- Final execution plan.
- Voice consent/asset folder verified.
- V1 script status verified by typecheck.
- Demo requirements and fallback policy documented.

Commands:

```bash
npm run typecheck -w @mentorai/api
find storage/voice-rights/teacher-liu-authorized -maxdepth 3 -type f | sort
```

Exit criteria:

- This plan exists.
- Voice assets and consent placeholder are present.
- Known gaps are explicit.

### 2026-06-15: Voice Provider Decision And First Audio

Deliverables:

- Selected provider documented in `voice-model.json`.
- One generated authorized voice sample for segment 01.
- A/B comparison against Edge-TTS.

Tasks:

- Pick provider: ElevenLabs, Fish Audio, MiniMax, or another authorized voice clone provider.
- Upload or register the cleaned WAV dataset.
- Generate segment 01 from the rewritten narration.
- Normalize to MP3:

```bash
ffmpeg -y -i input.wav -af loudnorm=I=-16:TP=-1.5:LRA=11 output-normalized.wav
ffmpeg -y -i output-normalized.wav -codec:a libmp3lame -q:a 3 \
  storage/voice-rights/teacher-liu-authorized/generated-audio/segment-01-audio.mp3
```

Exit criteria:

- `storage/voice-rights/teacher-liu-authorized/generated-audio/segment-01-audio.mp3` exists.
- Voice quality is acceptable or fallback is chosen for demo.

### 2026-06-16: Full Authorized Voice Pass

Deliverables:

- Authorized voice MP3s for segments 01-08, or explicit fallback decision.
- Segment durations verified.

Commands:

```bash
for f in storage/voice-rights/teacher-liu-authorized/generated-audio/segment-*-audio.mp3; do
  printf '%s ' "$f"
  ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$f"
done
```

Exit criteria:

- Eight segment MP3s exist, or Edge-TTS fallback is formally locked by end of day.
- No segment has clipped, silent, or wrong-language audio.

### 2026-06-17: Visual Regeneration

Deliverables:

- New V1 blackboard slides.
- New illustrations for all segments.
- Visual contact sheet.

Command:

```bash
AUTHORIZED_VOICE_SPEAKER_ID=teacher-liu-authorized \
npm run video:childhood-wonder -w @mentorai/api
```

If authorized voice files are not ready:

```bash
npm run video:childhood-wonder -w @mentorai/api
```

Exit criteria:

- `storage/childhood-wonder-video/segment-01-slide.png` through `segment-08-slide.png` exist and reflect blackboard teaching design.
- Generated images have no fake readable text.
- Slide text is readable at 1080p.

### 2026-06-18: First Full Demo Video

Deliverables:

- First complete MP4 candidate.
- Timing and stream verification.
- Review notes.

Commands:

```bash
ffprobe -v error -show_entries stream=index,codec_type,codec_name,width,height,r_frame_rate \
  -of default=nw=1 storage/childhood-wonder-video/childhood-wonder-full.mp4
ffprobe -v error -show_entries format=duration,size -of default=nw=1 \
  storage/childhood-wonder-video/childhood-wonder-full.mp4
```

Exit criteria:

- MP4 plays from beginning to end.
- Audio and slide changes are aligned.
- Any issue list has owners and fixes.

### 2026-06-19: Backup Freeze

Deliverables:

- Backup demo MP4 frozen.
- Demo script draft.
- Known-risk fallback files copied into a release folder.

Release folder:

```text
storage/demo/2026-06-21/
├── mentorai-childhood-wonder-demo.mp4
├── demo-walkthrough.md
├── storyboard.json
├── voice-rights-summary.md
└── verification.txt
```

Exit criteria:

- A demo can be given even if no more model work succeeds.
- Final two days are polish, not core production.

### 2026-06-20: Polish And Rehearsal

Deliverables:

- Final demo MP4 candidate.
- 5-minute demo talk track.
- 10-minute extended Q&A notes.

Review order:

1. Watch video without sound for slide clarity.
2. Listen without watching for narration logic.
3. Watch full video for timing.
4. Verify the workflow files and commands.

Exit criteria:

- No blocking visual/audio issue remains.
- Demo can be run from local files without internet dependency.

### 2026-06-21: Demo Day

Deliverables:

- Final MP4.
- Demo walkthrough.
- Backup MP4.
- Clear next-step roadmap.

Recommended demo flow:

1. Show the problem: ordinary lecture recording is hard to repurpose.
2. Show input assets: reference, transcript, analysis.
3. Show transformation: storyboard, character design, rewritten narration.
4. Show voice rights path: consent and authorized voice asset.
5. Play final MP4.
6. Show how the same workflow scales to another lesson.

## Critical Path

The demo depends on this chain:

```text
voice provider decision
  -> segment MP3 generation
  -> V1 render
  -> QA
  -> frozen demo package
```

The voice provider decision is the highest-risk item. If it is not solved by the end of 2026-06-16, use Edge-TTS for the 2026-06-19 backup and continue authorized voice work as an upgrade.

## Fallback Strategy

Fallback A: authorized voice ready

- Use `AUTHORIZED_VOICE_SPEAKER_ID=teacher-liu-authorized`.
- Demo emphasizes authorized teacher voice workflow.

Fallback B: provider not ready but assets are ready

- Use Edge-TTS final video.
- Demo shows the authorized voice asset folder, consent record, and adapter as the next integration step.
- Be transparent that voice cloning is ready in workflow but not rendered in the backup MP4.

Fallback C: visual generation fails

- Use existing old V1 MP4 as evidence of the renderer.
- Use the updated SVG slides and storyboard as the new design direction.
- Do not block demo entirely on remote image generation.

## Demo Acceptance Checklist

- [ ] `npm run typecheck -w @mentorai/api` passes.
- [ ] Final MP4 exists.
- [ ] Final MP4 has audio and video streams.
- [ ] Final MP4 duration is plausible.
- [ ] `segment-01-slide.png` through `segment-08-slide.png` exist.
- [ ] Voice mode is documented: authorized clone or fallback TTS.
- [ ] Consent/voice asset record exists.
- [ ] Demo walkthrough exists.
- [ ] Backup MP4 exists by 2026-06-19.
- [ ] All demo files are in `storage/demo/2026-06-21/`.

## Owner Notes

Default owner: Codex + user.

User decisions needed:

- Choose voice clone provider if multiple options are available.
- Confirm whether likeness/name usage is also authorized, not just voice.
- Approve final demo MP4 by 2026-06-20.