Qiaomu Screen2Video

已有錄影 + 講述 → 可選對齊/降噪 → ASR → 文字清理/翻譯 → 語義動效計畫 → ASS/FFmpeg 成片。封面和配樂在轉寫完成後可並行準備。只有實際取得的資產才能計入已完成。

預設選擇

原音完整保留，不剪口頭語或停頓。錄影教學預設以 speed: 1.35 同步加速畫面、講述和字幕；使用者明確要求原速時設為 1.0。字幕刪除無意義的「呃、啊、然後」等，但保留有先後邏輯的「然後」、否定詞、數字、專名。保留原始轉寫及文字差異。
固定預設組合 signature：中文 霞鶩新晰黑 Regular 400，英文 Atkinson Hyperlegible Next SemiBold 600。中文結構清晰、略有人文感而不過度圓潤，英文強化易混淆字母與數字的區分；適合手機小螢幕雙語字幕。兩份上游字體及各自授權（中文 IPA Font License 1.0、英文 OFL-1.1）隨 skill 打包，執行時複製到快取。
中文白字黑描邊，英文黑字白描邊；中文在上、英文在下。同一字幕單元共享時間碼。1080 高度基準字號為 56/38，英文約為中文 68%；中文使用 1.2px、55% 不透明黑影，英文使用 0.8px、40% 不透明黑影，描邊與陰影都隨畫面高度同比縮放。兩行使用緊湊電影字幕間距，英文基線位於底部約 7.5% 安全區。不要把剪映「字號 7」當作 FFmpeg 7px。
預設開啟內容驅動動效：帶詞時間戳的重點詞使用向陽朱逐詞高亮；結論、數字和產品名可出現短花字；明確介面操作使用箭頭、描邊框與聚光遮罩；只有真實結構轉換才使用章節卡。所有時長按最終成片時間軸判斷，必須計入 speed：全螢幕章節卡至少 1.8 秒，依文字量通常需要 2.2–4.0 秒；短於 60 秒的成片預設最多 1 張，其他轉場改用花字或介面指引。花字、指引、章節卡同時只保留一個主視覺。配套 pop/click/whoosh/chime 均由腳本原創合成，預設輕量混入，不依賴外部音效版權素材。品牌色固定為喬木黑 #111513、向陽朱 #F05A3C、暖白 #F5F0E8。先讀剪輯方法，具體 schema 見語義動效。
原畫面比例、內容與像素尺寸優先保留。預設採用電影字幕式 overlay，不得自動增加整塊黑底。中文位於英文上方，英文靠近畫面底部 7% 安全區；確有遮擋時先調整字幕位置或斷句，只有使用者明確選擇時才使用 band。
封面預設片頭 0.7 秒；對原影片和兩種字幕同時後移。使用者只要獨立封面時設 intro_seconds: 0。
片尾固定預設 terminal 6 秒：約 3 秒完成頭像彈入、終端打字和帳號行入場，完整畫面定格約 2.15 秒，再用 0.7 秒漸隱並保留約 0.15 秒純黑尾幀。文字使用隨字號縮放的輕微半透明暗影，與深色背景柔和分離；不要做發光字。帳號區固定為 X、GitHub、公眾號「向陽喬木推薦看」和網站 qiaomu.ai，每項使用對應圖示。根據來源影片比例自動採用橫版或原生豎版重排，禁止裁切橫版片尾冒充豎版。
所有成片都測最終混音響度並寫入 output/render.json。預設統一到 -17 LUFS-I、LRA 目標 7 LU、真峰值不高於 -1.5 dBTP：偏輕會提升，偏響會降低，超出 ±1 LU 或真峰值高於 -1 dBTP 則不交付。voice_lufs 只用於特別不穩定的原始人聲，預設 null；詳見響度與聽感。
配樂預設純器樂。教學採用「明快、專注、有推進感」，預設 96–112 BPM、輕打擊樂、簡單短動機和克制低頻；不要把「歡快」做成激烈鼓點、強 drop 或搶話的主旋律。低音量、半正弦曲線淡入 0.5 秒、淡出 3 秒，講話時側鏈壓低；配樂必須覆蓋完整片尾和末尾黑場，人聲結束後側鏈自然釋放、音樂輕微回升，並與畫面共同歸零。選定講述音軌是側鏈輸入。
每一步重新整理 review.html，不等使用者開啟、點選或批准。使用者反饋影響後續或重渲染；HTML 本身不能啟動任務。

快速路徑（預設依此順序，減少返工）

init → ASR（背景）；同時 visual.py analyze（約來源時長 0.4×）：鏡頭運動、穩定視窗、OCR 螢幕詞表。ASR 會自動讀取詞表作為提示，並對異常詞時間（單字跨數秒）自動重識別校時。
轉寫一出：對照 work/visual-analysis.json.vocabulary 校正產品名/型號拼寫（Whisper 提示詞修不全，必須人工對照），寫 captions.json（合併、拆分、重定時的字幕一律新 ID + parent_ids）、motion-plan.json、brief.json。
並行：生三張封面背景（一次三呼叫）、music_synth.py 出配樂、outro_compose.py。
motion 校驗 → 一次 render → 抽幀 + 分段響度複核 → 交付。全程只渲染一次成片；使用者反饋後再重渲染。
交付前先告訴使用者成片路徑，再做 skill 改進等附加工作。

啟動與執行

技能路徑取本 SKILL.md 所在目錄。個人原始碼只放 /Users/joe/Nutstore Files/.agents/skills/qiaomu-screen2video；其他發現路徑使用軟連結。可移植安裝不依賴這個絕對路徑。

# 環境只建一次；預設字幕字體已隨 skill 打包，其他可選字體按需快取。
uv venv ~/.cache/qiaomu-screen2video/venv
uv pip install --python ~/.cache/qiaomu-screen2video/venv/bin/python 'fonttools[woff]' pillow numpy opencv-python-headless ocrmac
# 下文 $PY 指該環境 Python，$SKILL 指 skill 根目錄，$JOB 指本次輸出目錄。
"$PY" "$SKILL/scripts/fonts.py"
# 配樂真實樂器音色（推薦，一次性）：FluidSynth + GeneralUser GS（32 MB，可商用）；缺失時自動退回純程式碼合成。
brew install fluid-synth   # Linux: apt install fluidsynth
mkdir -p ~/.cache/qiaomu-screen2video/soundfonts && curl -fL -o ~/.cache/qiaomu-screen2video/soundfonts/GeneralUser-GS.sf2 \
  https://raw.githubusercontent.com/mrbumpy409/GeneralUser-GS/684543d5e5efaef08d02be50dcda8d552478fa60/GeneralUser-GS.sf2
"$PY" "$SKILL/scripts/s2v.py" init "$VIDEO" --project "$JOB"
# 如需降噪或獨立錄音對齊，先執行下節的 local_audio.py，再開始 ASR。
"$PY" "$SKILL/scripts/visual.py" analyze "$JOB"   # 螢幕詞表與鏡頭運動，供 ASR、字幕和 callout 使用
"$PY" "$SKILL/scripts/asr.py" "$JOB" --engine auto --context '本次影片的產品名與術語'

系統 FFmpeg 必須帶 libass；腳本優先檢測 macOS 的 ffmpeg-full。依賴缺失只補所需依賴，不載入 qiaomu-cut 或安裝整套影片框架。辨識前依 ASR 判斷引擎與時間精度。

可選講述音訊處理

使用者要求降噪，或提供同一次講述的外接麥克風錄音時，讀本機音訊。在 init 後、ASR 前執行；處理後的同一音軌同時用於辨識、混音和側鏈。音訊變化會使舊辨識快取/字幕/成片失效，重新執行 ASR 和文字清理翻譯。預設仍保留原音。

"$PY" "$SKILL/scripts/local_audio.py" "$JOB" --denoise
# 自動估計獨立錄音的時間偏移，並可同時降噪：
"$PY" "$SKILL/scripts/local_audio.py" "$JOB" --voice "$VOICE" --denoise
# 恢復原聲，隨後重新執行 ASR 與渲染：
"$PY" "$SKILL/scripts/local_audio.py" "$JOB" --reset

配接器僅支援已驗證的 Apple Silicon macOS 剪映 11.5.0 庫/模型雜湊，原生推理禁止連網；不啟動剪映 UI，不打包專有庫/模型。檢測失敗明確報告，不把原聲成片稱為降噪成功。尚未跑通或品質不足的鏡頭切分、人聲分離、自動卡點等不進入本流程。

Agent 的四項內容工作

讀取 $JOB/transcript.raw.json 和代表幀。輸出 $JOB/captions.json：{"segments":[{"id":"c0001","start":0.1,"end":2.3,"zh":"清理後的中文","en":"Natural English."}]}。保留 ID 與時間；有意重分段時使用新 ID、parent_ids 和原時間範圍內的時間碼，優先利用 words，不能把文字長度均分說成精確對齊。空語氣詞可以中英文同時留空。用整段語境翻譯，再對映到這些 ID；不逐詞機翻，不用 Whisper turbo 執行翻譯。
讀取完整轉寫、帶詞時間戳和代表幀，先依剪輯方法確認 hook、主體、證明和收束，再依語義動效寫 $JOB/motion-plan.json。先理解「這句話為什麼需要動效」，再選擇逐詞高亮、關鍵詞花字（label 標籤 / stroke 抖音描邊 / card 卡片，整片統一一種，審美規則見語義動效文件）、表情/梗圖貼紙、介面指引或章節卡；沒有語義功能就不加。花字和貼紙用 at_word 踩在發音上，密度與位置規則見語義動效文件。介面指引的 target 必須來自實際畫面觀察，使用 0–1 歸一化座標，不能憑字幕猜按鈕位置。章節卡時長必須換算到最終成片，並在入場、完整停留和退場三段都可讀。寫完執行 motion 驗證；警告進入 HTML，但不阻塞正常生成，章節卡最終可見不足 1.8 秒會直接阻止渲染。
從實際講述寫 $JOB/brief.json，格式見內容與資產。標題承諾必須有轉寫證據。預設同時設計三份封面：片頭按來源影片像素與比例完全匹配，平臺縮圖單獨做 16:9，豎版分發單獨做 9:16；三者重新構圖，禁止用黑邊補比例或機械裁切。使用者沒要求候選輪次時，自選一個最清晰的 YouTube/B 站方向並繼續。首選目前 Codex 內建 imagegen；不可用時呼叫已設定的第三方圖片 API/技能。生圖負責無文字背景，準確標題由 cover_compose.py 排版。不偽造工具、API、解析度或成功狀態。
配樂預設用程式碼原創作曲：scripts/music_synth.py 依 brief.json.music_profile 寫譜，有 FluidSynth + 音色庫時用真實樂器音色渲染（約 2 秒），否則純程式碼合成；登記 provider 為 code-synth（結果 json 的 engine 記錄實際渲染器）。只有使用者明確要求 YuE2/Suno 或提供自己的音樂時才走對應路線：YuE2 讀 yue2-music 純音樂工作流（Apple Silicon 用 --device auto 走 MPS，單曲約 30 分鐘以上，背景執行，先交付程式碼配樂版），Suno 讀 qiaomu-suno-master。每次只登記實際取得且可播放的音訊。不得為了音樂接入 qiaomu-cut 全套流程。

"$PY" "$SKILL/scripts/s2v.py" asset "$JOB" cover "$INTRO_COVER" --provider codex-imagegen
"$PY" "$SKILL/scripts/s2v.py" asset "$JOB" music "$BGM" --provider yue2-music
"$PY" "$SKILL/scripts/s2v.py" motion "$JOB"
"$PY" "$SKILL/scripts/outro_compose.py" "$JOB"
# 程式碼原創配樂（回退或使用者指定）；--seconds 取最終成片時長：
"$PY" "$SKILL/scripts/music_synth.py" "$JOB/work/code-music/bed.wav" --seconds "$FINAL_SECONDS" --profile calm_explainer
"$PY" "$SKILL/scripts/s2v.py" asset "$JOB" music "$JOB/work/code-music/bed.wav" --provider code-synth
# 需要兩種平臺通用片尾資產時：
"$PY" "$SKILL/scripts/outro_compose.py" "$JOB" --variants
"$PY" "$SKILL/scripts/s2v.py" render "$JOB"

可選資產失敗不阻塞已授權的其他工作。匯出前已有資產直接使用；要等待的只有真正依賴的轉寫/翻譯。若使用者明確要求所有資產，先輸出的版本標為「字幕預覽版」，資產成功後再重渲染。

HTML 和修改

review.html 是本機檢視/決策頁面；開啟後可播放成片、看逐句字幕和語義動效時間線、檢查封面和配樂。可切換全部動效、逐詞高亮和輕量音效並調整音效增益。初始頁面的 CSS 字幕是示意，真實字體、描邊、換行、目標位置與動效由 ASS 渲染抽幀驗證。

"$PY" "$SKILL/scripts/s2v.py" report "$JOB"
"$PY" "$SKILL/scripts/s2v.py" apply "$JOB" /path/to/decisions.json
"$PY" "$SKILL/scripts/s2v.py" render "$JOB"

下載設定不會改變背景任務。Agent 明確應用後才生效；輸入、設定、字幕或素材改變會使舊成片標為過期。預設不建立伺服器、守護行程或等待確認環節。

交付與驗證

指令碼檢查字幕配對、時間範圍/重疊、字體覆蓋、換行、時長、畫面尺寸、音軌和完整解碼。失敗保留日誌；重試不覆蓋原影片。
看實際抽幀（片頭、最長字幕、每類動效至少一個、正片前中後）並按最終 1× 播放速度看完整成片，不能只檢查原素材時間碼。逐詞高亮必須與發音同步；指示框必須指向真實控制項；章節卡至少檢查入場中點、完整停留和退出前一幀，確認文字來得及讀且沒有遮住正在發生的關鍵操作。再聽一段講話+音樂+輕音效。output/render.json 的 visual_review/audio_review 只有實際複核後才改為 passed，數值檢測不能冒充人工聽看。
交付 output/final.mp4、zh.srt、en.srt、bilingual.srt、subtitles.ass、motion-plan.json、output/motion-qa.json、封面、review.html。報告 ASR 引擎和時間精度，列出未取得的可選資產。
不上傳/發布成片到影音平臺；這需要使用者另外要求。

剪輯判斷與節奏：剪輯方法。樣式依據與取捨：字幕方法。動效時機、schema 與安全區：語義動效。片尾規則：片尾與關注引導。音訊驗收：響度與聽感。ASR 配置：ASR。封面/配樂：內容與資產。

qiaomu-screen2video：錄屏 → 中英雙語示範成片