nestedbit/faceless-shorts

Faceless Shorts

您可以從一個主題產出完整的垂直式短影音：包含腳本、語音、與字詞同步的字幕、動畫鏡頭、音效和音樂，最終渲染成 MP4。所有環節皆以程式碼完成：畫布繪圖、無頭 Chrome 捕捉、ffmpeg、本地 Kokoro 語音、本地 Whisper 字詞計時、numpy 音效。不採用 AI 圖片或影片、不需 API 金鑰、也不消耗額外點數。 SKILL 代表此檔案所在的資料夾。專案則存放在 ~/faceless-shorts/<short-name>/ 中。

一種風格：吉祥物解說員 (mascot-explainer)。將您化身為一個扁平卡通吉祥物（由一張照片以程式碼繪製、綁定骨架、並會對嘴同步），呈現「N 個快速步驟」：一次一張卡片、撞入角落徽章的數字方塊、即時檢查清單、逐字標題字幕、以及每個擊中動作時的鏡頭震動與音效。長度約 30-45 秒 · 比例 9:16。最適合教學、提示、「N 種方法…」、科技/理財/生產力類的解說，且創作者本身就是品牌。

該風格由 styles/mascot-explainer/style-sheet.png（透過專屬程式碼繪製的風格參考圖）加上 STYLE.md（規則與引擎手冊）以及 example/（一個可直接渲染的完整專案）所定義。在規劃之前，請完整閱讀 STYLE.md。

0. 首次在電腦上使用

執行 bash SKILL/scripts/setup.sh 直到它顯示 All set（檢查 Node 22+、ffmpeg、Chrome；建立 ~/.faceless-shorts/venv；下載 Kokoro 語音模型約 340 MB 與 Whisper small.en 約 0.5 GB）。以官方免費方式安裝任何缺少的項目，並在需要密碼時先詢問。接著執行 bash SKILL/scripts/selftest.sh，必須顯示 SELFTEST PASSED：開啟聯絡表，檢視其剪輯名稱與畫面。

1. 輸入（一次訊息，預設值已填好）

僅一次詢問所有未知的項目：主題（或「你選 3 個點子」）、用戶喜歡的短影音格式連結（選填）、長度（預設約 30 秒）、語音（SKILL/scripts/py SKILL/scripts/voice.py --list；預設為 am_michael）、旁白模式：AI 語音（預設）· 用戶自己的錄音（用戶在查看腳本後自行錄製；words.py --audio）· 僅字幕（暫無語音；estimate.py）、音樂（內建背景音樂·無音樂·用戶自有的免版稅檔案）、結尾文字/帳號，以及一張清晰的正面照片（選填）與服裝，或儲存在 ~/faceless-shorts/_mascots/ 中的吉祥物名稱。輸入「Just go」則使用所有預設值。

2. 計畫（一次顯示，然後等待）

顯示：標題 · 完整旁白，每行一個剪輯，附帶其字幕片段（例如「1. 查看 | 真實的 *寄件人地址」）· 鏡頭清單，每行一個（畫面顯示什麼、什麼在移動、落在哪個字上）· 您將新增到工具包中的新元件（若有）· 事實及其來源。務必詢問 「開始建置？」 並等待。

腳本規則。 請以人們實際對朋友說話的方式書寫：完整的、流暢的句子，帶有連接詞（「嗯」、「其中」、「但是」、「所以」、「這表示」），而不是一串簡短標題式的陳述。約 90-110 個字可對應 35 秒。一行就是一個剪輯，而非一個句子：將每個句子在自然停頓處（逗號、「和」、「其中」）分成 1-3 行，使畫面每 1.5-3.5 秒改變一次，同時語音流暢進行（voice.py 會一次唸完整個句子）。結構：一個帶有真實數字來源的鉤子、一句承諾、3-6 個以「第一，……」開頭的步驟、一個明確的結尾行動。以口語方式書寫數字（例如「七」）。在腦中朗讀一遍：如果聽起來像字幕，就重新改寫。僅限原創：您可以參考喜歡的格式，但絕不能抄襲其他創作者的腳本或鏡頭。每個事實都必須依據可靠來源進行查核（在 script.json 的「sources」中列出）。

3. 建置

1. 執行 bash SKILL/scripts/new_video.sh mascot-explainer <short-name>，將範例複製到 ~/faceless-shorts/<short-name>/。
2. 撰寫 script.json（包含台詞、字幕片段與間隔；詳見 STYLE.md）。首先製作吉祥物（mascot.json，STYLE.md §2），渲染其姿勢表，並在撰寫任何鏡頭前獲得用戶同意。
3. 計時：執行 SKILL/scripts/py SKILL/scripts/voice.py <proj>，然後執行 SKILL/scripts/py SKILL/scripts/words.py <proj>（用戶自行錄音：執行 words.py <proj> --audio their.m4a；僅字幕模式：執行 estimate.py <proj>）。
4. 改寫 src/shots.js：每行一個鏡頭（較長行則每行兩個鏡頭），每個鏡頭使用 cut(i) 定位，並使用 Wd('word', line) 設定其於特定字詞上的關鍵時刻。重複使用工具包（src/core/kit.js）；如有需要，在該風格外觀下於工具包中新增元件。
5. 在專案中：依序執行 node tools/capture.mjs check（必須顯示 CHECK OK）→ node tools/capture.mjs cues → SKILL/scripts/py tools/mix.py . → 品質檢查（第 4 節）→ node tools/capture.mjs video renders/<name>.mp4。若要迭代修改單一鏡頭：執行 node tools/capture.mjs frames review/f "4.2,4.6" 並檢視。

4. 品質檢查：絕不展示未經檢視的影格

執行 node tools/capture.mjs sheet review/all.jpg 0.5 10（每 0.5 秒一個影格，並帶有時間戳記），完整閱讀整個聯絡表，然後以全尺寸檢視關鍵影格。針對每個影格務必檢查：

• 畫面是否合理？ 一次只顯示一張卡片；吉祥物的姿勢符合台詞；道具隨手持物移動。任何物件都不應在觸發原因之前出現。
• 是否與當下的旁白匹配？ 畫面應在台詞開始前改變；揭示動作應落在對應的字詞上。
• 是否有任何元素互相碰撞？ 手臂、印章和爆發效果絕不能意外地重疊到標題、卡片、徽章、檢查清單或彼此。
• 字幕： 每個字幕 1-4 個單字，最多一個紫色強調字，拼寫正確，且切勿在該字被說出前顯示。
• 風格表： 僅使用指定色板、扁平形狀、硬墨水陰影，紅色僅用於危險提示。
• 音效： 語音應清晰可聞於音樂之上；效果音需柔和（避免刺耳的滴答聲或嗶嗶聲）。 修正問題，重新渲染聯絡表，並再次檢查。告知用戶您發現了哪些問題並已修正。

5. 交付

為用戶開啟 MP4 檔案。如果檔案大於 35 MB，同時提供一個可供分享的副本（使用 ffmpeg -i in.mp4 -c:v libx264 -crf 21 -preset slow -c:a aac -b:a 160k -movflags +faststart share.mp4）、最佳封面影格（使用 capture.mjs frames）、一個標題、一段說明文字以及 5-8 個主題標籤。如果是用戶自行錄音模式，請同時提供包含每行台詞計時的腳本，供其作為錄音參考。提供一輪精確的修改與僅渲染已變更部分的重新輸出。

5b. 透過 Zapier 發布到 YouTube（僅在用戶要求上傳時）

所有呼叫皆使用程式碼模式工具：在 execute 中以 tools.zapier.* 的方式執行（請勿作為一般工具呼叫）。已在一次真實上傳中驗證過；以下數值為確切值。

1. 連線。 如果 list_zapier_skills 中有儲存用於上傳的技能，則直接使用。否則請確認 YouTube 應用程式已啟用：執行 discover_zapier_actions({ app: "YouTube" }) → enable_zapier_action({ selected_api: "YouTubeV4CLIAPI", app_display_name: "YouTube", action: "upload_video" })。 如果尚無連線存在，請執行 manage_zapier_connections({ selected_api: "YouTubeV4CLIAPI" })，它會回傳一個連線網址供用戶使用。
2. 託管檔案。 該動作的 video / thumbnail 參數需要一個 Zapier 伺服器可以取得的 URL；使用本地路徑會導致無訊息錯誤。 依照以下順序將 MP4 檔案放到一個臨時託管服務上（所有項目已於 2026-11-03 測試；Windows 請使用 curl.exe）：
   • a. litterbox（1 小時至 72 小時有效期，上限 1 GB）：curl -F "reqtype=fileupload" -F "time=1h" -F "fileToUpload=@renders/<name>.mp4" https://litterbox.catbox.moe/resources/internals/api.php → 回傳直接下載 URL（純文字）。
   • b. uguu.se（約 3 小時有效期，適合小於 35 MB 的短影音）：curl -F "files[]=@renders/<name>.mp4" https://uguu.se/upload → 回傳 JSON；使用 files[0].url（即 d.uguu.se/... 連結）。
   • c. catbox（永久有效，無到期日）：呼叫方式與 (a) 相同，但不加 -F "time=1h"。上傳後永久公開，因此僅在用戶同意後使用。
   • 跳過這些（已於 2026-11-03 確認失效，無需重試）：0x0.st（上傳已停用）、tmpfiles.org（連結會導向檢視頁面，非原始檔案）、gofile.io（原始下載需帳戶權杖）、file.io（curl API 會重新導向到其網頁應用程式）、bashupload.com、temp.sh（已失效）。
   • 務必在使用前驗證 URL：執行 curl -sSI <url> 必須回傳 200/206 狀態碼，且 Content-Type 為影片類型。絕不要未經檢查就信任任何主機的 JSON 回傳。
   • 告知用戶這會將他們的影片上傳到一個會自動過期的公開臨時主機。
3. 先確認。 此操作會寫入用戶的真實頻道，因此在執行前務必確認：標題、可見度（私人 / 不公開 / 公開）和分類。 如有需要，使用 inspect_zapier_actions({ tool_name: "youtube_upload_video", enum_property: "category_id" }) 解析 category_id。 教育類別 = 27（教學短片的預設值）、喜劇類別 = 23、如何與風格類別 = 26。
4. 上傳。 execute_zapier_write_action({ selected_api: "YouTubeV4CLIAPI", action: "upload_video", tool_name: "youtube_upload_video", params: { video: "<臨時URL>", title, description（以 #shorts 結尾）, tags: [5-8 個不含 # 的主題標籤], category_id: "27", privacy_status, made_for_kids: false, embeddable: true, notify_subscribers: true, default_language: "en", license: "youtube" } })
5. 回報。 結果包含 id；影片連結為 https://www.youtube.com/watch?v=<id>。長度 60 秒或更短的垂直影片會自動成為 Short（無需額外欄位）。 為用戶開啟本地檔案（tools.browser.preview({ path: "renders/<name>.mp4" })），並以文字形式提供 YouTube 網址。應用程式內瀏覽器經常因 ERR_ABORTED 而無法載入 youtube.com；這不表示上傳失敗。
6. 縮圖。 不公開的上傳無法透過此動作設定自訂縮圖；請將儲存的封面影格提供給用戶，供其日後將影片設為公開時使用。

禁止事項

使用 AI 生成圖片或影片；花費用戶的金錢或點數；在用戶未要求並確認的情況下上傳至 YouTube 或任何主機；複製其他創作者的腳本、鏡頭或影格；在未詢問的情況下覆蓋用戶的專案；交付未經您檢視的影格。