weeeha/video-notes

Video Notes

ユーザーは画面収録にナレーションを載せてフィードバックを記録します。一回撮り、数分程度で、カーソルが遅れたときに同じポイントを繰り返すことがよくあります。成果物は、別のセッションが動画を見なくても実行できるパンチリストです。Whisper と ffmpeg はローカルで動作し、動画や音声がクラウドの音声 / 画像 API に送信されることはありません。

手順

1. ヘルパーを実行します（このファイルと同じフォルダにあります）。

   python3 "<このスキルのフォルダ>/video-notes.py" "<video>"
   

   動画と同じ場所に <video>.srt があればそれを再利用し、なければ whisper --model base.en を CPU で実行します（Apple Silicon 搭載ノートPC で 5 分の動画あたり約 2.5 分）。出力は <stem>.notes/ フォルダに生成されます：transcript.md（結合セグメントごとに 1 行＋フレーム名）と 1600px のスチル画像。<stem>.notes/ が動画より新しい場合はそのまま再利用され、--force で再構築、--model turbo でベースの文字起こしが乱れている場合、--every 10 でナレーションのないデモ、--sheet で 2x2 のコンタクトシート、--max-row 5 で会話と画面の動きが速いときのフレーム数を増加（行は最大 8 秒、1 行あたり 1 フレーム）、--max-frames 40 がデフォルトです。
2. transcript.md を読み、次にフレームを確認します。 --sheet を使用している場合は、最初に sheet_NN.jpg にざっと目を通してください（1 枚あたり 4 フレーム表示；タイルはフレーム順に左から右、上から下に並ぶため、シート 01 はフレーム 1 ～ 4 を保持し、左上のタイルが最も古いフレームです）。次に、言葉が画面を指している行（「この領域」「ここ」「これらの 2 つのアイコン」）や、テキストを読む必要がある行の、すべての行の単一フレームを読んでください。コンタクトシートは位置を特定するためのものであり、ラベルやサイズの証拠となるのは単一フレームのみです。
3. 動画の隣に <stem>.notes.md を絶対パスで書き込みます。セッションの作業ディレクトリは問いません。形式：

   # <動画名> · <録画日> · <長さ> · <フレームに表示されているアプリまたは URL>
   
   ## パンチリスト
   ### <画面上の領域：画面上の表示名で記述：左ペイン、ヘッダー、設定パネル>
   1. [mm:ss] <1 文での修正指示>。発言: "<短いそのままの引用>"。フレーム: frame_mmss.jpg
   2. ...
   
   ## Parked（後回し）
   <「後で」「いずれ」「今は不要」とマークされた項目、同じ行形式>
   
   ## Unclear（不明点）
   <ユーザーの回答が必要な項目ごとに 1 行>
   

   番号はリスト全体を通して連番となり、ユーザーが「3 と 7」のように返信できます。領域は訪問された順に従います。同じ内容の繰り返しメモは 1 つの項目にまとめ、繰り返しが重要な場合は「3 回発言」と追記します。
4. 返信には、ファイルパス、項目数付きの領域ヘッダー、最初の 3 項目を含めます。Unclear にエントリがない限り、質問は行いません。
5. 画面を表示しているリポジトリが開かれている場合は、## Where in code（コード内の場所）セクションを追加します：項目番号とファイルパス（フレームに見えるコンポーネント名やラベルを grep して特定）。リポジトリがない場合はこのセクションをスキップし、パスを推測してはいけません。

ルール

• スチル内の読めないテキストは推測せず、--width 2400 または ffmpeg の領域クロップで再取得します。
• .notes/ フォルダと .notes.md は動画の隣に置きます。リポジトリ内ではそのフォルダを無視する設定（.git/info/exclude）にし、大規模な録画が git に含まれないようにします。
• 競合他社や製品デモの場合も同じ手順で、リストは「修正」ではなく「彼らのやっていること」として読みます。
• 文字起こしは ~/.cache/whisper のローカル Whisper モデルで実行します。クラウドの音声 API や画像 API は使用せず、セッションモデルはスチル画像を読み取ります。

完了チェック

• transcript.md が生成され、各項目を書く前にすべてのフレームを読んだ
• <stem>.notes.md が書き込まれた：グローバルな番号付け、訪問順の領域、すべての項目にタイムスタンプとフレームがある
• 繰り返しがまとめられ、Parked と Unclear がパンチリストから分離されている
• 動画や音声がマシンの外部に送信されていない