Communitygithub.com

josueh04/产品视频技能

编写产品视频的脚本,并将其转化为带有单词时间戳、发音修正、音效和响度控制的语音片段。脚本事先转换为时刻表,然后生成 audio/lines.tsv(每句一个片段,包含角色和语速列);tts.py 使用 ElevenLabs 或免费的 macOS say 语音合成,将品牌重拼映射回屏幕拼写,归一化每个片段并写入 audio/timings.json;make_sfx.py 从真实按键声构建打字音轨,并放置录制的点击和爆破音。当视频需要脚本、旁白、画外音、lines.tsv、timings.json、TTS、新版本、语音或角色选择、发音修正(“它念错了名字”)、句子改动、语调调整(“太嗨”、“声音断断续续”)、音频电平、片段末尾的点击声、打字或点击音效,或构建阶段要求语音时,均可使用。静默循环也适用,只需时刻表和音效。

产品视频技能 是什么?

此技能专注于产品视频的脚本编写与语音生成全流程,确保动画节拍与旁白单词精确对齐。它首先将脚本组织为时刻表,并为每一句生成独立的音频片段(lines.tsv),通过 tts.py 调用 ElevenLabs 或 macOS 内置语音引擎,自动处理品牌名称的拼写映射和发音修正,最终输出带有单词时间戳的 timings.json。此外,make_sfx.py 使用真实键盘录制精确还原打字音效和点击声。其核心优势在于:任何脚本或发音的修改仅需重新生成一个片段及其之后的内容,而无需手动调整整个时间线,从而大幅提升迭代效率。该技能支持多种平台(Claude Code、Cursor、Codex等),适用于产品演示、教程、解说视频等场景。

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

在你喜欢的 AI 中提问

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

文档

脚本与语音

语音是视频的时钟。动画的每一个节拍都锚定在旁白的单词上(在 build.py 中为 T[clip] + w(clip, "word")),因此脚本及其片段先于动画产生,更改一个句子只需重新生成一个片段及之后的所有时间。在这些技能所源自的制作流程中,更换整个 TTS 引擎后,无需任何手动编辑即可重新同步已完成视频的时间线,这正是因为上述设计。先制作动画再适配语音意味着每次修改都需要手动拉伸音频或拖拽节拍。

仅写入 <video_dir>/audio/(以及 BRIEF.md 中的脚本章节)。每个句子必须在 TRUTH.md 中有依据,并遵守 CLAIMS.md;如果您需要的句子没有来源,请请求验证或删除。

脚本调用方式,详见 docs/contracts.md:

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/script-and-voice/scripts"
"$PVS_HOME/bin/pvs-py" "$S/check_script.py" <video_dir>                 # 检查 lines.tsv
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir> [--only N3,N4] [--provider say] [--force] [--restore]
"$PVS_HOME/bin/pvs-py" "$S/pronounce_check.py" <video_dir> [--only N3]  # ASR 是否识别了品牌词?
"$PVS_HOME/bin/pvs-py" "$S/make_sfx.py" <video_dir> [--list]            # sfx.tsv,或列出音效库

1. 脚本是时刻表

产品录制是参考,而非时间线:真实的加载等待和屏幕变化不应出现在视频中。将脚本编写为多个时刻,每个时刻包含屏幕上发生的内容、句子(或静默)及其持续时间。一个时刻的持续时间等于其动作和句子中较长者。压缩真实等待时间:四十秒的加载约改为两秒的思考状态。

将表格添加到 BRIEF.md 的 ## Script 下方,按章节顺序排列:

时刻屏幕内容台词编号文本(或静默)保持时长
开场产品名称,背景为失焦的应用N1这是 Acme Tasks,一款为您规划日程的待办事项列表。结束后 0.8 秒
等待计划正在生成(静默)2.0 秒

然后根据视频格式选择模板并遵循其结构:阅读 references/script-templates.md(宣传片、导览、文档页、教程、静默循环)。

如何编写台词及其理由:

  • 解释重要功能,而非罗列。 在 UI 展示功能的同时,说明它对用户的作用。在这些技能所源自的制作中,26 个版本中有 9 个是因为视频仅提及功能名称而未加解释。COVERAGE.md 指出哪些功能必须在屏幕上解释:每个标记为“必须解释”的行至少需要一句解释性台词。
  • 向从未见过该产品的人解释每一步骤。 角色是谁,他们请求什么,每个步骤的作用。在审核中,一段快速且未作解释的开场被拒绝。
  • 每个句子一个想法,每个片段一个句子。 修改一个句子只需影响一个片段。
  • 当光标触摸某元素时,在台词中说出其名称。 节拍锚定在这些单词上,因此屏幕上的名词和片段中的单词必须一致。
  • 使用真实的 UI 标签,即使审核者使用其他词语。这样视频才能与用户在应用中看到的匹配。
  • 将数字和时间写为单词("ten a.m.","thirty minutes later")。TTS 引擎对数字的读取不一致,且语音转文字的质量检查比较的是单词,而非数字。
  • 在等待前后留出空档。 电话铃响前约三秒,使用"about a minute"而非无人能验证的精确数字。
  • 以完整的句子结尾,语速稍慢。 在审核中,末尾的标语片段听起来像被截断;而包含 CLAIMS.md 定位的完整句子则不会。
  • 保持视频内人称一致:第一人称作为虚构用户("First, I connect my calendar.")或第三人称描述用户。仅使用 product.yaml 中的虚构演员,并在每个视频中使用相同名称。
  • 定位来源于 CLAIMS.md,而非源文档:源文档可能包含团队已禁止的短语,规则优先。

2. lines.tsv

audio/lines.tsv,制表符分隔,表头为 id\trole\tspeed\ttext,每行一个片段,按播放顺序排列,# 行为注释。完整格式及 build.py 如何读取结果:references/audio-formats.md。

  • id:旁白使用 N1、N2、N7b;其他字母代表角色(A1 表示客服代表,C1 表示客户)。在 N7 和 N8 之间插入一行作为 N7b 可以保持其他所有 id 及其使用的锚点稳定。
  • role:product.yaml 中 voice.roles 的一个键(narrator、agent、customer,或如 narrator_close 的变体,见第 3 节)。语音由角色而非 id 选择。
  • speed:默认为 1.0,范围 0.7 至 1.2。开场和结束行使用 0.9 至 0.96。
  • text:与屏幕和字幕中的显示完全一致,使用产品名称的标准拼写。此处绝不要写入重拼;发音修正位于 product.yaml 中。

在修改已交付版本的台词前,将 lines.tsv 复制为 lines-v<N>.tsv,并将 timings.json 复制为 timings-v<N>.json,以便可以重新构建先前版本。

每次编辑后运行 check_script.py。该脚本会检查重复 id、未知角色、语速超出范围、超过 40 个单词的片段、禁用术语、never_say 短语、遗留名称以及脚本中的重拼,并对长片段、数字和破折号发出警告。在配音前修复所有错误:禁用短语一旦进入 TTS 就会耗费一次录制版本,而一旦进入渲染则会耗费一个发布版本。

3. 选角

在提议语音前请阅读 references/casting-and-pronunciation.md。简而言之:

  • 优先提供逼真的语音。产品自带的默认语音和最便宜的模型在审核中被评价为“非常假”;对角色而言,最自然的可用模型值得投入。
  • 在上文中试听:每个角色使用两句连续的台词,每个角色提供三到六个候选。
  • 将每个选择作为封闭式问题提出,并附带推荐默认项("旁白:语音 B,温暖且从容。保留吗?")。开放的选项列表会连续数天无人回应。
  • 确定每个角色的处理方式:treatment: phone 用于通话中的人,treatment: room 用于录制的会议,旁白无需处理。
  • 每行特有的朗读方式(更平稳、更慢、风格更少)是一个角色变体,指向同一语音但使用其他设置,因此选择在配置中,并且重新运行后仍可保留。

voice.provider: say(或 --provider say)使用免费的 macOS 语音和 whisper 获取单词时间戳。在密钥就绪前,将其用于草稿、测试和时间线工作;最终交付时使用真实语音。

4. 生成片段

"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir>

对于每一行,它仅对 TTS 重拼品牌词,将未经处理的录制版本保留在 audio/raw/ 中(先前的录制版本移至 audio/raw/prev/),修剪静音,重采样为 48 kHz 单声道,应用角色处理,归一化至 voice.clip_lufs(使用 ffmpeg loudnorm,两次通过;峰值低于 -1.5 dBTP),淡入淡出,并将该片段的条目合并到 audio/timings.json 中。

每个处理步骤的存在理由:

  • 原始录制版本始终归档并作为源文件。 早期客户在完全重新渲染后从一个过时的原始文件进行了归一化;现在每个片段始终从生成它的录制版本重建。
  • 尾部在最后一个单词后最多 0.6 秒处裁剪,并带有淡出。 TTS 片段可能以点击声或另一个短语的开头结束;有一次这样的点击声以音频中“奇怪的剪切”形式发布。
  • 每个片段具有相同的响度。 一个角色语音在归一化前比旁白高出 6 dB。
  • 未更改的行将被跳过(基于 audio/raw/cache.json 中文本、语音和设置的哈希值),因此编辑一行后完整运行只会调用一次提供者。如果只更改了 clip_lufs 或处理方式,片段将免费从已归档的录制版本重建。--force 会无论如何请求新的录制版本。

密钥由脚本从环境变量或 PVS_HOME/.env 读取,且从不打印。请勿自行读取 .env 或在聊天中询问密钥:如果密钥缺失,告知用户自行将行添加到 .env,或切换到 say。

在任何新录制版本后运行 pronounce_check.py。它会在不提示 ASR 的情况下转录每个片段,标记未被识别的品牌和演员词、被听到的遗留名称以及发音偏移的元音(第 5 节)。标记意味着需要聆听,而非重新生成:ASR 可能会误听正确说出的品牌词。

5. 发音

脚本和屏幕保留真实拼写。product.pronounce 仅更改发送给 TTS 的内容,而 tts.py 会将时间戳映射回来,因此 timings.json 在 w 中保留屏幕单词,在 say 中保留重拼({"w": "Acme", "say": "AK-mee", ...})。build.py 中的锚点使用屏幕单词。

product:
  pronounce:
    Acme: AK-mee                                    # 简单重拼
    Acme Tasks: {say: AK-mee Tasks, vowel: ae, confusable: ey}   # 含首元音检查

当审核者说名称发音错误时,尝试在同一行上测试三四种重拼,使用元音检查进行测量,保留通过的那个,然后检查包含该单词的其他所有行:提供者在不同录制版本中可能不同。详情和元音表:references/casting-and-pronunciation.md。

6. 录制版本

  • 除非用户另有说明,每行最多两个录制版本;提供者配额通常由团队共享。在运行前告知用户完整运行将消耗多少字符。
  • 仅重新生成需要修改的行:tts.py <video_dir> --only N7 --force。
  • 如果新录制版本更差,使用 --only N7 --restore 将其与时间戳一起换回。
  • 对于语调调整("太嗨"、"听起来像半句话"),制作两三个变体(角色变体或语速变化),让审核者在上文中与前一行的内容进行比较。
  • 修改一行,按顺序:复制版本文件,编辑行,运行 check_script.py,运行 tts.py --only <id>,运行 pronounce_check.py --only <id>,然后合成器重新构建;该片段之后的所有内容会自动调整。

7. 音效

仅使用录制的音效,来自 HyperFrames 附带的音效库(make_sfx.py --list)。合成的打字声在审核中被评价为“像吸管声,不像键盘声”,合成嗖嗖声则像“白噪声”,因此脚本拒绝使用嗖嗖声和上升音效,除非简报要求,否则旁白下方不添加音乐。这些技能所源自的制作没有背景音乐和闪避处理,也无人怀念。

  • 打字:typing_track(text, start, cps) 使用从真实录音中剪切的单个按键声构建音轨,空格键使用更重的击键,并具有种子节奏,因此它是确定性的,同一段文本始终听起来相同。使其持续时间恰好等于显示文本的节拍长度(dur=),并让打出的单词与说出的单词对齐。
  • 点击和爆破音:在光标按下的帧上使用 library_sfx("click", start)。
  • audio/sfx/CREDITS.md 列出使用的每个音效库文件并附有音效库许可证。
  • 建议的电平:旁白 1.0,角色 1.0,点击 0.35(拖拽释放时为 0.22),打字 0.45,爆破音 0.12 到 0.3。同一音频轨道上的两个片段绝不能重叠:片段开始时间至少比前一个片段结束时间晚 0.02 秒,或将其移至另一轨道。

build.py 导入这些函数;make_sfx.py <video_dir> 配合 audio/sfx.tsv 可从命令行预构建相同的文件(格式见脚本的文档字符串)。

8. 移交给合成器

交付到 <video_dir>/audio/:lines.tsv、clips/<id>.wav、timings.json 以及带有 CREDITS.md 的 sfx/。告知合成器每个节拍应锚定到哪些单词(光标触摸的名词,打字落定的单词)以及时刻表中的等待时长。切勿手动编辑 timings.json:它会从片段重新生成,手动编辑将在下次运行时丢失。

向用户报告:已配音的行、每个片段的时长、任何发音标记及其内容、使用的语音(对任何未决定的内容提供推荐的默认选项)以及消耗的提供者字符数。

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

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

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.

相关技能