レンダリングQA
レンダリングが完了するのはレンダラーが終了したときではありません。証拠がクリーンであると示したとき、すなわち自動レポート、すべてのコンタクトシートの確認、すべてのトランジションのストリップの確認、そしてナレーションのエッジの聴取が完了したときです。このスキルが元となったプロダクションでは、サブエージェントが「クリーン」と報告したレンダリングに、ロックアップ前の0.3秒のUIフラッシュ、クリップされたモーダル、および3フレームごとに消えるタイトルが含まれていることがありました。スクリプトとストリップがこれらすべてを発見しました。
スクリプトはこのファイルの隣にあります。一度だけワークベンチを解決してください:
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"
S="$PVS_HOME/skills/render-qa/scripts"
インタプリタとスクリプトフォルダは別々の変数に保持し、両方を引用符で囲んでください("$PY" "$S/qa.py")。コマンドとパスを1つの変数に保持すると、zshでは分割されず、bashではパスにスペースがあると動作しません。
<video_dir> は products/<slug>/videos/<video>/ です(BRIEF.md、audio/、video/ を含みます)。
ゲートの順序
- レンダリング前。 モーションリント(
seek-safe-motionスキル)、hyperframes check、およびすべてのセットアップビートのスナップショットを実行します。checkだけでは不十分です。かつて、動く要素が4つのうち3つの区間で見えなかったビデオをパスしたことがあります。レンダリング前の手順はreferences/checklist.mdにあります。 - レンダリング直後、高速スキャン(数秒):
"$PY" "$S/scan_render.py" <mp4>。WORKER PATTERNという行はシークセーフティのバグを意味します:停止してタイムラインを修正し(seek-safe-motionを参照)、残りの工程を実行しないでください。 - 完全なレポート:
"$PY" "$S/qa.py" <video_dir> <mp4>。すべての自動チェックを実行し、qa/REPORT.jsonとqa/REPORT.md、qa/sheets/内のコンタクトシート、qa/strips/内のストリップ(各外れ値ランと最後の5秒間)、およびqa/asr.txt内の文字起こしを生成します。最近のMacで2〜3分の60fpsビデオの場合、音声テキスト変換を含めて約15秒かかります。REPORT.mdを最初から最後まで読み、警告とすべてのASR差分を確認してください。 - 目視によるパス。 レポートはスクリプトでは確認できない内容で終わります。すべて実行してください:
- すべてのコンタクトシートを確認します(サンプルではありません)。
- すべてのモーダルの開閉、スクロール、カメラ移動、チャプター変更、このバージョンで変更されたビート、およびエンドスクリーンからロックアップへのハンドオフの周辺で、5〜6fpsのストリップを作成します:
"$PY" "$S/strips.py" <mp4> <video_dir>/qa/strips modal:21.0:23.4:8 lockup:57:60。1fpsのシートは1秒間に1フレームをサンプリングします。0.3秒のフラッシュは2つのサンプルの間に収まる可能性があります。 "$PY" "$S/edges.py" <mp4> <video_dir>を実行し、マークされたすべてのエッジを聴取します。- このバージョンが承認済みバージョンを編集する場合、残りの部分が変更されていないことを証明します:
"$PY" "$S/parity.py" <approved.mp4> <new.mp4> --skip 41.0:48.5。 シート、ストリップ、パリティ出力の読み方:references/reading-sheets-and-strips.md。
- トリアージ:すべての失敗と警告を
references/triage.mdを使用して評価します。このチェックで見つかった実際の欠陥と誤検出が、それぞれの見分け方とともにリストされています。原因をソース(テンプレート、ビルド、lines.tsv、オーディオ)で修正し、再ビルド、再レンダリングし、ステップ2からゲートを再度実行します。index.htmlを手動で編集しないでください。ビルドが再生成します。 - 配信はこのスキルの判断ではありません。
deliver.pyは、ユーザー、またはユーザーが開始したスキル(/video-build、/video-review)が配信を要求した場合にのみ実行されます。レポートがパスしていない場合、ドラフトである場合、またはMP4とバイト単位で一致しない場合は拒否されます。
チェックの測定内容
| チェック | 失敗条件 | この閾値の理由 |
|---|---|---|
size、fps | サイズが video.size と異なる場合。fpsは警告のみ | 間違ったサイズは壊れたレンダリングです。異なるfpsは意図的である可能性があります(30 vs 60) |
worker_pattern | 4つ以上の外れ値フレームがすべて同じフレームインデックスmod 3で連続して発生する場合 | HyperFramesは3つのインターリーブワーカーでレンダリングします。1つが状態を失うと、3フレームごとに影響が出ます |
outliers | 失敗なし(警告) | フルスピードのスクロール、ブラーフォーカス、カメラの戻りは孤立した外れ値を発生させます。各ストリップを確認してください |
black_frames | 最初の1秒と最後の2秒以外で平均輝度が3未満の場合 | 黒へのフェードイン/アウトは意図的です。ビデオ途中の黒はバグです |
voice_overlap | 2つの音声クリップの話し言葉が20ミリ秒以上重なる場合 | クリップ境界ではなく単語タイミングで測定します。無音の末尾が重なっても問題ありません |
loudness | インテグレーテッドラウドネスが voice.mix_lufs から1LU以上乖離している場合 | 納品された最終版は、-16ターゲットに対して-16.8〜-15.3 LUFSと測定されました |
true_peak | -1.0 dBFSを超える場合 | アップロードプラットフォームの非可逆エンコーダのためのヘッドルーム |
clipping | 実際のチャンネルで0.995以上のサンプルがある場合 | ダウンミックスではなくチャンネルごとに測定されるため、片側だけのクリップは隠れません |
clicks_outside_clips | すべてのオーディオクリップの外側でインパルス的なクリックがある場合 | SFX内では予想されます。音声内ではほぼ常に子音です |
abrupt_edges | 失敗なし(警告) | SFX以外で5ms以内に終了する音は、通常、トリミングが不適切なクリップです。聴取が必要です |
asr | 単語一致率が0.93未満、またはスキップされた場合 | 最終版は0.953〜0.988と測定されました。スクリプトはファイル順ではなく再生順で比較されます |
banned_terms_* | 禁止用語、決して言ってはいけないフレーズ、またはレガシー名が音声で聞こえる、index.htmlで見える、またはlines.tsvに含まれている場合 | product.yaml から。ライブUIには古い名前が表示される可能性がありますが、ビデオには表示してはいけません |
camera_zoom | 失敗なし(警告) video.max_zoom を超える場合 | 約2倍のフルページスクリーンは「超ズームイン」として2回却下されました。ズームアウトされたキャンバスはより多くのズームを許容します |
motion_lint | seek-safe-motionリントがエラーを報告する場合 | レンダリングコストが発生する前にタイムラインバグをキャッチします |
--no-asr はレポートを意図的に失敗させます。スクリプトから逸脱したナレーションは、レビュアーが最初に聞くものだからです。音声テキスト変換には、英語用に whisper small.en、その他の lang には多言語 small モデルを使用します(不足している場合は一度ダウンロードされます)。
レポート契約
qa/REPORT.json は docs/contracts.md に従います:mp4(ビデオフォルダからの相対パス)、sha256、created、draft、checks(name、passed、detail、および警告の場合は level: warn)、passed。また、draft_reason、probe、artifacts、およびASR差分も含まれます。draft は、BRIEF.md のいずれかの署名が空であるか、video/index.html に <meta name="pvs-draft" content="1"> が含まれている場合にtrueになります(build.py --draft によって書き込まれます)。ドラフトはすべてのチェックに合格しても配信されることはありません。未署名のカバレッジは、レビュアーが気にしていた機能がビデオに欠落している理由になります。
配信(要求された場合のみ)
"$PY" "$S/deliver.py" <video_dir> <mp4> [--archive-previous] [--dry-run]
<product_dir>/deliveries/ に review.naming(デフォルトは {product} {video} v{version}.mp4、バージョンは BRIEF.md から)としてコピーします。可能な場合はAPFSクローンを使用し、コピーをバイト単位で検証し、その隣に <same name>.BRIEF.md を書き込みます。上書きは絶対に行いません。同じバイトが再度コピーされる場合は何もせず、配信済みの名前で異なるバイトがコピーされようとした場合は、ファイル名のバージョンを上げます(その後 BRIEF.md のバージョンも合わせて上げます)。--archive-previous は、ビデオの古いバージョンを deliveries/previous/ に移動し、レビュアーのフォルダには最新版のみが保持されるようにします。配信後、レビュアーに1つのテーブルで伝えてください:ビデオ、バージョン、再生時間、変更点、および最大3つの未決定事項(各項目に推奨されるデフォルトを添えて)。すでにどこかにアップロードされているコピーは古くなっています。その旨を伝えてください。
インシデントから生まれたルール
- 証拠は自分で確認すること。 サブエージェントがレンダリングはクリーンだと言った場合、その
REPORT.mdを読み、シートとストリップを開き、sha256が配信するファイルと一致することを確認してください。エージェントの「クリーン」は主張であり、レポートが証拠です。 - すべてのバージョンは独自のファイル名を
renders/内に持ちます。古いバージョンを決して削除しないでください。修正サイクル内で、レビュアーがまだ見ていないバージョンのみを上書きしてください。 - 自分が起動していないプロセス(Chrome、ffmpeg、node)を強制終了しないでください。他のエージェントが同じマシンでレンダリングしています。
- ビジョンAPIなしのスナップショット:
hyperframes snapshotに--describe falseを渡し、未公開製品のフレームがマシンの外部に漏れないようにします。 - スペル違いのみのASR差分は問題ありません(ブランド名が2つの単語として認識される、時間が単語で書かれているなど)。判断する前に各差分を読んでください。複数の単語の差分は、カットまたは音割れした行を示します。
スクリプト
| スクリプト | 用途 |
|---|---|
qa.py <video_dir> <mp4> [--out DIR] [--no-asr] [--strip name:t0:t1[:fps]] | 完全なレポート。パスしなかった場合は終了コード1 |
scan_render.py <mp4> [--json] | 高速フリッカー、黒、ラウドネススキャン。ワーカーパターンまたはビデオ途中の黒で終了コード1 |
qa_full.py <video_dir> <mp4> [--out DIR] [--no-asr] | 測定値のみを REPORT.txt として出力 |
sheets.py <mp4> <outdir> [--fps 1] | 1fpsのコンタクトシート、4x4 |
strips.py <mp4> <outdir> name:t0:t1[:fps] ... | トランジション周辺のラベル付きストリップ(デフォルト6fps) |
edges.py <mp4> <video_dir or index.html> | 各ナレーションクリップの前後のレベル |
parity.py <old> <new> [--end T] [--skip A:B] [--threshold 1.0] [--audio] | フレームパリティ。閾値を超えると終了コード1 |
banned_terms.py [--product DIR] [--text T] [FILE or DIR ...] | 禁止用語、決して言ってはいけないフレーズ、レガシー名。ヒット時に終了コード1 |
deliver.py <video_dir> <mp4> [--archive-previous] [--dry-run] | 配信ゲート |
banned_terms.find_banned(text, product) は [(term, kind)] を返し、他のスキルで再利用できます。
リファレンス
references/checklist.md:ビルドからレビュアーメッセージまでのゲート全体をチェックボックスとしてまとめたもの。ビデオの最初のレンダリング前および配信前に読んでください。references/reading-sheets-and-strips.md:シート、ストリップ、クロップ、パリティ、および数値チェック(明るいピクセル数、差分ボックス)で何を見るべきか。ステップ4を行うときに読んでください。references/triage.md:このQAが生成したすべての失敗(実際のものと誤検出)、およびその見分け方と修正方法。チェックが失敗または警告を発したらすぐに読んでください。