SwiftClip 詳細教學

本教學對應 repo commit 1ab3903 (2026-05-11)，最後驗證日 2026-05-20。 涵蓋專案定位、安裝、核心架構、CLI 詳細用法、應用情境、資安、FAQ、進階技巧、整合建議共 11 章。

1. 專案定位

1.1 是什麼

SwiftClip 同時是三件事：

1. Remotion 影片模板庫 — 32 個生產級 .tsx 模板，從 ProductLaunch 到 Macintosh（含 WebGL panorama 的 AppleMovie）
2. Next.js 16 預覽站 — swift-clip.vercel.app，可線上預覽每個模板
3. Claude Code / Codex Plugin — swiftclip-remotion 是雙 marketplace 相容 plugin，提供「brief → 模板挑選 → 衍生 component」的 storyboard-driven 工作流

1.2 為什麼重要

• AI 影片自動化的 reference：Remotion 把影片合成寫成 React，SwiftClip 加上 Claude/Codex agent，就完成「LLM → 影片」整條 pipeline
• 可重用 plugin 架構：plugins/swiftclip-remotion/ 內的三件式 (plugin.json + hooks.json + agent.md) 可直接拷貝作為其他 Claude plugin 起手式
• Apple Light Mode 視覺一致：32 個模板都用 #f5f5f7 背景 + SF Pro 字型，統一視覺基線，免再調設計

1.3 與相關工具的關係

1.4 一句話總結

「把影片合成寫成 React」的 32 個模板庫，外加 Claude/Codex agent 工作流，讓 AI 從 brief 自動產生可渲染的 4K MP4 影片元件。

2. 安裝指南

2.1 系統需求

2.2 方案 A — 只用模板（最簡單）

 1# 1. 開新 Remotion 專案
 2npx create-video@latest
 3cd my-video-project
 4
 5# 2. 從 SwiftClip 複製想要的模板
 6curl -o remotion/ProductLaunch.tsx \
 7  https://raw.githubusercontent.com/zz41354899/SwiftClip/main/remotion/ProductLaunch.tsx
 8
 9# 3. 在 remotion/Root.tsx 註冊
10# 4. 預覽 + 渲染
11npm run dev                          # http://localhost:3000
12npx remotion render remotion/index.tsx ProductLaunch output.mp4

2.3 方案 B — 安裝 Claude Code plugin

 1# 前提：已在 Remotion 專案內、Claude Code 環境已啟動
 2cd my-video-project
 3
 4# 加 marketplace
 5claude plugin marketplace add zz41354899/SwiftClip
 6
 7# 安裝 plugin
 8claude plugin install swiftclip-remotion@swiftclip-tools --scope project
 9
10# 在 Claude Code session 內
11/reload-plugins

plugin 用 git commit SHA 當 version key（未發 npm，目前快速迭代中）。

2.4 方案 C — 安裝 Codex plugin

1# 在 Codex 環境
2codex marketplace add https://github.com/zz41354899/SwiftClip
3codex plugin install swiftclip-remotion

2.5 安裝流程圖

flowchart TD
    A[使用者] --> B{有 Remotion 專案了嗎?}
    B -->|沒有| C[npx create-video@latest]
    C --> D[cd my-video-project]
    B -->|有| D
    D --> E{要哪種使用方式?}
    E -->|只要模板| F[複製 .tsx → remotion/]
    E -->|要 Claude agent| G[plugin marketplace add zz41354899/SwiftClip]
    E -->|要 Codex agent| H[codex marketplace add SwiftClip]
    F --> I[註冊到 Root.tsx]
    G --> J[/reload-plugins]
    H --> J
    J --> K[與 agent 對話: 描述 brief]
    I --> L[npm run dev → 預覽]
    K --> M[agent 自動產衍生 component + 註冊]
    M --> L
    L --> N[npx remotion render → MP4]

2.6 常見安裝問題

3. 核心架構解析

3.1 三層結構

flowchart TB
    subgraph L1["Layer 1: 32 個 Remotion 模板（.tsx）"]
        T1[ProductLaunch] --- T2[TutorialIntro] --- T3[SaaSPromo]
        T4[SocialStory] --- T5[LowerThird] --- T6[DataViz]
        T7[Macintosh
CRT shader] --- T8[AppleMovie
WebGL panorama] --- T9[...32]
    end
    subgraph L2["Layer 2: Next.js 16 預覽站 (app/)"]
        P1[/templates/
RemotionPlayer]
        P2[/docs/]
        P3[/community/]
    end
    subgraph L3["Layer 3: Claude/Codex plugin (plugins/swiftclip-remotion/)"]
        A1[plugin.json
manifest]
        A2[hooks/hooks.json
+ validate-remotion.sh]
        A3[agents/remotion-builder.md
sonnet, 12 turns]
        A4[skills/
brief → preflight JSON]
    end
    L1 -.被預覽.-> L2
    L1 -.被生成 / 衍生.-> L3
    L3 -.寫入註冊.-> L1

3.2 模板分類（共 32 個）

3.3 模板統一規範

• 背景色 #f5f5f7（Apple Light Mode 一致）
• 字型 SF Pro / -apple-system
• 動畫 hook：useCurrentFrame()、interpolate()、spring()（Remotion 標準）
• 無外部 SDK：每個模板只依賴 remotion + react + lucide-react（icons）
• 預設 4K-ready：透過 --scale flag 渲染任意解析度

3.4 Plugin 架構詳解

plugins/swiftclip-remotion/ 結構：

1plugins/swiftclip-remotion/
2├── .claude-plugin/
3│   └── plugin.json        # name / description / skills / agents
4├── hooks/
5│   └── hooks.json         # PreToolUse hook 指向 validate-remotion.sh
6├── scripts/
7│   └── validate-remotion.sh   # 確認 Root.tsx 存在 + 含 Composition
8└── agents/
9    └── remotion-builder.md    # sonnet, maxTurns=12, 從 brief → component

3.4.1 Hook (validate-remotion.sh)

1# 邏輯
2if [[ ! -f "remotion/Root.tsx" ]]; then exit 0    # 跳過
3if [[ ! -f "lib/templates.ts" ]]; then exit 0    # 跳過
4if ! grep -q "Composition" "remotion/Root.tsx"; then exit 1   # 阻擋

阻擋規則：Root.tsx 必須註冊 <Composition /> 才能繼續生成。

3.4.2 Agent (remotion-builder.md)

• 模型：sonnet, effort=medium, maxTurns=12
• 流程：
  1. 確認 workspace 是 Remotion 專案（package.json 含 remotion + 有 Root.tsx）
  2. 從 brief 路由到 5 個內部 core template 之一：ProductLaunch / TutorialIntro / SocialStory / LowerThird / SaaSPromo
  3. 產 preflight JSON（machine-readable storyboard 摘要）
  4. 產衍生 component + 註冊到 Root.tsx

3.5 工作流序列

sequenceDiagram
    participant U as User
    participant C as Claude Code
    participant A as remotion-builder agent
    participant H as validate-remotion.sh
    participant FS as filesystem

    U->>C: 描述影片 brief (主題 / 規格 / 文案)
    C->>A: 啟動 agent
    A->>H: 跑 pre-hook
    H->>FS: 檢查 Root.tsx + lib/templates.ts
    H-->>A: ✅ pass / ❌ fail
    A->>U: 確認 base template (ProductLaunch / TutorialIntro / ...)
    U-->>A: 確定
    A->>A: 產 preflight JSON (storyboard beats)
    A->>FS: 寫新 .tsx 衍生 component
    A->>FS: 更新 Root.tsx 註冊
    A->>U: 回 component path + 渲染指令
    U->>FS: npx remotion render → output.mp4

4. CLI 詳細用法

4.1 Remotion 標準 CLI（透過模板）

 1# 預覽 Studio（互動式）
 2npm run dev
 3# → http://localhost:3000
 4
 5# 渲染單一模板
 6npx remotion render remotion/index.tsx ProductLaunch output.mp4
 7
 8# 高解析度
 9npx remotion render remotion/index.tsx Macintosh output.mp4 --scale=2
10
11# 自訂 props
12npx remotion render remotion/index.tsx ProductLaunch output.mp4 \
13  --props='{"title":"MyApp","subtitle":"Ship faster"}'
14
15# 串流渲染（CI）
16npx remotion render remotion/index.tsx ProductLaunch output.mp4 --concurrency=4

4.2 SwiftClip plugin 互動式指令（Claude Code 內）

1# 範例 prompt（從 plugin.json 內 defaultPrompt 抽出）
2> Help me choose the right Remotion template for a product launch video.
3> Turn my video brief into preflight JSON and storyboard beats.
4> Generate a new Remotion derivative component and register it in Root.tsx.

4.3 Next.js 預覽站（自己跑 demo 站）

1npm run dev      # next dev
2npm run build    # next build
3npm run start    # next start
4npm run lint     # next lint

4.4 替換模板 metadata（replace_templates.js）

1node replace_templates.js
2# 編輯 lib/templates.ts，把 "glitch-title" 那筆模板替換為 "dynamic-island"
3# 純本地檔案操作，無網路 / 無副作用

5. 應用場景

6. 資安掃描報告

掃描日期：2026-05-20 / 範圍：*.ts/tsx/mjs/js/sh/json/md（排除 node_modules）

6.1 紅黃綠燈總結

6.2 詳細發現

• ❌ 無 eval() / new Function() / child_process / execSync
• ❌ 無 fetch / axios / XMLHttpRequest / WebSocket
• ❌ 無 dangerouslySetInnerHTML、無 innerHTML 直接寫入
• ❌ 無 hardcoded secret / API key / token / password
• ✅ 唯一寫檔點：replace_templates.js:93 fs.writeFileSync('lib/templates.ts', content) — 本地 build script，更新模板註冊表，安全

6.3 plugin 部分

• validate-remotion.sh：純檢查 grep -q "Composition"，不執行任何外部命令
• hooks.json：只指向 validate 腳本，無 shell injection 風險
• agent prompt 內無外部 fetch 指令

6.4 結論

🟢 整體低風險。純 React/TS 模板 + 本地 build helper，無網路請求、無 secret、無動態執行。可放心 fork / 安裝。

唯一注意：plugin 用 git commit SHA 當 version，安裝時 marketplace 會拉最新 main 分支，建議定期確認 commit history（特別是 hooks 與 agent 提示詞變動）。

7. FAQ

Q1: 我沒有 Remotion 專案能用嗎？ A: 不行。SwiftClip 是模板庫不是 scaffold，先跑 npx create-video@latest。

Q2: 一定要裝 Claude / Codex plugin 嗎？ A: 不用。模板本身就是 plain .tsx 檔，複製進 remotion/ + 註冊 Root.tsx 就能用。Plugin 只是讓「AI 從 brief 自動產衍生模板」這條路更順。

Q3: License 標 ISC 還是 MIT？ A: LICENSE 檔是 MIT，package.json 標 ISC — 不一致。Repo 描述也說 MIT，實務上以 LICENSE 為準（MIT）。要 fork 商用前可開 issue 確認。

Q4: package.json 標 private: "true" 是什麼意思？ A: 這個值有問題 — 應該是 "private": true (boolean) 而非 "true" (string)。true 才會阻止意外發佈到 npm；字串 "true" 也是 truthy，但屬於格式 bug。

Q5: 怎麼自己加新模板？ A: 看 §8.2 進階技巧。簡言之：建 .tsx、註冊 Root.tsx、加進 lib/templates.ts 預覽站列表。

Q6: 32 個模板都用 Apple 風格，能改顏色嗎？ A: 可以。每個模板都把 background: "#f5f5f7" 直接寫在 style，改成 props 化或抽出 theme 即可。

Q7: 可以渲染影片嗎？需要付費嗎？ A: 用 Remotion 本地渲染完全免費。Remotion 商業使用如年營收 > $100k 需買 license（與 SwiftClip 無關）。

8. 進階技巧

8.1 把 plugin 拆出來作為自己團隊的 plugin 起手式

1cp -r plugins/swiftclip-remotion my-team-plugin
2cd my-team-plugin
3# 改 plugin.json 內 name / description
4# 改 agents/remotion-builder.md 為自己的 agent
5# 改 hooks/hooks.json 與 validate.sh

三件式 (plugin.json + hooks.json + agent.md) 是 Claude plugin 最小可用單元，非常適合複製。

8.2 加新模板的完整流程

1. 寫 remotion/MyNewTemplate.tsx（用既有模板當底）
2. 在 remotion/Root.tsx 加 <Composition id="MyNewTemplate" ... />
3. 在 lib/templates.ts 加入預覽 metadata（id / title / videoUrl / codeSnippet）
4. （選用）放 public/videos/my-new-template.mp4 預覽片
5. npm run dev 驗證 → push

8.3 用 agent 產衍生模板

在 Claude Code session 內：

1我要做一個產品發表片頭，1920×1080、15 秒、主色 #0066cc。
2標題："Helix Studio 2.0"，副標："The AI-first IDE."
3故事板：
4- 0-3s: Logo 從中心 spring 出現
5- 3-8s: 標題 typewriter 一行行打出
6- 8-15s: 三個 feature 卡片 stagger fade-in

agent 會：

1. 路由到 ProductLaunch core template
2. 產 preflight JSON
3. 產 remotion/HelixLaunch.tsx
4. 自動加入 Root.tsx

8.4 4K 渲染

1npx remotion render remotion/index.tsx ProductLaunch output.mp4 \
2  --scale=2 --concurrency=8

8.5 修正 license 標記不一致

1# package.json
2sed -i 's/"license": "ISC"/"license": "MIT"/' package.json
3sed -i 's/"private": "true"/"private": true/' package.json

9. 整合進其他工作流

9.1 與本知識庫其他 Layer 配合

9.2 衍生 / 後續題目

• 論文摘要影片：用 paper-search + paper-tutorial 取得 paper 重點 → 餵 SwiftClip agent 產 60 秒 SocialStory
• 內部 demo 影片自動化：每次 release 時跑 GH Action，從 CHANGELOG.md → ProductLaunch.tsx → 推 Slack
• Storyboard ↔ SwiftMographer：上游用姊妹專案 SwiftMographer 做 storyboard handoff，下游用 SwiftClip 生成

10. 重點摘要 Checklist

• 32 個 Remotion 模板，純 React/TS，Apple Light Mode 統一視覺
• 三層產出：模板 / Next.js 預覽站 / Claude+Codex plugin
• 必須先有 Remotion 專案才能用（npx create-video@latest）
• plugin 三件式 (plugin.json + hooks.json + agent.md) 可獨立複用
• agent 路由到 5 個 core template (ProductLaunch / TutorialIntro / SocialStory / LowerThird / SaaSPromo)
• 資安：🟢 低（無 eval / 無 fetch / 無 secrets）
• License 標 MIT（package.json 有 ISC 筆誤）
• 版本用 commit SHA（未發 npm）
• 姊妹專案 SwiftMographer 處理 storyboard 上游

11. 進一步閱讀

本教學由 gh-tutorial-qd skill 自動生成 / 2026-05-20 / commit 1ab3903。