video-captioner

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

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)