video-transcripts

動画の文字起こし

クイックスタート

関連する動画ごとに、ヘルパーを1回実行します。<skill> はこのスキルのディレクトリです：

bash <skill>/scripts/generate_video_transcript.sh \
  "https://uploads.linear.app/.../screen-recording.mov" \
  --title "PDF preview hyperlinks trigger leave-page modal"

または、GitHub の添付ファイルの場合：

bash <skill>/scripts/generate_video_transcript.sh \
  "https://github.com/user-attachments/assets/..." \
  --title "Slash menu loses selection after confirm"

または、Screencastify の視聴ページの場合：

bash <skill>/scripts/generate_video_transcript.sh \
  "https://app.screencastify.com/watch/..." \
  --title "Bulk send expands filtered recipients"

または、ローカルファイルの場合：

bash <skill>/scripts/generate_video_transcript.sh \
  "/absolute/path/to/video.mov" \
  --title "Preview hyperlink exits workflow"

認証が必要な Linear のアップロードの場合、ヘルパーは macOS のローカル Linear デスクトップアプリの Cookie を使って自動的に再試行します。プライベートな GitHub アセット URL の場合、利用可能であれば GITHUB_TOKEN、GH_TOKEN、または gh auth token を使って再試行します。

こんなときに使います

• GitHub または Linear の issue、PR、コメントに画面録画が含まれている場合。
• 添付ファイルの URL が uploads.linear.app を指している場合。
• 添付ファイルの URL が GitHub の添付ファイルまたはプライベートな GitHub アセットホストを指している場合。
• トラッカーから公開 Screencastify 視聴ページにリンクされている場合。
• 曖昧な要約ではなく、タイムライン形式の文字起こし行が必要な場合。
• 結果を次の正確な XML 形式にしたい場合：

<video-transcripts>
<video-transcript title="...">
[00:00] (...)
</video-transcript>
</video-transcripts>

ワークフロー

公開リポジトリ上のものなど、チーム外の誰もが読めるトラッカーのコメントや返信には、明示的なメッセージ権限が必要です。チームだけが読めるものには、プロジェクトのメッセージルールが適用されます。公開が許可されていない場合は、文字起こしをローカルで作成または返却してください。以下のキャッシュの場所と再利用ルールは、投稿の許可を与えるものではありません。

1. 関連する動画ごとにヘルパーを1回実行します。
2. 実行ごとに、バグに焦点を当てた短い --title を指定します。
3. 追跡対象の作業では、正規の共有キャッシュを、その内容を説明する証拠の隣にあるトラッカー内に保存します。
4. 動画が issue または PR の本文にある場合は、トラッカーのトップレベルコメントを使用します。
5. 動画が Linear のコメントにある場合は、文字起こしキャッシュをその特定のコメントへの返信として投稿します。
6. 動画が GitHub の issue または PR のコメントにある場合は、そのコメント内の動画一式に対して専用のトップレベルキャッシュコメントを1つ使用します。GitHub には返信機能がないため、関係のないコメント内の動画をまとめず、キャッシュコメントを元のコンテナごとに分けます。
7. キャッシュコメントまたは返信の本文は、文字起こしのソースリンクに続いてタイムスタンプ行を記述します：

[[Transcript](link to video or comment if not available)]
[00:00] (...)

8. ヘルパーの XML をキャッシュする場合は、<video-transcripts> と <video-transcript ...> のラッパー行を削除し、ソースリンクの後にタイムスタンプ行だけを貼り付けます。
9. 同じソースコンテナに複数の動画がある場合は、動画ごとに [[Transcript](...)] ソースリンクとタイムスタンプ行を繰り返します。
10. ヘルパーを実行できる場合は、動画の動作を手書きしたり、言い換えたりしないでください。実際の文字起こし出力を使用します。
11. 動画 URL が利用可能な場合は、[[Transcript](...)] を動画 URL にリンクします。動画 URL が利用できない、または不安定な場合は、動画を含むソースコメントにリンクします。
12. uploads.linear.app などの署名付きトラッカーホスト URL では、クエリー文字列を削除し、新しい署名によって有効なキャッシュエントリーが無効にならないようにします。Screencastify の場合は、署名付きの dash-assets HLS URL ではなく、安定した https://app.screencastify.com/watch/<id> URL を基準にキャッシュします。
13. 後続のワークフローで本当に必要にならない限り、キャッシュされた文字起こしエントリーに title などの装飾的なメタデータを追加しないでください。
14. 追跡対象の作業で文字起こしをやり直す前に、まずソースコンテナごとにキャッシュエントリーを照合します：
    • issue または PR の本文内の動画には、キャッシュコメントを1つ
    • 動画を含む各コメントには、Linear の返信を1つ
    • 動画を含む各 issue または PR コメントには、専用の GitHub キャッシュコメントを1つ
15. 一致するキャッシュが、そのソースコンテナの現在の正規化済み動画キーをすでに網羅している場合は、再利用します。不足している動画証拠または新しい動画証拠のみ文字起こしします。
16. 生のトラッカー文字起こしキャッシュに docs/ を使用しないでください。そこは永続的なリポジトリ知識のための領域であり、issue の生の証拠を保存する場所ではありません。
17. これを codex exec 経由で実行する場合は、CLI の進行状況メッセージを含めずに最終 XML を取得できるよう、-o <file> を優先します。

出力形式

• Markdown ではなく XML を返します。
• 観察したアクションまたはシステムの応答ごとに、[MM:SS] (...) 形式の行を 1 行出力します。
• 読み取れる場合は、画面に表示されたテキストを引用します。
• 目に見えるアクション、画面の変化、音声がある場合はその発話のみを記述します。
• 隠れた状態、動機、実装の詳細を推測してはいけません。
• キー入力ごとの冗長な記述より、簡潔で重要度の高い行を優先します。

モデルの選択

ヘルパーは、コスト効率を高めるため、デフォルトで gemini-3.1-flash-lite-preview を使用します。

出力に不備がある場合、内容が薄すぎる場合、または明らかなノイズがある場合は、gemini-3-flash-preview で再試行します。

Gemini 3 モデルでは、隠れた推論ではなく文字起こしに出力の予算を割り当てるため、ヘルパーは思考を最小限に設定します。

次の方法で上書きします。

VIDEO_TRANSCRIPTS_MODEL=gemini-3-flash-preview bash <skill>/scripts/generate_video_transcript.sh ...

または：

bash <skill>/scripts/generate_video_transcript.sh ... \
  --model gemini-2.5-flash

注意事項

• ヘルパーは、ローカルファイルパスまたはリモート URL を受け付けます。
• uploads.linear.app の URL では、まず LINEAR_COOKIE_HEADER を試し、次に LINEAR_COOKIES_DB を試してから、ローカルの Linear デスクトップアプリの Cookie ストア ~/Library/Application Support/Linear/Cookies にフォールバックします。
• GitHub のアセット URL では、まず GITHUB_TOKEN を試し、次に GH_TOKEN、その次に gh auth token を試してから、認証なしのダウンロードにフォールバックします。
• Screencastify の視聴 URL では、https://umbrella.svc.screencastify.com/api/umbrellaService/watch/<id> を呼び出し、署名付き HLS マニフェストを解決して、セグメントに署名が引き継がれるよう子プレイリストを書き換え、ffmpeg で録画を再多重化します。
• Screencastify の URL に対応するには ffmpeg が必要です。
• まず GEMINI_API_KEY を探し、次に GOOGLE_API_KEY を探します。
• どちらも設定されていない場合は、失敗する前に ~/.bash_profile を試します。
• リクエストとレスポンスの成果物を保存する場合は、--debug-dir <dir> を使用します。
• 品質ゲートは、部分的な入力の繰り返しなど、明らかに情報量の少ない文字起こしを拒否し、自動的にフォールバックします。