Communitygithub.com

josueh04/product-video-skills

編排一個帶旁白的產品示範影片,使用 HyperFrames:舞台(重現產品真實視口並縮放至 1080p)、攝影機、利用面紗進行焦點偏移、章節標題、游標與點擊、打字、串流文字、彈出視窗、提示訊息、滾動、結束畫面與鎖定畫面)以及 build.py,將每個節拍錨定在旁白的每個字詞上。

product-video-skills 是什麼?

此技能用於在 HyperFrames 工作台中創建產品示範影片。它將產品 UI 在其真實視口重建並縮放至 1080p,支援鏡頭移動、對焦模糊、章節標題、游標點擊、打字動畫、串流文字、彈出視窗、提示訊息、滾動以及結束畫面。核心檔案是 `video/build.py`,其中定義了一個節拍表(beat table)`T`,每個節拍都精準錨定到旁白的特定字詞。技能提供了 `kit/stage.js` 和 `kit/stage.css` 等輔助工具,用於安全地處理時間軸和舞台圖層。工作流程包括閱讀簡報與規格、在 `src/template.tpl` 和 `src/app.css` 中重建畫面、編寫節拍、使用 `--draft` 和 `--fake-timings` 建立草稿、透過快照 lint 和檢查每個設定節拍,最後渲染 MP4。此技能支援 Claude Code、Cursor 和其他相容的 AI 編碼代理。其設計哲學強調單一事實來源的時間控制(所有節拍錨定在旁白字詞上)、透過測量而非試誤來定位 UI 元素、以及透過「簽署門檻」(signature gate)強制在編寫程式碼之前先就內容達成共識。此技能能有效避免因衝太快或縮放過度而導致的常見剪輯錯誤。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/ui-demo-composer

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

UI 示範編輯器

產品影片在這裡是一個 HyperFrames 組合,由每個影片你編寫的三個檔案和每個影片共享的工具包組成:

檔案用途編輯者
video/build.py節拍表 T:所有時間點皆源自字詞時間你
video/src/template.tpl重建的 UI、螢幕圖層和 GSAP 時間軸你
video/src/app.css產品 UI CSS,來自 specs/ 的字面值你
kit/stage.css、kit/titles.css、kit/stage.js舞台圖層和防跳動輔助工具此技能
products/<slug>/kit/tokens.css、fonts/、icons/、ui/產品的 tokens、字型、圖示和共享 UI 片段product-kit
video/index.html由 build.py 產生。切勿手動編輯。無人

scripts/buildlib.py 處理每個建置的通用部分(時間點、簽署門檻、音訊標籤、內嵌、佔位符、圖示、攝影機限制),讓 build.py 保持為簡短的節拍列表。

舞台模型

#root > #stage > #camera > #blurWrap > #app      產品,以應用程式像素為單位
               > #veil, .pvs-ttl, #endS, #lock, #fade      螢幕空間,1920x1080
  • UI 在其真實視口重建並縮放一次。 #app 是 product.yaml app_canvas.logical CSS 像素(例如 1440x810),透過一個 transform 縮放至 1920x1080。生產 CSS 保留其字面像素,因此規格值可直接貼入,且每個測量值都能與程式碼進行 1:1 比較。選擇一個高於應用程式斷點、長寬比為 16:9 的桌面寬度;如果有螢幕錄影,則使用其邏輯尺寸。非 16:9 的畫布會加上黑邊(buildlib 會發出警告)。
  • 位置是測量出來的,不是手動輸入的。 S.box(sel) 在字型載入後將偏移量加總至 #app。如果 CSS 更改,游標仍會落在按鈕上。
  • 游標和點擊漣漪是 #app 的最後一個子元素,因此它們會隨產品一起縮放和模糊。彈出視窗(.pvs-modal)和提示訊息(.pvs-toast-slot)也位於 #app 中。
  • 只有 #camera 移動,只有 #blurWrap 模糊。 切勿對 #app 或 #stage 進行補間動畫。

取景:預設為 1 倍全頁

預設每個產品節拍為 1 倍、全頁,彈出視窗以自然大小顯示並置中,如同應用程式顯示它們的方式。推近是溫和的(最高 video.max_zoom,預設為 1.35),保持整個區域在畫面內,切勿讓畫面邊緣穿過標籤。每個章節一個取景:在產品失焦時,在章節標題後方進行移動,或作為一個緩慢的簽名式移動。

原因:在這些技能所源自的生產過程中,一個設定影片因縮放而被拒絕了兩次。1.67 倍的推近裁剪了標籤的一半(「我看不出發生了什麼事」),之後每欄約 2 倍的取景即使沒有裁剪也感到擁擠。審查者視為模型的影片全程以 1 倍執行。一個較遠的畫布(顯示為 50%)或一個狹窄的聊天欄可以容忍更多:為該產品在 product.yaml 中提高 max_zoom,而不是為每個節拍。b.cam() 和 S.cam() 會將值限制在 max_zoom 以上並發出警告。詳細資訊和數字:references/framing-and-pacing.md。

節奏:章節是暫停

  • 從背景開始,切勿從 UI 中間開始:標誌、產品名稱和一行關於它是什麼的文字,位於失焦的產品上方。
  • 每個章節以一個雙色標題開頭,位於產品模糊失焦(模糊加面紗)之上,至少保持約 1.4 秒,並且正好在命名第一個動作的字詞之前恢復對焦。畫面變化發生在標題後方,因此沒有硬切。
  • 每個章節一個想法,一次一個變化,間隔 0.6 到 1 秒,每個章節結束時暫留約 0.8 秒。產品的實際等待時間壓縮為 1 或 2 秒。
  • 結束畫面顯示廣度(產品還能做什麼,使用真實的 UI 片段),然後是鎖定畫面。

原因:一個密集的一鏡到底剪輯,每 0.5 秒有一個微動作,對製作者來說是精緻,對審查者來說是雜訊(「太快、一次太多、令人難以承受」);在結果中放大和縮小使它們無法跟上。平靜的章節化版本獲得批准。

每個節拍都錨定在一個字詞上

b = buildlib.Build(__file__)
T, w, end = b.T, b.w, b.end
T["N2"] = T["ch1"] + 0.3                                  # 放置剪輯 ID 會放置該剪輯
T["rack1"] = T["N2"] + w("N2", "after") - 0.25            # 對焦正好在 "after" 之前恢復
T["send1"] = max(T["type1"] + T["type1Dur"] + 0.4, end("N3") + 0.15)
  • w(clip, prefix, nth=1) 是第一個以 prefix 開頭的字詞的開始時間(相對於該剪輯)。當找不到該字詞時會引發錯誤(沒有靜默回退:一個會將節拍靜默地落在預設時間的回退,正是動作不知不覺偏離旁白的原因)。
  • UI 事件比命名它的字詞早 0.05 到 0.45 秒發生。max() 同時保留了旁白順序和「UI 已完成」;end(k) 是 T[k] 加上剪輯持續時間(或 b.dur(k, d))。
  • 打字速度以每秒字元數為單位(約 17 到 21),或固定以符合一個節拍。
  • 點擊、打字和彈出視窗的聲音發生在同一個 T 上(b.click(t)、b.typing(text, t, dur)、b.pop(t)),因此重新調整時間的節拍也會移動其聲音。
  • 重新產生一行語音會重新計時整個影片。這就是重點。

原因:時間控制有單一事實來源。當一行臺詞重新產生時,所有錨定在它上面的東西都會一起移動;手動輸入的秒數在第一次重拍時就會過時。

工作流程

  1. 閱讀 BRIEF.md(章節、取景)、COVERAGE.md(每個章節必須在螢幕上解釋什麼)、specs/*.md 和 TRUTH.md。不要發明 UI:一個沒有 SOURCES.md 或 specs/ 中來源的螢幕或行為,就應排除在外。
  2. 根據規格在 src/template.tpl 和 src/app.css 中重建螢幕,使用來自 product.yaml cast 的虛構資料。使用 {{UI:name}} 重用 kit/ui/ 中的產品片段,而不是從另一個影片複製(references/ui-component-library.md)。
  3. 使用工具輔助工具在 build.py 中編寫節拍,並在範本中編寫時間軸(API 請參閱 references/stage-kit.md,每個節拍的詳細資訊請參閱 references/beat-recipes.md,請參閱 references/end-screen-and-lockup.md)。遵循每個補間動畫的防跳動運動技能。
  4. 建立草稿並讀取它列印的節拍表:
    PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
    "$PVS_HOME/bin/pvs-py" <video_dir>/video/build.py --draft
    
    在任何語音存在之前,--draft --fake-timings 會從 lines.tsv 發明字詞時間,以便你可以佈局螢幕。
  5. Lint 和檢查,從 <video_dir>/video/:
    "$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" .
    npx --yes [email protected] check
    
    預期 0 個錯誤和 0 個執行時期警告。對於單一架構舞台,預計會有一個 lint 警告:composition_file_too_large(工具包已內嵌)。然後執行建置列印的第二個 check,check --at <設定節拍時間>:預設樣本通常只落在失焦的時刻,工具包在那裡對比度傳遞隱藏了產品文字(因為它故意模糊),因此那裡的 contrast ... checked 0 並未稽核讀者看到的任何內容。僅 check 是不夠的:它在一個移動項目在其路徑的大部分時間都不可見的影片上通過了。查看畫格。
  6. 快照每個設定節拍並親自查看每個圖片。在 build.py 中使用 b.snap(t, label) 標記它們;建置會列印確切的命令:
    npx --yes [email protected] snapshot . --at 3.2,4.7,9.98 --no-end --describe false -o snapshots/setup
    
    --no-end 僅捕獲那些時間點;--describe false 防止畫格被發送到外部視覺 API。檢查取景(沒有在邊緣裁剪任何東西)、游標在其目標上、彈出視窗以自然大小居中、標題完整。--zoom "#toast" --zoom-scale 2 會裁剪一個元素。要測試可疑的補間動畫,--at <start>,<later> 必須與 --at <later> 匹配。
  7. 渲染。一個用於審查的草稿,然後在 BRIEF.md 簽署後進行交付(build.py 會列印此行):
    npx --yes [email protected] render . -o renders/<video>-v<k>.mp4 --fps 30 --quality draft
    npx --yes [email protected] render . -o renders/<video>-v<k>.mp4 --fps 30 --quality delivery
    
    然後在 MP4 上執行 render-qa。保留每個版本的 MP4。

簽署門檻

build.py 拒絕建置,直到 coverage_signed_by 和 claims_signed_by 在 BRIEF.md 中設定(退出碼 2)。--draft 無論如何都會建置,並將 <meta name="pvs-draft" content="1"> 蓋入 index.html;QA 將其報告標記為草稿,而交付則拒絕它。不要代表審查者簽署,也不要移除 meta:草稿是為了查看,絕不能用於發布。

原因:在這些技能所源自的生產過程中,26 個版本中有 9 個是因為影片沒有解釋審查者在意的功能,而且沒有人在建置之前寫下這些功能。門檻確保協議優先。

來自事件的規則

  • 修復生產瑕疵,保留外觀。 保持佈局、tokens 和行為 1:1,但修復即時應用程式的可見缺陷(缺少的內邊距、溢出或裁剪的文字、灰色原生控制項、點擊後留下的焦點環)。在 BRIEF.md 筆記中列出每個修復。
  • 當產品可設定時,顯示可設定的內容。 買家會問到的設定應顯示在螢幕上,而不僅在旁白中。
  • 在開啟覆蓋於選單上方的模態視窗前一畫格,關閉該選單。 一個新對話框下開啟的下拉選單在一個渲染中留下了幽靈文字。
  • 僅將結束畫面內容淡入鎖定畫面,在鎖定畫面出現之前保留其背景。兩者都淡出會在它們之間顯示一個尖銳 UI 的畫格(S.lockup 會執行此操作)。
  • 在點擊之前懸停(在點擊前約 0.12 秒使用 hov 類別),游標在第一次失焦之後進入,並在結束畫面之前移出。
  • UI、資料或旁白中不得有供應商或禁止的名稱(product.yaml banned_terms、names)。如果真實螢幕顯示了一個,請將該片段保持在畫面外,並且切勿讓它明顯地空白。
  • 不要為了及早顯示進度而渲染。 使用快照進行迭代;當設定節拍看起來正確時再進行渲染。

檔案

路徑何時閱讀
references/stage-kit.md當你需要輔助工具的簽名、佔位符、CSS 變數或 buildlib API 時
references/beat-recipes.md當你建立特定節拍時:開場、章節、點擊、打字、串流、彈出視窗、下拉選單、提示訊息、滾動、推近
references/framing-and-pacing.md當你選擇取景或節奏,或審查者說「縮放」、「太快」、「混亂」時
references/end-screen-and-lockup.md當你建立結尾時
references/ui-component-library.md當一個 UI 片段會出現在多個影片中,或你正要從另一個影片複製標記時
scripts/buildlib.py當你需要 API 參考未涵蓋的行為時
kit/stage.js相同,用於時間軸輔助工具
PVS_HOME/_template/video/video/每個新影片開始時的範例 build.py、template.tpl 和 app.css

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

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

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.

相關技能