video-captioner

视频字幕工具

为视频添加文字叠加、字幕和说明文字，并全面控制其位置、样式、时间和动画效果。

用途

视频字幕和文字叠加，适用于：

• 社交媒体视频（Instagram、TikTok、YouTube）
• 教育内容和教程
• 字幕生成和翻译
• 品牌标识和水印
• 无障碍合规

功能

• 文字叠加：为视频添加静态或定时显示的文字
• 字幕轨道：导入 SRT 文件或通过程序创建
• 自定义样式：字体、大小、颜色、背景、描边
• 位置设置：顶部、中部、底部、自定义坐标
• 动画效果：淡入/淡出、打字机效果
• 批量添加字幕：为多个视频应用相同样式
• 预览：渲染前生成预览帧

快速开始

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 用法

# 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 参考

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'

文字位置

可用位置：

• 'top'：顶部居中
• 'bottom'：底部居中（默认）
• 'center'：正中
• 'top-left'：左上角
• 'top-right'：右上角
• 'bottom-left'：左下角
• 'bottom-right'：右下角
• (x, y)：自定义像素坐标（元组）

样式预设

Instagram 快拍：

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

YouTube 字幕：

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

简约：

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

粗体：

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

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": [
    {
      "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"
    }
  ]
}

高级样式

带背景框的文字：

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

带描边的文字：

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

半透明背景：

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

使用场景

社交媒体视频：

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

教程视频：

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

无障碍：

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

品牌标识：

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

性能提示

• 预先渲染预览帧以测试样式
• 使用 h264 编码器以加快编码速度
• 字幕时长保持在 2 秒以上以便阅读
• 使用高对比度颜色以满足无障碍需求
• 在手机屏幕上测试社交媒体视频效果

限制

• 文字渲染性能取决于视频时长
• 复杂动画可能会增加渲染时间
• 文字过长可能会超出屏幕边界
• Emoji 支持情况取决于已安装的字体
• 无法编辑现有的内嵌字幕（需要原始视频）