Workflow: video + transcript → deck YAML → PPTX → MP4

Workflow: video + transcript → deck YAML → PPTX → MP4

End-to-end map of how PraisonAIPPT turns a HeyGen (or other) talking-head video and a Whisper transcript into a polished deck with correct timing, layouts, PiP framing, and export.

Related: HeyGen examples · Recent features · Avatar calibration · Video export · YAML reference

What you start with

Steps outside this repo today: record in HeyGen, run Whisper, write article copy for rich slides.

Pipeline overview

flowchart TB
  subgraph external [Outside PraisonAIPPT]
    H[HeyGen render MP4]
    W[Whisper transcript JSON]
    C[Human: article slide copy and layout plan]
  end

  subgraph yaml [YAML layer]
    T[transcript-to-yaml bootstrap]
    M[heygen-50590-content.yaml master]
    S[sync_heygen_variants.py]
    V[5 variant YAMLs]
  end

  subgraph quality [Quality gates]
    CAL[avatar_calibration auto]
    PFC[pip-face-centre optional]
    VAL[validation-image PNG]
  end

  subgraph build [Build and export]
    PPTX[PPTX build]
    JPG[slide JPEGs optional]
    MP4[MP4 compositor]
  end

  H --> M
  W --> T
  W --> M
  C --> M
  T --> V
  M --> S
  S --> V
  V --> CAL
  CAL --> PFC
  PFC --> VAL
  CAL --> PPTX
  PPTX --> JPG
  PPTX --> MP4

All steps (ordered)

Phase 0 — Acquire media (manual / external tools)

Phase 1 — Bootstrap deck YAML from transcript (automated CLI)

Purpose: First-pass YAML with segment timing, notes, simple slide_type, and audio_start_sec — not the full article deck.

praisonaippt transcript-to-yaml \
  -i examples/short-script-50590_timestamps.json \
  -o examples/heygen-article-50590 \
  --transcript-mode thematic \
  --transcript-audio examples/short-script-50590.mp3 \
  --align silence,karaoke \
  --variants all

Layout at this stage: avatar_headline, avatar_quote, etc. from THEMATIC_LAYOUTS — not deck_* / big_number article layouts.

Phase 2 — Content and layout plan (manual + assisted)

Purpose: Rich slides, deck layouts, bullets, tables, quotes — the “good PPT” layer.

Source of truth (50590 article): examples/heygen-50590-content.yaml

Phase 3 — Propagate to media variants (automated script)

Each variant gets correct video_export.narration_mode, audio_source, and per-verse audio_path / avatar_video_path flags.

Phase 4 — Head centre and PiP framing (automated on build)

Phase 5 — Build PPTX (automated)

VARIANT=heygen-50590-video-audio-heygen

praisonaippt -i examples/${VARIANT}.yaml \
  -o examples/${VARIANT}.pptx \
  --no-list-slides

Internal order:

1. Load and validate YAML
2. maybe_auto_calibrate_deck
3. maybe_auto_place_hero_text_deck (when hero_text_placement.auto: true)
4. create_presentation (renderers per slide_type)
5. Optional: GDrive upload, PDF, slide JPEGs

Phase 6 — Slide JPEG previews (optional, automated)

Requires slide_images_dir in YAML. See Slide JPEG export.

Phase 7 — MP4 export (automated)

praisonaippt -i examples/${VARIANT}.yaml \
  -o examples/${VARIANT}.pptx \
  --convert-video \
  --video-output examples/${VARIANT}.mp4

Standalone rerun: praisonaippt convert-video deck.pptx (needs YAML sidecar beside PPTX).

Phase 8 — Batch rebuild (automated)

python examples/build_showcase_examples.py

Runs sync + builds avatar gallery, deck gallery, and all five HeyGen variants.

Two production paths (choose one)

Recommended loop for Path B:

1. Phase 1 optional — seed timings/notes from transcript
2. Phase 2 — edit heygen-50590-content.yaml
3. Phase 3 — sync_heygen_variants.py
4. Phase 4–7 — build with --convert-video; use pip-face-centre --validation-image until centred: yes
5. Phase 6 — review slide_images/*.jpg

YAML artefacts per stage

Automation plan (what exists vs what to add)

Already automated

Semi-automated (human in the loop)

External only (not in repo)

Unified pipeline (implemented)

VARIANT=heygen-50590-video-audio-heygen

# Full run: sync → validate → calibrate → PPTX → JPEGs → MP4 → report.json
praisonaippt pipeline -i examples/${VARIANT}.yaml \
  -o examples/${VARIANT}.pptx \
  --content-master examples/heygen-50590-content.yaml \
  --transcript-json examples/short-script-50590_timestamps.json \
  --convert-video \
  --video-output examples/${VARIANT}.mp4 \
  --export-slide-jpegs \
  --validate-pip \
  --validation-image examples/qa/pip-validation.png \
  --pipeline-report examples/.praisonaippt/${VARIANT}.pipeline-report.json

Deck YAML may include:

pipeline:
  content_master: heygen-50590-content.yaml
  transcript_path: examples/short-script-50590_timestamps.json
  auto_sync: true
  validate_pip: true
  variant_prefix: heygen-50590

Build with --convert-video runs post-render ffprobe (duration, audio stream, resolution, FPS).

CI gates validation matrix

Each gate is recorded in report.json under gates with exit_code (0 = pass, 1 = fail).

# CI-friendly validate (exit 1 on any failed gate)
praisonaippt validate-deck -i examples/heygen-50590-video-audio-heygen.yaml \
  --validate-pip --pipeline-report report.json
echo $?   # 0 = pass

# Plan workflow (before sync, not after MP4)
praisonaippt plan-slides -i examples/short-script-50590_timestamps.json \
  -o examples/heygen-50590-draft.yaml
praisonaippt approve-plan -i examples/heygen-50590-draft.yaml

Minimal command cheat sheet (Path B today)

# 1. Edit examples/heygen-50590-content.yaml

# 2. One-shot pipeline (replaces manual sync + validate + build)
praisonaippt pipeline -i examples/heygen-50590-video-audio-heygen.yaml \
  -o examples/heygen-50590-video-audio-heygen.pptx \
  --convert-video --video-output examples/heygen-50590-video-audio-heygen.mp4 \
  --validate-pip --export-slide-jpegs

Checklist before calling a deck “done”

• Whisper timings match wall-clock video (no large drift on last slide)
• notes readable and aligned with narration
• slide_type appropriate per beat (deck vs avatar vs list)
• sync_heygen_variants.py run after content edits
• pip-face-centre shows centred: yes or L≈R on validation PNG
• Listened to MP4 — correct audio source variant (HeyGen vs MP3)
• Slide JPEGs look correct (quote slide may omit baked avatar — check MP4 or mp4-frames/)
• validate-deck passes (slide_jpegs, slide_qa, mp4_frames when configured)
• Full-bleed hero slides: headline panel clears PiP and key UI text

See also

• Commands — video & avatar
• Examples/heygen-50590-examples.md (repo copy)
• examples/avatar_calibration_agents.py — three-phase calibration helper