Agent skill

video-captioner

Use when asked to add text overlays, subtitles, or captions to videos with customizable positioning, styling, and timing.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/video-captioner

SKILL.md

Video Captioner

Add text overlays, subtitles, and captions to videos with full control over positioning, styling, timing, and animation.

Purpose

Video captioning and text overlays for:

  • Social media videos (Instagram, TikTok, YouTube)
  • Educational content and tutorials
  • Subtitle generation and translation
  • Branding and watermarks
  • Accessibility compliance

Features

  • Text Overlays: Add static or timed text to videos
  • Subtitle Tracks: Import SRT files or create programmatically
  • Custom Styling: Font, size, color, background, outline
  • Positioning: Top, middle, bottom, custom coordinates
  • Animations: Fade in/out, typewriter effect
  • Batch Captions: Apply same style to multiple videos
  • Preview: Generate preview frames before rendering

Quick Start

python
from video_captioner import VideoCaptioner

# Add simple text overlay
captioner = VideoCaptioner()
captioner.load('video.mp4')
captioner.add_text(
    text="Hello World!",
    position='bottom',
    font_size=48,
    color='white'
)
captioner.save('captioned.mp4')

# Add timed captions
captioner.add_caption(
    text="First caption",
    start=0.0,
    end=3.0,
    position='bottom'
)
captioner.add_caption(
    text="Second caption",
    start=3.0,
    end=6.0,
    position='bottom'
)
captioner.save('with_captions.mp4')

# Import SRT subtitles
captioner.import_srt('subtitles.srt')
captioner.save('subtitled.mp4')

CLI Usage

bash
# Simple text overlay
python video_captioner.py input.mp4 --text "Subscribe!" --position bottom --output captioned.mp4

# Add SRT subtitles
python video_captioner.py input.mp4 --srt subtitles.srt --output subtitled.mp4

# Custom styling
python video_captioner.py input.mp4 --text "Sale!" --font-size 72 --color red --bg-color black --position center --output promo.mp4

# Timed text (JSON format)
python video_captioner.py input.mp4 --captions captions.json --output video_with_captions.mp4

API Reference

VideoCaptioner

python
class VideoCaptioner:
    def load(self, filepath: str) -> 'VideoCaptioner'
    def add_text(self, text: str, position: str = 'bottom',
                font: str = 'Arial', font_size: int = 48,
                color: str = 'white', bg_color: str = None,
                outline: bool = True) -> 'VideoCaptioner'
    def add_caption(self, text: str, start: float, end: float,
                   **style_kwargs) -> 'VideoCaptioner'
    def import_srt(self, srt_filepath: str, **style_kwargs) -> 'VideoCaptioner'
    def import_captions_json(self, json_filepath: str) -> 'VideoCaptioner'
    def style_preset(self, preset: str) -> 'VideoCaptioner'
    def preview_frame(self, time: float, output: str) -> str
    def save(self, output: str, codec: str = 'libx264') -> str
    def clear_captions(self) -> 'VideoCaptioner'

Text Positioning

Available positions:

  • 'top': Top center
  • 'bottom': Bottom center (default)
  • 'center': Middle center
  • 'top-left': Top left corner
  • 'top-right': Top right corner
  • 'bottom-left': Bottom left corner
  • 'bottom-right': Bottom right corner
  • (x, y): Custom pixel coordinates (tuple)

Style Presets

Instagram Story:

python
captioner.style_preset('instagram-story')
# White text, large font, top position, strong outline

YouTube Subtitle:

python
captioner.style_preset('youtube')
# Yellow text, medium font, bottom position, black background

Minimal:

python
captioner.style_preset('minimal')
# White text, no background, subtle shadow

Bold:

python
captioner.style_preset('bold')
# Large white text, black background box

SRT Format

Create SRT subtitle files:

srt
1
00:00:00,000 --> 00:00:03,000
First subtitle text

2
00:00:03,000 --> 00:00:06,000
Second subtitle text

JSON Captions Format

json
{
  "captions": [
    {
      "text": "First caption",
      "start": 0.0,
      "end": 3.0,
      "position": "bottom",
      "font_size": 48,
      "color": "white"
    },
    {
      "text": "Second caption",
      "start": 3.0,
      "end": 6.0,
      "position": "center",
      "font_size": 60,
      "color": "yellow"
    }
  ]
}

Advanced Styling

Text with Background Box:

python
captioner.add_text(
    text="Important!",
    color='white',
    bg_color='black',
    font_size=60
)

Text with Outline:

python
captioner.add_text(
    text="Subscribe",
    color='yellow',
    outline=True,
    outline_color='black',
    outline_width=2
)

Semi-transparent Background:

python
captioner.add_text(
    text="Overlay text",
    bg_color='rgba(0,0,0,128)',  # Black, 50% opacity
    font_size=48
)

Use Cases

Social Media Videos:

python
# Instagram reel with centered text
captioner.style_preset('instagram-story')
captioner.add_text("Check this out!", position='top')

Tutorial Videos:

python
# Add step-by-step instructions
captioner.add_caption("Step 1: Open the app", 0, 5)
captioner.add_caption("Step 2: Click settings", 5, 10)
captioner.add_caption("Step 3: Enable feature", 10, 15)

Accessibility:

python
# Add full subtitles from SRT
captioner.import_srt('subtitles.srt')
captioner.style_preset('youtube')  # High contrast for readability

Branding:

python
# Add persistent watermark
captioner.add_text(
    "@username",
    position='bottom-right',
    font_size=24,
    color='white',
    outline=True
)

Performance Tips

  • Pre-render preview frames to test styling
  • Use h264 codec for faster encoding
  • Keep caption duration >2 seconds for readability
  • Use high contrast colors for accessibility
  • Test on mobile screens for social media

Limitations

  • Text rendering performance depends on video length
  • Complex animations may increase render time
  • Very long text may overflow screen bounds
  • Emoji support depends on installed fonts
  • Cannot edit burned-in existing captions (requires original)

Didn't find tool you were looking for?

Be as detailed as possible for better results