HyperFrames 媒體前置處理
三個 CLI 指令,可為組合產生資產:tts(語音)、transcribe(時間戳記)和 remove-background(透明影片)。每個指令在首次執行時會下載模型,並快取在 ~/.cache/hyperframes/ 目錄下。將輸出放入專案中,然後從組合 HTML 中引用它——請參閱 hyperframes 技能以了解音訊/影片元素的慣例。
文字轉語音 (tts)
使用 Kokoro-82M 在本地生成語音音訊。無需 API 金鑰。
npx hyperframes tts "Text here" --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 <code>(無.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(編輯用)
npx 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/ 目錄。
不要對具有白色外框的鏤空貼紙使用 u2net
remove-background (u2net) 是顯著物件分割——它分割主體身體並切掉白色鏤空外框,因為圖形周圍的白色筆畫不是「物件」。對於在平坦已知顏色背景上以白色外框渲染的透明 Telegram / 訊息貼紙,請對背景進行去背,而不是分割主體:
- 對平坦背景進行洪水填充。 從所有四個邊緣的點(步長約 24px)開始用 PIL
ImageDraw.floodfill進行填充,將填充的像素標記為 alpha 0,其他所有內容不透明。這會保留白色外框、內部相同顏色的道具以及分離的孤立部分(與身體分離的飛杯會保留自己的外框)。需要生成提示將主體放在平坦均勻的背景上,並明確要求白色鏤空外框。 - 無外框變體(比去除烘焙外框更乾淨): 對每張影像重新執行圖生圖——將完成的渲染作為
--ref傳遞,並提示「重新建立相同的姿勢/道具,但移除白色外框,並將其放在平坦的純色去背綠 (#00b140) 上」,然後使用軟去背,絕不使用二進位遮罩對綠色進行去背(alpha = clip((HIGH-(G-max(R,B)))/(HIGH-LOW),0,1),LOW≈30 HIGH≈95,加上全域去溢色G = min(G, max(R,B)))。二進位洪水填充 + 腐蝕會產生階梯狀 / 鋸齒狀邊緣——對二進位 alpha 進行模糊處理(GaussianBlur(0.8))以獲得平滑邊緣,而不是進行腐蝕。 - 訊息貼紙的尺寸調整: 裁剪到實心 alpha 邊界框,並將長邊縮放到完全等於目標(例如 512)——不要填充到 512² 正方形(這會使主體變小,周圍有空曠空間)。
不適用於:用於影片疊層的人物裁切(u2net 在那裡是正確的);沒有鏤空外框的藝術作品;處於非均勻 / 繁忙背景上的主體(洪水填充需要平坦的去背顏色)。
圖層分離 (--background-output)
傳遞 --background-output(或 -b)以在裁切影片之外再輸出一個透明影片:相同的來源 RGB,alpha 是 255 − 遮罩 而不是 遮罩。裁切影片是主體,帶有透明背景;背景圖層是原始環境,在主體所在位置有一個透明空洞。
| 檔案 | Alpha 是… | 用途 |
|---|---|---|
-o subject.webm | 遮罩——主體不透明,背景透明 | 前景圖層,放置在最上方 |
--background-output plate.webm | 反向——周圍環境不透明,主體區域透明 | 底層圖層;將文字或圖形放在此圖層與主體之間 |
兩個輸出共享相同的 --quality 預設值,並從單次推理處理中運行——編碼成本大約翻倍,分割成本保持不變。僅對影片輸入和 .webm/.mov 輸出有效。
裁切洞的背景圖層,不是修復後的乾淨背景圖層。 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 可以像任何其他靜音自動播放影片一樣插入組合——請參閱 hyperframes 技能以了解 <video> 軌道慣例。
品質預設
--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)下,你會看到輕微的顏色偏移 / 邊緣光暈。 |