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 秒を超えるようにします
• アクセシビリティのため、コントラストの高い色を使用します
• ソーシャルメディア向けには、モバイル画面でテストします

制限事項

• テキストのレンダリング性能は動画の長さによって異なります
• 複雑なアニメーションはレンダリング時間を延ばす場合があります
• 非常に長いテキストは画面の境界からはみ出す場合があります
• 絵文字のサポート状況は、インストールされているフォントによって異なります
• すでに動画に焼き付けられた字幕は編集できません（元の動画が必要です）