video-narrado 是做什麼的？
**輸入：**一個 .md 檔案。輸出，依序為：
- 詳細影片 16:9（2 至 4 分鐘），完整涵蓋 MD 內容。
- 短版影片 9:16（2 或 3 部，每部少於 60 秒）：每部從詳細影片中提取一個重點。
- 每部影片的
publicacion.md（標題、說明、主題標籤與替代文字）。
全部使用所選語音、字幕與自訂背景音樂。
- 引擎：
motor/，位於此技能內部（Playwright 1.63.0 + ffmpeg；純 Python 3，無依賴套件）。MOTOR為該資料夾的絕對路徑。 - 專案：每個影片一個資料夾，例如
videos/AAAA-MM-DD_主題/，內含每部影片的子資料夾：largo/、short-1-…/、short-2-…/。每部影片內含其storyboard.json。 - 安裝（僅需一次）：請參閱
README.md。
所選語音
預設使用 HeyGen 的克隆語音「audio_pmm」：
create_speech 欄位 | 值 |
|---|---|
voiceId | b088805628184836963fa5d2881bb23b |
engine | elevenlabs |
settings | {"model_id": "eleven_v4"} |
language | es |
如果要求影片的人想要其他語音，請先使用 mcp__heygen__list_voices 搜尋，並在生成前確認。
流程
1. 讀取 MD 並提議影片項目
讀取完整的 MD 檔案。定義詳細影片的敘事路線（所有發現，依序呈現）以及每部短版影片的一個發現（最強的先放）。在撰寫分鏡腳本前，先列出所有影片項目。
2. 分鏡腳本 → 審核
每個想法一個場景。詳細影片包含 8 到 16 個場景；一部短版影片包含 4 到 7 個場景，並在第一個場景加入鉤子（destacado）。完整範例請見：motor/ejemplos/storyboard-desalacion-16x9.json。
{"id": "03-sesiones", "tipo": "barras", "kicker": "各案件會談次數", "titulo": "討論最熱烈的案件",
"items": [{"etiqueta": "Caleta Chañaral", "valor": 6}], "destacar": 0, "nota": "來源…",
"subtitulo": "Chañaral de Aceituno 是會談次數最多的案件。",
"voz": "Chañaral de Aceituno 是會談次數最多的案件。"}
分鏡腳本標頭：titulo、serie（顯示於「Rizoma ·」旁的文字）、formato（詳細影片為 "16:9"，短版影片為 "9:16"）、fuente_md，以及選擇性的 musica（請見步驟 5）。
場景類型（全部支援 kicker、tono: "oscuro" 與 lluvia: true）：
| 類型 | 欄位 | 用途 |
|---|---|---|
portada | titulo、bajada | 開啟詳細影片 |
cifras | titulo、items[{valor, prefijo?, sufijo?, texto, detalle?}]（1 到 3 個）、destacar | 數字向上計數 |
barras | titulo、items[{etiqueta, valor, rotulo?}]（最多 8 個）、destacar、nota | 比較數量 |
hito | fecha、etiqueta、titulo、texto、progreso{i, n} | 時間軸中的一個事件 |
lista | titulo、items[{marca?, texto, alerta?}]（最多 6 個） | 論點或步驟 |
cita | fecha、texto、quien、nota | 某人說的話 |
destacado | texto、bajada | 必須記住的句子；短版影片的鉤子 |
cierre | bajada、url、fuente | 品牌標誌與來源 |
編輯規則：
- 僅使用 MD 中的事實。MD 標記為可疑的內容要麼省略，要麼如實說明。
voz是朗讀內容：數字、年份、百分比與縮寫必須以文字呈現（texto_voz.py會拒絕數字）。subtitulo是顯示在螢幕上的文字，可使用數字。texto是hito、cita與destacado場景中顯示在螢幕上的文字。- 句子簡短，使用中性智利西班牙語，約每秒 2.9 個單詞。一部短版影片的旁白不超過約 140 個單詞。
- 取自自動轉錄的內容必須標記為改寫（
nota）。 - 發布內容不得提及客戶或內部平台。結尾需標示來源。
以表格形式顯示每個分鏡腳本（場景 · 類型 · 畫面內容 · 旁白內容），並等待核准：每次旁白都會消耗語音配額。
3. 語音（每部影片一次 API 呼叫）
python3 $MOTOR/texto_voz.py <pieza>
將其輸出的文字（每個場景的旁白由 <break time="1.2s"/> 連接）傳遞給 mcp__heygen__create_speech，並使用所選語音。取得傳回的 audio_url 後：
python3 $MOTOR/bajar_voz.py <pieza> "<audio_url>"
這會下載音檔，並透過搜尋停頓來將音檔按場景切割。如果提示缺少停頓，請使用更低閾值重新對已下載的音檔執行：python3 $MOTOR/bajar_voz.py <pieza> <pieza>/voz/narracion.wav --pausa 0.7（實際上 ElevenLabs 有時會稍微縮短某些停頓）。如果仍然失敗，表示語音未遵守某個 <break>：請在重新生成前先詢問。錯誤發生時絕不單獨重試生成。
4. 建置與渲染
bash $MOTOR/producir.sh <pieza> # 完整影片
bash $MOTOR/producir.sh <pieza> --hasta 15 --salida prueba.mp4 # 短版測試
每個場景的長度等於其旁白的長度。MP4 檔案會生成在 <pieza>/salida/video.mp4；渲染時間大致等於影片長度。
5. 背景音樂
自動：使用 ffmpeg 合成的環境背景音（無第三方版權），音量低於語音 14 dB，帶有柔和閃避，最終混音為 -16 LUFS。在分鏡腳本中："musica": {"bajo_voz_db": 18} 可降低音量；{"archivo": "pista.mp3"} 使用自訂音軌（僅限可自由使用的音軌，並需註明授權）；false 則關閉音樂。
6. 短版影片
在詳細影片通過審核後，將每部短版影片作為獨立項目（formato: "9:16"），並重複使用詳細影片中的場景：鉤子 → 2 到 4 個數據場景 → 結尾。重複步驟 3（每部影片一次語音 API 呼叫）與步驟 4。
7. 審查與交付
- 使用 ffmpeg 擷取 4 到 8 個畫面並進行檢查：確保字幕沒有遮擋數據、任何文字都沒有超出畫面範圍、且沒有任何場景是空白的。
- 為每部影片撰寫
publicacion.md：標題（不超過 60 個字元）、含來源的說明、3 到 5 個主題標籤、替代文字，以及發布前需驗證的注意事項。 - 將 MP4 檔案複製到
~/Downloads，並使用清晰的名稱（Video_<主題>.mp4、Short_<序號>_<主題>.mp4）。音檔與 MP4 檔案不會納入 git 版本控制（**/voz/*.wav、**/salida/）。
使用自訂動畫 HTML
如果已有具備 window.seek(t) 與固定時間場景的 HTML，可以手動撰寫 guion.json（每個片段使用 html: [a, b]），然後執行 preparar.py + render.mjs。對於手動製作的短版影片：motor/plantillas/motor-vertical.js。
格式與安全區域
- 16:9：1920×1080，底部字幕 34 px，句子最多 58 個字元。
- 9:16：1080×1920，字幕 54 px，距離底部邊緣 400 px，句子最多 34 個字元；內容位於 y=400 至 y=1380 之間（上方與下方為各平台的按鈕區域）。
- 任何字幕結尾不得為「que」、「las」、「por」等類似詞語。
已知錯誤
- 無網路連線：Google 字型無法載入，渲染將回退為 Arial。
- ffmpeg 未包含 libass（Homebrew）：因此字幕直接在頁面內繪製。
- 未知的場景類型：影片會呈現空白；請檢查
tipo欄位。