niruvai/storytelling

/storytelling

┌──────────────────────┐
│ [4:12] [封面] [留言] │  三張卡片，同時出現
│  我幾分鐘前做了     │  黑底標題，1-2 行
│  這個輪播貼文       │
│ 而且它表現得很好   │  白色小副標
│        (人臉)       │  連續鏡頭，稍微放大
│     整個輪播貼文    │  TikTok 字幕
└──────────────────────┘

初次使用

此技能所在的資料夾即為 Claude Code 載入時顯示的「Base directory」。

SKILL_DIR="<此技能的基底目錄>"   # Claude Code 列出的「Base directory for this skill」
KIT=$(python3 -c 'import os,sys;print(os.path.realpath(os.path.join(sys.argv[1],"..","..","kit")))' "$SKILL_DIR")
PY="$KIT/.venv/bin/python"; [ -x "$PY" ] || bash "$KIT/setup.sh"

孟加拉語影片。 如果講者使用孟加拉語，請在第一次呼叫 words 前設定 REEL_LANGUAGE=bn（可匯出變數或在指令前加上前綴），以便 Whisper 直接轉錄孟加拉語而非翻譯成英文。所有螢幕上的文字（標題、標籤、項目）也應使用孟加拉語書寫，並根據 words 輸出的孟加拉文字詞精準定位時間點。孟加拉語在同字號下比英文更寬，因此標題請控制在 2 到 4 個詞之間，並檢查 contact sheet 是否有文字溢出。Whisper 經常拼錯孟加拉語（例如 "ধাকার মেওর" 應為 "ঢাকার মেয়র"）：在撰寫規格檔之前，請閱讀所選片段的文字稿，直接在 <clip>.transcript.json 中修正錯誤拼寫（僅修改 word，保留 start/end），然後重新執行 words，確保字幕與錨點使用正確的文字。如果 words 缺少一大段語音，請刪除轉錄檔案並再次執行 words；轉錄器會重新檢查跳過的段落。如果影片不是 9:16（例如 1080x1080 的正方形手機影片），請檢查第一幀：直接裁切可能導致臉部填滿畫面並遮蓋視覺元素，此時應通知使用者並建議重新錄製 9:16 格式。

需要設定 GROQ_API_KEY 才能進行轉錄。需要 ffmpeg 和 Node.js。

步驟

1. 影片。 任何 9:16 的說話者鏡頭影片。
2. 文字稿。 執行 "$PY" "$KIT/reel.py" words <影片>。它會以一行一個句子的方式輸出，並在結尾標示 [ends …]（最後一個詞結束的時間點），請以此作為 end。挑選一段連續 4 到 8 秒、能講述一個小故事或提供證明內容的片段。請不要拼接不同片段，因為跳接會使影片顯得突兀。
3. 規格檔。 撰寫 <影片>.storytelling.json（格式如下）。規格檔中的路徑相對於規格檔本身。三張卡片代表用圖片講述的故事：努力、事件與結果。
4. 建置。 執行 "$PY" "$SKILL_DIR/build.py" <規格檔.json>。
5. 檢查。 查看 <輸出>.sheet.jpg：
   • 卡片與標題未與頂部 220px 區域重疊。
   • 字幕未遮蓋嘴巴（可調整 caption_top，預設值 1385）。
   • 標題文字能完整容納在行內。
6. 交付 mp4 檔案路徑。

規格檔格式

{
  "video": "my-clip.mp4", "start": 42.3, "end": 47.8,
  "zoom": 1.3,
  "cards": [
    {"type": "stat", "label": "花費時間", "value": "4:12", "unit": "分鐘"},
    {"type": "cover", "image": "my-photo.jpg", "text": "最棒的 *ai 工具*\n當你
*年輕又沒錢* 時使用"},
    {"type": "comments", "title": "留言", "rows": [["sarah.creates", "輪播貼文"], ["mike.builds", "輪播貼文!!"]]}
  ],
  "title": ["我幾分鐘前做了", "這個輪播貼文"],
  "subtitle": "而且它表現得很好"
}

cards 必須正好 3 張，每張可以是以下類型之一：

• image：{"src": "photo.jpg"}，一張正方形照片。
• cover：輪播貼文封面，包含 image 與 text（*文字* 會呈現黃色，\n 代表換行）。它會緩慢移動。
• stat：包含 label、value、unit 以及一個圓環。
  • 當 value 是數字（如 "250"、"10,000"）或時間（如 "4:12"）時，數值會動態增加。
  • ring（0 到 1）控制圓環的填滿程度。
• comments：最多 4 列 [使用者名稱, 文字]。
• text：{"big": "3×", "small": "更多儲存"}。

其他欄位：

• title：1 或 2 行，每行最多約 22 個字元。
• subtitle：一行簡短的副標題。
• zoom：鏡頭的放大倍率。預設值 1.3，設為 1 則無放大。

美感原則

• 所有元素在影片開始後的 0.3 秒內同時出現，絕不逐一出現。
• 標題是一口氣說完的故事，副標則是回饋或結果。
• 卡片內容必須是真實的：使用者自己的貼文、數字、螢幕截圖。留言列與使用者名稱必須是真實提供的資料。如果使用者沒有提供相關資料，請使用 text 或 stat 卡片，而不是虛構人物。