| 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:
- Transcription & Chapters: Convert video clips into timestamped transcripts, SRT subtitles, and AI-generated YouTube chapters
- YouTube Thumbnail Generation: Create AI-powered YouTube thumbnails with face references and style matching
- LinkedIn Post Images: Generate professional LinkedIn infographics and post images
- 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
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:
-
transcript.md - Markdown with timestamps
# Transcript
[00:00] Welcome back to the channel...
[00:15] Today we're going to talk about...
-
transcript.srt - SRT subtitles for video editors/YouTube
1
00:00:00,000 --> 00:00:15,500
Welcome back to the channel...
-
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:
uv run chapters.py ./my-video/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:
-
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
-
The script automatically uses assets/face.jpg if it exists
-
Override with --face for different expressions
-
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:
- Generates thumbnail with AI (using face as reference for positioning)
- Post-processes with Replicate to swap in your actual face
Setup:
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:
- "OPENAI_API_KEY not set": Add key to
.env file
- "GEMINI_API_KEY not set": Add key to
.env file
- "FFmpeg not installed": Install FFmpeg (see README)
- "No video files found": Check file extensions and ensure files are in folder root
- Quota errors (thumbnails): Ensure billing enabled on Google AI account
Workflow Examples
Complete Video Processing Workflow
-
Transcribe video clips:
cd video-processor
uv run transcribe.py ./my-video/
-
Review and edit chapters if needed:
uv run chapters.py ./my-video/transcript.md
-
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
