Segment Video Roundup

Segment video roundup pipeline

Per-segment production (hook + N topics + outro) → compositor MP4 per segment → ffmpeg concat → Short video walkthrough on mer.vin.

Reference: examples/videos/june-2026-ai-roundup/ · layout index: examples/videos/README.md
Single-topic (Phase 1 B-roll): .cursor/skills/daily-single-video/SKILL.md · docs/daily-single-video.md — converges here in Phase 2 (HeyGen per beat)
Deck template: examples/heygen-50590-video-audio-heygen-images.yaml
Publish: .cursor/skills/mer-vin-article-video-upload/SKILL.md
YAML QA: .cursor/skills/ppt-yaml-deck-workflow/SKILL.md
SDK: praisonaippt/segment_video/

When to use

Do not regenerate ElevenLabs/HeyGen when narration.mp3 and heygen.mp4 exist unless the user explicitly asks.

Handoff crawl / review-data enrichment is owned by the create-news agent. This skill fixes downstream pipeline gaps only unless the user asks you to touch handoff files.

Prerequisites

- [ ] Mac: ffprobe, ffmpeg, praisonaippt (conda: test or windsurf)
- [ ] praisonaiwp: praisonaiwp doctor --server default
- [ ] Repo .env: ELEVEN_API_KEY, HEYGEN_API_KEY, ELEVEN_VOICE_ID, AVATAR_ID
- [ ] MER_HEYGEN_VERTICAL unset → landscape HeyGen 1280×720, compositor 1920×1080
- [ ] research_dir with review-data.json + review-assets/

See reference.md for env defaults and manifest schema.

Protocol stages (order matters)

Defined in scripts/config/protocol.json. Critical rule: after sync-media adds or changes cue count, always run align-cues before yaml. Running yaml alone leaves stale single-verse decks.

cd examples/videos/<project>/scripts
PROJECT=../  # project root

Phase 0 — Bootstrap

zsh .cursor/skills/segment-video-roundup/scripts/bootstrap-project.sh \
  "my-roundup-slug" "/path/to/research/my-roundup" POST_ID

Or copy examples/videos/june-2026-ai-roundup/ → examples/videos/<slug>-roundup/, edit manifest.json, reset segments/*/, merge/, media_assets.json.

Phase 2 — Scripts

python3 write_scripts.py

Gate: User review before Phase 3 (TTS cost).

Phase 3 — ElevenLabs + HeyGen

python3 run_segment_media.py --skip-existing
python3 run_segment_media.py --skip-existing 01-nvidia-nemotron-3-ultra  # one segment

Outputs: narration.mp3, heygen.mp4, timestamps.json.

Phase 4 — Media sync (image selection)

python3 pipeline.py run sync-media
python3 pipeline.py run validate-media --strict
python3 pipeline.py run validate-assets    # handoff pool report
python3 pipeline.py run audit-images

• Heroes from review-data.json via praisonaippt.segment_video.image_selection
• Multi-cue: one sentence → one image when pool allows (max_cues_per_segment: 4)
• Audit-driven fixes in scripts/sync_media_assets.py:
  • CUE_IMAGE_OVERRIDES — wrong rank, file already in handoff
  • VISION_ENRICHMENTS — stub handoff vision → alignment keywords (prefer fixing handoff instead)
  • HERO_REUSE_ENRICHMENTS — thin pools (1 image / 3 sentences)
  • Overrides run twice (before + after fill_missing_sentence_cues); recalc script_alignment
  • Hook montage: prepend script_fragment to vision text before alignment
• Sparse pools: hero reuse is downstream stopgap — handoff should supply ≥1 relevant image per sentence
• Zoom: edit media_fit: cover in segment.yaml after yaml, before build (yaml resets to contain)

After sync-media changes cue count → Phase 5 align-cues is mandatory.

See reference.md — Handoff vs downstream gaps.

Phase 5 — Align, YAML, build (mandatory order)

SEGS="01-nvidia-nemotron-3-ultra 05-aws-bedrock-gpt-5-5-codex-ga"  # space-separated dirs

python3 pipeline.py run align-cues --force $SEGS
python3 pipeline.py run yaml --force $SEGS          # or: build_segment_yaml.py $SEGS
python3 pipeline.py run build --force $SEGS
python3 pipeline.py run normalize-audio --force   # always project-wide, not $SEGS
python3 pipeline.py run merge --force

Footgun: normalize-audio $SEGS can write an empty loudness_report.json and skip rebuilt segments — always run project-wide before merge.

Hook montage (00-hook)

• Montage starts after "roundup:" (~2.44 s); compositor needs a lead-in verse or MP4 truncates ~2.7 s vs HeyGen
• build_segment_yaml.py prepends intro slide when first cue audio_start_sec > 0
• When len(verses) != len(cue_timings): SRT from verses (write_verses_srt), not cue_timings alone
• Caption rules: .cursor/skills/video-script-captions/SKILL.md
• Rebuild hook: align-cues → yaml → build --force 00-hook → normalize-audio → merge

Multi-cue topic segments

• media_assets.json cues must match cue_timings.json count and segment.yaml verse count
• avatar_timeline: continuous + slide_timestamps for 2+ cues (50590 pattern within segment)

Per-segment build internals

praisonaippt hero-panel-place -i segment.yaml --force
praisonaippt -i segment.yaml -o segment.pptx --convert-video --video-output segment.mp4

Post-build: fix-jpegs, seed-golden if validate-deck golden fails.

Phase 6 — Merge

python3 pipeline.py run normalize-audio          # loudnorm segments before merge
python3 pipeline.py run normalize-audio --force  # re-normalise even if near target
python3 pipeline.py run merge
# Hard cut: segment-video run merge --no-transitions

Outputs:

• merge/final-roundup.mp4 — 1920×1080 @ 30fps (Full HD); verify with user before publish
• merge/final-roundup.srt
• merge/timeline.json

Resolution chain: HeyGen 1280×720 → compositor build → segment.mp4 1920×1080 → merge (no rescale). Merge alone cannot fix resolution — rebuild segments if not 1080p. See reference.md.

Phase 7 — Validation (run after every rebuild)

python3 pipeline.py status
python3 pipeline.py validate-all
python3 pipeline.py run validate-display
python3 pipeline.py run validate-hook

Or use the gap audit script:

zsh .cursor/skills/segment-video-roundup/scripts/gap-audit.sh examples/videos/<project>

validate-all gates (downstream focus)

HD verification (ffprobe)

Expected deliverable: 1920×1080, 30 fps, H.264 + AAC on every segment.mp4 and merge/final-roundup.mp4.

ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,r_frame_rate \
  -of csv=p=0 merge/final-roundup.mp4
# Expected: 1920,1080,30/1

for f in segments/*/segment.mp4; do
  echo "$f: $(ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0 "$f")"
done

If output is 720p: set video_export.preset: high in deck/base style → build_segment_yaml.py → build --force → normalize-audio → merge. Native 1080p HeyGen (not upscaled 720p) requires changing run_segment_media.py dimensions and regenerating all heygen.mp4.

Ignore for downstream-only work: handoff_uncrawled, insufficient_pool, manual_asset_gaps (handoff agent).

Reports: validation_report.json, loudness_report.json, image_audit_report.json, display_validation_report.json, hook_validation_report.json.

Multi-agent gap audit (recommended)

When user asks to verify or find gaps, launch parallel explore agents (not handoff crawl):

1. Validation report — read validation_report.json; list downstream failures only
2. Segment sync — compare cue_timings.json vs yaml verses vs slide_jpegs/ vs heygen/segment duration drift
3. Hook + image audit — hook_validation_report.json, image_audit_report.json swap recommendations
4. Loudness — read loudness_report.json or gap-audit loudness section; spread should be ≤ 2 LUFS post-normalise
5. HD resolution — ffprobe final + sample segments; expect 1920×1080 @ 30fps on all segment.mp4

Fix order:

sync-media (if picks wrong) → align-cues → build_segment_yaml.py → build --force → normalize-audio → merge → validate-all

Do not block on handoff catalogue failures if per-segment display_sync passes.

Phase 8 — Publish

Follow mer-vin-article-video-upload skill.

praisonaiwp media upload examples/videos/<project>/merge/final-roundup.mp4 \
  --post-id=POST_ID --server default

Insert wp:video block before At a glance. Update manifest.json → final_video.

Re-run cheat sheet

Full downstream rebuild (no TTS/HeyGen):

cd examples/videos/<project>/scripts
python3 pipeline.py run sync-media
python3 pipeline.py run align-cues --force
python3 build_segment_yaml.py $(python3 -c "import json; m=json.load(open('../manifest.json')); print(' '.join(s['dir'] for s in m['segments'] if s.get('slide_type') in ('avatar_media_3','big_number')))")
python3 pipeline.py run build --force
python3 pipeline.py run normalize-audio --force
python3 pipeline.py run merge --force
python3 pipeline.py validate-all

Studio & CLI

cd examples/videos/<project>
segment-video -p . studio
segment-video -p . regenerate --change deck --segment 01-nvidia-nemotron-3-ultra
cd scripts && python3 pipeline.py status

Additional resources

• Handoff schema, thresholds, failures: reference.md
• June 2026 worked commands: examples.md
• Gap audit script: scripts/gap-audit.sh
• In-repo protocol: examples/videos/june-2026-ai-roundup/PROTOCOL.md