ussefehab/egyptian-promo-video

埃及宣傳影片

完全在本機製作一支約 60~70 秒的直式宣傳影片：

script.json ──► 旁白 (Gemini TTS, 免費) ──► 逐行片段 ──► 時間軸
screenshots ──► promo.html (seek(t) 動畫) ──► puppeteer 畫面 ──► ffmpeg
synth.cjs (原創節拍 + 音效) ──► sidechain-ducked 混音 ──► loudnorm −14 LUFS ──► MP4 + WhatsApp 副本

每個場景的長度完全等於其對應口白，因此只要更改一個字或換一個聲音，整個影片就會自動重新計時。

經過驗證的範例（餐廳點餐系統：忙碌電話鉤子 → WhatsApp 痛點 → 揭露 → 菜單 → 購物車 → QR 桌號 → 訂單追蹤 → 儀表板 → 統計 → 品牌 + 行動呼籲）是預設範本。只需更改場景，而非引擎，即可將此結構套用於其他產品。

你需要準備

• Node 18+、ffmpeg/ffprobe 需在 PATH 中、Google Chrome（或設定 CHROME_PATH）。
• 在 build 資料夾中：npm i puppeteer-core qrcode msedge-tts@2（若 C 槽空間不足，可將 npm_config_cache 和 TEMP 指向其他磁碟）。
• 一個 免費 的 Google AI Studio 金鑰（aistudio.google.com/apikey）用於旁白。使用者需自行將金鑰貼入 VIDEO/.env 作為 GEMINI_API_KEY=…——請建立檔案但將金鑰留空，且絕不要求使用者在聊天中貼上或列印金鑰。首次呼叫時可能會顯示 Generative Language API 未啟用：請提供錯誤訊息中的主控台連結供使用者點擊 啟用，然後在一分鐘後重試。

資料夾結構

在使用者的專案中建立 VIDEO/（例如 marketing/video-<brand>/）：

VIDEO/.env            GEMINI_API_KEY=      (使用者自行填入)
VIDEO/script.json     複製自 assets/script.example.json，並進行編輯
VIDEO/build/          來自此技能的 scripts/* + assets/template/*
VIDEO/build/img/      promo.html 所使用的截圖與標誌
VIDEO/vo/             s01.wav … s10.wav (旁白片段)
VIDEO/out/            渲染結果、sheet.jpg、timeline.json

工作流程

1. 簡報（僅詢問你無法從程式碼中取得的資訊）

產品及其功能、目標受眾（誰會購買）、品牌名稱 及其發音、色調與標誌（在使用者的程式碼中查詢：tailwind 設定檔、icon.svg、Logo 元件）、行動呼籲、聯絡資訊（如果有的話）。預設格式：9:16、60–70 秒、埃及方言、男性能量充沛的聲音。

2. 腳本 → script.json

十行，每行對應一個場景。以下是被證實有效的結構：

1. 鉤子 (0–4 秒)：一個觀眾能辨識的痛苦問題（「كام أوردر ضاع منك النهارده… عشان التليفون كان مشغول？」）。
2. 痛點：現有的糟糕方式，以損失作結。
3. 揭露：「طب تخيّل…」+ 產品（此處節拍驟降）。 4–9. 每個場景介紹一個功能，每個功能皆搭配真實截圖。
4. 品牌 + 行動呼籲：誰提供此產品、邀請訂閱/聯絡。

voice 是 TTS 朗讀的內容：請以埃及人說話的方式書寫（عامية，用「…」表示呼吸，用「؟」表示疑問語氣，數字以文字表示「أربعة وعشرين」，QR 寫成「كيو آر」）。subtitles 是觀眾閱讀的內容（數字用「٢٤」，QR 用拉丁字母，品牌用拉丁字母）。headlines 是場景 1–9 的 2–5 字動態標題；將強調的字詞以 *…* 包圍。

請勿捏造統計數據、百分比、價格、獎項或推薦——觀眾和客戶無法驗證，且會帶來法律風險。清楚陳述的好處就足以說服人。

含有 V/P/G 的品牌名稱：阿拉伯語中沒有 V，因此「نوفيكس」讀作「NOFIX」。請在 voice 中使用 ڤ（「نوڤيكس」）或拉丁字母（「NOVIX」），然後在步驟 4 中以 check-v.cjs 進行驗證。

3. 螢幕截圖（真實產品，手機尺寸）

使用 puppeteer 以 390×844, deviceScaleFactor 3（→ 1170×2532）的尺寸進行截圖，並儲存至 build/img/。範本預期檔案名稱：phone-home.png, phone-sweets.png, phone-restaurant.png, phone-options.png, phone-cart.png, tracking.png, dashboard-cancel.jpg, dashboard-stats.jpg, dashboard-products.jpg——請根據產品重新命名/取代（請參閱 references/template.md）。

• 重新品牌 / 通用展示：使用 evaluateOnNewDocument + MutationObserver 注入一段腳本，將舊品牌名稱改寫、替換標誌 src、隱藏電話號碼並取代品牌照片，然後檢查 innerText 是否還有殘留。
• 已登入頁面（儀表板）：使用使用者已登入的應用程式內瀏覽器面板，模擬 375×812 的視口，以 javascript_tool 套用相同的 DOM 置換，並在該處進行截圖（它會儲存一個檔案，你可以複製）。該面板可能在任務進行中重置大小——請在每次拍攝前重新套用行動視口。
• 真實客戶資料：在擷取前遮蓋螢幕上的姓名/電話。如果需要真實狀態（例如新訂單、取消請求），請建立標籤清楚的示範記錄、擷取，然後刪除那些確切的記錄並確認它們已消失。

4. 旁白

免費、自然的埃及語音來自 Gemini TTS（scripts/vo-gemini.cjs）：

• gemini-3.8-flash-tts 有 92 個原生埃及語音（ar-eg-*，例如 ar-eg-concierge-1 年輕/明亮、ar-eg-commercial-11 廣告聲音、ar-eg-storyteller-3 隨意）。免費層級：此模型每天僅 10 次請求。
• gemini-3.1-flash-tts-preview 有單獨的免費配額，但只有通用語音（Puck 開朗男性——使用者選擇、Orus 穩重男性……）透過風格文字導向埃及語。
• 指令（從 VIDEO/build 執行）：
  • node vo-gemini.cjs voices → 列出 ar-EG 語音。
  • node vo-gemini.cjs sample <voice> [voice…] → 將每個語音的鉤子行存入 vo/samples/（每次請求一個）。轉換為 mp3 並傳送給使用者，讓他們用耳朵挑選——你無法收聽。
  • node vo-gemini.cjs all <voice> → 一次請求 整個腳本，在停頓處分割成 10 個片段（節省配額，聽起來像一次連續錄音）。舊片段會被備份。
  • node vo-gemini.cjs line <voice> <n> → 重新錄製單一行。
  • 使用 GEMINI_TTS_MODEL=gemini-3.1-flash-tts-preview 切換模型。
• 請謹慎使用樣本（5 個語音 = 5 次請求）。如果 3.8 的配額用完，可以提供以下選項：等待重置（約太平洋時間午夜），或今天改用 3.1 錄製。請勿建議使用者建立額外的 Google 帳戶以獲得更多配額——Google 的 API 條款禁止規避限制，且可能導致兩個帳戶都被停權。
• 替代方案：vo-edge.cjs（Microsoft ar-EG-ShakirNeural，無限次數，無需金鑰——但使用者認為它機械化/不像埃及人），或者使用者用自己的手機錄製行，你再修剪/標準化為 vo/sNN.wav。ElevenLabs 效果極佳但需付費。

驗證每一段錄音——你無法聽到它：

• node transcribe.cjs [s05 s06…] 使用 Gemini 文字模型轉錄每個片段。每個轉錄結果必須等於其腳本行。如果下一行的字詞出現在片段結尾，則表示切割過晚：使用 ffmpeg -af silencedetect=noise=-38dB:d=0.1 尋找停頓，並將尾部移到下一個片段（請參閱 gotchas 中關於 -ss 陷阱的說明）。從 vo/take/ 的原始檔案進行修正。
• node check-v.cjs s10 詢問品牌子音是 /v/ 還是 /f/（每個片段兩次）。請包含已知有問題的錄音作為對照，以確認檢查功能正常。

5. 主題化範本

範本還需要 img/qr.png（使用 node -e "require('qrcode').toFile('img/qr.png','<site url or brand>',{errorCorrectionLevel:'H',margin:1,width:680})" 建立——觀眾可以掃描它，因此請指向真實位置或純文字）、img/rest-logo.svg（示範業務的標誌）以及品牌圖示（範例中的 img/novix-icon.svg）。

assets/template/promo.html 採用 NOVIX 風格（海軍藍 #0B1020，藍→紫漸層）。透過編輯 :root 變數、舞台背景與發光顏色、.hl 漸層、晶片/環/字幕膠囊、QR 卡片以及最後一個場景（標誌、文字商標、標語、行動呼籲、功能列表）來進行重新主題化。references/template.md 列出了每個元素的位置以及場景如何連接。

6. 檢查、預覽、渲染

從 VIDEO/build：

1. node build.cjs --check——執行所有約 2000 幀而不擷取螢幕截圖；可在數秒內而非 5 分鐘渲染後捕捉 JS 錯誤。
2. node build.cjs --preview 3 → out/sheet.jpg。查看它（讀取圖片）：標題換行、超出畫布、對比度問題（例如橘色文字在橘色卡片上）、殘留的舊品牌。
3. node build.cjs（在背景執行，約 66 秒需 5 分鐘）。它會報告影片與音訊長度（必須相符）以及音量（約 −14 LUFS）。
4. 使用 SendUserFile 傳送 WhatsApp 副本（完整檔案通常 > 30 MB，且僅在桌面上顯示），告知使用者兩個檔案的位置，並明確說明你已透過轉錄/畫面進行檢查，但無法收聽。

7. 音樂

synth.cjs 創作一首原創 98 BPM 中東陷阱節拍（darbuka、808、D Hijaz 中的撥弦烏德風主奏），並在揭露場景處加入節拍驟降，以及忙碌音/呼嘯聲/叮噹聲/嗶聲/爆裂聲等音效。有授權的音樂庫（例如 Epidemic Sound 連接器）可能只允許預覽而非下載——預覽版不能用於廣告，因此請勿使用。

交付

• 最終檔案：out/<name>-9x16.mp4（1080×1920，30 fps，H.264，AAC，−14 LUFS）以及 out/<name>-9x16-whatsapp.mp4。
• 提及任何預留位置（例如結尾卡片上缺少電話號碼等），並提供顯而易見的下一步（新增聯絡資訊、橫向版本、嵌入其網站）。
• 如果螢幕截圖必須公開託管（僅在雲端影片工具需要時），請告知使用者位置，並提供移除的選項。

在執行任何操作之前，請先閱讀 references/gotchas.md——它列出了建立此技能時遇到的所有失敗情況及解決方法。