/daniel-video-annotate
入力:動画ファイルと、各ステップを実行する理由(チケット、マージリクエスト、ユーザーのメッセージなど)。出力は入力と同ディレクトリに <名前>-trimmed.mp4 と <名前>-explained.mp4 として保存されます。入力ファイルは変更されません。
解説付き動画では、収録を再生し、各停止箇所でフレームをホールド時間だけ静止し、1つの操作対象の周囲を暗転させ、収録の下または上に黒い帯で1文のキャプションを表示します。この帯で動画が縦に拡大されるため、収録部分は隠れません。
annotate.py はこのファイルと同じディレクトリにあります。以下のコマンドでは、A は python3 "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/daniel-video-annotate/annotate.py" を表します。必要なのは ffmpeg、ffprobe、Python標準ライブラリのみです。<work> はスクラッチフォルダです。セッションスクラッチパッドがある場合はそれを、ない場合は ${TMPDIR:-/tmp}/video-annotate/<名前>/ を使用します。
動画が開発用VM上にある場合は、まず dvm get <リモートパス> <ローカルディレクトリ> でローカルにコピーしてください。
0. 読み上げ速度の選択
ホールド時間は、各キャプションが画面に表示され読み取れる時間です。各停止は、1.5秒+キャプションを読み上げ速度で読む時間、最低でも2.5秒間ホールドします。ユーザーが指定した速度(語/分)を使用します。指定がない場合は350 wpmを使用します。質問しないでください。ユーザーが固定のホールド時間(秒)を指定した場合は、すべての停止でその値を使用します。
読み上げ速度または固定ホールド時間が決まったら完了です。
1. 待機時間のカット
A trim <video> <名前>-trimmed.mp4
このコマンドは、画像が1.5秒以上静止しているすべての区間を検出し、各区間の最初の1秒を保持し、残りをカットします。カットした区間の数と、前後の動画時間を表示します。ユーザーが待機時間を残したい場合はこのステップをスキップし、元の動画を以下の <trimmed> として使用します。
以降のステップのすべての時間は <trimmed> 内の時間です。再度トリミングするとすべての時間がずれるため、新たにトリミングした後はステップ2から6をやり直してください。
2. 内容の把握
A sheets <trimmed> <work>/sheets
このコマンドは、6フレームずつのコンタクトシートを1秒あたり1フレーム、各フレームに正確な時間を焼き込んで出力します。すべてのシートを読んでください。各ステップの理由については、チケットやその他の情報源を読んでください。
画面上の操作の順序、各アクションで設定された値、収録の目的を証明する結果を、順に説明できるようになったら完了です。
3. 停止箇所の選択
各選択(値の選択、ボタンの押下、意図的なページ遷移)ごとに1回、目的を証明する結果ごとに1回停止します。判断を伴わないナビゲーションはスキップします。
各停止について、フレームと枠を見つけます。
A frames <trimmed> <work>/frames 23.0 23.2 23.4 23.6
このコマンドは、指定された各時刻のフルサイズPNG画像を、正確な時刻をファイル名として出力します。画像には100ピクセルごとの赤いグリッドと、上端と左端にピクセル座標が表示されます。
- 安定したフレームを選択してください。 収録には描画途中のフレーム(例:クリック直後にパネルが一瞬空白になる)が含まれます。0.2秒刻みで進め、操作対象とその周辺が完全に描画されたフレームを選んでください。
- リストからの選択の場合、リストが開いてカーソルが選択肢の上にあるフレームを優先してください。そのフレームが描画途中の場合は、直後のフィールドに新しい値が表示されているフレームを使用してください。
- 枠の値は
[x, y, width, height]としてグリッドのラベルから読み取ります。単位は元のピクセルです。Readツールは大きな画像を縮小するため、表示画像で測定した位置は間違っていますが、ラベルは正しいままです。 - キャプションで説明する単一の操作対象を、数ピクセルのマージンを付けて枠で囲みます。枠を省略することもでき、その場合は暗転処理は行われません。
すべての停止について、フレームを確認し、その同じフレームから枠を読み取った時刻が決まったら完了です。
4. キャプションの作成
停止ごとに1文のキャプションを作成します。何をしているか、なぜかを説明するか、画面に何が表示されているか、なぜかを説明します。具体的なもの(行、フィールド、古い値と新しい値)を名前で指定します。
「理由」は情報源から取得します。情報源に理由の記載がない場合は、表示されている内容を書き、そのキャプションが推測であることをレポートに記載します。キャプションには writing-tics スキルを適用してください。各キャプションは約180文字以内に抑えてください。帯の高さは最も長いキャプションに合わせられます。
5. レンダリング
<work>/spec.json を時間順のリストとして作成します。
[
{"at": 12.0, "box": [399, 569, 180, 29], "caption": "テーブル内のアイテム1のサイズをMからLに変更し、Lがサーバーに保存されます。"},
{"at": 23.6, "box": [659, 500, 192, 24], "caption": "..."}
]
at は <trimmed> 内の秒単位の時刻です。次に、各停止に hold を設定します。
A holds <work>/spec.json [--wpm <速度>]
このコマンドは、各停止のホールド時間をスペックに書き込み、単語数とともに表示します。固定ホールド時間が指定されている場合は、自分ですべての停止に hold を設定してください。hold がない停止は6秒間ホールドされます。
A annotate <trimmed> <work>/spec.json <名前>-explained.mp4 [--position top|bottom] [--clearance <行数>]
キャプション帯はユーザーの指定した位置に表示されます。指定がない場合は下部に表示されます。
--position bottomがデフォルトです。動画プレーヤーは下部にコントロールを描画するため、キャプションの下に空白領域が確保されます。--clearanceでその行数を指定(デフォルトは3行)し、小さな埋め込みプレーヤーのコントロールを避けます。--position topは帯を収録の上部に配置し、プレーヤーのコントロールが重なることはありません。クリアランスは不要です。
枠の座標はどちらの位置でも <trimmed> の座標系に従います。
6. 全停止の確認
A check <名前>-explained.mp4 <work>/spec.json <work>/check
このコマンドは、各停止の中央付近から1フレームずつ画像を出力します。すべての画像を確認してください。枠が操作対象に正しく配置されていること、キャプションが完全で右端で切れていないこと、フレームが選択した安定したフレームであることを確認します。すべての停止が合格するまでスペックを修正してレンダリングし直してください。
7. レポート
解説付き動画のパス、サイズ、時間を表示し、次にキャプションを順に、それぞれの枠の対象とともに表示します。どのキャプションが推測かを記載します。各停止の1フレームのみを確認し、再生は確認していないことを伝えます。
制限事項
- 出力に音声は含まれません。入力に音声トラックがあった場合はユーザーに伝えてください。
- フレームレートは入力の平均フレームレートを四捨五入し、5〜30 fpsの範囲に制限されます。
trimは完全に静止した画像のみをカットします。スピナー、プログレスバー、点滅するカーソル、時計などは画像を動かし続けるため、それらの待機時間は保持されます。小さな変更1つで途切れた待機時間は、複数の1秒間の断片として保持されます。trimは静止区間内のフレームのみをカットし、各変化の最初のフレームは保持します。--noise許容値(デフォルト0.003)より小さい変化(例:小さな文字1つ)は静止とみなされ、カットされる可能性があります。ステップ2が確認手段です。すべての操作がシートに表示されている必要があります。不足がある場合は--noiseを0.001に下げてください。
エラー
| 表示される内容 | 原因 | 修正方法 |
|---|---|---|
this ffmpeg build has no drawtext filter | ffmpeg が libfreetype なしでビルドされている | brew install ffmpeg などで完全なビルドをインストール |
no font file found | 既知の macOS または Linux のフォントパスが存在しない | sheets、frames、annotate に --font /path/to/font.ttf を指定 |
Unrecognized option 'fps_mode' | ffmpeg が5.1より古い | ffmpeg をアップグレード |
no still stretches found, nothing written | 画像が1.5秒以上静止しない | 元の動画を <trimmed> として使用するか、--min-freeze を下げる |
| トリミング後の動画がまだ遅い | アニメーションのある待機時間が保持された、または1秒/静止区間の積み重ね | --keep を0.5に下げる |
| トリミング後の動画が速すぎて追いつけない | 1画面1秒ではこの収録には短すぎる | --keep を2、--min-freeze を3に上げる |
pause N at Ts が動画の終端を超えています | 時間が元の動画から取得され、<trimmed> からではない | <trimmed> の sheets と frames から再度時間を読み取る |
pause N box ... がフレームの外側、または check で枠が操作対象からずれている | 枠を縮小された画像上で測定した | frames のPNG画像のグリッドラベルから読み直す |
| キャプションが右端で切れている | フォントがスクリプトの想定より幅広い | annotate に --wrap 80 またはより小さい数値を指定 |
| プレーヤーのコントロールがキャプションを覆う | キャプション下のスペースがコントロールより短い | --clearance を5に上げるか、--position top を指定 |
pause N would sit at ..., past the end | check にトリミング動画を渡した | 解説付き動画を渡す |
その他の ffmpeg failed | 不明 | A selftest を実行。生成されたクリップをトリミングおよび注釈処理するため、成功すればffmpegは正常で、入力またはスペックに問題があることになります |
dvm get --help が scp エラーで失敗する | dvm get はすべての引数をscpに渡す | dvm help を実行 |
macOS には timeout コマンドがありません。1分間の720p動画は数秒でレンダリングされるため、コマンドはそのまま実行してください。