Starsoup Script-to-Video Pipeline

需求文檔 + AI Agent Context

版本: v0.1 — 初稿
日期: 2026-03-19
作者: Ted / Starsoup
狀態: 待確認 → Phase 2 Feasibility Review

一、項目背景與目標

1.1 背景

Starsoup 是一個以技術和創意為核心的品牌，現正建設一套以 AI 驅動的內容生產基礎設施。本項目的出發點是：給定一段戲劇腳本，自動生成一段帶有素材和語音的視頻初稿，全程無需人工介入。

這套系統將跑在PC上，通過 Docker Compose 部署，

1.2 目標

最小成本：AI 調用之外的每個環節均優先免費或自托管方案
全自動閉環：腳本輸入 → 結構化場景解析 → 素材匹配 → 語音合成 → 視頻合成 → 輸出通知，全程無人干預
可延伸性：流水線各節點可獨立替換供應商（例如日後換用 Runway 生成視頻）
Harness 設計：每個 AI 調用節點都有明確的輸入/輸出格式約束，防止模型漂移

二、系統架構概覽

[輸入層]
  腳本文本（中文/英文）
       │
       ▼
[場景解析層] ── Xiaomi Mimo Omni
  腳本 → 結構化 JSON（場景列表 + 關鍵詞 + 時長估算）
       │
       ▼
[素材獲取層] ── Pexels API / Pixabay API（並行請求）
  每個場景關鍵詞 → 搜尋視頻素材 → 下載 MP4 片段
       │
       ├──────────────────────────┐
       ▼                          ▼
[語音合成層]               [（可選）AIGC 補充層]
  Edge TTS / OpenAI TTS      Replicate / fal.ai
  台詞文本 → MP3 音頻         補充無法從庫找到的場景
       │
       └──────────────┐
                      ▼
              [合成層] ── FFmpeg + MoviePy
              裁剪視頻片段 → 按場景順序拼接
              → 疊加語音軌道 → 輸出 MP4
                      │
                      ▼
              [通知層] ── n8n
              飛書/郵件通知 + 輸出文件路徑

調度中樞：n8n（自托管，Docker 部署）
所有節點由 n8n Workflow 串聯，通過 Webhook 觸發，並提供執行日誌和錯誤重試。

三、功能需求

3.1 腳本輸入

項目	描述
輸入方式	n8n Webhook（HTTP POST 請求）或 n8n 表單頁面
輸入格式	純文本（中文或英文戲劇腳本）
腳本結構	支持帶場景標記（`【場景1】`）或無標記的連續文本
最大長度	初版限制 5000 字（約 10 分鐘視頻）

3.2 場景解析（xiaomi/mimo-v2-omni）

Prompt 約束（Harness）：

你是一個視頻場景分析師。給定一段戲劇腳本，請：
1. 將腳本切分為若干場景（每個場景5-15秒）
2. 為每個場景生成3個英文搜索關鍵詞（用於視頻素材庫搜尋）
3. 根據台詞字數估算場景時長（中文：每秒3字，英文：每秒2.5詞）
4. 提取每個場景的台詞原文（用於語音合成）

僅輸出 JSON，不要任何解釋文字。格式如下：
{
  "total_duration": 120,
  "scenes": [
    {
      "id": 1,
      "description": "黃昏城市街道，人群稀少",
      "keywords": ["sunset city street", "urban evening", "empty sidewalk"],
      "duration": 6,
      "dialogue": "台詞原文..."
    }
  ]
}

輸出：標準 JSON，直接傳入下一節點。

3.3 素材搜尋與下載

項目	描述
主要來源	Pexels Video API（免費，每小時200次）
備用來源	Pixabay Video API（每小時100次）
搜尋策略	每個場景用 `keywords[0]` 搜尋，無結果則依次嘗試 `keywords[1]`、`keywords[2]`
素材選取	取搜尋結果第1個，時長須 ≥ 場景估算時長；否則取第2個
下載路徑	服務器本地臨時目錄 `/tmp/starsoup-pipeline/{job_id}/clips/`
失敗處理	搜尋全部關鍵詞失敗時，使用預設黑色底板 + 白字字幕作為 fallback

3.4 語音合成

初版：Edge TTS（免費，自托管，無 API 限制）

bash

# n8n 通過 Execute Command 節點觸發
edge-tts \
  --voice zh-CN-XiaoxiaoNeural \
  --text "{{台詞內容}}" \
  --write-media /tmp/starsoup-pipeline/{job_id}/audio/{scene_id}.mp3

聲線配置（可在 n8n 環境變量中調整）：

中文女聲：zh-CN-XiaoxiaoNeural（預設）
中文男聲：zh-CN-YunxiNeural
英文：en-US-AriaNeural

升級路徑：若需要更自然的聲線，替換為 OpenAI TTS（約每視頻 $0.03）。

3.5 視頻合成（核心節點）

由 n8n Execute Command 觸發 Python 腳本，在服務器上執行：

python

# /opt/starsoup/scripts/compose_video.py
from moviepy.editor import *
import json, sys

job_id = sys.argv[1]
meta = json.load(open(f"/tmp/starsoup-pipeline/{job_id}/scenes.json"))

clips = []
for scene in meta["scenes"]:
    # 加載視頻素材並裁剪到對應時長
    clip = VideoFileClip(scene["clip_path"]).subclip(0, scene["duration"])
    clips.append(clip)

# 拼接所有場景
video = concatenate_videoclips(clips, method="compose")

# 合成完整語音（把每個場景語音合併為一個音軌）
audios = [AudioFileClip(scene["audio_path"]) for scene in meta["scenes"]]
full_audio = concatenate_audioclips(audios)

# 疊加語音
final = video.set_audio(full_audio)
final.write_videofile(
    f"/opt/starsoup/outputs/{job_id}.mp4",
    fps=24,
    codec="libx264",
    audio_codec="aac"
)

輸出文件：/opt/starsoup/outputs/{job_id}.mp4

3.6 通知輸出

n8n 最後一個節點，合成完成後自動：

發送飛書消息（Webhook）包含任務 ID、視頻文件路徑、耗時
（可選）若服務器有對外存儲，上傳到指定位置並返回下載鏈接

四、技術棧總覽

層級	技術	托管方式	費用
流程調度	n8n	自托管 Docker	免費
場景解析	mimo-v2-omni	xiaomi	~$0.003/次
素材庫	Pexels API	外部免費 API	免費
語音合成	Edge TTS	自托管 Python	免費
視頻合成	FFmpeg + MoviePy	自托管 Python	免費
總計（每個5分鐘視頻）			< $0.01

五、n8n Workflow 設計

Workflow 節點順序

[Webhook 觸發] → [HTTP Request: Claude Haiku 場景解析]
→ [Code Node: 解析 JSON + 生成 job_id]
→ [Loop: 每個場景]
    → [HTTP Request: Pexels 搜尋]
    → [HTTP Request: 下載視頻片段]
    → [Execute Command: Edge TTS 語音生成]
→ [Execute Command: compose_video.py]
→ [If: 合成成功?]
    → [Yes] → [HTTP Request: 飛書通知]
    → [No]  → [HTTP Request: 飛書錯誤告警]

環境變量（n8n）

env

PEXELS_API_KEY=your_pexels_key
ANTHROPIC_API_KEY=your_anthropic_key
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
TTS_VOICE=zh-CN-XiaoxiaoNeural
OUTPUT_DIR=/opt/starsoup/outputs
TEMP_DIR=/tmp/starsoup-pipeline

六、目錄結構

starsoup-infrastructure/
└── services/
    └── script-to-video/
        ├── docker-compose.yml       # n8n + 依賴
        ├── .env                     # 環境變量（不入 Git）
        ├── .env.example             # 環境變量模板
        ├── scripts/
        │   ├── compose_video.py     # MoviePy 合成腳本
        │   ├── requirements.txt     # moviepy, edge-tts 等
        │   └── fallback_clip.py     # 生成黑底字幕 fallback
        ├── n8n/
        │   └── workflows/
        │       └── script-to-video.json  # n8n Workflow 導出文件
        ├── outputs/                 # 最終視頻輸出目錄
        └── AGENTS.md                # AI Agent 上下文導航

七、AGENTS.md（AI Context）

此文件放在 script-to-video/ 根目錄，供 AI agent 在協助開發時快速定向。

markdown

# AGENTS.md — Script-to-Video Pipeline

## 這個項目做什麼
輸入戲劇腳本文本，自動生成包含視頻素材和語音的 MP4 視頻。
調度中樞：n8n（自托管）
核心 AI 節點：Claude Haiku（場景解析）

## 模塊邊界
- `scripts/compose_video.py`：只負責合成，不調用任何 API
- `scripts/fallback_clip.py`：只生成黑底 fallback，不依賴外部服務
- n8n Workflow：唯一允許調用外部 API 的層（Pexels, Anthropic, 飛書）

## 關鍵約束
- Claude Haiku 的 prompt 必須強制輸出純 JSON，不得有解釋文字
- 所有臨時文件寫入 /tmp/starsoup-pipeline/{job_id}/，合成完成後清理
- 最終輸出只寫入 /opt/starsoup/outputs/

## 當前狀態
- [ ] n8n Docker 服務部署
- [ ] Pexels API 測試
- [ ] Edge TTS 測試
- [ ] compose_video.py 最小閉環測試
- [ ] n8n Workflow 完整串聯

## 禁止事項
- 不引入付費視頻生成 API（Runway/Kling）直到 MVP 驗證完成
- 不在 compose_video.py 中調用任何網絡請求
- 不在 Git 中提交 .env 文件

八、MVP 里程碑

Phase 1 — 最小閉環（目標：1天）

[ ] Python 腳本本地跑通：給定 JSON → 下載Pexels視頻 → FFmpeg 拼接 → 輸出 MP4
[ ] Edge TTS 測試：輸入台詞 → 輸出 MP3

Phase 2 — AI 串聯（目標：1天）

[ ] Claude Haiku 場景解析 Prompt 驗證
[ ] Pexels API 關鍵詞搜尋 + Fallback 邏輯
[ ] compose_video.py 完整版（場景+語音疊加）

Phase 3 — n8n 串聯（目標：2天）

[ ] n8n Docker 部署到 Server A
[ ] Workflow 完整串聯（Webhook → 合成 → 飛書通知）
[ ] Cloudflare Tunnel 暴露 Webhook

Phase 4 — 穩定化（目標：按需）

[ ] 錯誤重試邏輯
[ ] 任務隊列（防止並發合成吃爆服務器資源）
[ ] 日誌收集

九、開放問題（待確認）

#	問題	影響
Q1	腳本是否需要支持多角色台詞分配不同聲線？	影響 TTS 調用邏輯複雜度
Q2	輸出視頻是否需要字幕疊加？	影響 MoviePy 字幕渲染
Q3	Server A 的 CPU/RAM 規格？	影響並發合成能力和 FFmpeg 性能
Q4	素材版權：Pexels 免費授權是否符合項目的最終使用場景？	如為商業用途需確認 Pexels 授權條款
Q5	是否需要支持批量輸入（一次提交多個腳本）？	影響 n8n Queue 設計

文檔生成：Claude Sonnet 4.6 / Starsoup Internal

cis

pixel-web-property

script-to-video

sip

starsoup規則

Starsoup-docs

Starsoup Script-to-Video Pipeline

需求文檔 + AI Agent Context

一、項目背景與目標

1.1 背景

1.2 目標

二、系統架構概覽

三、功能需求

3.1 腳本輸入

3.2 場景解析（xiaomi/mimo-v2-omni）

3.3 素材搜尋與下載

3.4 語音合成

3.5 視頻合成（核心節點）

3.6 通知輸出

四、技術棧總覽

五、n8n Workflow 設計

Workflow 節點順序

環境變量（n8n）

六、目錄結構

七、AGENTS.md（AI Context）

八、MVP 里程碑

Phase 1 — 最小閉環（目標：1天）

Phase 2 — AI 串聯（目標：1天）

Phase 3 — n8n 串聯（目標：2天）

Phase 4 — 穩定化（目標：按需）

九、開放問題（待確認）

Starsoup Script-to-Video Pipeline ​

需求文檔 + AI Agent Context ​

一、項目背景與目標 ​

1.1 背景 ​

1.2 目標 ​

二、系統架構概覽 ​

三、功能需求 ​

3.1 腳本輸入 ​

3.2 場景解析（xiaomi/mimo-v2-omni） ​

3.3 素材搜尋與下載 ​

3.4 語音合成 ​

3.5 視頻合成（核心節點） ​

3.6 通知輸出 ​

四、技術棧總覽 ​

五、n8n Workflow 設計 ​

Workflow 節點順序 ​

環境變量（n8n） ​

六、目錄結構 ​

七、AGENTS.md（AI Context） ​

八、MVP 里程碑 ​

Phase 1 — 最小閉環（目標：1天） ​

Phase 2 — AI 串聯（目標：1天） ​

Phase 3 — n8n 串聯（目標：2天） ​

Phase 4 — 穩定化（目標：按需） ​

九、開放問題（待確認） ​

Starsoup Script-to-Video Pipeline

需求文檔 + AI Agent Context

一、項目背景與目標

1.1 背景

1.2 目標

二、系統架構概覽

三、功能需求

3.1 腳本輸入

3.2 場景解析（xiaomi/mimo-v2-omni）

3.3 素材搜尋與下載

3.4 語音合成

3.5 視頻合成（核心節點）

3.6 通知輸出

四、技術棧總覽

五、n8n Workflow 設計

Workflow 節點順序

環境變量（n8n）

六、目錄結構

七、AGENTS.md（AI Context）

八、MVP 里程碑

Phase 1 — 最小閉環（目標：1天）

Phase 2 — AI 串聯（目標：1天）

Phase 3 — n8n 串聯（目標：2天）

Phase 4 — 穩定化（目標：按需）

九、開放問題（待確認）