Communitygithub.com

Ahmed-OC/motion-video-skills

レンダリングされた動画(生成・非生成問わず)のQAと仕上げゲート:仕様のプローブ、ラウドネス測定・正規化、ビジュアルレビュー用コンタクトシート生成、構造化批評、レンダリング決定性検証を行います。

motion-video-skills とは?

このスキルは、動画の公開準備が整っているかどうかを確認するための包括的なQAパイプラインを提供します。MP4、WebM、MOVなど、あらゆる動画ファイルに対応し、生成された動画だけでなく、従来の方法でレンダリングされた動画にも使用できます。具体的には、`scripts/probe.sh` を用いた仕様プローブ(duration、fps、解像度、コーデック、pix_fmt、オーディオ有無)、`ffmpeg` と `ebur128` / `loudnorm` フィルターによるラウドネス測定と−14 LUFSへの正規化、`scripts/contact_sheet.sh` によるコンタクトシートと連続フレームストリップの生成、10点満点の構造化批評(フック、可読性、モーション、シンク、スタイル一貫性、サウンド)、そして `ffmpeg -f framemd5` によるレンダリングの決定性検証を実行します。このスキルはClaude Code環境で設計されていますが、ffmpegとbashスクリプトが利用可能なあらゆるターミナル環境で機能します。ユーザーが動画のチェック、確認、監査、レビュー、診断、正規化、公開準備を依頼したとき、または動画が「おかしい」と感じたときに使用することで、再レンダリング前に問題を特定できます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Ahmed-OC/motion-video-skills/tree/HEAD/skills/video-qa

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

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

ドキュメント

Video QA — リリースゲート

動画はレンダリングされただけでは完了しません。プローブされ、コンタクトシートで目視確認され、正規化されて初めて完了です。このスキルは、どのように作成されたかにかかわらず、あらゆるファイルで機能します。

1. 事実をプローブする(決して想定に頼らない)

scripts/probe.sh video.mp4

すべての値を、発注内容(タイムライン、ブリーフ、プラットフォーム仕様)と比較します。

チェック項目期待値
duration発注 duration ± 0.1秒
fps / 解像度発注 fps / W×H
codec / pix_fmth264 / yuv420p(yuvj420p = full-range variant、通常は問題なし)
オーディオストリーム動画に音声が必要な場合のみ存在する
統合ラウドネス−14 ± 2 LUFS(ソーシャルプラットフォームは−14付近で正規化)

不一致があれば、それは味覚の問題ではなく、レンダリングのバグです。上流を修正し、再レンダリングしてください。

2. ラウドネス:測定 → 正規化(音声のみ、秒単位)

# 測定
ffmpeg -hide_banner -i video.mp4 -af ebur128 -f null - 2>&1 | awk '/Integrated loudness/{getline; print}'

# −14 LUFSに正規化(ビデオストリームはコピー、再エンコードなし)
ffmpeg -i video.mp4 -c:v copy -af "loudnorm=I=-14:TP=-1.5:LRA=11" -c:a aac -b:a 192k video_norm.mp4 \
  && mv video_norm.mp4 video.mp4

音量フィルターで耳で正規化しないでください。LUFSはプラットフォームが実際に使用する単位です。

3. 目で見る:コンタクトシート + ストリップ

scripts/contact_sheet.sh video.mp4 contact.png 2 8x    # 1タイル / 0.5秒、8列
# デリケートな瞬間(Tでのトランジション)の周辺の連続12フレーム:
ffmpeg -y -ss <T-0.2> -i video.mp4 -frames:v 12 -vf "scale=320:-1,tile=6x2" strip_T.png

シートをフィルムストリップとして読み取ります。リズムが見えるか? ビートグリッド上でカットされているか? 空のシーンや混みすぎたシーンはないか? コンタクトシートはモーションの品質を隠します—承認する前に必ず動画全体を最低1回は視聴してください。

4. 批評パス(作成者 ≠ 審査者)

レンダリング(ソースや意図ではなく)をレビューし、各項目を10点満点でスコアリングします。

  1. フック — 最初の2秒で最も大胆なフレームか?
  2. 可読性 — テキストは最小サイズ以上で、安全ゾーン内にあり、重なりや切れがなく、十分な長さ表示されるか?
  3. モーション — リニアイージングがないか? マルチプロパティのエントランス、スタガー、エグジットはエントランスより速いか?
  4. シンク — イベントがビート/ワードグリッド上に位置しているか?
  5. スタイルの一貫性 — 一つのパレットファミリー、一つのタイプシステム、統一されたトランジションか?
  6. サウンド — VOはクリアか? 音楽はダッキングされているか? ターゲットラウドネスか? クリッピングはないか?

プロトコル:最も悪い欠陥3つをタイムスタンプ付きで記録 → それらを正確に修正 → 再レンダリング → 再スコアリング。すべての項目で8/10以上になるまで3〜5ラウンド行うのが標準です。批評は新しいコンテキスト(またはサブエージェント)で実行してください。コードの作成者はコードの最悪のレビューアです。

5. 決定性(生成/再現可能な動画向け)

# 同じ入力の2つのフィンガープリントはバイト単位で一致しなければならない
ffmpeg -i video.mp4 -map 0:v -f framemd5 - | sha1sum

同じパイプライン、同じ入力 → 異なるハッシュは、隠れた壁掛け時間、シードされていないランダム性、または蓄積された状態を意味します。生成元を修正し、「ロールし直し」はしないでください。

6. 納品チェックリスト

video.mp4        H.264, yuv420p, +faststart, −14 LUFS
poster.png/jpg   フックフレーム
contact.png      2 fps フィルムストリップ
sources          動画を生成するものすべて(編集可能 > 最終版)

ユーザーに、何かを変更するためにどのファイルを編集すべきか、そして再レンダリングコマンドを正確に伝えてください。

エビデンスのルール

レビューア(人間でもビジョンモデルでも)がジオメトリ欠陥(「テキストが切れている」「要素が重なっている」)を主張した場合、バグでないものを「修正」する前に、測定(プレイヤー検査、ピクセルサンプル、または生成コード自体のメトリクス)で確認してください。レビューアは、レンダリングがテキストをクリップするよりもはるかに頻繁にマージンを幻覚します。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

関連スキル