HyperFrames 媒體預處理
三個 CLI 指令,用於為組合產生資產:tts(語音)、transcribe(時間戳記)和 remove-background(透明影片)。每個指令在首次運行時下載模型並快取於 ~/.cache/hyperframes/ 下。將輸出放入專案中,然後從組合 HTML 中引用它 — 有關音訊/視訊元素的慣例,請參閱 hyperframes 技能。
文字轉語音 (tts)
使用 Kokoro-82M 在本機生成語音音訊。無需 API 金鑰。
npx hyperframes tts "這裡的文字" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list # 所有 54 種語音
語音選擇
讓語音與內容匹配。預設為 af_heart。
| 內容類型 | 語音 | 原因 |
|---|---|---|
| 產品展示 | af_heart/af_nova | 溫暖、專業 |
| 教學 / 操作指南 | am_adam/bf_emma | 中立、易於理解 |
| 行銷 / 宣傳 | af_sky/am_michael | 充滿活力或權威性 |
| 文件 | bf_emma/bm_george | 清晰的英式英語、正式 |
| 休閒 / 社交 | af_heart/af_sky | 平易近人、自然 |
多語言
語音 ID 以第一個字母編碼語言:a=美式英語,b=英式英語,e=西班牙語,f=法語,h=印地語,i=義大利語,j=日語,p=巴西葡萄牙語,z=中文。CLI 會自動從前綴偵測音素轉換器的語言環境 — 當語音與文字匹配時,不需要 --lang 參數。
npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav
僅在需要覆蓋自動偵測時使用 --lang(例如風格化口音)。有效代碼:en-us、en-gb、es、fr-fr、hi、it、pt-br、ja、zh。非英語的音素轉換需要在系統範圍內安裝 espeak-ng(brew install espeak-ng / apt-get install espeak-ng)。
速度
0.7-0.8— 教學、複雜內容、無障礙1.0— 自然速度(預設)1.1-1.2— 引言、過場、節奏明快的內容1.5+— 很少適用;請仔細測試
長腳本
對於超過幾個段落的情況,請寫入一個 .txt 檔案並傳遞路徑。輸入超過約 5 分鐘的語音可能需要分割成片段。
需求
Python 3.8+ 及 kokoro-onnx 和 soundfile(pip install kokoro-onnx soundfile)。模型在首次使用時下載(約 311 MB + 約 27 MB 語音,快取於 ~/.cache/hyperframes/tts/)。
轉錄 (transcribe)
產生一個包含逐字時間戳記的標準化 transcript.json 檔案。
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt # 匯入現有字幕
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
語言規則(不可協商)
除非使用者明確指出音訊是英語,否則絕不使用 .en 模型。 .en 模型(small.en、medium.en)會翻譯非英語音訊為英語,而不是進行轉錄。這會默默地破壞原始語言。
- 語言已知且非英語 →
--model small --language <代碼>(無.en後綴) - 語言已知且是英語 →
--model small.en - 語言未知 →
--model small(無.en、無--language)— whisper 會自動偵測
預設模型是 small,不是 small.en。
模型大小
| 模型 | 大小 | 速度 | 何時使用 |
|---|---|---|---|
tiny | 75 MB | 最快 | 快速預覽、測試流程 |
base | 142 MB | 快 | 短片、清晰音訊 |
small | 466 MB | 中等 | 預設 — 大多數內容 |
medium | 1.5 GB | 慢 | 重要內容、有雜訊的音訊、音樂 |
large-v3 | 3.1 GB | 最慢 | 專業品質 |
有歌聲的音樂:至少從 medium 開始;生成的曲目通常需要手動匯入 SRT/VTT。有關字幕品質檢查(每次轉錄後必須執行)、清理 JS、重試規則以及 OpenAI/Groq API 匯入路徑,請參閱 hyperframes/references/transcript-guide.md。
輸出格式
組合使用一組平面的單詞物件陣列。id 欄位(w0、w1、...)在標準化過程中添加,以便在字幕覆蓋中提供穩定的參考;為了向後相容,它是可選的。
[
{ "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
{ "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }
]
背景移除 (remove-background)
從影片或圖片中移除背景,使主體(通常是人物 — 頭像、簡報者、談話頭像)在組合中作為透明疊加層放置。
npx hyperframes remove-background subject.mp4 -o transparent.webm # 預設:VP9 alpha WebM
npx hyperframes remove-background subject.mp4 -o transparent.mov # ProRes 4444(編輯用)
px hyperframes remove-background portrait.jpg -o cutout.png # 單張圖片去背
npx hyperframes remove-background subject.mp4 -o subject.webm \
--background-output plate.webm # 一次處理兩個圖層
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info # 偵測到的提供者
使用 u2net_human_seg(MIT 授權)。首次執行會下載約 168 MB 的權重到 ~/.cache/hyperframes/background-removal/models/。
圖層分離 (--background-output)
傳遞 --background-output(或 -b)以在去背影片之外額外產生一個第二個透明影片:相同的來源 RGB,Alpha 是 255 − mask 而不是 mask。去背影片是主體加上透明背景;底板(plate)是原始背景,但主體所在位置是透明的洞。
| 檔案 | Alpha 內容是… | 用途 |
|---|---|---|
-o subject.webm | 遮罩 — 主體不透明,背景透明 | 前景圖層,放置於頂層 |
--background-output plate.webm | 反相 — 背景不透明,主體區域透明 | 底層圖層;將文字或圖形放置在此層與主體之間 |
兩個輸出共享相同的 --quality 預設,並從單一推理過程運行 — 編碼成本大致翻倍,分割成本保持不變。僅對影片輸入和 .webm/.mov 輸出有效。
這是挖洞底板(hole-cut plate),不是修補過的乾淨底板(inpainted clean plate)。 plate.webm 中的主體區域是完全透明的 — 在其下方合成不透明內容來填充這個洞。判斷 --background-output 是否是正確工具的唯一測試是:在主體原本所在的位置,是否會有任何東西透過主體的輪廓可見?
| 使用案例 | 正確工具 |
|---|---|
| 文字/圖形放在去背主體與底板之間(此指令存在的原因) | 挖洞底板 (--background-output) |
| 主體放在一個無關的場景之上 | 只需 subject.webm;忽略底板 |
| 顯示_沒有_人物的房間,單獨顯示,上方無其他內容 | 乾淨底板 — 需要修補工具(LaMa、ProPainter、E2FGVI)。不是此指令的職責。 |
| 用不同的主體替換目前主體 | 乾淨底板 — 同上 |
如果使用者問「移除人物後的房間」並打算單獨顯示它,不要使用 --background-output。告訴他們需要一個修補工具。
典型的圖層組合(標準的挖洞底板使用案例):
<!-- z=1 反相 Alpha 底板填滿除主體區域外的所有空間 -->
<video
src="plate.webm"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<!-- z=2 圖形/文字位於兩個圖層之間 -->
<h1 id="headline" style="z-index:2; ...">用 HYPERFRAMES 製作</h1>
<!-- z=3 去背主體將主體浮在標題之上 -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
<video
src="subject.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
這在功能上等同於下面的文字在主體後方模式,但你的專案中不需要原始的 presenter.mp4 — 底板取代了它。當你想要只發布兩個透明圖層並讓使用者在它們之間放置任意內容時很有用。
輸出格式
| 格式 | 何時使用 |
|---|---|
.webm(VP9 + alpha) | 預設。組合直接透過 <video> 播放。 |
.mov(ProRes 4444) | 在 DaVinci/Premiere/FCP 中編輯。檔案較大。 |
.png | 單張圖片去背(靜態主體,分層放置在背景之上)。 |
Chrome 原生解碼 VP9 Alpha,因此 .webm 可以像其他靜音自動播放影片一樣插入組合 — 有關 <video> 音軌慣例,請參閱 hyperframes 技能。
品質預設
--quality fast|balanced|best 僅控制 VP9 編碼器的 CRF — 分割品質是固定的。
| 預設 | CRF | 何時使用 |
|---|---|---|
fast | 30 | 疊代過程、較小檔案、顏色匹配較寬鬆 |
balanced | 18 | 預設。對大多數使用情況,視覺上無差異 |
best | 12 | 母版/最終交付。檔案最大,匹配最精確 |
合成模式 — 選擇正確的模式
去背 WebM 是來源 MP4 RGB 的重新編碼副本。這個選擇會根據你放在它後面的內容而產生不同的後果:
| 模式 | 去背主體後方是什麼 | 結果 |
|---|---|---|
| 去背主體放在不同場景之上(最常見) | 靜態圖片、漸層或無關的影片 | 看起來很棒。去背主體的 RGB 是主體的唯來源 — 沒有重疊,沒有邊緣光暈。這就是 remove-background 的設計目的。 |
| 去背主體放在其自身來源 MP4 之上(文字在主體後方) | 與生成去背主體相同的 MP4 | 同一個人的兩個 RGB 來源。在預設 --quality balanced(crf 18)下,重疊幾乎不可見;在 --quality fast(crf 30)下,你會看到輕微的顏色偏移/邊緣光暈。使用 --quality best(crf 12)以獲得母版品質。 |
| 去背主體放在同一主體的_不同_分鏡之上 | 同一主體的不同素材 | 看起來像兩個不同的人重疊在一起。不要這樣做。 |
文字在主體後方(標題放在簡報者背後):
<video
src="presenter.mp4"
id="bg"
data-start="0"
data-duration="6"
data-track-index="0"
muted
playsinline
></video>
<h1 id="headline" style="z-index:2; ...">用 HYPERFRAMES 製作</h1>
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
<video
src="presenter.webm"
data-start="0"
data-duration="6"
data-track-index="1"
muted
playsinline
></video>
</div>
兩個關鍵規則:
- 將去背影片包裝在一個無時間控制的
<div>中,並動畫包裝器的不透明度,而不是影片元素本身。框架會強制使作用中的剪輯(任何帶有data-start/data-duration屬性的元素)的不透明度為 1,因此直接動畫影片的不透明度會靜默地被覆蓋。包裝器沒有data-*屬性,因此由你的 CSS/GSAP 控制。 - 兩個影片都使用
data-start="0"和data-media-start="0",以便框架從 t=0 開始同步解碼它們。延遲掛載去背主體(data-start=3.3)會引入一次尋道 + 預熱,導致其畫面與基礎 MP4 相差一幀 — 在剪輯點處可見一幀的錯位。
然後在剪輯點使用 GSAP 翻轉包裝器的不透明度:tl.set(cutoutWrap, { opacity: 1 }, 3.3)。
TTS → 轉錄 → 字幕
當沒有預先錄製的旁白時,生成一個然後將其轉錄回來,以獲得用於字幕的逐字時間戳記:
npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav # → transcript.json
產生的 transcript.json 與來自任何其他來源的轉錄檔案格式相同,因此將它放入專案中並像平常一樣連接到字幕軌道。tts 後直接跟著 transcribe 是最常見的管道,但對於需要自訂時間、音高或語音清潔的專案,將生成作為第一步,然後在 WAV 檔案上進行後期處理,最後再進行轉錄。