extract-moves-from-video

動画からコマンドを抽出する

概要

このスキルでは、動画の録画からテキスト形式のコマンドを抽出する体系的な方法を紹介します。よくある用途として、テキストアドベンチャーゲーム（Zork など）のゲームプレイ中に入力されたコマンドの抽出、画面録画からのターミナルコマンドの取得、動画内に表示されるあらゆる入力テキストの文字起こしなどがあります。

ワークフロー

ステップ 1：ソース動画を分析する

処理を始める前に、動画の特性を把握します。

1. 動画のプロパティを確認する：解像度、長さ、フレームレート
2. テキスト領域を特定する：画面上のどこにコマンドが表示されるか（例：> のようなプロンプト文字の後）
3. テキストのスタイルを確認する：フォントの種類、色、背景とのコントラスト（暗い背景のターミナルテキストには、特別な処理が必要です）
4. 音声を確認する：音声の文字起こしで OCR を補完できるか確認します（Whisper のような大容量パッケージをインストールする前に、音声に関連する内容が含まれているか確認してください）
5. 入力パターンを把握する：新しいコマンドがどのくらいの頻度で表示されるかを見積もり、フレームのサンプリング間隔を決めます

ステップ 2：動画をダウンロードして準備する

1. 適切なツール（yt-dlp、youtube-dl、または直接ダウンロード）を使って動画をダウンロードする
2. 続行する前にダウンロードの整合性を確認する
3. 動画のメタデータを抽出する：プロパティが想定どおりであることを確認します

ステップ 3：フレームを効率よく抽出する

フレームの抽出では、網羅性と処理時間のバランスを取る必要があります。

1. まずコマンドの出現頻度を分析する：動画の一部を手動で確認し、新しいコマンドがどのくらいの頻度で表示されるかを把握します
2. 適切なサンプリング間隔を選ぶ：
   • 入力が速い場合：0.5～1 秒間隔
   • 入力が遅い場合：2～3 秒間隔
   • 判断が難しい場合：頻度を高めて抽出し、後から間引きます（再抽出を避けられます）
3. FFmpeg で抽出する：

   ffmpeg -i video.mp4 -vf "fps=1" frames/frame_%04d.png
   

4. 関連する画面領域に絞る：コマンドが特定の領域に表示される場合は、その領域にフレームをクロップすると OCR の精度が向上します

ステップ 4：OCR の設定を最適化する

OCR の精度は、動画の種類に合わせた適切な設定に大きく左右されます。

1. まずサンプルフレームでテストする：すべてのフレームを処理する前に、代表的な 5～10 枚のフレームで OCR の設定を調整します
2. Tesseract のページ分割モード（--psm）を設定する：
   • --psm 6：均一なテキストブロックを想定します
   • --psm 7：単一のテキスト行
   • --psm 13：生の行（単一行として扱い、解析は行いません）
3. OCR の精度を高めるために画像を前処理する：
   • 二値化：適切なしきい値を使って白黒に変換します
   • テキストが暗い背景に明るく表示されている場合は、色を反転する
   • コントラストが低い動画では、コントラストを上げる
   • 小さなテキストは拡大する（2～3 倍にすると改善することがよくあります）
4. 複数のしきい値を試す：一般的な値（127、150、180）でも動画によって結果が異なるため、どれが最適か実際にテストします

Python/OpenCV を使った前処理の例：

import cv2
img = cv2.imread('frame.png', cv2.IMREAD_GRAYSCALE)
# Invert if light text on dark background
img = cv2.bitwise_not(img)
# Binarize with tested threshold
_, img = cv2.threshold(img, 150, 255, cv2.THRESH_BINARY)
# Scale up for better OCR
img = cv2.resize(img, None, fx=2, fy=2, interpolation=cv2.INTER_CUBIC)

ステップ 5：コマンドを抽出して解析する

1. 前処理済みフレームに OCR を実行する：サブプロセス呼び出しより効率的な Python バインディング（pytesseract）を使います
2. コマンドのパターンを特定する：コマンドの前に表示されるプロンプト記号（例：>、$、>>>）を探します
3. OCR の出力を慎重に扱う：
   • コマンドが行頭から始まるとは限りません（OCR によって空白が挿入されます）
   • プロンプト文字の認識が不完全になる場合を考慮します（例：> が › や » に変わることがあります）
4. 柔軟なパターンマッチングを使う：

   # More robust than grep "^>"
   import re
   command_pattern = re.compile(r'[>›»]\s*(.+)')
   

ステップ 6：結果を整理して重複を除去する

重要：整理する前にデータの種類を把握してください。

1. 正当な重複は残す：多くの場面（ゲーム、シェルのセッションなど）では、同じコマンドが意図的に複数回表示されることがあります
2. 時間的な重複除去を行う：同じコマンドを表示している連続フレーム間の重複のみを除去し、全体からすべての重複を除去しないでください
3. 不完全なコマンドに対処する：入力途中のコマンドは一部だけが表示されます。完成したコマンドのみを取得してください
4. 修正内容を検証する：OCR の誤りを修正する場合は、文脈に適した修正であることを確認してください

時間的な重複除去の方法：

def temporal_dedupe(commands):
    """Remove only consecutive duplicates, preserving repeated commands."""
    result = []
    prev = None
    for cmd in commands:
        if cmd != prev:
            result.append(cmd)
            prev = cmd
    return result

ステップ 7：結果の検証

正確性を確保するには検証が欠かせません。

1. サンプル検証：ランダムに選んだサンプルについて、抽出したコマンドを元のフレームと手動で比較します
2. ドメインの検証：ゲームのコマンドを抽出する場合は、そのゲームで有効なコマンドであることを確認します
3. シーケンスの整合性チェック：コマンドのシーケンスが論理的に妥当であることを確認します（例：移動コマンドが妥当な経路に沿っている）
4. 件数の検証：動画の長さと入力速度から想定される件数と、抽出したコマンドの総数を比較します

よくある落とし穴

OCR の品質に関する問題

• 間違い：最適化せずにデフォルトの OCR 設定を使用する
• 解決策：まずサンプルフレームで --psm モードと画像の前処理を必ず調整します

不適切な重複排除

• 間違い：すべての重複コマンドを削除するグローバルな重複排除（例：awk '!seen[$0]++'）を使用する
• 解決策：連続した重複のみを削除する時間的な重複排除を使用します

プロンプト検出の失敗

• 間違い：特定の形式を前提とする grep "^>" のような厳格なパターンを使用する
• 解決策：OCR の揺らぎや空白を考慮した柔軟な正規表現を使用します

ツールのインストールによる無駄

• 間違い：必要かどうか確認せずに、大きなパッケージ（音声用の Whisper など）をインストールする
• 解決策：音声処理ツールをインストールする前に、音声に有用な内容が含まれているか確認します

中間チェックポイントがない

• 間違い：中間結果を保存せずにすべてのフレームを処理し、タイムアウトで進捗が失われる
• 解決策：各処理段階の後に結果を保存し、進捗チェックポイントを実装します

検証の放棄

• 間違い：抽出したコマンドを元の資料と照合しない
• 解決策：抽出結果のサンプルを必ず検証し、シーケンス全体の整合性も確認します

検証チェックリスト

抽出したコマンドを確定する前に、次の項目を確認します。

• 抽出したコマンドのサンプルを元のフレームと照合して検証した
• コマンド数が動画の長さに対して妥当である
• 明らかな OCR のノイズ（ランダムな文字、分割された単語）が残っていない
• 正当な繰り返しコマンドが保持されている（誤って重複排除されていない）
• コマンドのシーケンスが論理的な順序に従っている
• ドメイン固有の検証を実施した（例：コマンドがゲーム／アプリケーションで有効である）

ツール選定ガイド

タスク	推奨ツール	備考
動画のダウンロード	yt-dlp	youtube-dl よりもメンテナンスが活発です
フレームの抽出	ffmpeg	業界標準で、信頼性があります
OCR	pytesseract 経由の tesseract	効率化のため Python バインディングを使用します
画像の前処理	OpenCV（cv2）	柔軟で、ドキュメントも充実しています
パターンマッチング	Python の re モジュール	grep よりも柔軟です