Communitygithub.com

josueh04/product-video-skills

在任何人之前检查渲染的产品视频:工作线程模式闪烁、黑帧、响度和真峰值、削波、剪辑边缘的咔嗒声、旁白重叠、语音与脚本的文本匹配、禁用词汇和旧名称、相机缩放、接触表、转场处的帧条以及与批准版本的奇偶校验;然后写入 qa/REPORT.json,这是 deliver.py 唯一接受的文件。在每次 HyperFrames 渲染后使用,每当有人询问“渲染是否干净”、“QA 这个”、“检查视频”、“检查音频”、“为什么闪烁”、“有咔嗒声”、“比较 v3 和 v2”、“批准的部分是否改变”、或者在展示、发送、上传或交付任何 MP4 之前使用,即使请求没有提到 QA。也用于分类审阅者在渲染中报告的缺陷。

product-video-skills 是什么?

此技能(Render QA 的一部分)提供了一个全面的自动化视频质量保证流程,专为 HyperFrames 渲染的工作线程模式(worker-pattern)设计。它执行一系列自动检查,包括检测工作线程模式闪烁、黑帧、响度超过 -16 LUFS 目标、真峰值高于 -1.0 dBFS、单个通道的削波、音频剪辑边缘的瞬时咔嗒声、旁白重叠、以及将旁白与脚本进行语音转文本对比,确保准确率至少达到 93%。它还会生成接触表、在转场和 UI 变化处创建帧条,并与批准的版本进行奇偶校验。该技能通过 script/qa.py 运行,输出 machine-readable 的 qa/REPORT.json 和人类可读的 qa/REPORT.md。它在 Claude Code、Cursor 和其他基于终端的环境中运行,通过一个分步的门控流程:首先快速扫描工作线程模式,然后是完整的报告,接着是人工检查接触表、帧条和音频边缘,最后进行分类。有一个严格的交付门控:deliver.py 仅在满足所有条件时运行,并且永远不要手动编辑 index.html。所有检查的阈值都来源于实际生产事故(例如,工作线程模式阈值为 3 个连续异常帧,黑帧阈值为 1 秒后亮度低于 3),并明确列出了避免陷阱的规则(例如,永远不要自行重新生成证据,每个版本保留自己的文件名,不要杀死外来进程)。参考文件提供了详细的分类指南和脚本的使用方法。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

渲染 QA

渲染并不是在渲染器退出时就完成了。只有当证据表明它干净时才算完成:自动报告、每一张接触表都检查过、每个转场处的条带都检查过、旁白边缘都听过。在制作这些技能的生产环境中,子代理曾将一些渲染报告为“干净”,但实际存在 0.3 秒的 UI 闪烁(在锁定之前)、一个裁剪过的模态框,以及每隔三帧就消失一次的标题。正是脚本和条带发现了所有这三个问题。

脚本位于此文件旁边。先设置一次工作台:

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"):如果某个变量包含命令和路径,zsh 不会将其拆分,而在 bash 中,一旦路径包含空格,它就会失效。

<video_dir> 是 products/<slug>/videos/<video>/(其中包含 BRIEF.md、audio/、video/)。

门控流程,按顺序

  1. 在渲染之前。 运行运动检查(seek-safe-motion 技能)、hyperframes check 以及每个设置节拍的快照。仅靠 check 是不够的:它曾经让一个视频通过,其中移动元素在四段展现中有三段都不可见。预渲染步骤在 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 分钟 60 fps 的视频,大约需要 15 秒,包括语音转文本。从头到尾阅读 REPORT.md,包括警告和所有 ASR 差异。
  4. 肉眼检查。 报告以脚本无法看到的内容结尾。执行所有操作:
    • 查看每张接触表,而不是抽样。
    • 在每次模态框打开和关闭、滚动、相机移动、章节更改、此版本中发生变化的节拍以及结尾画面到锁定的交接处,以 5 到 6 fps 的速度制作条带:"$PY" "$S/strips.py" <mp4> <video_dir>/qa/strips modal:21.0:23.4:8 lockup:57:60。1 fps 的表格每秒采样一帧;0.3 秒的闪烁会夹在两个样本之间。
    • 运行 "$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 对 60)
worker_pattern连续 4 个或更多异常帧都落在一个帧索引模 3 上HyperFrames 使用 3 个交错的工作线程进行渲染;一个失去状态的工作线程会每三帧命中一次
outliers从不(仅警告)全速滚动、模糊调整和相机复位也会产生孤立的异常值;查看每个条带
black_frames在前 1 秒和后 2 秒之外,平均亮度低于 3渐黑和从黑渐出是预期的;视频中间变黑是一个错误
voice_overlap两个语音剪辑的口语单词重叠超过 20 毫秒基于单词时间测量,而不是剪辑边界:无声尾部重叠是可以的
loudness综合响度与 voice.mix_lufs 相差超过 1 LU已交付的最终成片测量结果为 -16.8 到 -15.3 LUFS,目标为 -16
true_peak高于 -1.0 dBFS为上传平台的损音频编码器留出余量
clipping任何真实的通道上的采样值达到 0.995 或更高按通道测量,而不是下混,因此不会隐藏单个通道削波
clicks_outside_clips在所有音频剪辑之外出现脉冲性咔嗒声在音效内部是预期的;在语音内部几乎总是辅音
abrupt_edges从不(仅警告)一个在 5 毫秒内结束且不在音效内的声音通常是剪辑不当的片段;请倾听
asr单词匹配率低于 0.93,或跳过最终测量结果在 0.953 到 0.988 之间;脚本按播放顺序比较,而不是文件顺序
banned_terms_*在音频中听到、在 index.html 中可见或在 lines.tsv 中出现的禁用词汇、禁止短语或旧名称来自 product.yaml;实时 UI 可能仍显示旧名称,但视频不能
camera_zoom从不(仅警告)高于 video.max_zoom全屏截图大约 2 倍两次被拒绝为“超级放大”;缩小的画布容差更大
motion_lintseek-safe-motion 检查报告错误在代价高昂的渲染之前捕获时间线错误

--no-asr 会使报告故意失败:偏离脚本的旁白正是评审者最先听到的内容。语音转文本使用 whisper small.en 处理英语,使用多语言 small 模型处理其他任何 lang(如果缺失,会下载一次)。

报告契约

qa/REPORT.json 遵循 docs/contracts.md:mp4(相对于视频文件夹)、sha256、created、draft、checks(name、passed、detail 和 level: warn 用于警告)、passed。它还包含 draft_reason、probe、artifacts 和 ASR 差异。当 BRIEF.md 中的任一签名为空或 video/index.html 包含 <meta name="pvs-draft" content="1">(由 build.py --draft 写入)时,draft 为 true。草稿可以通过所有检查,但永远不会被交付:未签名的覆盖率正是导致视频缺少评审者关心的功能的原因。

交付(仅在要求时)

"$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/,以便评审者的文件夹中只保留最新版本。交付后,用一张表格告知评审者:视频、版本、时长、更改内容以及最多三个未决决定,每个决定都附带一个推荐的默认值。任何已经上传到某处的副本现在都已过时:请说明这一点。

源于事故的规则

  • 自行重新运行证据。 当子代理说渲染干净时,阅读其 REPORT.md,打开接触表和条带,并检查 sha256 是否与您要交付的文件匹配。代理说“干净”只是一个声明,报告才是证据。
  • 每个版本在 renders/ 中都有自己的文件名;永远不要删除旧版本。仅在修复周期中覆盖评审者尚未见过的版本。
  • 不要杀死您自己没有启动的进程(Chrome、ffmpeg、node):其他代理在同一台机器上渲染。
  • 无需视觉 API 的快照:向 hyperframes snapshot 传递 --describe false,这样未发布产品的任何帧都不会离开机器。
  • 仅拼写错误的 ASR 差异是可以接受的(品牌词被听成两个词,时间以单词形式书写)。在决定之前阅读每个差异;多个单词的差异意味着剪切或线路混乱。

脚本

脚本用途
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]1 fps 的接触表,4x4 排列
strips.py <mp4> <outdir> name:t0:t1[:fps] ...在转场周围创建带标签的条带(默认 6 fps)
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.

相关技能