Imported from adnanul-islam-jisun/Auto-video-generator- (.agents/skills/generate_video_config/SKILL.md). Install upstream with npx skills add adnanul-islam-jisun/Auto-video-generator- --skill generate_video_config. Copyright stays with the author.

Professional Video Configuration Generator

🎯 Objective

Act as a professional videographer and editor. For ANY given set of images and voiceover, autonomously analyze the visual content of every image, deeply understand the voiceover script, and intelligently match images to narration so the final video tells a coherent visual story. Then generate a perfectly timed video_config.json.

This skill is UNIVERSAL. The images, voiceover, voice_details, and topic will be DIFFERENT every time. NEVER assume what the content is about. Always discover and analyze fresh.

🧠 Core Philosophy: Think Like a Professional Videographer

GOLDEN RULE: A professional videographer NEVER places images randomly. Every visual cut serves the story. The image on screen must emotionally and contextually reinforce the words being spoken at that exact moment. This is the #1 priority — regardless of what the video is about.

Visual Storytelling Principles (MANDATORY)

1. Emotional Resonance: Each image must evoke the same emotion as the narration at that moment.
2. Visual Variety: Avoid showing the same type of image back-to-back. Alternate between different visual types to maintain visual rhythm.
3. Scene Pacing: Emotionally intense moments get slightly longer screen time. Quick informational points can be shorter.
4. Opening & Closing Impact: First and last clips carry the most weight. Use strongest, most relevant images for these positions.
5. Transition Logic: Use crossfade for smooth flow, fade_black for scene/topic changes, slide_left for forward progression.

📁 Project File Structure Reference

<project-root>/
├── voice_details.json          # Word-level timestamps (from Google Speech API)
├── video_config.json           # ← OUTPUT: The final generated config
├── image_mapping.json          # ← INTERMEDIATE: AI's image→scene decisions
├── schema_video_config.json    # Schema/rules for video_config.json
├── assets/
│   ├── images/                 # All images for the video (any count, any format)
│   ├── voiceovers/             # Voiceover audio file(s) (.m4a, .mp3, .wav)
│   ├── music/                  # (Optional) Background music
│   ├── fonts/                  # Font files (.ttf, .otf)
│   └── watermark/              # (Optional) Logo/watermark images
└── .agents/skills/generate_video_config/
    ├── SKILL.md                # This file
    └── scripts/
        └── generate_config.py  # Timing engine script

🤖 Execution Workflow (Multi-Phase — STRICTLY Sequential)

CRITICAL RULE: Do NOT skip phases. Do NOT do all steps in a single output. Complete each phase fully before moving to the next. The quality of the final video depends entirely on Phase 1 and Phase 2.

Phase 1: Discovery & Deep Analysis

Step 1.1 — Schema Understanding

Read schema_video_config.json at the project root. Internalize all mandatory and optional fields.

Step 1.2 — Dynamic Asset Discovery

Scan the project filesystem to find all available assets. Nothing is hardcoded — discover everything fresh each time:

IMPORTANT: Note exact filenames — they change every project. Never assume main_voice.m4a or any specific name.

Step 1.3 — 🔍 VISUAL IMAGE ANALYSIS (MOST CRITICAL STEP)

For EVERY image found, you MUST use the view_file tool to actually LOOK at the image. NEVER guess from filenames — filenames like IMG_20240423.jpeg or WhatsApp Image 2026-04-23.jpeg tell you NOTHING.

For each image, create a profile:

• Primary Subject: What is the main thing? (person, animal, product, building, landscape, object, food, logo, etc.)
• Setting/Environment: Where? (indoor, outdoor, rural, urban, studio, natural, etc.)
• Mood/Emotion: What feeling? (happy, nostalgic, energetic, calm, professional, warm, etc.)
• Visual Tags: 2-4 descriptive tags based on what you SEE.
• Quality: Real photo / AI-generated / graphic / placeholder (solid color block)?

PLACEHOLDER DETECTION: Solid color rectangles (from make test) should be tagged [placeholder] and deprioritized. Only use if no real images are available.

You may need to view images in batches. Plan accordingly.

Step 1.4 — Voice Details & Script Analysis

Read voice_details.json. This follows Google Speech-to-Text format:

{
  "results": [{
    "alternatives": [{
      "transcript": "Full text here...",
      "words": [
        {"word": "word1", "startOffset": "0.600s", "endOffset": "1.200s"},
        ...
      ]
    }]
  }]
}

Extract:

1. Full transcript text
2. Every word with exact startOffset and endOffset
3. Total audio duration = last word's endOffset
4. Total word count

Then perform narrative scene decomposition:

• Break the transcript into logical scenes/sentences based on:
  • Punctuation marks (।, ?, !, ., etc.)
  • Natural pauses (gaps > 0.5s between words)
  • Topic shifts
• For each scene, identify:
  • Core message — What is being said?
  • Key visual concepts — What should the viewer SEE?
  • Emotional tone — What mood?

LANGUAGE NOTE: The transcript can be in ANY language (Bengali, English, Hindi, Arabic, etc.). Analyze meaning regardless.

Phase 2: Intelligent Image-to-Scene Mapping (The Director's Cut)

You are the film director. You decide what the viewer sees at every moment. This changes completely based on content.

Step 2.1 — Clip Count Strategy

Optimal clip duration: 4–10 seconds. If a scene > 15s, split across multiple images.

Step 2.2 — Semantic Matching Priority

1. Direct Match (Best): Image directly depicts what's being discussed.
2. Thematic Match (Good): Image evokes the same theme or category.
3. Atmospheric Match (Acceptable): Image sets the right mood.
4. Placeholder (Last Resort): Solid-color test images only if nothing else available.

Step 2.3 — Constraints

• Use ALL real (non-placeholder) images at least once.
• NEVER place the same image in two consecutive clips.
• If reusing, spread with 2-3 different images between reuses.

Step 2.4 — Visual Flow Review

After mapping, review the storyboard:

• Coherent visual story?
• Enough variety?
• Strong opening and closing?
• Adjust as needed.

Step 2.5 — Present the Mapping Table

Before generating config, output a clear summary:

| # | Image File | Scene (first 30 chars) | Duration | Why This Image? |
|---|-----------|------------------------|----------|-----------------|
| 1 | photo.png | "Opening sentence..."  | 10.1s    | Matches theme X |
| 2 | rural.jpg | "Second sentence..."   | 8.5s     | Shows Y context |

Phase 3: Generate Config via Script

After semantic mapping is finalized, use the Python script for mathematically perfect timing. The AI should NOT manually calculate 100+ word timings.

Step 3.1 — Write image_mapping.json

Create this file at the project root:

[
  {
    "clip_index": 0,
    "image": "exact_filename.png",
    "word_start_index": 0,
    "word_end_index": 20,
    "transition": "crossfade"
  },
  {
    "clip_index": 1,
    "image": "another_file.jpeg",
    "word_start_index": 21,
    "word_end_index": 45,
    "transition": "fade_black"
  }
]

Fields:

• clip_index — Sequential (0-based)
• image — Exact filename from assets/images/ (case-sensitive!)
• word_start_index — First word index (0-based) from voice_details word array
• word_end_index — Last word index (inclusive)
• transition — crossfade | fade_black | slide_left

Validation:

• Word indices must cover ALL words: 0 to (total_words - 1), no gaps, no overlaps
• Every real image must appear at least once
• Filenames must exactly match files in assets/images/

Step 3.2 — Run the Script

python3 .agents/skills/generate_video_config/scripts/generate_config.py

The script will:

1. Read voice_details.json + image_mapping.json
2. Discover voiceover, font, background music from assets/
3. Calculate relative word timings per clip
4. Create display chunks (max 4 words each)
5. Handle transition overlaps (1.0s default)
6. Write video_config.json
7. Print verification report

Fallback mode: If image_mapping.json doesn't exist, auto-distributes words across images alphabetically (no semantic matching).

Step 3.3 — Verify

Check the script's output:

• ✅ Total word count matches
• ✅ No negative timings
• ✅ All clips present
• ✅ Voiceover only on first clip (if voiceover file exists)

Phase 4: Cinematic Polish

Step 4.1 — Transitions

• crossfade — Default smooth flow
• fade_black — Topic change or dramatic pause
• slide_left — Forward momentum / call-to-action
• Last clip always → "none" (automatic)

Step 4.2 — Dynamic Text Defaults

Step 4.3 — Output Resolution

• Vertical (Shorts/Reels): [1080, 1920] (default)
• Landscape (YouTube): [1920, 1080]
• Ask or infer from context which to use.

⚠️ Edge Cases & Dynamic Handling

📄 Output Schema Quick Reference

The final video_config.json must follow schema_video_config.json. Structure:

{
  "output": {
    "resolution": [1080, 1920],
    "fps": 24,
    "filename": "output/final_video.mp4"
  },
  "dynamic_text": {
    "enabled": true,
    "font": "discovered_font.ttf",
    "font_size": 80,
    "text_color": "white",
    "highlight_color": "yellow",
    "bg_color": "rgba(0,0,0,0.6)",
    "position": "center",
    "y_offset": 250,
    "padding_x": 40,
    "padding_y": 20,
    "border_radius": 15
  },
  "clips": [
    {
      "image": "photo.jpeg",
      "voiceover": "narration.m4a",
      "duration": 10.14,
      "transition": "crossfade",
      "text_chunks": [
        {
          "start": 0.0,
          "end": 1.88,
          "words": [
            {"word": "example", "start": 0.0, "end": 0.6},
            {"word": "text", "start": 0.6, "end": 1.2}
          ]
        }
      ]
    }
  ],
  "background_music": {
    "file": "bg_music.mp3",
    "volume": 0.2,
    "duck_volume": 0.05
  },
  "watermark": {
    "enabled": false,
    "file": "logo.png",
    "position": "top_right",
    "opacity": 0.8,
    "size": 150,
    "margin": 20
  }
}

All file paths must match actual filenames in assets/ subdirectories. Verify before writing.