Commands - PraisonAI PPT

Complete Command Reference

PraisonAI PPT is invoked as praisonaippt. Deck input may be .yaml, .yml, or .json (same schema). Run praisonaippt --help for the latest flag list.

Command index

Command Purpose
(default) Load deck → build PPTX → optional PDF / MP4 / Drive / slide JPEGs
convert-pdf PPTX → PDF
convert-video PPTX → MP4 (sidecar deck.yaml / deck.json beside PPTX)
convert-json PPTX or YAML → JSON extract
convert-yaml JSON verses file → YAML
transcript-to-yaml Whisper JSON → thematic / HeyGen variant YAML
list-slides Print slide outline from deck or PPTX
export-slide-jpegs Rasterise PPTX slides to JPEGs
build-slide-images Build PPTX (if needed) + export slide_images_dir
calibrate-avatar PiP face framing; --write updates deck YAML or JSON
hero-panel-place Calibrate anchors; --write updates deck YAML or JSON
hero-panel-centre Measure panel vs UI text; --validation-image L/R/T/B diagram
slide-transition-plan Print resolved slide transition edge matrix (-i deck.yaml)
slide-transition-preview Show transition after slide N (-i deck.yaml --slide N)
pip-face-centre Measure L/R/T/B margins on PiP probe PNG
pipeline Unified sync → gates → build → MP4 → report.json
sync-variants Copy content master → HeyGen media variant YAMLs
plan-slides Draft slide plan from transcript JSON
approve-plan Approve plan draft (clears plan_approval gate)
validate-deck Gates only (no PPTX / MP4 build)
transcribe Audio → Whisper JSON (requires whisper CLI)
template Show resolved theme template style
config Show or edit ~/.praisonaippt/config.yaml
setup-oauth Google Drive OAuth setup
setup-credentials Service-account credentials setup
secure-credentials Restrict credential file permissions
daily-single Daily single-topic video pipeline (see below)

Architecture: Pipeline architecture · HeyGen workflow: Video + transcript workflow · Daily single video: Daily single pipeline

JSON and YAML decks

# Same flags for JSON or YAML
praisonaippt -i examples/job_sickness.json -o out.pptx
praisonaippt -i examples/heygen-50590-video-audio-heygen.yaml --convert-video
praisonaippt validate-deck -i deck.json --validate-pip
praisonaippt calibrate-avatar deck.json --write --force

calibrate-avatar --write preserves the file format (.json vs .yaml). See Deck reference.

Main build command (default)

🚀 Basic Commands

Create Presentation

Default Usage

# Use default verses.yaml in current directory
praisonaippt

Specify Input File

# YAML or JSON format
praisonaippt -i my_verses.yaml

# YAML format (recommended)
praisonaippt -i my_verses.yaml

Specify Output File

# Custom output filename
praisonaippt -i verses.yaml -o my_presentation.pptx

Use Custom Title

# Override JSON title
praisonaippt -i verses.yaml -t "My Custom Title"

Use Built-in Examples

# List available examples
praisonaippt --list-examples

# Use a specific example
praisonaippt --use-example tamil_verses
praisonaippt --use-example sample_verses

Help and Version

# Show help
praisonaippt --help

# Show version
praisonaippt --version

📄 PDF Conversion Commands

Convert Existing PPTX to PDF

Basic Conversion

# Convert presentation to PDF
praisonaippt convert-pdf presentation.pptx

# Specify output filename
praisonaippt convert-pdf presentation.pptx --pdf-output output.pdf

Backend Selection

# Choose specific backend
praisonaippt convert-pdf presentation.pptx --pdf-backend libreoffice
praisonaippt convert-pdf presentation.pptx --pdf-backend aspose
praisonaippt convert-pdf presentation.pptx --pdf-backend auto

Advanced PDF Options

# High quality PDF
praisonaippt convert-pdf presentation.pptx \
  --pdf-options '{"quality":"high","compression":false}'

# Password protected PDF
praisonaippt convert-pdf presentation.pptx \
  --pdf-options '{"password_protect":true,"password":"secret123"}'

# Custom slide range
praisonaippt convert-pdf presentation.pptx \
  --pdf-options '{"slide_range":[1,5]}'

Create PPTX and Convert to PDF in One Step

Basic Integrated Conversion

# Create presentation and convert to PDF
praisonaippt -i verses.yaml --convert-pdf

# Custom PDF output filename
praisonaippt -i verses.yaml --convert-pdf --pdf-output custom.pdf

Advanced Integrated Conversion

# With custom PDF options
praisonaippt -i verses.yaml --convert-pdf \
  --pdf-options '{"quality":"high","include_hidden_slides":true}'

# With backend selection
praisonaippt -i verses.yaml --convert-pdf \
  --pdf-backend aspose \
  --pdf-options '{"quality":"high","compression":false}'

🔄 PPTX → JSON Extraction Command

Convert slide content from a .pptx file back into the praisonaippt JSON schema, or convert a .yaml verse file back into .json.

Basic Extraction (PPTX → JSON)

# Auto-named output (<input>.json)
praisonaippt convert-json presentation.pptx

# Specify output file
praisonaippt convert-json presentation.pptx --json-output extracted.json

# Compact JSON (no indentation)
praisonaippt convert-json presentation.pptx --json-output data.json --no-pretty

Basic Conversion (YAML → JSON)

# Converts verses.yaml into verses.json
praisonaippt convert-json verses.yaml

Convert-JSON Command Options

Convert-JSON Command:
  positional arguments:
    input_file              Input file to extract (.pptx or .ppt)

  options:
    --json-output PATH      Output JSON file path (default: <input>.json)
    --pretty                Write indented JSON (default: enabled)
    --no-pretty             Write compact single-line JSON

Batch Extraction

# Extract all PPTX files in the current directory
for file in *.pptx; do
  praisonaippt convert-json "$file"
done

📖 Full reference: PPTX to JSON Guide

🔄 JSON → YAML Conversion Command

Convert legacy .json verse files to the new .yaml default format natively.

Basic Conversion

# Converts verses.json into verses.yaml
praisonaippt convert-yaml verses.json

Convert-YAML Command Options

Convert-YAML Command:
  positional arguments:
    input_file              Input file to convert (.json)

Batch Conversion

# Convert all JSON source files in the current directory to YAML
for file in *.json; do
  praisonaippt convert-yaml "$file"
done

⚙️ Command Options Reference

Global Options

Options:
  -h, --help            Show help message
  -v, --version         Show version number
  -i INPUT, --input INPUT
                        Input JSON/YAML file (default: verses.yaml)
  -o OUTPUT, --output OUTPUT
                        Output PowerPoint file (auto-generated if not specified)
  -t TITLE, --title TITLE
                        Custom presentation title (overrides JSON title)
  --use-example NAME    Use a built-in example file
  --list-examples       List all available example files

PDF Conversion Options

PDF Options:
  --convert-pdf         Convert the generated PowerPoint to PDF
  --pdf-backend {aspose,libreoffice,auto}
                        PDF conversion backend (default: auto)
  --pdf-options PDF_OPTIONS
                        PDF conversion options as JSON string
  --pdf-output PDF_OUTPUT
                        Custom PDF output filename

Convert-PDF Command Options

Convert-PDF Command:
  positional arguments:
    input_file            Input PPTX file to convert

  options:
    -h, --help            Show help message
    --pdf-backend {aspose,libreoffice,auto}
                        PDF conversion backend (default: auto)
    --pdf-options PDF_OPTIONS
                        PDF conversion options as JSON string
    --pdf-output PDF_OUTPUT
                        Custom PDF output filename

📋 PDF Options Reference

Available Options

{
  "backend": "auto",                    // "aspose", "libreoffice", "auto"
  "quality": "high",                    // "low", "medium", "high"
  "include_hidden_slides": false,       // Include hidden slides in PDF
  "password_protect": false,            // Password protect PDF
  "password": null,                     // PDF password
  "compression": true,                  // Compress PDF images
  "notes_pages": false,                 // Include notes pages
  "slide_range": null,                  // [start, end] slide range
  "compliance": null                    // "PDF/A", "PDF/UA" compliance
}

Quality Settings

Backend Comparison

| Backend | Quality | Cost | Dependencies | Best For | |———|———|——|————–|———-| | Aspose.Slides | Excellent | Commercial | Python package | Professional quality | | LibreOffice | Good | Free | LibreOffice install | Free option | | Auto | Varies | Varies | Auto-detected | Convenience |

🎯 Advanced Command Examples

Batch Processing

# Create multiple presentations with PDF
for file in *.json; do
  praisonaippt -i "$file" --convert-pdf
done

# Convert all PPTX files to PDF
for file in *.pptx; do
  praisonaippt convert-pdf "$file"
done

Custom Quality Settings

# High quality PDF (no compression)
praisonaippt -i verses.yaml --convert-pdf \
  --pdf-options '{"quality":"high","compression":false}'

# Low quality PDF (smaller file size)
praisonaippt -i verses.yaml --convert-pdf \
  --pdf-options '{"quality":"low","compression":true}'

Password Protected PDF

# Create password-protected PDF
praisonaippt -i verses.yaml --convert-pdf \
  --pdf-options '{"password_protect":true,"password":"secret123"}'

Slide Range Export

# Export specific slides to PDF
praisonaippt convert-pdf presentation.pptx \
  --pdf-options '{"slide_range":[1,5]}'

# Export slides 10-20
praisonaippt convert-pdf presentation.pptx \
  --pdf-options '{"slide_range":[10,20]}'

Compliance Standards

# PDF/A compliance (archival)
praisonaippt convert-pdf presentation.pptx \
  --pdf-options '{"compliance":"PDF/A"}'

# PDF/UA compliance (accessibility)
praisonaippt convert-pdf presentation.pptx \
  --pdf-options '{"compliance":"PDF/UA"}'

🔍 Command Examples by Use Case

Quick Presentation Creation

# Fastest way to create presentation
praisonaippt

# With custom title
praisonaippt -t "Sunday Service"

# From specific file
praisonaippt -i easter_verses.yaml

Professional PDF Export

# High quality PDF for printing
praisonaippt -i verses.yaml --convert-pdf \
  --pdf-options '{"quality":"high","compression":false}'

# PDF for web (smaller file)
praisonaippt -i verses.yaml --convert-pdf \
  --pdf-options '{"quality":"medium","compression":true}'

Batch Processing

# Process all JSON files in directory
find . -name "*.json" -exec praisonaippt -i {} --convert-pdf \;

# Create presentations for multiple services
for service in morning evening; do
  praisonaippt -i "${service}_verses.yaml" -o "${service}_service.pptx"
done

Development and Testing

# Use example for testing
praisonaippt --use-example tamil_verses

# Create test presentation with PDF
praisonaippt --use-example sample_verses --convert-pdf --pdf-output test.pdf

# List all available examples
praisonaippt --list-examples

🛠️ Troubleshooting Commands

Check Installation

# Verify installation
praisonaippt --version

# Check available commands
praisonaippt --help

# Test PDF conversion availability
praisonaippt convert-pdf --help

Debug PDF Issues

# Test with specific backend
praisonaippt convert-pdf test.pptx --pdf-backend libreoffice

# Check backend availability
python -c "from praisonaippt import PDFConverter; print(PDFConverter().get_available_backends())"

File Path Issues

# Use absolute paths
praisonaippt -i /full/path/to/verses.yaml -o /full/path/to/output.pptx

# Handle spaces in filenames
praisonaippt -i "my verses.yaml" -o "my presentation.pptx"

Main build flags (default command)

Used with praisonaippt -i deck.yaml (or .json):

Flag Purpose
-i, --input Deck file (default verses.yaml, falls back to verses.json)
-o, --output Output .pptx path
-t, --title Override presentation_title
--template Theme template (sermon-dark, path, or extends chain)
--list-templates List built-in / user templates
--use-example / --list-examples Built-in example decks
--convert-pdf Also export PDF
--convert-video Also export MP4
--video-output MP4 path
--video-preset draft, standard, high, 4k
--video-backend compositor, auto, powerpoint
--narration-mode fixed, audio_file, avatar, tts, auto
--video-options JSON merged into video_export
--slide-range START-END (1-based slides in MP4)
--export-slide-jpegs Export slide_images_dir JPEGs after build
--sync-variants Sync from pipeline.content_master before build
--seed-timing Update verse timings from pipeline.transcript_path
--validate-deck Run validation gates only (no build)
--validate-pip PiP face-centre QA (fails build if strict)
--strict-pip All calibration seeks must pass PiP QA
--strict-post-render Fail if post-render MP4 QC fails
--force Force avatar re-calibration (avatar_calibration.force)
--validation-image Save PiP centring diagram PNG
--golden-slide-dir Golden JPEG MD5 compare for CI
--rights-acknowledged Pass rights/licensing gate
--content-master Override pipeline.content_master
--transcript-json Override transcript path for timing / A-V gates
--pipeline-report Write pipeline-style report JSON on preflight
--no-list-slides Skip slide outline after build
--no-upload Skip Google Drive upload
-v / --verbose / -q Logging level

Video, avatar, and HeyGen commands

Feature overview: Recent features

Full behaviour: Video export · HeyGen examples · Avatar calibration · Slide JPEGs · Slide QA · Pipeline architecture

Video export

# Build deck + MP4
praisonaippt -i deck.yaml -o deck.pptx --convert-video --video-output deck.mp4
praisonaippt -i deck.json -o deck.pptx --convert-video   # JSON deck — same schema

# PPTX only (loads deck.yaml / deck.json sidecar beside PPTX for PiP paths)
praisonaippt convert-video deck.pptx --video-output deck.mp4

# Dependency check (also: praisonaippt --check with no command)
praisonaippt convert-video --check

# Override narration
praisonaippt -i deck.yaml -o deck.pptx --convert-video --narration-mode avatar
Flag Values
--convert-video On main command: build and export MP4
--video-output Output path
--video-preset draft, standard, high, 4k
--narration-mode fixed, audio_file, avatar, tts, auto
--video-options JSON merged into video_export
--slide-range START-END (1-based)
--keep-temp With convert-video: keep temp PNG/segments
--check With convert-video: preflight ffmpeg/LibreOffice tools

Slide JPEG export

praisonaippt build-slide-images -i deck.yaml -o deck.pptx
praisonaippt export-slide-jpegs deck.pptx --slide-images-dir slide_images
praisonaippt -i deck.yaml -o deck.pptx --export-slide-jpegs

Avatar PiP calibration

praisonaippt calibrate-avatar examples/heygen-50590-video-audio-heygen.yaml --force
praisonaippt calibrate-avatar --avatar-video examples/heygen-article-50590.mp4 --seek 6.0
praisonaippt calibrate-avatar deck.yaml --write   # persist into deck YAML or JSON
Flag Purpose
--force Ignore .praisonaippt/avatar-framing/ cache
--write Write calibrated crop_x into deck YAML
--seek-times Comma-separated probe times (seconds)
--validation-image Save annotated centring diagram PNG (optional path)

Face centre probe

praisonaippt pip-face-centre -i deck.yaml --slide 6
praisonaippt pip-face-centre --avatar-video speaker.mp4 --crop-x 0.53 --zoom 1.45
praisonaippt pip-face-centre --pip-image probe.png
praisonaippt pip-face-centre -i deck.yaml --validation-image out.png
praisonaippt calibrate-avatar deck.yaml --force --validation-image

--validation-image saves an annotated PNG: green circle centre, yellow face box, L/R/T/B pixel gaps from each side of the head to the circle (see Avatar calibration).

Slide transitions (plan / preview)

Resolve the edge matrix without building video. See Slide transitions.

# Print all edges (after_slide → type → duration)
praisonaippt slide-transition-plan -i examples/slide-transitions-showcase.yaml

# Inspect transition leaving slide 3
praisonaippt slide-transition-preview -i examples/slide-transitions-showcase.yaml --slide 3

# Build showcase MP4 (all types: segment_fade, crossfade, wipes, hard cut)
praisonaippt -i examples/slide-transitions-showcase.yaml \
  -o examples/slide-transitions-showcase.pptx --convert-video
Command Purpose
slide-transition-plan Resolved edge table (_slide_transitions sidecar logic)
slide-transition-preview One edge detail; requires --slide N (1 … slide_count−1)

Gate: validate-deck runs GATE_SLIDE_TRANSITIONS when pipeline.validate_transitions: true.

Transcript → YAML (HeyGen variants)

praisonaippt transcript-to-yaml -i timestamps.json -o examples/heygen-article-50590 --variants all

Deck pipeline (sync, validate, build, report)

Unified orchestration — see Pipeline architecture.

# Full HeyGen build (recommended for CI)
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 \
  --pipeline-report examples/.praisonaippt/heygen-50590-video-audio-heygen.pipeline-report.json

# Validate only (no PPTX / MP4) — JSON or YAML
praisonaippt validate-deck -i deck.json --validate-pip --transcript-json timestamps.json

# Sync five HeyGen variants from content master
praisonaippt sync-variants -i examples/heygen-50590-content.yaml

# Plan → approve → sync → build
praisonaippt plan-slides -i examples/short-script-50590_timestamps.json \
  -o examples/heygen-50590-draft.yaml \
  --content-master examples/heygen-50590-content.yaml
praisonaippt approve-plan -i examples/heygen-50590-draft.yaml

# Whisper transcript (input to plan-slides / pipeline.transcript_path)
praisonaippt transcribe -i examples/short-script-50590.mp3 \
  -o examples/short-script-50590_timestamps.json

# Skip PPTX build (gates + MP4 only)
praisonaippt pipeline -i deck.yaml --skip-build --convert-video
Command Builds PPTX Builds MP4 Writes report.json
pipeline Yes (unless --skip-build) If --convert-video Yes (default under .praisonaippt/)
validate-deck No No If --pipeline-report
Main -i + --validate-deck Yes Optional If --pipeline-report
Flag / YAML (pipeline:) Purpose
content_master Master deck for sync-variants
transcript_path Whisper JSON for timing / A-V sync
auto_sync Sync variants before build
variant_prefix HeyGen filename prefix (default heygen-50590)
validate_pip Run PiP centring gate
strict_pip CLI or YAML: all seeks must pass
export_mp4 YAML-only: export MP4 in pipeline without CLI flag
post_render_qc / strict_post_render ffprobe QC after MP4
golden_slide_dir Golden JPEG MD5 folder
export_mp4_frames Export MP4 seek frames per verse
mp4_frames_dir Output dir for mp4-slide-NNN.jpg
validate_slide_qa Run slide QA manifest gate
require_rights_ack / rights_acknowledged Rights gate
content_approved / plan_approved / plan_draft Plan / content gates
fail_fast Stop on first failed gate (default true)
--sync-variants Force variant sync
--seed-timing Refresh verse timings from transcript
--rights-acknowledged CLI override for rights gate
--pipeline-report Report JSON path
--skip-build Pipeline: validate + MP4 only

See Video + transcript workflow.

Other utility commands

# Slide outline
praisonaippt list-slides -i deck.yaml
praisonaippt list-slides deck.pptx

# Theme template preview
praisonaippt --list-templates
praisonaippt template sermon-dark

# Config (~/.praisonaippt/config.yaml)
praisonaippt config
praisonaippt --config-show

# Google Drive
praisonaippt setup-oauth
praisonaippt setup-credentials
praisonaippt secure-credentials

Showcase rebuild (examples)

python examples/build_showcase_examples.py --heygen-only
python examples/sync_heygen_variants.py

Daily single video pipeline

Module: python -m praisonaippt.daily_single (alias: daily-single).
Full guide: Daily single video pipeline · Testing: Daily single testing · QA stages: Video QA

conda activate test
PROJECT=examples/videos/anthropic-claude-fable-5-mythos-5

# QA-gated order (recommended)
daily-single -p $PROJECT validate-qa --when pre_build
daily-single -p $PROJECT sync-assets
daily-single -p $PROJECT synthesise-vo
daily-single -p $PROJECT validate-qa --when post_vo
daily-single -p $PROJECT bookend-media 00-hook 99-outro
daily-single -p $PROJECT validate-qa --when pre_assemble
daily-single -p $PROJECT build-captions
daily-single -p $PROJECT assemble-beats
daily-single -p $PROJECT validate-display
daily-single -p $PROJECT validate-spoken-visual
daily-single -p $PROJECT validate-qa --when post_build
daily-single -p $PROJECT validate-all

Legacy build-only order (same steps without intermediate gates):

python -m praisonaippt.daily_single --project $PROJECT sync-assets
python -m praisonaippt.daily_single --project $PROJECT synthesise-vo [--skip-existing] [--segments 00-hook]
python -m praisonaippt.daily_single --project $PROJECT bookend-media 00-hook 99-outro [--skip-existing]
python -m praisonaippt.daily_single --project $PROJECT build-captions
python -m praisonaippt.daily_single --project $PROJECT assemble-beats
python -m praisonaippt.daily_single --project $PROJECT validate-display
python -m praisonaippt.daily_single --project $PROJECT validate-spoken-visual
python -m praisonaippt.daily_single --project $PROJECT audit-visual [--interval 5] [--force]
python -m praisonaippt.daily_single --project $PROJECT validate-sync --runs 3
python -m praisonaippt.daily_single --project $PROJECT validate-all
Command Purpose
sync-assets Crawl canonical news page + HD YouTube (≥720p); patch beat-map
synthesise-vo ElevenLabs TTS; strips Hook: label
bookend-media HeyGen hook/outro
assemble-beats ffmpeg beat assembly + hook montage; writes timeline.json (uses final.srt for cue-aligned beats when present)
build-captions SRT from locked script (Whisper timing or proportional fallback)
validate-display Per-cue midpoint → visual; display_sync_report.json
validate-spoken-visual Full spoken↔visual gate (windows, charts, transitions); spoken_visual_sync_report.json
validate-qa Modular QA to merge/qa/ — use --when pre_build, post_vo, pre_assemble, or post_build
audit-visual Pixel audit every N seconds → visual_audit_report.json
validate-sync Script lock + hook montage + display + YouTube quality (×3 runs)
validate-all Full publish gate

Modular QA module: python -m praisonaippt.video_qa (alias: video-qa).

Agent skills: .cursor/skills/daily-single-video/SKILL.md, .cursor/skills/daily-single-video-pipeline/SKILL.md (spoken↔visual: spoken-visual-sync.md)


Need help? Open an issue on GitHub