Communitygithub.com

daniel-video-annotate

画面収録を、静止待ちをカットし、各キーアクションで一時停止し、操作箇所を枠で囲み、何をなぜ行ったかをキャプションで説明する、解説付き動画に変換します。ユーザーが /daniel-video-annotate を呼び出したとき、または動画の注釈や説明を依頼したときに使用します。

daniel-video-annotate とは?

このスキルは、画面収録動画を静的な待機時間をカットし、各重要な操作で一時停止して、操作対象を枠で囲み、その操作内容と理由を1文のキャプションで表示する「解説付き動画」に変換するエキスパートエージェントです。開発者向けのデモや手順説明動画の作成に非常に便利で、ユーザーがチケットやマージリクエストなどのコンテキストを提供すれば、操作の「理由」も自動的にキャプションに反映できます。サポート環境はローカルマシン(ffmpeg、ffprobe、Python標準ライブラリのみが必要)で、macOSとLinuxの両方に対応。Claude Codeや他のCLIベースのAIエージェントが実行する一連のスクリプト(`annotate.py`)を通じて動作し、7つのステップ(読み上げ速度の設定、待機時間カット、動画の内容理解、一時停止箇所の選択、キャプション作成、レンダリング、全フレーム確認、レポート出力)で構成されます。各ステップは自動化されていますが、エージェントはフレーム画像を確認してキャプションと枠の正確性を検証します。

対応✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/dancodes/skills-agents/tree/HEAD/skills/daniel-video-annotate

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

/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 filterffmpeg が 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 endcheck にトリミング動画を渡した解説付き動画を渡す
その他の ffmpeg failed不明A selftest を実行。生成されたクリップをトリミングおよび注釈処理するため、成功すればffmpegは正常で、入力またはスペックに問題があることになります
dvm get --help が scp エラーで失敗するdvm get はすべての引数をscpに渡すdvm help を実行

macOS には timeout コマンドがありません。1分間の720p動画は数秒でレンダリングされるため、コマンドはそのまま実行してください。

関連スキル