video-skill

video-skill は何をしますか？

スクリプトはこのファイルと同じディレクトリの scripts/ にあります。以下では $S と表記しますが、各コマンドでは絶対パスを明示してください（シェル変数はBash呼び出し間で引き継がれないため）。

あなたは動画を見ることができないため、すべてのステップで動画を読めるものに変換します：確認するフレーム画像とチェックする数値です。映像制作は「書く → フレームをレンダリング → コンタクトシートを読む → 修正する」のサイクルです。映像の理解は「プローブ → プロキシ → タイムスタンプ付きシート＋文字起こし → 判断」です。納品はコーデック、フレームレート、faststart、ラウドネスをチェックするスクリプトで行い、「どこでも再生できる」ことを事実として確認します。

Macで初めて使用する場合

自分で sh $S/setup.sh を実行してください。miseとffmpegを確認し（可能であればHomebrewでffmpegをインストール）、初回使用時に固定バージョンのOpenFilmをインストールして openfilm doctor を実行します。表示される各 TODO を修正するか、その内容を平易に説明してください。再実行しても安全です。

映像制作：OpenFilm

OpenFilm（MITライセンス）がオーサリングフォーマットです。フィルムは film.html を含むフォルダで、HTMLページ、映像、画像、音声をカット編集します。各ページは要求された任意の時点 t を描画します。Studioはローカルブラウザエディタです。

1. マニュアルを出力して全体を読んでください（短く、リリースごとに変わります）：$S/openfilm。それに従い、このファイルが異なる場合はこちらを優先します。
2. $S/openfilm がここでOpenFilmを実行する唯一の方法です：バージョンを固定し、初回使用時にmise経由でインストールし、Studioがブラウザウィンドウを開かないようにします。npx openfilm（固定を迂回）や npx skills add openfilm/openfilm（このスキルと競合する上流スキル）は使用しないでください。
3. FILM は常に絶対パス、$HOME/Movies/OpenFilm/Projects/<film-name> です。相対名は現在のフォルダ（誰かのgitリポジトリなど）に作成されます。フィルムは決してリポジトリ内に置かないでください。

ステップ	コマンド
作成または開く	$S/openfilm open FILM
フィルム全体をチェック	$S/openfilm -C FILM look
特定の瞬間、範囲、ファイルをチェック	… look 4.5、look 3-6、look assets/bed.wav
速い入力をチェック	… look 0-2 --count 24
MP4をレンダリング	$S/openfilm -C FILM render
接続されているメディアサービスを表示	$S/openfilm get
インストールを診断	$S/openfilm doctor

look と render はStudioを開かずに実行され、FILMからの相対パスを出力します。Studioのアドレスにはアクセスキーが含まれています：これを渡すのは一緒に作業している本人だけにしてください（127.0.0.1、ChromeまたはEdge、スマートフォンからは不可）。

何かを表示する前に必ずすべての look シートを読み、見つけた問題を修正してください。そのチェック（同じ t が同じ画像を描画する、フォントが読み込まれている、テキストがクリップされていない、ラウドネス）は、センスやレイアウトについては何も言いません。入場中にテキストが切れる ! は問題ありませんが、静止時に切れるのはバグです。その後、いくつかの瞬間をフルサイズで確認してください（look 12.5）：300ピクセルのタイルでは小さなもの（人物を含む）が見えません。

実際に制作して学んだフィルムの構築方法：

• ショットごとに1ページ。ページが共有するもの（ケンバーンズ移動、フォント、色）は、インポートするモジュールにまとめます。すべての値は t のみの関数：タイマー、アニメーションループ、状態はありません。
• ページは自身をフェード（t から不透明度を計算）します。1つのトラックでショット間を黒を通してフェードするのが最もシンプルなトランジションです。クロスディゾルブには、インカミングショットをアウトゴーイングショットの上のトラックに配置する必要があります。
• 写真の上のテキストには、背後にシェード（下部グラデーション）が必要です。そうしないと、込み入ったシーンに埋もれてしまいます。
• フォントは FILM/fonts/ に @font-face で配置し、window.film.ready（document.fonts.ready）で待機します。写真の場合は ready: img.decode() です。
• #t=in,out でトリミングし、新しいファイルをカットしないでください。フィルムより長い音声はフィルムを延長します。

音声

$S/openfilm get で接続状況を表示します。生成音声、音楽、効果音には本人のプロバイダキーが必要です（Studio：OpenFilmロゴ → 設定 → プロバイダ）。キーがない場合は、ffmpegで音声を作成し、FILM/assets/ に保存し、コマンドを FILM/sound-notes.txt に残して再構築可能にし、どのサービスがより適切かを伝えてください。あなたは音声を聞けないので、数値で判断します：

• 完成ミックスは -16 LUFS統合（ポッドキャスト、ほとんどのWeb動画）。ストリーミングプラットフォームは約-14に正規化します。トゥルーピークは -1 dBTP 以下に抑えてください。音声の下のBGMは約-22です。
• 測定：ffmpeg -i X -af ebur128=peak=true -f null -。生成したBGMを正規化するには loudnorm=I=-16:TP=-1.5:LRA=7 を使用します。最終マスターの場合は loudnorm を2回実行（測定→measured_* 値をフィードバック）してゲインを線形にします。
• look はミックスのラウドネスを出力し、footage.py check は目標を外れたレンダリングを不合格にします。

受け取った映像：取り込み

スマートフォンの動画は見た目通りであることはほとんどありません。以下を、確認またはカットする前に実行してください：

uv run --no-project --with pillow python -I $S/footage.py probe CLIP.mov ...
uv run --no-project --with pillow python -I $S/footage.py proxy CLIP.mov <scratch>/clip.mp4

probe は以下の各問題を警告し、proxy はそれらすべてを1パスで修正します（SDR BT.709、回転を焼き付け、固定30fps、偶数サイズ、H.264 yuv420p、AAC 48kHz、faststart）：

• HDR（iPhoneはデフォルトでHLG記録：color_transfer=arib-std-b67、BT.2020）。SDRとして読むと色あせて見え、色がずれます（朱色がオレンジに）。proxy はmacOS内蔵の avconvert、なければffmpeg zscale（多くのHomebrewビルドでは欠落）、なければ警告を出してトーンマッピングします。
• 回転：スマートフォンはポートレート動画を回転フラグ付きで横向きに保存します。一部のツールはこれを無視します。
• 可変フレームレート：公称24、平均23.997。フレーム時間がドリフトし、カット後に音声が同期しなくなります。probe は0.001fps以上の差をフラグします。
• 奇数サイズ：H.264 yuv420pには偶数幅と高さが必要です。

プロキシから確認・カットし、フル品質が必要なものにはオリジナルを保持してください。

映像の理解

uv run --no-project --with pillow python -I $S/footage.py frames <scratch>/clip.mp4 <scratch>/sheets --every 4

これにより、シーンチェンジごと（--scene 0.3）、および少なくとも --every 秒ごとに1フレーム（--max 60 で上限）を、0007 · 1:23.4 とラベル付けされた5×6タイルのシートに抽出し、manifest.json で各idと時間をマッピングします。シートを読み、idと時間で回答してください。実践的な指針：

• 制作されたフィルム：ショット長に合わせた均一サンプリング。既存の映像：シーンチェンジ＋2～5秒に1フレームの下限。速いアクション：--every 0.5 で短い範囲を。
• シートは長辺約2,500ピクセル以下に抑え、一度に数枚ずつ読んでください。長い映像の場合は、シートごとにサブエージェントに展開し、各タイルidに対して1行JSONLの判定を書き出させ、その後 python3 -I $S/check_verdicts.py manifest.json out/*.jsonl を実行します（不足、重複、架空のidは失敗。すべてのタイルが同じ回答だったシートはおそらく流し読みされています）。
• 会話動画の大部分は音声にあります。 デバイス上で単語タイムスタンプ付き文字起こし：uvx parakeet-mlx AUDIO.wav --output-format json --output-dir <scratch>（まず音声を抽出：ffmpeg -i clip.mp4 -ar 16000 -ac 1 audio.wav）。単語を時間でフレームに結合します。固有名詞は誤認識されることがあるため（「torii」→「Torrey」）、引用前に見たものと名前を照合してください。

納品

uv run --no-project --with pillow python -I $S/footage.py check FILM/<name>.mp4 --duration 30
uv run --no-project --with pillow python -I $S/footage.py share FILM/<name>.mp4 <scratch>/<name>-share.mp4
uv run --no-project --with pillow python -I $S/footage.py gif FILM/<name>.mp4 <scratch>/loop.webp --start 2.5 --duration 6 --width 480

• check はファイルを引き渡す前にパスする必要があります：H.264、yuv420p、偶数サイズ、固定フレームレート、moov が mdat の前（faststart：ダウンロード中に再生可能）、再生時間、ラウドネス±1.5 LU、トゥルーピーク。
• 本人がファイルを要求したとき、またはこのMacを使えないときにレンダリングします。最後のチェックとしてMP4自体に look を実行してください。share はWebページやチャット用の小さなコピー（幅1280、CRF 28：30秒の1080pレンダリングが34MBから3.8MBに）を作成します。フィルム自身のMP4は変更されません。
• ループ：アニメーションWebPをGIFより優先。 5.6秒の写真ループ（スローズーム）はGIFで6.7MB、WebPで1.6MBでした：GIFはすべてのピクセルが動く場合にピクセルを再利用できません。GIFは対象がWebPを表示できない場合のみ使用します。その場合、footage.py gif X.gif は生成されたパレット（palettegen/paletteuse）を使用します。
• 移動すべきでないものを除去：iPhone動画はメタデータにGPS、機種名、時刻を含みます。proxy と share はこれらすべてを削除します（-map_metadata -1）。元のファイル、またはAirDropや写真書き出しで作成したコピーには保持されます。exiftool -GPSCoordinates FILE で確認してください。

フィルム内の写真

photo-skill スキル（github.com/kylefritz/photo-skill；インストールされていない場合は ~/.claude/skills/photo-skill にクローンすることを提案）を使用して、写真を見つけ（ライブラリを説明で検索し、コンタクトシートで判断）、フル解像度のオリジナルをダウンロードしてください：プレビューは1080pには小さすぎます。フィルムが使用するものを FILM/assets/ にコピーし、EXIFなしで再保存します。誰かの写真が含まれるフィルムをどこかに送る前に、各ショットをフルサイズで確認してください：顔検出は群衆を見逃し、300ピクセルのタイルは1080pフレームに表示される人物を隠します。

その他のツール

OpenFilmは、フィルムがプレーンなHTMLであり look が必要な情報を正確に返すため、エージェントに最適です。2026年後半時点の代替ツール：

ツール	オーサリング	備考
HyperFrames（HeyGen、Apache-2.0）	HTML/CSS + GSAP、ヘッドレスChromeでレンダリング	最も近い類似品。check --json lint/レイアウト/コントラストゲート、スナップショット、Claude Codeプラグインあり
Remotion	Reactコンポーネント	成熟した公式エージェントスキル。ソースアベイラブルライセンス、一定規模以上の企業はライセンスが必要
Manim（MIT）	Pythonシーン	数学・図解説明用
MoviePy（MIT）/ raw ffmpeg	Python / フィルターグラフ	シンプルなカットとオーバーレイ。ffmpegはI/Oレイヤーとして最適

OpenFilmのアップグレード

上流は頻繁にリリースされます。リリースノートを読み、まず npm view openfilm scripts を実行し（preinstall や postinstall エントリは確認が必要）、その後 scripts/openfilm の OPENFILM_VERSION を変更して setup.sh を再実行してください。その後 ls ~/Library/Caches/ms-playwright を実行：OpenFilmの初回実行時にリンクマーカーのないPlaywrightブラウザが削除されます。setup.sh は削除したものを報告し、それを必要とするプロジェクトで npx playwright install chromium を実行すると復元されます。

よくある間違い

間違い	修正
npx openfilm …	$S/openfilm …：npxは固定を迂回する
間違ったフォルダで look または render	$S/openfilm -C FILM …
look のチェックをPNGを開かずに信頼する	シートを読むこと。チェック通過はレイアウトについて何も保証しない
iPhone映像を直接カットまたは確認	probe、次に proxy：HDR、回転、VFRすべてが問題を起こす
マスターMP4をチャットに送信	share してから、コピーを check
READMEやページにGIF	WebP、約4分の1のサイズ
アップグレード後に古いStudioが残る	古い studio/server/main.mjs プロセスを停止（pgrep -fl openfilm）。Studio1つは2プロセス