1. Generate dubbing via TTS → Get narration.mp3 + narration.json (timestamps)
2. Read narration.json and analyze the semantic meaning of each sentence
3. Determine which sentences each image corresponds to (match by content semantics, not average distribution!)
4. Duration of each image = end timestamp of the last corresponding sentence - start timestamp of the first corresponding sentence
5. Verification: Sum of all durations ≈ total audio duration (error < 1s)
6. ⛔ Run verify_alignment.py for validation (must pass before synthesis!)
7. Only write video_config.yaml after passing validation; otherwise, stop!

Timestamps in narration.json:
  Sentence 0 [0.1-2.6]  "Quiet Night Thoughts, Tang Dynasty, Li Bai."
  Sentence 1 [2.6-5.7]  "Before my bed a pool of light, I wonder if it's frost on the ground."
  Sentence 2 [5.7-8.6]  "I lift my eyes and look at the bright moon, I lower my head and think of my hometown."
  Sentence 3 [8.6-16.4] "This poem was written by Li Bai, a great poet of the Tang Dynasty..."
  Sentence 4 [16.4-20.9] "In just twenty characters..."
  Sentence 5 [20.9-22.6] "Before my bed a pool of light."
  ...

Image Allocation:
  01_title.png    → Sentences 0-2 (Full poem recitation) → duration = 8.6 - 0.1 = 8.5s
  02_poet.png     → Sentences 3-4 (Poet introduction) → duration = 20.9 - 8.6 = 12.3s
  03_moonlight.png → Sentences 5-8 (Interpretation of the first line) → duration = 38.6 - 20.9 = 17.7s
  ...

Validation: 8.5 + 12.3 + 17.7 + ... = 114.4s ≈ Audio duration 114.5s ✅

# ✅ Default: Do not specify -r parameter, or explicitly write -r 16:9
python text_to_image.py "prompt" -o output.png
python text_to_image.py "prompt" -r 16:9 -o output.png

# ❌ Forbidden: Randomly switch ratios, alternating between portrait and landscape
# All images in the same video project must use the same ratio!

# ❌ Wrong: Use English prompt
python text_to_image.py "modern tech illustration, AI robot, blue gradient background"

# ❌ Wrong: Mix English and Chinese in prompt
python text_to_image.py "tech style, Chinese text 'Duel', blue theme"

# ✅ Correct: Chinese-only prompt
python text_to_image.py "Modern tech illustration style, cute AI robot sitting in front of a computer, blue-purple gradient background, neon lighting effects, multiple floating holographic UI panels, high information density, professional infographic style"

# ❌ Wrong: Too little text
Only "AI Comparison" in the image

# ✅ Correct: Rich text points
Image includes:
- Title: QoderWork vs OpenClaw
- Subtitle: Desktop AI Assistant Comparison
- Point 1: Out-of-the-box vs Customizable
- Point 2: $19/month vs Free & Open Source
- Point 3: General Users vs Tech Enthusiasts

# ❌ Wrong: Too empty
Only text, no icons, charts, or decorations

# ✅ Correct: Rich visualization
- Match with icons (checkmarks, crosses, arrows, stars)
- Match with charts (bar charts, pie charts, comparison bars)
- Match with illustrations (robots, computers, user avatars)
- Match with decorations (lighting effects, gradients, borders)

# ❌ Wrong: Too vague
"A robot"
"Tech-style image"
"Comparison image"

# ✅ Correct: Detailed and specific
"Cute blue AI robot mascot, rounded metallic texture, sitting at a modern minimalist desk,
with a 27-inch curved monitor displaying code, a coffee cup and succulent plant beside it,
three holographic panels floating above the robot showing line charts, pie charts, and progress bars,
dark blue tech background, blue light strips on the floor, cyberpunk style, soft volumetric lighting"

# Define unified style prefix (Chinese!)
STYLE="Modern tech illustration style, clean vector design, blue-purple gradient color scheme, professional infographic aesthetics, high information density, neon glow effect, dark background"

# All images use this prefix + same aspect ratio
python text_to_image.py "$STYLE, [specific scene content]" -r 16:9 -o scene01.png
python text_to_image.py "$STYLE, [specific scene content]" -r 16:9 -o scene02.png

┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Story → Split into scenes → Parallel generation of scene main images (text-to-image) │
│                                                              │
│   Havoc in Heaven →  Scene 1: Sun Wukong humiliated as Horse Keeper │
│              Scene 2: Returns to Flower Fruit Mountain on Cloud Somersault │
│              Scene 3: Jade Emperor sends troops │
│              ...                                              │
│              → Parallel call text_to_image.py to generate main image for each scene │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Each scene main image → Generate close-up shots via image-to-image (maintain character consistency) │
│                                                              │
│   Scene 1 main image → Close-up 1: Sun Wukong doubts the official seal │
│              Close-up 2: Sun Wukong kicks over the horse trough │
│   Scene 2 main image → Close-up 1: Soars on Cloud Somersault │
│              Close-up 2: Proclaims himself Great Sage Equal to Heaven at Flower Fruit Mountain │
│              → Parallel call image_to_image.py with main image as reference │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ Layer 3: Generate dubbing + subtitles + validation + video synthesis │
│                                                              │
│   1. tts_generator.py generates dubbing + timestamps │
│   2. [Rule] Precisely calculate duration of each image based on timestamps │
│   3. Generate SRT subtitles │
│   4. Generate video_config.yaml │
│   5. ⛔ Run verify_alignment.py for validation (must pass!) │
│   6. video_maker.py synthesis: │
│      → Image synthesis (with transitions) │
│      → Audio merging │
│      → Burn subtitles (ASS format, fixed at bottom center) │
│      → Auto-append outro (QR code + "Follow for more content") │
│      → Add BGM │
└─────────────────────────────────────────────────────────────┘

**Rule: All videos must auto-append outro!**

assets/generated/{project_name}/
├── scene1/
│   ├── main.png         # Scene 1 main image (text-to-image)
│   ├── shot_01.png      # Close-up 1 (image-to-image)
│   └── shot_02.png      # Close-up 2 (image-to-image)
├── scene2/
│   ├── main.png
│   ├── shot_01.png
│   └── shot_02.png
├── ...
├── narration.mp3        # Dubbing
├── narration.json       # Timestamps
├── subtitles.srt        # Subtitles
├── video_config.yaml    # Video configuration
└── {project_name}.mp4   # Final video

# Layer 1: Parallel generation of scene main images (default 16:9)
python .opencode/skills/image-service/scripts/text_to_image.py "Style description, Scene 1 content" -r 16:9 -o scene1/main.png &
python .opencode/skills/image-service/scripts/text_to_image.py "Style description, Scene 2 content" -r 16:9 -o scene2/main.png &
wait

# Layer 2: Parallel image-to-image generation of close-up shots (same aspect ratio)
python .opencode/skills/image-service/scripts/image_to_image.py scene1/main.png "Maintain character style, close-up description" -r 16:9 -o scene1/shot_01.png &
python .opencode/skills/image-service/scripts/image_to_image.py scene1/main.png "Maintain character style, close-up description" -r 16:9 -o scene1/shot_02.png &
wait

# Layer 3: Generate dubbing + validation + video synthesis
python .opencode/skills/video-creator/scripts/tts_generator.py --text "Full narration" --output narration.mp3 --timestamps

# ⛔ Mandatory validation (must pass before synthesis!)
python .opencode/skills/video-creator/scripts/verify_alignment.py video_config.yaml

# Synthesize only after validation passes
python .opencode/skills/video-creator/scripts/video_maker.py video_config.yaml --srt subtitles.srt --bgm epic

# video_config.yaml
ratio: "16:9"           # Default landscape! Must be quoted to avoid YAML parsing errors
bgm_volume: 0.12
outro: true

scenes:
  - audio: narration.mp3
    images:
      # Arrange all close-up shots in scene order
      - file: scene1/shot_01.png
        duration: 4.34
      - file: scene1/shot_02.png
        duration: 4.88
      - file: scene2/shot_01.png
        duration: 2.15
      # ...

import json
with open("narration.json", "r") as f:
    timestamps = json.load(f)
audio_duration = timestamps[-1]["end"]
print(f"Total audio duration: {audio_duration:.1f}s")

# Example: Division based on narration content
# Find timestamp points where theme changes
scenes = [
    ("cover.png", 0, 12.5),      # Opening to first theme change
    ("scene01.png", 12.5, 26),   # Second segment content
    # ... Precisely divide based on sentence boundaries in narration.json
]

for file, start, end in scenes:
    duration = end - start
    print(f"{file}: {duration:.1f}s")

total_duration = sum(end - start for _, start, end in scenes)
assert abs(total_duration - audio_duration) < 1.0, \
    f"Duration mismatch! Total image duration {total_duration}s vs Audio duration {audio_duration}s"

# ⛔ Must run validation script before video synthesis. Forbid synthesis if it fails!
python .opencode/skills/video-creator/scripts/verify_alignment.py video_config.yaml

# Validation Content:
# 1. Whether all image files exist
# 2. Whether duration is a precise numerical value (reject non-numeric values directly!)
# 3. Total image duration vs Total audio duration (error < 1s)
# 4. Whether each image duration is within reasonable range (1-7s)
# 5. Semantic cross-check between image filename keywords and voice content keywords
# 6. Output complete comparison table (Image + Duration + Semantic ✅/❌ + Corresponding voice text)

# Exit code 0 = Pass, 1 = Fail
# Forbid synthesis if failed, must fix and re-validate!

| Scene Image | Corresponding Content | Start | End | Duration |
|-------------|-----------------------|-------|-----|----------|
| cover.png | Opening Introduction | 0s | 12.5s | 12.5s |
| scene01.png | AI Agent Era | 12.5s | 26s | 13.5s |
| ... | ... | ... | ... | ... |
| **Total** | | | | **{total}s** |

Total Audio Duration: {audio_duration}s
Difference: {diff}s ✅/❌

python video_maker.py config.yaml [options]

python verify_alignment.py video_config.yaml

python tts_generator.py --text "Text" --output audio.mp3 [options]

# Method 1: Shortcut parameter (Recommended)
python video_maker.py config.yaml --bgm epic
python video_maker.py config.yaml --bgm ancient
python video_maker.py config.yaml --bgm edm

# Method 2: Full filename
python video_maker.py config.yaml --bgm bgm_ancient_tale.mp3

# Method 3: Custom path
python video_maker.py config.yaml --bgm /path/to/custom.mp3

video-creator/
├── SKILL.md
├── scripts/
│   ├── video_maker.py        # Main script: Images + Audio → Video (built-in duration hard check)
│   ├── verify_alignment.py   # Mandatory pre-synthesis validation (Duration + Semantic cross-check)
│   ├── tts_generator.py      # TTS Voice Generation
│   └── scene_splitter.py     # Scene Splitter (Optional)
├── assets/
│   ├── outro.mp4             # General outro (16:9)
│   ├── outro_9x16.mp4        # Portrait outro
│   ├── outro_3x4.mp4         # 3:4 outro
│   └── bgm_*.mp3             # 22 BGM tracks (see BGM Resource Table)
└── references/
    └── edge_tts_voices.md

# System Dependencies
brew install ffmpeg  # Mac

# Python Dependencies
pip install edge-tts pyyaml