Communitygithub.com

josueh04/product-video-skills

レンダリングされた製品ビデオの品質を自動チェックし、QAレポートを生成するスキルです。ちらつき、黒フレーム、ラウドネス、クリッピング、クリックノイズ、ナレーションの重複、音声テキスト変換とスクリプトの一致、禁止用語、カメラズーム、コンタクトシート、トランジションのフレームストリップ、承認版とのパリティをチェックし、`qa/REPORT.json` を出力します。HyperFramesレンダリング後や「レンダリングはきれいか」「QAを実行して」「ビデオをチェックして」「このMP4を確認して」といったリクエストがあったときに使用します。

product-video-skills とは?

このスキルは、製品ビデオのレンダリング品質を自動および手動で検証するための包括的なQAパイプラインを提供します。主な目的は、人間の目で確認する前に、レンダリングに潜む様々な欠陥(ワーカーパターンのちらつき、黒フレーム、クリッピング、クリックノイズ、ナレーションの重複、音声認識とスクリプトの不一致、禁止用語、カメラズーム、承認済みバージョンとの不一致など)を検出することです。このスキルはHyperFramesレンダラーと連携して使用することを前提としており、macOS上で動作します。QAプロセスは、レンダリング前のモーションリント、レンダリング直後の高速スキャン、そして詳細な自動レポート生成(qa.py)という段階を踏みます。最終的には、人間によるコンタクトシートとフレームストリップの目視確認、およびエッジの聴覚チェックが必須です。出力としてqa/REPORT.jsonとqa/REPORT.mdを生成し、これが配信スクリプトdeliver.pyが受け入れる唯一のレポート形式です。このスキルは、Claude CodeやAgent ModeなどのAIエージェント環境で使用され、レンダリング結果の品質保証を自動化します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/render-qa

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

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

ドキュメント

レンダリング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/ を含みます)。

ゲートの順序

  1. レンダリング前。 モーションリント(seek-safe-motion スキル)、hyperframes check、およびすべてのセットアップビートのスナップショットを実行します。check だけでは不十分です。かつて、動く要素が4つのうち3つの区間で見えなかったビデオをパスしたことがあります。レンダリング前の手順は references/checklist.md にあります。
  2. レンダリング直後、高速スキャン(数秒): "$PY" "$S/scan_render.py" <mp4>。WORKER PATTERN という行はシークセーフティのバグを意味します:停止してタイムラインを修正し(seek-safe-motion を参照)、残りの工程を実行しないでください。
  3. 完全なレポート:"$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差分を確認してください。
  4. 目視によるパス。 レポートはスクリプトでは確認できない内容で終わります。すべて実行してください:
    • すべてのコンタクトシートを確認します(サンプルではありません)。
    • すべてのモーダルの開閉、スクロール、カメラ移動、チャプター変更、このバージョンで変更されたビート、およびエンドスクリーンからロックアップへのハンドオフの周辺で、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。
  5. トリアージ:すべての失敗と警告を references/triage.md を使用して評価します。このチェックで見つかった実際の欠陥と誤検出が、それぞれの見分け方とともにリストされています。原因をソース(テンプレート、ビルド、lines.tsv、オーディオ)で修正し、再ビルド、再レンダリングし、ステップ2からゲートを再度実行します。index.html を手動で編集しないでください。ビルドが再生成します。
  6. 配信はこのスキルの判断ではありません。deliver.py は、ユーザー、またはユーザーが開始したスキル(/video-build、/video-review)が配信を要求した場合にのみ実行されます。レポートがパスしていない場合、ドラフトである場合、またはMP4とバイト単位で一致しない場合は拒否されます。

チェックの測定内容

チェック失敗条件この閾値の理由
size、fpsサイズが video.size と異なる場合。fpsは警告のみ間違ったサイズは壊れたレンダリングです。異なるfpsは意図的である可能性があります(30 vs 60)
worker_pattern4つ以上の外れ値フレームがすべて同じフレームインデックスmod 3で連続して発生する場合HyperFramesは3つのインターリーブワーカーでレンダリングします。1つが状態を失うと、3フレームごとに影響が出ます
outliers失敗なし(警告)フルスピードのスクロール、ブラーフォーカス、カメラの戻りは孤立した外れ値を発生させます。各ストリップを確認してください
black_frames最初の1秒と最後の2秒以外で平均輝度が3未満の場合黒へのフェードイン/アウトは意図的です。ビデオ途中の黒はバグです
voice_overlap2つの音声クリップの話し言葉が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_lintseek-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が生成したすべての失敗(実際のものと誤検出)、およびその見分け方と修正方法。チェックが失敗または警告を発したらすぐに読んでください。

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Write a product video's narration and turn it into voice clips with word timings, pronunciation fixes, sound effects and even loudness. The script becomes a table of moments and then audio/lines.tsv (one clip per sentence, with role and speed columns); tts.py voices it with ElevenLabs or the free macOS say voice, maps brand respellings back to the on-screen spelling, normalizes every clip and writes audio/timings.json for the composer; make_sfx.py builds typing tracks from real keystrokes and places recorded click and pop sounds. Use it whenever a video needs a script, narration, voice-over, lines.tsv, timings.json, TTS, a new take, a voice or casting choice, a pronunciation fix ("it says the name wrong"), a changed sentence, a tone note ("too hype", "sounds cut off"), audio levels, a click at the end of a clip, typing or click sounds, or when the build stage asks for the voice. Also use it for silent loops, which still need a moment table and SFX.

josueh04/product-video-skills

The animation rules that keep HyperFrames' parallel render workers from dropping, flashing or flickering elements, plus a static lint (lint_motion.py) that finds the violations in a video's template before it costs a render. Use it whenever you write or edit GSAP tweens, timelines, cursors, camera moves, typing, scrolls or pop-ups in a HyperFrames composition or a video's src/template.tpl, whenever a render shows flicker, stutter, an element that vanishes on some frames, a title that flashes, or a "WORKER PATTERN" line from scan_render.py or qa.py, and whenever the preview looks right but the MP4 does not. Also use it to review someone else's timeline code before rendering.

josueh04/product-video-skills

Pin a product's source code (read-only exports in sources/ plus sources.lock), confirm that the pinned commit is what runs in production, and map every screen of a video brief to its route, components, i18n strings and state, written to the video's SOURCES.md. Use it whenever a video needs to know where a screen lives in the code, when sources/ is missing or stale, before ui-spec-from-code or product-truth start on a video, after the product's frontend changed ("what changed", "which videos are affected", "refresh the sources", "is this checkout current", "which commit is in prod"), and when there is no code and you need an inventory of the no-code references (recordings, recovered captures, docs) a screen can be rebuilt from.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Gather pixel references for UI that the code cannot show, or to check a rebuild against the real thing, using frames and timed OCR text from screen recordings, captures recovered from past Claude Code session transcripts, a local instance of the app built like production, and web research for third-party apps, plus side-by-side parity images and contact sheets. Use it whenever someone hands over a screen recording (.mov or .mp4) of the product, when a screen has no usable source code (a stale checkout, another company's UI such as a sign-in page, calendar or CRM, runtime output from a backend not in the repos), when asked "what does it really look like", "match the recording", "how long does that animation take in the app", "compare our render to the real app", or when screenshots from an earlier session might already exist. Never uses the reviewer's personal browser.

josueh04/product-video-skills

Turn a product's real frontend code into 1:1 rebuild specs for a video, one read-only subagent per screen, each returning static HTML, CSS with every variable resolved to its literal value and cited (role/path:line@sha), every state, transitions with exact durations and easings, icons from the code's own icon sets, and the exact i18n strings; plus resolve_tokens.py to write the product's design tokens to kit/tokens.css. Use it whenever a screen of the product has to appear in a video, when writing or fixing video/src/app.css or the template markup, when someone asks for exact sizes, colors, fonts, paddings, animations or icons of a screen, when a rebuilt screen "looks off" next to the real app, and when the design tokens or theme of a product need extracting. Framework adapters cover Angular with PrimeNG (proven), React, Vue, Tailwind and plain HTML (unproven).

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

関連スキル