Back to Details

video-captioner

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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
视频字幕与文本叠加适用于：
  • 社交媒体视频（Instagram、TikTok、YouTube）
  • 教育内容与教程
  • 字幕生成与翻译
  • 品牌标识与水印
  • 无障碍合规支持

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
  • 文本叠加层：为视频添加静态或定时文本
  • 字幕轨道：导入SRT文件或程序化创建
  • 自定义样式：字体、大小、颜色、背景、轮廓
  • 位置设置：顶部、中间、底部、自定义坐标
  • 动画效果：淡入淡出、打字机效果
  • 批量字幕：为多个视频应用相同样式
  • 预览功能：渲染前生成预览帧

Quick Start

快速开始

python
from video_captioner import VideoCaptioner
python
from video_captioner import VideoCaptioner

Add simple text overlay

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

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

Import SRT subtitles

captioner.import_srt('subtitles.srt') captioner.save('subtitled.mp4')
undefined
captioner.import_srt('subtitles.srt') captioner.save('subtitled.mp4')
undefined

CLI Usage

CLI 用法

bash
undefined
bash
undefined

Simple text overlay

Simple text overlay

python video_captioner.py input.mp4 --text "Subscribe!" --position bottom --output captioned.mp4
python video_captioner.py input.mp4 --text "Subscribe!" --position bottom --output captioned.mp4

Add SRT subtitles

Add SRT subtitles

python video_captioner.py input.mp4 --srt subtitles.srt --output subtitled.mp4
python video_captioner.py input.mp4 --srt subtitles.srt --output subtitled.mp4

Custom styling

Custom styling

python video_captioner.py input.mp4 --text "Sale!" --font-size 72 --color red --bg-color black --position center --output promo.mp4
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)

Timed text (JSON format)

python video_captioner.py input.mp4 --captions captions.json --output video_with_captions.mp4
undefined
python video_captioner.py input.mp4 --captions captions.json --output video_with_captions.mp4
undefined

API Reference

API 参考

VideoCaptioner

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'
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)
可用位置：
  • 'top'
    : 顶部居中
  • 'bottom'
    : 底部居中（默认）
  • 'center'
    : 中间居中
  • 'top-left'
    : 左上角
  • 'top-right'
    : 右上角
  • 'bottom-left'
    : 左下角
  • 'bottom-right'
    : 右下角
  • (x, y)
    : 自定义像素坐标（元组）

Style Presets

样式预设

Instagram Story:
python
captioner.style_preset('instagram-story')
Instagram 快拍：
python
captioner.style_preset('instagram-story')

White text, large font, top position, strong outline

White text, large font, top position, strong outline


**YouTube Subtitle:**
```python
captioner.style_preset('youtube')

**YouTube 字幕：**
```python
captioner.style_preset('youtube')

Yellow text, medium font, bottom position, black background

Yellow text, medium font, bottom position, black background


**Minimal:**
```python
captioner.style_preset('minimal')

**极简风格：**
```python
captioner.style_preset('minimal')

White text, no background, subtle shadow

White text, no background, subtle shadow


**Bold:**
```python
captioner.style_preset('bold')

**粗体风格：**
```python
captioner.style_preset('bold')

Large white text, black background box

Large white text, black background box

undefined
undefined

SRT Format

SRT 格式

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
创建SRT字幕文件：
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 字幕格式

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"
    }
  ]
}
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
)
带背景框的文本：
python
captioner.add_text(
    text="Important!",
    color='white',
    bg_color='black',
    font_size=60
)
带轮廓的文本：
python
captioner.add_text(
    text="Subscribe",
    color='yellow',
    outline=True,
    outline_color='black',
    outline_width=2
)
半透明背景：
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
undefined
社交媒体视频：
python
undefined

Instagram reel with centered text

Instagram reel with centered text

captioner.style_preset('instagram-story') captioner.add_text("Check this out!", position='top')

**Tutorial Videos:**
```python
captioner.style_preset('instagram-story') captioner.add_text("Check this out!", position='top')

**教程视频：**
```python

Add step-by-step instructions

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

**无障碍支持：**
```python

Add full subtitles from SRT

Add full subtitles from SRT

captioner.import_srt('subtitles.srt') captioner.style_preset('youtube') # High contrast for readability

**Branding:**
```python
captioner.import_srt('subtitles.srt') captioner.style_preset('youtube') # High contrast for readability

**品牌标识：**
```python

Add persistent watermark

Add persistent watermark

captioner.add_text( "@username", position='bottom-right', font_size=24, color='white', outline=True )
undefined
captioner.add_text( "@username", position='bottom-right', font_size=24, color='white', outline=True )
undefined

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
  • 预渲染预览帧以测试样式
  • 使用h264编码以加快编码速度
  • 字幕时长保持2秒以上以保证可读性
  • 使用高对比度颜色以支持无障碍需求
  • 针对社交媒体在移动屏幕上进行测试

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)
  • 文本渲染性能取决于视频长度
  • 复杂动画会增加渲染时间
  • 过长文本可能超出屏幕边界
  • 表情符号支持取决于已安装的字体
  • 无法编辑已嵌入视频的现有字幕（需要原视频文件）