video-captioner

name	video-captioner
description	Use when asked to add text overlays, subtitles, or captions to videos with customizable positioning, styling, and timing.

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

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

# 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

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) -> 
     () -> 
     () -> 

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:

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

YouTube Subtitle:

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

Minimal:

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

Bold:

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

SRT Format

Create SRT subtitle files:

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

{
  "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:

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

Text with Outline:

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

Semi-transparent Background:

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

Use Cases

Social Media Videos:

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

Tutorial Videos:

# 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:

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

Branding:

# 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)