ClipForge

https://github.com/xixihhhh/clipforge
Admin
ClipForge is an open-source AI-powered short video generator that automatically transforms a single...
Tokens:24,977
Snippets:278
Trust Score:8.6
License:AGPL-3.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Local Development Setup

Source: https://github.com/xixihhhh/clipforge/blob/main/README.md

Clone the repository and install dependencies using pnpm. Ensure pnpm is installed before proceeding.

```bash
# 克隆项目
git clone https://github.com/xixihhhh/clipforge.git
cd clipforge

# 安装依赖（必须用 pnpm）
pnpm install

# 启动开发服务器
pnpm dev

# 打开浏览器
open http://localhost:3000
```

--------------------------------

### Run ClipForge from Source

Source: https://github.com/xixihhhh/clipforge/blob/main/docs/guide.html

Clone the repository and start the development server. Requires pnpm and FFmpeg installed on the host system.

```bash
git clone https://github.com/xixihhhh/clipforge.git
cd clipforge && pnpm install && pnpm dev
```

--------------------------------

### Install ClipForge Skill

Source: https://github.com/xixihhhh/clipforge/blob/main/skills/clipforge-video/SKILL.md

Commands to install the ClipForge skill via npx or manual directory copying.

```bash
npx skills add xixihhhh/clipforge
```

```bash
cp -r skills/clipforge-video ~/.claude/skills/
```

```bash
/plugin marketplace add xixihhhh/clipforge
```

--------------------------------

### Build the ClipForge Plugin

Source: https://github.com/xixihhhh/clipforge/blob/main/integrations/infinite-canvas/README.md

Commands to clone the infinite-canvas repository, install dependencies, and build the plugin from the source directory.

```bash
git clone https://github.com/basketikun/infinite-canvas.git
cp -r clipforge-node infinite-canvas/plugins/canvas/clipforge
cd infinite-canvas/plugins/canvas/sdk && bun install
cd ../clipforge && bun install && bun run build   # → dist/clipforge.js（同步到 web/public/plugins/）
```

--------------------------------

### Start ClipForge Instance

Source: https://github.com/xixihhhh/clipforge/blob/main/docs/mcp.html

Run the ClipForge service using Docker or source code to provide the backend for the MCP server.

```bash
docker run -d -p 3000:3000 -v clipforge-data:/data ghcr.io/xixihhhh/clipforge
# 或源码:git clone https://github.com/xixihhhh/clipforge.git && cd clipforge && pnpm install && pnpm dev
```

--------------------------------

### Run ClipForge Instance with Docker

Source: https://github.com/xixihhhh/clipforge/blob/main/mcp/README.md

Start a ClipForge instance using Docker to provide the base URL for the MCP server.

```bash
docker run -d -p 3000:3000 -v clipforge-data:/data ghcr.io/xixihhhh/clipforge
```

--------------------------------

### Install and Render Motion Graphics

Source: https://github.com/xixihhhh/clipforge/blob/main/remotion/README.md

Commands to install necessary Remotion dependencies and render specific animated elements like title cards or captions.

```bash
# one-time: install the optional Remotion deps (~300MB, headless render shell)
npm i remotion @remotion/cli react react-dom

# render an animated intro title card (9:16, 2.5s) → intro.mp4
npm run render:element -- --kind title --text "在家手冲 三步搞定" --subtitle "COFFEE" --out intro.mp4

# render a kinetic per-word caption
npm run render:element -- --kind caption --text "买它 真的 好用" --aspect 9:16 --duration 3 --out cap.mp4
```

--------------------------------

### Manage Node Dependencies

Source: https://github.com/xixihhhh/clipforge/blob/main/TUTORIAL.md

Commands to ensure correct dependency installation and native module rebuilding for Electron.

```bash
pnpm install
```

```bash
pnpm electron:rebuild
```

--------------------------------

### Install Agent Skills

Source: https://github.com/xixihhhh/clipforge/blob/main/docs/mcp.html

Commands to add ClipForge skills to your development environment for natural language workflow control.

```bash
npx skills add xixihhhh/clipforge
```

```bash
Claude Code 里 /plugin marketplace add xixihhhh/clipforge
```

--------------------------------

### Install ClipForge via Docker

Source: https://github.com/xixihhhh/clipforge/blob/main/docs/guide.html

Run the ClipForge container using Docker. Ensure port 3000 is available on your host machine.

```bash
docker run -d -p 3000:3000 -v clipforge-data:/data ghcr.io/xixihhhh/clipforge:latest
```

--------------------------------

### Deploy with Docker

Source: https://github.com/xixihhhh/clipforge/blob/main/README.md

Run the application using Docker to avoid manual Node.js or FFmpeg installation. Data is persisted in a named volume.

```bash
docker run -d -p 3000:3000 -v clipforge-data:/data ghcr.io/xixihhhh/clipforge
# 打开 http://localhost:3000 —— 免 Key 即可出片（免费素材 + Edge TTS）
```

--------------------------------

### Install System FFmpeg Dependencies

Source: https://github.com/xixihhhh/clipforge/blob/main/TUTORIAL.md

Install FFmpeg via system package managers to ensure required filters like drawtext are available.

```bash
brew install ffmpeg
```

```bash
apt install ffmpeg
```

--------------------------------

### Generate Video via Agent

Source: https://github.com/xixihhhh/clipforge/blob/main/docs/mcp.html

Example prompt to trigger the video generation tool within an AI agent interface.

```text
用 clipforge 做一条关于「在家如何泡手冲咖啡」的竖屏短视频
```

--------------------------------

### 使用 CLI 执行 ClipForge 任务

Source: https://github.com/xixihhhh/clipforge/blob/main/docs/mcp.html

通过 npm 脚本执行视频生成、质检及发布门禁等操作。确保已配置 CLIPFORGE_LLM_* 环境变量。

```bash
npm run cli -- trends                              # 不知道做什么?先拉热搜选题
npm run cli -- create --topic "在家手冲咖啡" --quality hd --bgm   # 一句话出片,回填 videoUrl
npm run cli -- qc --project <id>                   # 成片质检(黑屏/静音/响度)
npm run cli -- gate --project <id> --strict        # 发布门禁,拦截时退出码 2(可接 CI)
npm run cli -- --help                              # 全部命令与参数
```

--------------------------------

### Docker 运维常用命令

Source: https://github.com/xixihhhh/clipforge/blob/main/TUTORIAL.md

用于查看容器状态、日志、停止容器及升级镜像的常用 Docker 操作。

```bash
docker ps                      # 看是否在跑
docker logs -f <容器ID>         # 看日志（启动失败时看这里）
docker stop <容器ID>            # 停止
docker pull ghcr.io/xixihhhh/clipforge:latest   # 升级到最新版（然后 stop 旧容器、用同样命令重新 run，数据卷不动就不会丢数据）
```

--------------------------------

### Configure Development Server Port

Source: https://github.com/xixihhhh/clipforge/blob/main/TUTORIAL.md

Override the default port if the application fails to start due to port conflicts.

```bash
PORT=3001 pnpm dev
```

--------------------------------

### CLI and Environment Configuration Commands

Source: https://github.com/xixihhhh/clipforge/blob/main/docs/guide.html

Commands for script-based video generation and managing local development ports.

```bash
node bin/clipforge.mjs create --topic "..."
```

```bash
PORT=3001 pnpm dev
```

--------------------------------

### 源码运行环境配置

Source: https://github.com/xixihhhh/clipforge/blob/main/TUTORIAL.md

开发者模式下的环境准备与启动流程，需确保已安装 Node.js、pnpm 和 FFmpeg。

```bash
# 1) 装 pnpm（本项目必须用 pnpm，用 npm install 会报错）
corepack enable          # 或者 npm i -g pnpm

# 2) 装 FFmpeg（合成视频要用）
brew install ffmpeg      # macOS
sudo apt install ffmpeg  # Ubuntu / Debian
# Windows：到 https://ffmpeg.org/download.html 下载后把 bin 目录加进 PATH

# 3) 跑起来
git clone https://github.com/xixihhhh/clipforge.git
cd clipforge
pnpm install
pnpm dev
# 打开 http://localhost:3000
```

--------------------------------

### Inspect Docker Logs

Source: https://github.com/xixihhhh/clipforge/blob/main/TUTORIAL.md

Check container logs to diagnose startup failures.

```bash
docker logs
```

--------------------------------

### Linux 赋予执行权限

Source: https://github.com/xixihhhh/clipforge/blob/main/TUTORIAL.md

Linux 下运行 AppImage 文件前需先赋予其可执行权限。

```bash
chmod +x ClipForge-*.AppImage
./ClipForge-*.AppImage
```

--------------------------------

### GET /api/stock/search

Source: https://github.com/xixihhhh/clipforge/blob/main/README.md

Search for media assets across multiple sources. Supports single-source or aggregated searching with automatic prioritization for media type, keyless sources, and vertical orientation.

```APIDOC
## GET /api/stock/search

### Description
Search for images, videos, or audio across various free-to-use media platforms. The API supports aggregated searching to find the best match based on media type and source availability.

### Method
GET

### Endpoint
/api/stock/search

### Parameters
#### Query Parameters
- **source** (string) - Required - The source to search (e.g., "Openverse", "Wikimedia", "Pixabay", "Pexels", "Coverr", "Jamendo", "Freesound") or "all" for aggregated search.
- **query** (string) - Required - The search term (English recommended for better recall).
- **type** (string) - Optional - The media type to filter by (e.g., "image", "video", "audio").

### Response
#### Success Response (200)
- **results** (array) - List of media assets including source, URL, and attribution information.
```

--------------------------------

### Automate Daily Video Production with Cron

Source: https://github.com/xixihhhh/clipforge/blob/main/docs/mcp.html

Use a crontab entry to fetch trending topics and trigger video creation automatically at a scheduled time.

```bash
crontab -e   # 加入下面一行(路径与环境变量换成你的):每天 9 点从国内热榜拿榜一出一条
0 9 * * * cd /path/to/clipforge && TOPIC=$(node bin/clipforge.mjs trends --json | python3 -c "import json,sys;print(json.load(sys.stdin)['topics'][0]['title'])") && node bin/clipforge.mjs create --topic "$TOPIC" --bgm >> daily.log 2>&1
```

--------------------------------

### Development CLI Commands

Source: https://github.com/xixihhhh/clipforge/blob/main/README.md

Standard commands for managing the development lifecycle, including testing, linting, database migrations, and production builds.

```bash
# 运行测试（750+ 用例）
pnpm test

# 代码规范检查
pnpm lint

# 数据库迁移（修改 schema 后生成迁移）
pnpm drizzle-kit generate

# 构建生产版本（含 .next/standalone，供 Electron 打包）
pnpm build

# 打包桌面 App（mac；首次需让 pnpm 装好 electron/ffmpeg 二进制）
pnpm pack:dir   # 出免安装 .app 到 release/（快，验证布局）
pnpm dist       # 出 .dmg 安装包
```

--------------------------------

### Execute ClipForge CLI Commands

Source: https://github.com/xixihhhh/clipforge/blob/main/TUTORIAL.md

Common commands for managing projects, generating content, and performing quality checks via the CLI.

```bash
node bin/clipforge.mjs trends                                          # 拉热搜选题
node bin/clipforge.mjs create --topic "在家手冲咖啡" --quality hd --bgm  # 一句话出片，最后打印 videoUrl
node bin/clipforge.mjs list                                            # 列出项目
node bin/clipforge.mjs get --project <id>                              # 查最新成片地址
node bin/clipforge.mjs qc --project <id>                               # 成片质检（黑屏/静音/响度）
node bin/clipforge.mjs gate --project <id> --strict                    # 发布门禁，拦截时退出码 2
node bin/clipforge.mjs --help                                          # 全部命令
```

--------------------------------

### Configure MCP via npx

Source: https://github.com/xixihhhh/clipforge/blob/main/mcp/README.md

Use npx for zero-installation integration once the package is published to npm.

```json
{
  "mcpServers": {
    "clipforge": {
      "command": "npx",
      "args": ["-y", "clipforge-mcp"],
      "env": {
        "CLIPFORGE_BASE_URL": "http://localhost:3000",
        "CLIPFORGE_LLM_BASE_URL": "https://api.atlascloud.ai/v1",
        "CLIPFORGE_LLM_API_KEY": "sk-...",
        "CLIPFORGE_LLM_MODEL": "deepseek-ai/deepseek-v4-pro"
      }
    }
  }
}
```

--------------------------------

### CLI Video Generation Commands

Source: https://github.com/xixihhhh/clipforge/blob/main/README.md

Use the ClipForge CLI to manage projects, generate content from trends, create videos, and perform quality checks.

```bash
node bin/clipforge.mjs trends                                            # 不知道做什么？先拉热搜选题(默认抖音/头条国内榜,--geo US 走 Google Trends)
node bin/clipforge.mjs create --topic "在家手冲咖啡" --quality hd --bgm   # 一句话出片，回填 videoUrl
node bin/clipforge.mjs import --project <id> --file my-script.txt        # 用自己写好的稿子出片
node bin/clipforge.mjs dub --project <id> --lang en                      # 换语种译制(出海)，再 compose
node bin/clipforge.mjs cover --project <id> --title "手冲咖啡 三步搞定"     # 给成片生成封面图(提升点击率)
node bin/clipforge.mjs qr --project <id> --platform douyin               # 生成商品「扫码购买」二维码(UTM追踪)
node bin/clipforge.mjs qc --project <id>                                 # 成片质检(黑屏/静音/响度,发布前把关)
node bin/clipforge.mjs gate --project <id> --strict                      # 发布门禁:脚本就绪+质检+授权一键体检,拦截时退出码 2
node bin/clipforge.mjs credits --project <id> --format md                # 素材授权清单(商用风险+署名行,投流审核用)
node bin/clipforge.mjs native --project <id> --strength medium           # 原生感处理(手持感+颗粒,反AI精致感)
node bin/clipforge.mjs preview --project <id>                            # 生成预览 GIF(分享/嵌入)
node bin/clipforge.mjs carousel --project <id>                           # 生成小红书图文卡片(标题+逐条要点)
node bin/clipforge.mjs list            # 列出项目
node bin/clipforge.mjs --help          # 全部命令与参数
```

--------------------------------

### Docker Execution Command

Source: https://github.com/xixihhhh/clipforge/blob/main/docs/guide.html

Recommended command for running the ClipForge Docker container with persistent data storage.

```bash
run 时一定要带 -v clipforge-data:/data
```

--------------------------------

### 下载本地模型

Source: https://github.com/xixihhhh/clipforge/blob/main/TUTORIAL.md

使用 Ollama 命令行工具下载指定的中文模型，适用于本地离线运行环境。

```bash
ollama pull qwen2.5
```

--------------------------------

### POST /api/project/[id]/stock-fill

Source: https://github.com/xixihhhh/clipforge/blob/main/README.md

Automatically populate project segments with stock media. This endpoint analyzes script segments and retrieves matching assets from free libraries to fill gaps.

```APIDOC
## POST /api/project/[id]/stock-fill

### Description
Automatically matches and fills project segments with appropriate stock media based on the script's generated search terms. It prioritizes local assets and free stock sources while preserving product image integrity.

### Method
POST

### Endpoint
/api/project/{id}/stock-fill

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **status** (string) - Confirmation of the stock filling process completion.
- **filled_segments** (integer) - Number of segments successfully populated with media.
```
Tokens:
Raw