Recent features (video, HeyGen, PiP calibration)

Recent features (video, HeyGen, PiP calibration)

Summary of capabilities added for HeyGen talking-head decks, MP4 export, PiP framing, slide transitions, daily single video pipeline, and visual validation. Each item links to the full guide.

Daily single pipeline + modular Video QA

YouTube-style walkthroughs from create-news handoff (examples/videos/anthropic-claude-fable-5-mythos-5/):

PROJECT=examples/videos/anthropic-claude-fable-5-mythos-5
daily-single -p $PROJECT validate-qa --when post_build
pytest tests/test_video_qa.py -q

Docs: Pipeline overview · Daily single pipeline · Video QA · Daily single testing

Slide transitions (YAML parity)

Configure per-edge, per-verse, or global transitions for MP4 export. Default is none (hard cut). Types include segment_fade, crossfade, and directional wipes. Showcase deck: examples/slide-transitions-showcase.yaml. See slide-transitions.md.

Narration and audio sources

Choose where slide audio comes from in video_export:

With narration_mode: auto, HeyGen embedded audio wins when the avatar file has a track, even if audio_path is also set on verses.

video_export:
  narration_mode: avatar
  audio_source: heygen_video   # optional alias when narration_mode omitted

Docs: Video export — narration modes · HeyGen examples · YAML reference

HeyGen 50590 article workflow

One content YAML drives five media variant decks (video+audio, video+MP3, audio-only, silent variants).

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

# 2. Sync variants
python examples/sync_heygen_variants.py

# 3. Build + MP4 (default = HeyGen audio)
VARIANT=heygen-50590-video-audio-heygen
praisonaippt -i examples/${VARIANT}.yaml -o examples/${VARIANT}.pptx \
  --convert-video --video-output examples/${VARIANT}.mp4

Docs: HeyGen article examples · Video + transcript workflow · Commands · Pipeline architecture

Avatar PiP auto-calibration

Centres the presenter face in the circular PiP using hybrid calibration:

1. MediaPipe (or YuNet) estimates face position → crop_x seed
2. Face-centred refine — sweeps crop_x / crop_y to minimise L/R/T/B margin asymmetry (same metric as the validation diagram)
3. Results cached under .praisonaippt/avatar-framing/ next to the deck YAML (gitignored)

avatar_calibration:
  auto: true
  method: hybrid
  crop_x_preferred: 0.53
  crop_x_window: [0.50, 0.56]
  detector: auto

pip install praisonaippt[avatar-calibrate]
praisonaippt calibrate-avatar examples/heygen-50590-video-audio-heygen.yaml --force --write

Install extras (PyPI):

Docs: Avatar PiP calibration

PiP face centre measurement and validation diagram

Measure whether the head is centred in the PiP circle and save an annotated PNG for visual QA.

praisonaippt pip-face-centre -i deck.yaml --slide 6 \
  --validation-image examples/heygen-pip-validation.png

praisonaippt calibrate-avatar deck.yaml --force --validation-image

The diagram shows:

• Green circle + centre crosshair
• Yellow face box, blue face centre
• L / R / T / B pixel gaps from each side of the head to the circle
• Banner: centred=yes/no and suggested crop_x / crop_y adjustments

CLI hints come from centring_advice() (e.g. increase crop_x when L ≫ R).

Docs: Avatar calibration — validation diagram · Commands

Slide JPEG export and QA

Export per-slide JPEG previews while building (for thumbnails, vision checks, or social).

slide_images_dir: slide_images/heygen-50590-images
skip_title_slide: true
jpeg_show_pip_preview: true

slide_qa:
  expect_pip: true
  min_hero_coverage_ratio: 0.62

pipeline:
  golden_slide_dir: slide_images/heygen-50590-images/golden
  export_mp4_frames: true
  mp4_frames_dir: slide_images/heygen-50590-images/mp4-frames
  validate_slide_qa: true

praisonaippt build-slide-images -i deck.yaml -o deck.pptx
praisonaippt export-slide-jpegs deck.pptx --slide-images-dir slide_images
praisonaippt validate-deck -i deck.yaml   # golden + slide_qa + mp4_frames gates

Docs: Slide JPEG export · Slide QA

Full-bleed hero layouts (avatar_media_3)

Product screenshot slides can use full-screen media with a floating headline panel at a per-slide anchor (instead of a fixed top band).

slide_style:
  layouts:
    avatar_media_3:
      hero_layout: full_bleed
      text_style: semi_panel

- slide_type: avatar_media_3
  headline: Dreaming
  media_path: slide_images/HHt8A9BbYAAUfvZ.jpg
  media_fit: cover
  text_panel:
    anchor: top_right

Reference deck: examples/heygen-50590-video-audio-heygen-images.yaml.

Docs: Avatar layouts — full-bleed hero · HeyGen examples

Layout and export fixes

Docs: Avatar layouts — avatar_quote · Layouts overview

Python API (new symbols)

from praisonaippt import (
    calibrate_avatar_framing,
    calibrate_deck_avatars,
    maybe_auto_calibrate_deck,
    AvatarFramingResult,
    export_pptx_slide_jpegs,
    SlideImageOptions,
    convert_deck_to_video,
    VideoOptions,
)
from praisonaippt.pip_face_measure import (
    measure_pip_video,
    measure_pip_image,
    centring_advice,
    save_pip_validation_diagram,
    PipFaceMetrics,
    PipCentringAdvice,
)

metrics, probe = measure_pip_video("speaker.mp4", crop_x=0.545, crop_y=0.07)
advice = centring_advice(metrics)
if not advice.is_centred:
    print(advice.summary, advice.crop_x_delta, advice.crop_y_delta)

Docs: Python API — video and calibration

CLI commands (quick reference)

Full flags: Commands — video, avatar, and HeyGen

MkDocs preview

pip install -r requirements-docs.txt
mkdocs serve

Open http://127.0.0.1:8000 and use the Video & media section in the nav.