cig13zs/hf-kit

hf-kit 是做什麼的？

HyperFrames 0.8.77 的擴充層。所有內容皆基於量化研究：48 個 YouTube 影片涵蓋 16 個利基領域，相關數據收錄在 research/ 目錄中。以下路徑均以儲存庫根目錄為基準。請閱讀 SPEC.md 了解合約規範，並遵循 hyperframes-core 的組合規則。

下方的 hyperframes 意指 npx [email protected] 或本機安裝的 0.8.77 版本。Python 工具需要 Python 3.10+ 及 numpy 與 Pillow 套件，並須將 ffmpeg 加入系統 PATH。

工作流程

1. 選擇風格。 styles/README.md 將利基領域對應至風格 ID → 區塊、字幕與混音預設。風格 JSON 檔案包含測量範圍（各段落每分鐘剪輯數、鏡頭長度、每分鐘字數、LRA、靜音時長）以及主目標音量（-14 LUFS、-1 dBTP）。

2. 建立專案樣板。 python tools/scaffold.py <目錄> --format 16:9|9:16 --duration 秒數 --style <id> [--blocks a,b]。此指令會建立 index.html，內含該風格的 Token，將 hyperframes.json 鎖定至 v0.8.77 註冊表，並將區塊複製到 compositions/ 目錄。若目錄非空則拒絕覆寫。

3. 區塊。 目錄 blocks/README.md 提供完整目錄：pill-label、chapter-card、number-card（簡潔版或金錢版）、progress-badge、question-card、doc-highlight、film-gate、world-camera、ui-window、tier-board、face-banner-stack（附有 topic-top 排版，適合圓角 16：9 主題框）、zoom-through、blur-swap。每個區塊都是一個子組合，使用 data-composition-variables 定義變數，並透過 data-variable-values 傳遞數值。examples/<block>/ 目錄中提供每個區塊的運作範例。設定區塊樣式時，請使用單純的 #root 與一般後代選擇器，切勿使用複合選擇器 #root[data-composition-id=...]，因為 lint 檢查雖會通過，但實際渲染將呈現空白。

4. 字幕。 python tools/captions.py words.json --variant cards|karaoke|speaker|keyword|punch --format 9:16 --out compositions/captions.html。輸入格式為 [{text,start,end,speaker?,class?}] 或 hyperframes transcribe 產生的 JSON。

5. 音效。 sound/MIX.md 提供 10 個可直接複製使用的 hyperframes-audio 預設（例如：語音優先平面、轉折處暫停、最重台詞處靜音、片段前降低音量等），每個預設均標明其資料來源列。sound/sfx/ 目錄包含 11 個生成音效，sound/SFX.md 則說明事件與檔案及音量的對應關係。7 個情境背景音樂檔案未直接納入儲存庫：執行 python sound/gen_bed.py 可將所有音樂渲染至 sound/beds/ 目錄（音量 -20 LUFS），執行 python sound/gen_bed.py --mood <名稱> --seconds 秒數 --out bed.wav 則可產生任意長度的音樂。兩個生成器皆為確定性演算法，輸出為 CC0 授權。

6. 來自 YouTube 的背景素材或音樂。 python tools/bg_source.py <網址> [--download --out assets/ --audio]。

   • 接受（退出碼 0）：僅當 yt-dlp 回報該影片為 Creative Commons 授權時。此工具會輸出可用於影片敘述的致謝文字。影片下載需至少指定 --min-height（預設 1080）；--audio 則無高度下限。
   • 需審核（退出碼 3）：當標準授權的上傳者在其標題或敘述中聲明可重複使用時。出現「無版權」標題僅代表上傳者的單方面說詞，請確認上傳者為原始創作者，並保留授權條款的螢幕截圖。
   • 拒絕（退出碼 2）：其他情況。

   每次決策結果都會附加至 sources/provenance.jsonl 檔案（可使用 --log 參數更改檔案路徑）。請注意，Content ID 仍可能對他人作品之 Creative Commons 重新上傳提出主張，因此請優先使用原始頻道的內容。下載的檔案請保留在專案的 assets/ 目錄中，切勿上傳至公開儲存庫。

7. 渲染前檢查。 執行 hyperframes lint <目錄> 與 hyperframes check <目錄>；接著執行 hyperframes snapshot <目錄> --frames 6 並檢視生成的聯絡表。Lint 檢查通過不代表視覺效果沒問題。

8. 渲染與測量。 執行 hyperframes render <目錄> --output out.mp4，再執行 python tools/check.py out.mp4 --style <id>。此工具會分別顯示每個測量值與風格參考範圍的比對結果，以及主音量是否符合標準。這些僅為建議：若測量值超出範圍，代表剪輯偏離參考基準，您需自行判斷此偏差是否重要。

研究摘要

• 在所有 16 個利基領域中，剪輯頻率與音量並未將表現突出者與對照組明顯區分開來。真正具有區別性的是：影片中人物的利害關係、在前幾秒內即陳述利害關係、螢幕上呈現證據，以及提供完整的解答（詳細假說請見 research/TECHNIQUES.md 中的「什麼未能區分表現突出者與對照組」章節）。
• 硬剪輯的數量為最低門檻。在有旁白的情況下，節奏感並不可靠。研究中並未實際聆聽音訊：音效相關發現來自 R128 音量數值、頻譜分析與字幕標記。

檔案位置

需求	路徑
合約與規則	SPEC.md
風格及其測量範圍	styles/README.md、styles/<id>.json
區塊目錄與示範	blocks/README.md、examples/<block>/
混音預設與音效對應表	sound/MIX.md、sound/SFX.md
技巧庫與情緒對應表	research/TECHNIQUES.md
利基領域 DNA 表與抄襲清單	research/niches/<niche>.md
每個影片的卡片與資料檔案	research/cards/<niche>/<id>.md、research/data/<id>.json
知識章節（音樂與情緒、聲音設計、VFX 與動態）	research/knowledge/