Video Processor

Process video files for YouTube content creation and generate social media graphics. This skill provides four main capabilities:

1. Transcription & Chapters: Convert video clips into timestamped transcripts, SRT subtitles, and AI-generated YouTube chapters
2. YouTube Thumbnail Generation: Create AI-powered YouTube thumbnails with face references and style matching
3. LinkedIn Post Images: Generate professional LinkedIn infographics and post images
4. Generic Image Generation: Create custom images for any platform with flexible dimensions and prompts

When to Use This Skill

Use this skill when the user:

• Wants to transcribe video files or clips
• Needs to generate YouTube chapters
• Wants to regenerate chapters from existing transcripts
• Wants to create YouTube thumbnails
• Wants to create LinkedIn post images or infographics
• Wants to generate images for other platforms (Instagram, Twitter, Facebook, etc.)
• Mentions face swapping for thumbnails
• Asks about providing face or style references for graphics

Choosing the Right Image Generation Tool

The skill provides three image generation scripts. Choose based on platform and requirements:

Use thumbnail.py (YouTube thumbnails) when:

• User mentions "YouTube", "thumbnail", or "video thumbnail"
• 16:9 aspect ratio requested
• Dramatic, eye-catching style with faces desired
• Default: 1920x1080

Use linkedin-post.py (LinkedIn infographics) when:

• User mentions "LinkedIn", "LinkedIn post", or "business infographic"
• Square format infographic requested
• Professional, dark theme, no faces
• Default: 1200x1200

Use image-gen.py (generic) when:

• Custom dimensions specified (Instagram, Twitter, Facebook, etc.)
• Platform is not YouTube or LinkedIn
• User explicitly requests flexible/custom tool
• User provides full prompt with specific style requirements
• Required parameter: --dimensions WIDTHxHEIGHT

Priority: Always prefer thumbnail.py or linkedin-post.py when the use case matches. Use image-gen.py as fallback for other platforms or custom requirements.

Installation & Requirements

The video processor is located at video-processor/ in the project repository.

Requirements:

• Python 3.9+
• uv package manager
• FFmpeg (for transcription)
• OpenAI API key (for Whisper transcription)
• Gemini API key (for chapters and thumbnails)
• Replicate API token (optional, for face swap)

Environment Setup:

cd video-processor
uv sync
# Ensure .env exists with required API keys

1. Video Transcription & Chapters

Basic Transcription Command

Transcribe video clips and generate transcript, subtitles, and chapters:

cd video-processor
uv run transcribe.py <folder_path>

Example:

uv run transcribe.py ./my-youtube-video/

Input Format

Videos should be in a folder with numeric prefixes for ordering:

my-youtube-video/
├── 1.mp4          # Intro
├── 2.mp4          # Main content
├── 3.mov          # Demo
└── 4.mp4          # Outro

Supported formats: MP4, MOV, MKV, AVI, WEBM, M4V

Output Files

The script generates three files in the same folder:

1. transcript.md - Markdown with timestamps

   # Transcript
   
   [00:00] Welcome back to the channel...
   [00:15] Today we're going to talk about...
   

2. transcript.srt - SRT subtitles for video editors/YouTube

   1
   00:00:00,000 --> 00:00:15,500
   Welcome back to the channel...
   

3. chapters.txt - YouTube chapter suggestions (AI-generated)

   0:00 Introduction
   2:30 Setting Up
   5:45 Main Tutorial
   

Features

• Multi-clip support: Processes numbered clips with automatic timestamp offset calculation
• Long video support: Automatically chunks videos longer than 20 minutes (API limit)
• Timestamped transcript: Markdown format with precise timestamps
• AI chapters: Gemini generates contextual chapter markers

Regenerate Chapters Only

If you already have a transcript and want to regenerate chapters:

cd video-processor
uv run chapters.py <transcript.md or folder_path>

Examples:

# Point to transcript file directly
uv run chapters.py ./my-video/transcript.md

# Or point to folder containing transcript.md
uv run chapters.py ./my-video/

Use cases:

• Tweaking chapters without re-transcription
• Regenerating after editing the transcript
• Using a different Gemini model

Important Notes

• Clips must be in a flat folder (no subdirectories)
• Videos are processed in numeric order by filename prefix
• Estimated cost: ~$0.006 per minute of audio (Whisper API)
• Long videos are automatically chunked to handle API limits
• Internet connection required

2. Thumbnail Generation

Basic Thumbnail Command

Generate AI-powered YouTube thumbnails:

cd video-processor
uv run thumbnail.py "your thumbnail idea here"

Default behavior:

• Generates 3 variations
• Saves to: ./output/Thumbnails/[YYYY-MM-DD]/
• Uses assets/face.jpg if it exists
• Output: 1920x1080 PNG files
• Brand Guidelines: See references/brand-guidelines.md for color palette, composition, and style best practices

Thumbnail Parameters

Required

• idea (positional): Your thumbnail concept/idea

Face Reference Options

• --face PATH: Specify a face reference image (default: assets/face.jpg)
• --no-face: Don't include any face reference
• --face-swap: Post-process with Replicate to swap in real face (requires REPLICATE_API_TOKEN)

Style & References

• --style PATH: Style reference thumbnail - AI matches layout and aesthetic
• --ref PATH: Additional reference image (can use multiple times)

Logo & Output

• --logo PATH: Logo to composite onto thumbnail
• --logo-position [bottom-right|bottom-left|top-right|top-left]: Logo placement (default: bottom-right)
• -o, --output PATH: Output directory or file path
• --variations N: Number of variations to generate (default: 3)

Thumbnail Examples

Basic - 3 variations with default settings:

uv run thumbnail.py "shocked reaction to mass layoffs at Google"

With style reference:

uv run thumbnail.py "my new video idea" --style ./existing-thumbnail.jpg --face ./me.jpg

With face swap for exact likeness:

uv run thumbnail.py "excited about new AI feature" --face ./me.jpg --face-swap

Single variation for quick testing:

uv run thumbnail.py "quick test idea" --variations 1

Custom output directory:

uv run thumbnail.py "my video concept" -o ./custom-folder/

No face (scene only):

uv run thumbnail.py "dramatic code on screen with error" --no-face

With logo overlay:

uv run thumbnail.py "my video concept" --logo ./assets/logo.png

Face Reference Setup

For consistent thumbnails:

1. Add your headshot(s) to the assets/ folder:

   video-processor/assets/
   ├── face.jpg           # Default face (auto-loaded)
   ├── face-excited.jpg   # Alternative expressions
   ├── face-shocked.jpg
   └── logo.png           # Channel logo
   

2. The script automatically uses assets/face.jpg if it exists

3. Override with --face for different expressions

4. Use --no-face to skip face reference entirely

Style References

The --style flag matches existing thumbnail aesthetics:

• Overall layout and composition
• Color schemes and mood
• Text styling (font weight, colors, placement)
• Background style and effects

Perfect for maintaining consistent channel branding.

Brand Guidelines & Best Practices

IMPORTANT: Before generating thumbnails, read references/brand-guidelines.md for:

• Blue brand color usage (as accent, not dominant)
• Natural skin tone requirements (no blue tint on face)
• Balanced color palettes (mix of vibrant colors)
• Text highlighting patterns (1-2 keywords in blue)
• Composition guidelines (layout, visual flow)
• Proven examples from past successful thumbnails

These guidelines ensure thumbnails maintain brand consistency while avoiding common pitfalls like over-saturation or unnatural lighting.

Face Swap for Exact Likeness

AI-generated faces may not be exact. Use --face-swap for post-processing:

uv run thumbnail.py "my video idea" --face ./me.jpg --face-swap

How it works:

1. Generates thumbnail with AI (using face as reference for positioning)
2. Post-processes with Replicate to swap in your actual face

Setup:

• Get Replicate API token at https://replicate.com/account/api-tokens
• Add to .env: REPLICATE_API_TOKEN=r8_your_token_here
• Cost: ~$0.003 per face swap (~370 swaps per $1)

Thumbnail Specifications

Element	Value
Resolution	1920x1080 (1080p)
Aspect Ratio	16:9
Format	PNG (or JPG with --output .jpg)
Default Variations	3
Model	Gemini 3 Pro (Nano Banana Pro) by default

Important Thumbnail Notes

• Gemini model supports reference images; Imagen does not
• Cost: ~$0.13 per image with Gemini 3 Pro
• Face swap adds ~$0.003 per thumbnail
• 3 thumbnails with face swap: ~$0.40 total
• Internet connection required

3. LinkedIn Post Image Generation

Basic LinkedIn Image Command

Generate AI-powered LinkedIn post images and infographics:

cd video-processor
uv run linkedin-post.py "your post concept here"

Default behavior:

• Generates 3 variations
• Saves to: ./output/LinkedIn/[YYYY-MM-DD]/
• Output: 1200x1200 PNG files (LinkedIn square format)
• Optimized for infographic layouts (no faces, white background, flat design)

LinkedIn Image Parameters

Required

• idea (positional): Your LinkedIn post concept/idea

Style & References

• --style PATH: Style reference image - AI matches layout and aesthetic
• --ref PATH: Additional reference image (can use multiple times)

Logo & Output

• --logo PATH: Logo to composite onto image
• --logo-position [bottom-right|bottom-left|top-right|top-left]: Logo placement (default: bottom-right)
• -o, --output PATH: Output directory or file path
• --variations N: Number of variations to generate (default: 3)

LinkedIn Image Examples

Basic - 3 variations:

uv run linkedin-post.py "AI Validation Pyramid with 5 layers showing human vs agent responsibilities"

With style reference:

uv run linkedin-post.py "my infographic concept" --style ./existing-infographic.jpg

Single variation for testing:

uv run linkedin-post.py "quick test" --variations 1

Custom output directory:

uv run linkedin-post.py "my concept" -o ./custom-folder/

With logo overlay:

uv run linkedin-post.py "my infographic" --logo ./assets/logo.png

LinkedIn Image Specifications

Element	Value
Resolution	1200x1200 (LinkedIn square)
Aspect Ratio	1:1
Format	PNG (or JPG with --output .jpg)
Default Variations	3
Model	Gemini 3 Pro (Nano Banana Pro) by default
Style	Professional infographic, no faces, flat design

Important LinkedIn Image Notes

• Optimized for professional business infographics
• Dark theme with modern sleek aesthetic
• NO faces or people included (pure diagram/infographic style)
• Blue color theme with gradients
• Higher information density than YouTube thumbnails
• Cost: ~$0.13 per image with Gemini 3 Pro
• Internet connection required

4. Generic Image Generation

Basic Generic Image Command

Generate AI-powered images with custom dimensions for any platform:

cd video-processor
uv run image-gen.py "your image concept" --dimensions WIDTHxHEIGHT

Key features:

• Custom dimensions (required parameter)
• Minimal prompt wrapping (maximum flexibility)
• Supports style references
• Saves to: ./output/Images/[YYYY-MM-DD]/
• Default: 3 variations

Generic Image Parameters

Required

• idea (positional): Your image concept with full prompt details
• --dimensions WIDTHxHEIGHT: Image dimensions (e.g., 1080x1080, 1200x675)

Style & References

• --style PATH: Style reference image - AI matches aesthetic
• --ref PATH: Additional reference image (can use multiple times)

Logo & Output

• --logo PATH: Logo to composite onto image
• --logo-position [bottom-right|bottom-left|top-right|top-left]: Logo placement (default: bottom-right)
• -o, --output PATH: Output directory or file path
• --variations N: Number of variations to generate (default: 3)

Generic Image Examples

Instagram square post:

uv run image-gen.py "minimalist product photo on white background" --dimensions 1080x1080

Instagram story:

uv run image-gen.py "vertical motivational quote design" --dimensions 1080x1920

Twitter post image:

uv run image-gen.py "tech announcement graphic with blue theme" --dimensions 1200x675

Facebook cover photo:

uv run image-gen.py "professional business header" --dimensions 820x312

With style reference:

uv run image-gen.py "my concept" --dimensions 1200x1200 --style ./reference.jpg

Common Dimensions Reference

Platform	Size	Aspect Ratio	Command
YouTube Thumbnail	1920x1080	16:9	Use thumbnail.py instead
LinkedIn Square	1200x1200	1:1	Use linkedin-post.py instead
Instagram Square	1080x1080	1:1	--dimensions 1080x1080
Instagram Story	1080x1920	9:16	--dimensions 1080x1920
Twitter Post	1200x675	16:9	--dimensions 1200x675
Facebook Post	1200x630	1.91:1	--dimensions 1200x630
Pinterest Pin	1000x1500	2:3	--dimensions 1000x1500

Generic Image Specifications

Element	Value
Resolution	Custom (user-specified via --dimensions)
Aspect Ratio	Auto-calculated from dimensions
Format	PNG (or JPG with --output .jpg)
Default Variations	3
Model	Gemini 3 Pro (Nano Banana Pro) by default
Prompting	Minimal wrapper - user has full control

Important Generic Image Notes

• Use specific tools first: Prefer thumbnail.py for YouTube or linkedin-post.py for LinkedIn
• Maximum flexibility: Minimal opinionated prompting - you control the style
• Custom dimensions required: Must specify --dimensions parameter
• Platform-agnostic: Works for any social media platform or use case
• Cost: ~$0.13 per image with Gemini 3 Pro
• Internet connection required

Asking for Missing Information

When the user doesn't provide necessary information, ask them:

For Transcription

• Path to video folder: "What's the path to the folder containing your video clips?"
• Single video or clips: "Is this a single video file or multiple clips that should be stitched together?"
• If regenerating chapters: "Do you already have a transcript, or should I transcribe the video first?"

For Thumbnails

Before generating: Read references/brand-guidelines.md to understand color palette and composition requirements.

• Thumbnail idea: "What's your thumbnail idea or concept?"
• Face reference: "Would you like to include a face reference? If so, what's the path to the image?"
• Face swap: "Do you want to use face swap for exact likeness? (This requires REPLICATE_API_TOKEN)"
• Style reference: "Do you have an existing thumbnail style to match? If so, provide the path."
• Logo: "Would you like to add a logo to the thumbnail? If so, provide the path."
• Number of variations: "How many thumbnail variations would you like? (Default is 3)"
• Output location: "Where should I save the thumbnails? (Default is ./output/Thumbnails/[today's date]/)"

For LinkedIn Images

• LinkedIn post idea: "What's your LinkedIn post or infographic concept?"
• Style reference: "Do you have an existing infographic style to match? If so, provide the path."
• Logo: "Would you like to add a logo to the image? If so, provide the path."
• Number of variations: "How many variations would you like? (Default is 3)"
• Output location: "Where should I save the LinkedIn images? (Default is ./output/LinkedIn/[today's date]/)"

For Generic Images

• Image concept: "What's your image concept? Provide full prompt details including style, mood, and visual elements."
• Dimensions (REQUIRED): "What dimensions do you need? (e.g., 1080x1080 for Instagram, 1200x675 for Twitter, 1080x1920 for Instagram Story)"
• Platform: "What platform is this for? (Instagram, Twitter, Facebook, etc.)"
• Style reference: "Do you have a style reference image? If so, provide the path."
• Logo: "Would you like to add a logo? If so, provide the path."
• Number of variations: "How many variations would you like? (Default is 3)"
• Output location: "Where should I save the images? (Default is ./output/Images/[today's date]/)"

Cost Estimates

Transcription

• Whisper API: $0.006 per minute of audio
• Gemini (chapters): Free tier available, then pay-per-use
• Example: 20-minute video = ~$0.12-0.15 (transcription + chapters)

Thumbnails

• Gemini (generation): ~$0.13 per image
• Face swap (optional): ~$0.003 per swap
• Example: 3 thumbnails with face swap = ~$0.40

LinkedIn Images

• Gemini (generation): ~$0.13 per image
• Example: 3 LinkedIn infographics = ~$0.40

Generic Images

• Gemini (generation): ~$0.13 per image
• Example: 3 Instagram posts = ~$0.40

Configuration

Environment variables in video-processor/.env:

Variable	Default	Description
OPENAI_API_KEY	(required)	OpenAI API key for Whisper
WHISPER_MODEL	whisper-1	Transcription model
GEMINI_API_KEY	(required)	Gemini API key
GEMINI_MODEL	gemini-3-flash-preview	Model for chapters
GEMINI_THUMBNAIL_MODEL	gemini-3-pro-image-preview	Model for thumbnails
REPLICATE_API_TOKEN	(optional)	For face swap feature

Error Handling

Common issues and solutions:

1. "OPENAI_API_KEY not set": Add key to .env file
2. "GEMINI_API_KEY not set": Add key to .env file
3. "FFmpeg not installed": Install FFmpeg (see README)
4. "No video files found": Check file extensions and ensure files are in folder root
5. Quota errors (thumbnails): Ensure billing enabled on Google AI account

Workflow Examples

Complete Video Processing Workflow

1. Transcribe video clips:

   cd video-processor
   uv run transcribe.py ./my-video/
   

2. Review and edit chapters if needed:

   # Edit chapters.txt manually or regenerate
   uv run chapters.py ./my-video/transcript.md
   

3. Generate thumbnails:

   uv run thumbnail.py "my video concept" --face ./assets/face.jpg --variations 3
   

Quick Thumbnail Testing

cd video-processor
uv run thumbnail.py "quick test" --variations 1 --no-face

Professional Thumbnail with Branding

cd video-processor
uv run thumbnail.py "professional video title" \
  --face ./assets/face-excited.jpg \
  --style ./previous-thumbnail.jpg \
  --logo ./assets/logo.png \
  --logo-position bottom-right \
  --face-swap