video-processor

name

video-processor

description

Process video files for YouTube content creation and generate social media graphics - transcribe videos/clips into timestamped transcripts with SRT subtitles and AI-generated chapters, generate AI-powered YouTube thumbnails with face references, create LinkedIn post infographics, or generate custom images for any platform with flexible dimensions. Use when the user wants to transcribe video clips, create chapters, generate thumbnails, create LinkedIn graphics, or generate images for social media. Triggers on requests like "transcribe this video", "create chapters for...", "generate a thumbnail for...", "create a LinkedIn infographic", "generate an Instagram post", or any video transcription/image generation tasks.

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