ビデオスキル
ffmpeg、Deepgram Nova 3、S3/トンネル共有を使って動画を処理・共有します。
デフォルト：軽量動画、同じ解像度
常に、ソースの解像度を維持したまま、より小さなファイルにエンコードし直します。 圧縮された同一解像度のコピーは、ほとんどの場合ユーザーが求めるものです。アップロードが速く、共有が軽量で、視聴体験は変わりません。これを全てのフロー（サイレントモード、インタラクティブモード、Gemini dev-video 再生エンコード）でデフォルトにします。ユーザーが明示的に別の指示をした場合のみ、デフォルトから逸脱します。具体的には：
- デフォルトの最適化 =
--resolution keep— libx264 + CRF で再エンコードし、スケールフィルタは使用しません。解像度は変更されず、ファイルサイズだけが小さくなります。これは推奨されるQ1の選択であり、サイレントモードのデフォルトです。 - 解像度を下げる（例：1080p）のは、 ソースが1080pより実質的に大きい（≥1440p / 4K）場合、またはユーザーが明示的に要求した場合のみです。絶対にアップスケールしないでください。
- 再エンコードをスキップする（元のファイルをそのまま使用・ストリームコピー）のは、 ユーザーが明示的に「元のまま」「再エンコードしない」などと要求した場合のみです。
- 安全確認： エンコード後、出力サイズをソースと比較します。実質的に小さくなっていない場合（既に低ビットレートのソースなど、稀なケース）、CRFを上げるか（26–28）、元のファイルにフォールバックします。画面録画は特に圧縮効率が良く、CRF 24–26、
preset slowで、画面上のテキストを鮮明に保ちながら70～80%削減できます。 - ダウンロードボタン： デフォルトではページに 1つの「ダウンロード動画」ボタン のみ表示されます（再生動画を指します）。変更されていない元のファイルをそのファイル名で出力フォルダに実際にアップロードした場合にのみ、
render_page.py --original-filename <name>を渡して 「オリジナルをダウンロード」ボタン を追加します。そうしない場合、ボタンは存在しないファイルにリンクし404エラーになります。デフォルトの圧縮維持フローではオリジナルは保持されないため、--original-filenameを渡さないでください。
前提条件
ffmpegとffprobeがインストールされていること- Python 3 が利用可能であること
awsCLI が利用可能であること（S3アップロード用）- Deepgram APIキー — 音声文字起こし/字幕用（デフォルトエンジン）
- OpenRouter APIキー — Gemini分析エンジン用（
dev-video/transcript-cheapモード）。オプション。これらのモードが選択された場合のみ必要です。
ディレクトリ
- スクリプト:
<skill_dir>/scripts/— すべてのPythonスクリプトと player.html テンプレート - 認証情報:
~/.config/video-skill/— プラグインのアップデート後も保持されますdeepgram_token— 1行のDeepgram APIキーopenrouter_token— 1行のOpenRouter APIキー（Gemini分析エンジン）s3_credentials— key=value 形式（endpoint, bucket, access_key, secret_key）
- 設定:
~/.config/video-skill/preferences.json— セッション間で保存されるユーザー設定
認証情報の設定
必要な認証情報が不足している場合、AskUserQuestion を使用してユーザーに問い合わせてください：
Deepgram: DEEPGRAM_API_KEY 環境変数を確認し、次に ~/.config/video-skill/deepgram_token ファイルを確認します。どちらも存在しない場合、ユーザーに問い合わせてファイルに保存します。
OpenRouter: OPENROUTER_TOKEN 環境変数を確認し、次に ~/.config/video-skill/openrouter_token ファイルを確認します。dev-video / transcript-cheap 分析モードでのみ必要です。Geminiモードが選択されていてトークンがない場合、ユーザーに問い合わせてファイルに保存します。
S3: 環境変数（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、S3_ENDPOINT、S3_BUCKET）を確認し、次に ~/.config/video-skill/s3_credentials を確認します。不足している場合、ユーザーに endpoint、bucket、access_key、secret_key を問い合わせて保存します。
重要： 認証情報をCLI引数として渡さないでください。スクリプトは --credential-dir ~/.config/video-skill を介して内部でファイルから読み取ります。
設定
{
"language": "en",
"last_folder": "/Users/example/screencasts",
"share_folder": "/Users/example/screencasts",
"sharing_method": "s3",
"optimization": "compress-keep",
"crf": 23,
"preset": "medium",
"audio": "aac-128k",
"subtitles": "track",
"subtitle_style": "modern",
"subtitle_font": "Helvetica Neue",
"target_language": "ru",
"download_button": true,
"passcode": true,
"mode": "subtitles"
}
optimization: 再生動画のエンコード方法。デフォルトは compress-keep = ソース解像度を維持して軽量化（--resolution keep）。その他の値：web-1080p（1080pにダウンスケール — ≥1440p/4Kソース用）、custom、keep-original（再エンコードなし — ユーザーからの明示的な要求があった場合のみ）。上記の 「デフォルト：軽量動画、同じ解像度」 を参照してください。
mode: トランスクリプト/分析エンジンを決定する単一フィールド。以下の4つの値のいずれか（古い analysis_mode と developer_analysis のペアを統合）：
mode | エンジン | 字幕 | 開発者分析 | 使用するタイミング |
|---|---|---|---|---|
subtitles（デフォルト） | Deepgram | 高精度 | なし | 通常の共有、キャプションのみ必要 |
dev-audio | Deepgram | 高精度 | あり（トランスクリプトテキストから） | ツール/バグフィードバック、クリーンなキャプションも必要 |
dev-video | Gemini ビデオ | 粗い | はい + スクリーンショット | 最もリッチなツール/UXフィードバック（画面を読み取る） |
transcript-cheap | Gemini オーディオ | 粗い | なし | 安価で大まかなトランスクリプト、タイミングは重要でない |
内部動作：subtitles/dev-audio は process_and_share.py を実行（後者は --developer-analysis 付き）。dev-video/transcript-cheap は Gemini エンジン（gemini_analyze.py）を実行。「開発者分析」= ページ内分析ブロック プラス 分析Markdownアーティファクト（そのセクションを参照）。エンジンガイダンス（2026年6月時点）：高精度字幕にはDeepgram を維持。分析には Gemini-video、安価で大まかなトランスクリプトには Gemini-audio を使用。dev-video で高精度キャプションも重要な場合は、トラック用にDeepgramパスを追加で実行します。
保存： インタラクティブな選択のたびに、preferences.json を更新します。実行後は必ず last_folder を保存します。
読み込み： 開始時に読み込みます。保存された値を「（推奨）」デフォルトとして使用します。サイレントモードでは、直接使用します。
スクリプトリファレンス
すべてのスクリプトは <skill_dir>/scripts/ にあります。認証情報のために --credential-dir を受け入れ、ステータス追跡のために [PROGRESS] 行を出力します。
| スクリプト | 目的 | 主要引数 |
|---|---|---|
process_and_share.py | メインワークフロー：最適化 + 文字起こし + レンダリング + アップロード | <video> --output-dir --share-folder --share s3|tunnel |
share_existing.py | 事前処理済みフォルダを共有 | <folder> --share-folder --share s3|tunnel |
upload_s3.py | フォルダをS3にアップロード | <folder> --key <key> --credential-dir |
render_page.py | テンプレートからindex.htmlを生成 | --output-dir --template --metadata |
manage_registry.py | レジストリCRUD（追加/削除/一覧/取得/移行） | <subcommand> --share-folder |
partial_update.py | 共有フォルダの再レンダリング＋再アップロード（レジストリからキーを解決、パスコードを転送） | <output_folder> [--key] |
font_name.py | TTFの内部ファミリー名を表示（ASS Fontname 用） | <font.ttf> |
transcribe.py | Deepgram文字起こし → SRT + VTT | <video> --credential-dir [--language] |
gemini_analyze.py | Geminiエンジン：音声トランスクリプト OR ビデオ分析＋スクリーンショット | <video> --mode audio|video --output-dir --credential-dir [--key] |
burn_subtitles.py | 字幕を動画に焼き付け | <video> <srt> [--font --fontsize ...] |
share_server.py | トンネル共有用のローカルHTTPサーバー | <share_root> [--port] |
ワークフロー
ステップ0：引数の解析とモードの検出
コマンド：
/video→ インタラクティブモード（ステップ1-5）/video process <path>→ インタラクティブモード（特定ファイル）/video share→ サイレントモード：最新動画を処理して共有/video share <path>→ サイレントモード：特定ファイルを処理して共有/video share <path> "context"→ サイレントモード（メタデータ用の追加コンテキスト付き）/video start→ 共有サーバー＋トンネルを開始/video stop→ 共有を停止/video status→ 共有中の動画を一覧表示/video copy <key_or_name>→ リンクとパスコードをクリップボードにコピー/video remove <key_or_name>→ レジストリから削除
共有コマンド（直接処理、加工なし）
共有レジストリ： <share_folder>/.share_registry.json — manage_registry.py で管理。
start コマンド：
- 設定を読み込み →
share_folder。設定されていない場合は問い合わせ。 pgrep -f share_server.pyを確認。実行中の場合はステータスを表示。- サーバーを起動：
python3 "<scripts>/share_server.py" "<share_folder>" --port 8080 & - トンネルを開始：
ssh -p 443 -R0:localhost:<port> -o StrictHostKeyChecking=no a.pinggy.io 2>&1 & - トンネルURLを解析。「Server running at <base_url>」を表示。
- 既存の動画を完全なURL（
<base_url>/v/<key>）で一覧表示。
stop コマンド：
pkill -f share_server.py; pkill -f "ssh.*pinggy"; pkill -f "ngrok http"
status コマンド：
python3 "<scripts>/manage_registry.py" list --share-folder "<share_folder>"を実行。pgrep -f share_server.pyでトンネルステータスを確認。- テーブルを表示：キー、タイトル、S3 URL、トンネルURL、パスコード、作成日時。
copy コマンド：
python3 "<scripts>/manage_registry.py" get --share-folder "<share_folder>" --key "<query>"を実行。- フォーマット：
<title>\n<url>\nPasscode: <code>→pbcopy
remove コマンド：
python3 "<scripts>/manage_registry.py" remove --share-folder "<share_folder>" --key "<query>" を実行。
サイレントモード（/video share）
1回の確認、1回のスクリプト実行、最小限のやり取り。
フロー：
-
動画を特定（引数のパス、または
last_folder/ カレントディレクトリの最新ファイル） -
出力フォルダを作成
<share_folder>/<video_name>/ -
パスコードを生成（ランダム6桁、または保存済み設定）
-
確認を表示：
クイック共有: demo.mov → 同じ解像度・圧縮 (CRF 23)・AAC 128k → 文字起こし＋字幕 (トラック) → S3経由で共有 (パーマネントリンク) → パスコード: 482910 続行しますか？オプション：続行（推奨） / インタラクティブモードに切替
modeがdev-videoまたはtranscript-cheapの場合、process_and_share.pyを実行せず、代わりに「Gemini分析エンジン」セクション（保存済み設定を使用、サイレントに）に従い、その後アップロードとレジストリ登録を行います。 -
メインワークフロースクリプトを実行。
modeがdev-audioの場合は--developer-analysisを渡します：python3 "<scripts>/process_and_share.py" "<video_path>" \ --output-dir "<output_folder>" \ --share-folder "<share_folder>" \ --credential-dir ~/.config/video-skill \ --resolution keep --crf 23 --preset medium --audio aac-128k \ --subtitles track \ --share s3 \ --passcode "<passcode>" \ [--developer-analysis] \ [--context "<user_context>"]デフォルトは
--resolution keep（圧縮、同じ解像度）。--resolution 1080pはソースが≥1440p/4Kの場合のみ、keep-original処理はユーザーが未変更ファイルを明示的に要求した場合のみ使用します。 -
METADATA_READY:のstdoutを監視 — スクリプトがこのマーカーを出力した時： a. その前に出力されたTRANSCRIPT_PREVIEW:とMETADATA_INFO:を読み取ります。 b. トランスクリプトプレビューからタイトル、説明、4～8のチャプターを生成します。 c.modeがdev-audioの場合（開発者分析オン）：出力ディレクトリのSRT/VTTから完全なトランスクリプトを読み取り、分析ブロック と 分析Markdownを構築します（切り詰められたプレビューではありません）。正確な形状と契約については、「metadata.jsonリファレンス」 および 「分析Markdown」 セクションを参照してください。ページの言語（RU / DE / EN）に一致させます。 d. metadata.jsonリファレンス に従って、metadata.jsonを出力ディレクトリに書き込みます。 e. スクリプトは metadata.json を検出し、自動的に続行します。 -
スクリプトが終了。結果を表示し、l
…（省略）…