### Environment setup and verification for autoclip

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/DEVELOPER_GUIDE.md

Set up the development environment for the repository: clone, create and activate a virtual environment, install Python dependencies and frontend packages, then run backend tests and frontend lint, typecheck, tests, and build.

```bash
git clone https://github.com/zhouxiaoka/autoclip.git
cd autoclip
python3 -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
(cd frontend && npm ci)
python -m pytest backend/tests -q
(cd frontend && npm run lint && npm run typecheck && npm test && npm run build)
```

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

### Test environment setup

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_SETUP.md

For test environments, no installation is needed; the system will automatically generate test subtitle files.

```bash
# 无需安装，使用测试字幕
# 系统会自动生成测试字幕文件
```

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

### Preview community board setup

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/COMMUNITY_BOARD.md

Runs the setup script in preview mode to show what categories are missing and how to fix them, without making changes.

```bash
python3 scripts/setup_community_board.py
```

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

### Start backend with python main.py

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SYSTEM_REBUILD_GUIDE.md

Starts the backend service. Run from the project root; first change to the backend directory. The service listens on port 8000.

```bash
cd backend
python main.py
```

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

### Install base model for development

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_SETUP.md

Install the base model for development environments, balancing speed and accuracy.

```bash
pip install openai-whisper
```

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

### Install autoclip from source

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/CLI_AND_MCP.md

Clones the repository, creates and activates a virtual environment, installs dependencies, and installs the package in editable mode to provide the autoclip and autoclip-mcp commands. Requires ffmpeg in PATH and optionally faster-whisper for local transcription.

```bash
git clone https://github.com/zhouxiaoka/autoclip.git && cd autoclip
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
pip install -e .            # 得到 autoclip / autoclip-mcp 两个命令
```

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

### Install for production

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_SETUP.md

Install openai-whisper for production environments, optionally using GPU acceleration for better performance.

```bash
pip install openai-whisper
# 考虑使用GPU加速
```

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

### Verify Windows installation

Source: https://github.com/zhouxiaoka/autoclip/blob/main/RELEASE_CHECKLIST.md

Run Windows installation verification using the installed Python; checks ffmpeg, Chinese filenames, yt-dlp, backend startup, and source guard.

```bash
scripts/verify_windows_install.py
```

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

### Clone and prepare .env

Source: https://github.com/zhouxiaoka/autoclip/blob/main/DOCKER.md

Clones the repository, enters the project directory, and copies the environment template to .env for initial setup.

```bash
git clone https://github.com/zhouxiaoka/autoclip.git
cd autoclip
cp env.example .env
```

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

### Logging for speech recognition

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_REDESIGN.md

Python logging setup and examples for logging the start, success, and failure of speech recognition operations.

```python
import logging
logger = logging.getLogger(__name__)

# 语音识别开始
logger.info(f"开始语音识别: {video_path}")

# 语音识别成功
logger.info(f"语音识别成功: {output_path}")

# 语音识别失败
logger.error(f"语音识别失败: {error}")
```

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

### Install wheel and run autoclip produce with --portrait-style podcast

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/RELEASE_1_5.md

Install the wheel in a fresh virtual environment (Python 3.11 recommended, FFmpeg/FFprobe on PATH), then produce a portrait-style video from an existing SRT and export kits. Use --force-reinstall --no-deps to replace an older 1.5.0 candidate wheel; Windows activation uses .venv\Scripts\Activate.ps1.

```bash
# 解压到一个目录后，建立同事自己的虚拟环境。建议 Python 3.11，需 FFmpeg / FFprobe 在 PATH。
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m pip install --force-reinstall --no-deps autoclip-1.5.0-py3-none-any.whl
autoclip --version

# 复用已保存的桌面模型配置；已有字幕可跳过语音识别。
autoclip produce /absolute/path/talk.mp4 --srt /absolute/path/talk.srt --platform douyin --portrait-style podcast --json
autoclip outputs PROJECT_ID --export-kits
```

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

### 命令行运行 app 查看后端输出

Source: https://github.com/zhouxiaoka/autoclip/blob/main/BUILD_GUIDE.md

直接运行 app 可执行文件以查看后端日志。应看到 'Backend started on port: XXXXX' 和 'Application startup complete'。

```bash
'/Applications/AutoClip Desktop.app/Contents/MacOS/autoclip-desktop'
```

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

### Run development server

Source: https://github.com/zhouxiaoka/autoclip/blob/main/frontend/README.md

Starts the development server for local development.

```bash
npm run dev
```

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

### Start development mode

Source: https://github.com/zhouxiaoka/autoclip/blob/main/DOCKER.md

Starts the development orchestration and follows its logs. Do not run it simultaneously with the production orchestration because they may use the same ports.

```bash
docker compose -f docker-compose.dev.yml up -d --build
docker compose -f docker-compose.dev.yml logs -f
```

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

### Start frontend with npm run dev

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SYSTEM_REBUILD_GUIDE.md

Starts the frontend development server. Run from the project root; first change to the frontend directory. The frontend is served on port 3000.

```bash
cd frontend
npm run dev
```

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

### Test Whisper and FFmpeg installation

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/OPTIONAL_SRT_UPLOAD_GUIDE.md

Verify that Whisper and FFmpeg are correctly installed and accessible from the command line. Use this when debugging Whisper installation issues.

```bash
whisper --help
ffmpeg -version
```

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

### GET /api/v1/speech-recognition/install-guide

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_REDESIGN.md

获取指定语音识别服务的安装指南。

```APIDOC
## GET /api/v1/speech-recognition/install-guide

### Description
获取指定语音识别服务的安装指南。

### Method
GET

### Endpoint
/api/v1/speech-recognition/install-guide

### Parameters
#### Query Parameters
- **method** (string) - Required - 语音识别服务方法，如whisper_local

```

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

### Verify Whisper installation

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_SETUP.md

Verify that Whisper is installed correctly by displaying its help information.

```bash
whisper --help
```

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

### Install local Whisper and dependencies

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_REDESIGN.md

Commands to install Python dependencies (openai-whisper) and system dependencies (ffmpeg) for Ubuntu/Debian, macOS, and Windows. Verify installation with 'whisper --help'.

```bash
# 安装Python依赖
pip install openai-whisper

# 安装系统依赖
# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows
# 下载ffmpeg并添加到PATH

# 验证安装
whisper --help
```

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

### start_quick_output

Source: https://github.com/zhouxiaoka/autoclip/blob/main/skills/autoclip/SKILL.md

Starts a quick output job to generate platform-ready videos from a local video or a supported URL. This is the preferred method for publishing finished videos.

```APIDOC
## start_quick_output

### Description
Starts a quick output job to generate platform-ready videos from a local video or a supported URL. This is the preferred method for publishing finished videos.

### Method
MCP Tool

### Endpoint
`start_quick_output`

### Parameters
#### Request Body
- **source** (string) - Required - Local video absolute path or HTTPS URL from Bilibili or YouTube.
- **platforms** (array of string) - Required - Target platforms: douyin, xiaohongshu, bilibili, tiktok, instagram_reels, youtube_shorts, youtube_long.
- **srt_path** (string) - Optional - Path to an existing subtitle file to skip transcription.
- **portrait_style** (string) - Optional - Portrait layout style: auto, interview, or podcast. Only affects vertical layout; language follows platform.

### Response
- **id** (string) - The job ID to poll with get_quick_output_status.

```

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

### Start development server with npm or yarn

Source: https://github.com/zhouxiaoka/autoclip/blob/main/frontend/README.md

Launch the development server using either npm or yarn. The comment '# 或' indicates the alternative command.

```bash
npm run dev
# 或
yarn dev
```

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

### Install missing dependencies

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_SETUP.md

Install missing system dependencies (ffmpeg) and Python dependencies (torch, torchvision, torchaudio) for Whisper.

```bash
# 安装系统依赖（Ubuntu/Debian）
sudo apt update
sudo apt install ffmpeg

# 安装系统依赖（macOS）
brew install ffmpeg

# 安装Python依赖
pip install torch torchvision torchaudio
```

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

### AutoClip contribution workflow commands

Source: https://github.com/zhouxiaoka/autoclip/blob/main/CONTRIBUTING.md

These bash commands cover the workflow for contributing to AutoClip: cloning and setting up the repository, installing dependencies, running quality checks and tests, and submitting a pull request. They apply to macOS/Linux for web development; Windows desktop setups require different toolchain steps.

```bash
cd autoclip
git remote add upstream https://github.com/zhouxiaoka/autoclip.git
git fetch upstream
git switch -c fix/your-change upstream/main

```

```bash
python3 -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
(cd frontend && npm ci)
cp env.example .env

```

```bash
python scripts/quality_gate.py --report /absolute/local/evidence/quality.json

```

```bash
python -m pytest backend/tests -q
# 开发时可先运行与改动相关的现有测试文件

```

```bash
cd frontend
npm run lint
npm run typecheck
npm test
npm run build

```

```bash
git add -p
git commit -m "fix: describe the problem being resolved"
git push -u origin fix/your-change

```

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

### Install openai-whisper

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_SETUP.md

Install openai-whisper using pip, conda, or from source. Choose one method based on your environment.

```bash
pip install openai-whisper
```

```bash
conda install -c conda-forge openai-whisper
```

```bash
git clone https://github.com/openai/whisper.git
cd whisper
pip install -e .
```

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

### Install dependencies with npm or yarn

Source: https://github.com/zhouxiaoka/autoclip/blob/main/frontend/README.md

Install project dependencies using either npm or yarn. The comment '# 或' indicates the alternative command.

```bash
npm install
# 或
yarn install
```

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

### 一键安装 opencode MCP 配置

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/OPENCODE.md

运行 `autoclip mcp install opencode` 将 AutoClip 作为 MCP server 写入 opencode 配置。命令会探测启动命令、合并配置，并在文件已存在时备份为 `opencode.json.bak`。

```bash
autoclip mcp install opencode
# ✓ 已写入 ~/.config/opencode/opencode.json（Windows: %USERPROFILE%\.config\opencode\opencode.json）
```

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

### Initialize release acceptance template with scripts/release_acceptance.py

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/TESTING_ACCEPTANCE.md

Generates an empty acceptance template for a release candidate. All fields start as pending; fill in platforms, regressions, blockers, observation, and approval with real results, and use timezone-aware ISO timestamps. Evidence must be non-empty sanitized Markdown/JSON files in the same directory, and each scenario must be recorded individually.

```bash
python scripts/release_acceptance.py init \
  --tag vX.Y.Z --commit FULL_40_CHAR_SHA --build-run-id BUILD_RUN_ID \
  --release-type hotfix --assets /absolute/local/release-assets \
  --manifest /absolute/local/acceptance/acceptance.json
```

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

### Run autoclip-desktop backend binary

Source: https://github.com/zhouxiaoka/autoclip/blob/main/HANDOFF.md

Run the AutoClip desktop backend binary from the macOS app bundle to diagnose startup issues. Expect a line like `Backend started on port: XXXXX` or `Application startup complete` when healthy.

```bash
'/Applications/AutoClip Desktop.app/Contents/MacOS/autoclip-desktop'
# 应看到 Backend started on port: XXXXX / Application startup complete
```

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

### Seed issues after approving seed list

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/COMMUNITY_BOARD.md

Runs the setup script with --apply and --seed-issues to create issues from the seed list.

```bash
python3 scripts/setup_community_board.py --apply --seed-issues
```

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

### Install local Whisper and FFmpeg

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/OPTIONAL_SRT_UPLOAD_GUIDE.md

Install the local Whisper speech recognition service along with FFmpeg on macOS or Ubuntu/Debian. This is the recommended configuration.

```bash
# 安装Whisper
pip install openai-whisper

# 安装FFmpeg
# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt install ffmpeg
```

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

### Upload API: request example for video only

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/OPTIONAL_SRT_UPLOAD_GUIDE.md

Example of uploading only a video file, relying on AI speech recognition for subtitles.

```python
files = {
    'video_file': ('video.mp4', video_content, 'video/mp4')
}
data = {
    'project_name': '我的项目',
    'video_category': 'knowledge'
}
```

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

### Upload API: request example for video with SRT file

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/OPTIONAL_SRT_UPLOAD_GUIDE.md

Example of uploading both video and SRT subtitle files together.

```python
files = {
    'video_file': ('video.mp4', video_content, 'video/mp4'),
    'srt_file': ('subtitle.srt', srt_content, 'application/x-subrip')
}
data = {
    'project_name': '我的项目',
    'video_category': 'knowledge'
}
```

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

### Build, fix ownership, and start services

Source: https://github.com/zhouxiaoka/autoclip/blob/main/DOCKER.md

Builds and starts the stack, then fixes ownership of the bind-mounted directories so the container's autoclip user can write to them. The chown command modifies file ownership and is especially for Linux; run it on empty directories for new deployments. Avoid setting permissions to 777.

```bash
mkdir -p data logs uploads
docker compose build
docker compose run --rm --no-deps --user root --entrypoint sh autoclip -c 'chown -R autoclip:autoclip /app/data /app/logs /app/uploads'
docker compose up -d
docker compose ps
```

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

### Dockerfile for deployment

Source: https://github.com/zhouxiaoka/autoclip/blob/main/frontend/README.md

Defines a Docker image using Node 16 Alpine, installs dependencies, builds the app, and runs the preview server on port 3000.

```dockerfile
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "run", "preview"]
```

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

### Validate path configurations with validate_paths.py

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SYSTEM_REBUILD_GUIDE.md

Validates all path configurations. Run from the project root. Output indicates any inconsistencies or errors in the path setup.

```bash
# 验证所有路径配置
python scripts/validate_paths.py
```

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

### Run regression, backend pytest, and standalone reproduction commands

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/ANALYTICS_SYSTEM_REVIEW_2026-09-29.md

Commands used to verify the analytics system review. The first runs the frontend regression suite (36/36 passing). The second attempts the backend Sentry setup test but fails because pytest is missing. The third runs a standalone reproduction script that loads real TypeScript source and isolates network/storage to confirm current F2/F3 defects.

```bash
node --test frontend/tests/analytics.test.cjs frontend/tests/studio-native-download.test.cjs frontend/tests/sentry-build.test.cjs frontend/tests/feedback-draft.test.cjs
```

```bash
.venv/bin/python -m pytest backend/tests/test_sentry_setup.py -q
```

```bash
node docs/evidence/analytics-review-repro-20260929.cjs
```

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

### Configure LLM provider in .env

Source: https://github.com/zhouxiaoka/autoclip/blob/main/DOCKER.md

Example .env configuration for DashScope provider. Model availability depends on provider and account permissions. Saved settings in the web UI may override environment variables.

```dotenv
LLM_PROVIDER=dashscope
API_MODEL_NAME=qwen-plus
API_DASHSCOPE_API_KEY=your_api_key
```

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

### MCP start_quick_output and get_quick_output_status payloads

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/CLI_AND_MCP.md

JSON payloads for MCP `start_quick_output` and `get_quick_output_status`. The first starts a quick output job; the second polls its status with the returned project ID and optional kit export.

```json
{"source":"/absolute/path/talk.mp4","srt_path":"/absolute/path/talk.srt","platforms":["douyin","youtube_shorts"],"portrait_style":"podcast"}
```

```json
{"project_id":"返回的ID","export_kits":true}
```

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

### Configure local Ollama model

Source: https://github.com/zhouxiaoka/autoclip/blob/main/DOCKER.md

Example .env configuration for using a local Ollama model from Docker Desktop. The hostname resolves but does not guarantee connectivity; the host model must listen on an interface accessible from the container and the firewall must allow the connection.

```dotenv
LLM_PROVIDER=ollama
OPENAI_BASE_URL=http://host.docker.internal:11434/v1
API_MODEL_NAME=qwen2.5:7b
```

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

### Build and preview production

Source: https://github.com/zhouxiaoka/autoclip/blob/main/frontend/README.md

Builds the production bundle and then previews it locally.

```bash
npm run build
npm run preview
```

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

### Configure MCP server for OpenCode

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/CLI_AND_MCP.md

Configuration for OpenCode to use the AutoClip MCP server. Place in ~/.config/opencode/opencode.json or a project-level opencode.json; commented .jsonc is also supported. AutoClip can generate this via 'autoclip mcp install opencode'.

```json
{
  "mcp": {
    "autoclip": { "type": "local", "command": ["/path/to/autoclip/venv/bin/autoclip", "mcp"], "enabled": true }
  }
}
```

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

### GET /api/v1/publish/upload-post/requests/{request_id}

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/PUBLISH_UPLOAD_POST.md

Directly queries Upload-Post by request_id to get the publish status.

```APIDOC
## GET /api/v1/publish/upload-post/requests/{request_id}

### Description
Directly queries Upload-Post by request_id to get the publish status.

### Method
GET

### Endpoint
/api/v1/publish/upload-post/requests/{request_id}

### Parameters
#### Path Parameters
- **request_id** (string) - Required - The ID of the publish request.

### Response
#### Success Response (200)
- **status** (string) - The status of the request.
- **results** (array) - Per-platform results.

#### Response Example
{
  "status": "completed",
  "results": [
    {
      "platform": "youtube",
      "success": true,
      "url": "https://...",
      "error": null,
      "skipped": false
    }
  ]
}
```

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

### 运行验收脚本（基本用法）

Source: https://github.com/zhouxiaoka/autoclip/blob/main/scripts/winqa/README.md

设置必需的环境变量 WINQA_HOST 和 WINQA_USER，然后调用 run_winqa.sh 指定上一版和候选安装包路径及版本号。可选参数包括 --prev-version、--marker、--with-asr、--no-smoke、--no-failure、--out 和续跑参数。

```bash
export WINQA_HOST=<验收机地址> WINQA_USER=<Windows 账号>
scripts/winqa/run_winqa.sh \
  --prev      /path/AutoClip.Desktop_<上一正式版>_x64-setup.exe \
  --candidate "/path/AutoClip Desktop_<候选>_x64-setup.exe" \
  --version   <候选版本号>
# 可选：--prev-version X.Y.Z  --marker 'resources\backend\...'（只在新版存在的文件）
#       --with-asr  --no-smoke  --no-failure  --out DIR
# 续跑：--out <原证据目录> --from-step N [--to-step M]
```

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

### 启动与管理脚本：start_autoclip.sh 等

Source: https://github.com/zhouxiaoka/autoclip/blob/main/STARTUP_GUIDE.md

提供前台运行、后台运行、状态检查和停止服务的脚本。脚本从自身所在目录运行，可从其他目录调用。后台模式也可使用 --detach 参数。

```bash
./start_autoclip.sh             # 前台运行，Ctrl+C 停止本次启动的服务
./quick_start.sh                # 同一启动流程，通过健康检查后转入后台
./status_autoclip.sh            # 返回非零状态表示服务缺失或检查失败
./stop_autoclip.sh              # 停止当前 checkout 记录的服务及子进程
```

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

### 设置社区看板（setup_community_board.py）

Source: https://github.com/zhouxiaoka/autoclip/blob/main/HANDOFF.md

运行此脚本以在 GitHub 上创建标签和公开 Project。脚本会列出需要手动在网页上新建或修改的 Discussion 分类，因为 Discussion 分类没有写入接口。使用 --seed-issues 参数可避免一次创建过多种子 Issue。

```bash
python3 scripts/setup_community_board.py --apply
```

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

### Backup data and configuration

Source: https://github.com/zhouxiaoka/autoclip/blob/main/DOCKER.md

Stops services, creates a timestamped backup archive of the data, logs, uploads directories and .env, then restarts services. The backup contains local videos and possibly sensitive configuration; store it in a controlled location.

```bash
docker compose stop
tar -czf "../autoclip-backup-$(date +%Y%m%d-%H%M%S).tar.gz" data logs uploads .env
docker compose start
```

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

### GET /api/v1/speech-recognition/status

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_REDESIGN.md

查询语音识别服务的可用方法、支持的语言、Whisper模型和默认配置。

```APIDOC
## GET /api/v1/speech-recognition/status

### Description
查询语音识别服务的可用方法、支持的语言、Whisper模型和默认配置。

### Method
GET

### Endpoint
/api/v1/speech-recognition/status

### Response
#### Success Response (200)
- **available_methods** (object) - 各语音识别服务是否可用
- **supported_languages** (array) - 支持的语言代码列表
- **whisper_models** (array) - 可用的Whisper模型列表
- **default_config** (object) - 默认配置，包括method、language、model、timeout

#### Response Example
{
  "available_methods": {
    "whisper_local": true,
    "openai_api": false,
    "azure_speech": false,
    "google_speech": false,
    "aliyun_speech": false
  },
  "supported_languages": ["zh", "en", "ja", "ko", "auto"],
  "whisper_models": ["tiny", "base", "small", "medium", "large"],
  "default_config": {
    "method": "whisper_local",
    "language": "auto",
    "model": "base",
    "timeout": 300
  }
}
```

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

### PostHog 环境变量配置

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/ANALYTICS.md

在 frontend/.env.local 中配置 PostHog 的 key 和 host，缺省时埋点全程 no-op。模板见 frontend/.env.example。

```text
VITE_PUBLIC_POSTHOG_KEY=phc_xxx
VITE_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
```

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

### GET /api/v1/publish/upload-post/profiles

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/PUBLISH_UPLOAD_POST.md

Lists all profiles and the platforms each profile is connected to.

```APIDOC
## GET /api/v1/publish/upload-post/profiles

### Description
Lists all profiles and the platforms each profile is connected to.

### Method
GET

### Endpoint
/api/v1/publish/upload-post/profiles

### Response
#### Success Response (200)
- **profiles** (array) - List of profiles, each with connected platforms.

#### Response Example
{
  "profiles": [
    {
      "name": "main",
      "platforms": ["tiktok", "youtube"]
    }
  ]
}
```

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

### 安装脚本：复制同步文件并提交

Source: https://github.com/zhouxiaoka/autoclip/blob/main/scripts/website/README.md

在官网仓库目录下运行，将同步脚本和教程页复制到 autoclip_intro 仓库，并提交更改。

```bash
bash scripts/website/install.sh ../autoclip_intro
cd ../autoclip_intro && git add -A && git commit -m "build: sync release info automatically" && git push
```

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

### 检查 Upload-Post 配置和平台列表

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/PUBLISH_UPLOAD_POST.md

使用 CLI 命令 `autoclip publish --list-profiles` 检查配置是否就绪，并列出每个 profile 已连接的社交平台。输出示例显示了 profile 'main' 和 'brand' 的平台列表。

```bash
autoclip publish --list-profiles
# ● main          tiktok, youtube, instagram
#   brand         linkedin
```

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

### GET /api/v1/publish/upload-post/{project_id}/records

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/PUBLISH_UPLOAD_POST.md

Retrieves the publish records for a specific project.

```APIDOC
## GET /api/v1/publish/upload-post/{project_id}/records

### Description
Retrieves the publish records for a specific project.

### Method
GET

### Endpoint
/api/v1/publish/upload-post/{project_id}/records

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **records** (array) - List of publish records.

#### Response Example
{
  "records": [
    {
      "clip_id": "clip_123",
      "platforms": ["tiktok"],
      "status": "submitted",
      "created_at": "2026-10-01T09:00:00Z"
    }
  ]
}
```

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

### Run autoclip with provider and options

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/CLI_AND_MCP.md

Runs the main pipeline on a video file with various options: using the desktop app's configured model, specifying a provider (ollama, lmstudio, openai), providing an SRT file, setting a category and minimum score, or outputting JSON for scripting. The --json flag makes stdout contain only a JSON object.

```bash
autoclip run talk.mp4                                  # 用桌面应用设置页里配好的模型
autoclip run talk.mp4 --provider ollama                # 本地 Ollama（默认 qwen2.5:7b，无需 key）
autoclip run talk.mp4 --provider lmstudio --model qwen2.5-7b-instruct
autoclip run talk.mp4 --provider openai --base-url https://api.deepseek.com/v1 --model deepseek-chat --api-key sk-...
autoclip run talk.mp4 --srt talk.srt --category knowledge --min-score 0.6
autoclip run talk.mp4 --json                           # 给脚本 / agent：stdout 只有一个 JSON
```

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

### Fix whisper command not found

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_SETUP.md

Troubleshoot 'whisper: command not found' by checking installation, reinstalling, and verifying PATH.

```bash
# 检查是否安装成功
pip list | grep whisper

# 重新安装
pip uninstall openai-whisper
pip install openai-whisper

# 检查PATH
which whisper
```

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

### 更新和检查yt-dlp版本

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SUBTITLE_DOWNLOAD_TROUBLESHOOTING.md

更新yt-dlp到最新版本并检查当前版本。

```bash
pip install --upgrade yt-dlp
```

```bash
yt-dlp --version
```

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

### 真实私密试发脚本（verify_live_publish.py）

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/PUBLISH_UPLOAD_POST.md

使用环境变量配置 API Key、用户、平台和 B 站 Cookie，然后运行脚本生成 3 秒试片进行真实私密发布。脚本不会打印密钥。

```bash
export UPLOAD_POST_API_KEY=…
export UPLOAD_POST_USER=main          # 可选
export UPLOAD_POST_PLATFORM=youtube   # 或 tiktok
export BILIBILI_COOKIE='SESSDATA=…; bili_jct=…; DedeUserID=…'
python3 scripts/verify_live_publish.py
```

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

### docker compose up -d --build for AutoClip

Source: https://github.com/zhouxiaoka/autoclip/blob/main/HANDOFF.md

Start the entire stack in detached mode and rebuild images. The frontend is exposed at http://localhost:3000 and the API health endpoint at http://localhost:8000/api/v1/health/. On a Linux host, run `mkdir -p data logs uploads && chmod -R 777 data logs uploads` before the first start because the container runs as a non-root user.

```bash
docker compose up -d --build
# 前端 http://localhost:3000 · API http://localhost:8000/api/v1/health/
```

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

### Upload API: success response example

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/OPTIONAL_SRT_UPLOAD_GUIDE.md

Success response indicating that subtitle generation via speech recognition will be used.

```json
{
    "id": "project-id",
    "name": "我的项目",
    "description": "Video: video.mp4 (Will generate subtitle using speech recognition)",
    "settings": {
        "auto_generate_subtitle": true,
        "video_category": "knowledge"
    }
}
```

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

### 运行真实模型场景（--real）

Source: https://github.com/zhouxiaoka/autoclip/blob/main/scripts/winqa/README.md

真实模型场景（第 10–14 步）会产生模型费用，需要授权后运行。先通过 read -rs 读取 API key 并导出，然后调用 run_winqa.sh 并指定 --real、模型接口、模型名等参数。

```bash
read -rs WINQA_MODEL_API_KEY && export WINQA_MODEL_API_KEY   # 不要写进 shell 历史
scripts/winqa/run_winqa.sh ... --real --model-base-url <接口地址> --model <模型> [--model-provider dashscope] \
  [--bili-url <B 站公开短视频>] [--hf-mirror] --from-step 10 --to-step 14
```

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

### 运行 CLI 处理视频（autoclip run）

Source: https://github.com/zhouxiaoka/autoclip/blob/main/HANDOFF.md

使用真实视频运行 CLI 端到端测试，指定 provider 为 ollama 并输出 JSON 格式结果。

```bash
autoclip run --provider ollama --json
```

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

### Run Windows QA harness

Source: https://github.com/zhouxiaoka/autoclip/blob/main/RELEASE_CHECKLIST.md

Run the Windows QA harness (steps 0-9 zero-cost; steps 10-14 with --real for real model scenarios). Use --from-step/--to-step to rerun affected steps.

```bash
run_winqa.sh
```

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

### GET /api/v1/publish/upload-post/config

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/PUBLISH_UPLOAD_POST.md

Retrieves the current configuration status, including whether it is configured, masked API key, default profile, and supported platforms.

```APIDOC
## GET /api/v1/publish/upload-post/config

### Description
Retrieves the current configuration status, including whether it is configured, masked API key, default profile, and supported platforms.

### Method
GET

### Endpoint
/api/v1/publish/upload-post/config

### Response
#### Success Response (200)
- **configured** (boolean) - Whether the configuration is set.
- **api_key_masked** (string) - The API key with masking.
- **default_profile** (string) - The default profile name.
- **supported_platforms** (array) - List of supported platforms.

#### Response Example
{
  "configured": true,
  "api_key_masked": "sk-****",
  "default_profile": "main",
  "supported_platforms": ["tiktok", "youtube"]
}
```

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

### CLI 导出项目为短视频预设

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/FAQ.md

用于将项目导出为短视频预设（如 shorts）。需将 PROJECT_ID 替换为真实项目 ID。其他预设包括 douyin、xiaohongshu、bilibili 和 original。

```bash
autoclip export PROJECT_ID --preset shorts
```

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

### start_clip_job

Source: https://github.com/zhouxiaoka/autoclip/blob/main/skills/autoclip/SKILL.md

Starts an asynchronous clipping job for long videos or when tool calls have timeout limits. Poll with get_job_status every 10-20 seconds.

```APIDOC
## start_clip_job

### Description
Starts an asynchronous clipping job for long videos or when tool calls have timeout limits. Poll with get_job_status every 10-20 seconds.

### Method
MCP Tool

### Endpoint
`start_clip_job`

### Parameters
#### Request Body
- **video_path** (string) - Required - Absolute path to the video file.
- **srt_path** (string) - Optional - Path to an existing subtitle file to skip Whisper transcription.
- **category** (string) - Optional - Content category: default, knowledge, business, opinion, experience, speech, content_review, entertainment. Defaults to default.
- **min_score** (number) - Optional - Minimum score threshold (0-1). Default 0.7. If no clips found, retry with 0.5.
- **provider** (string) - Optional - Model provider: ollama or lmstudio. If omitted, uses the model configured in the desktop app.
- **model** (string) - Optional - Model name, only when explicitly specified.
- **base_url** (string) - Optional - Base URL for the model API, only when explicitly specified.
- **api_key** (string) - Optional - API key for the model, only when explicitly specified.

### Response
- **job_id** (string) - The job ID to poll with get_job_status.

```

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

### 本地启动后端并加载 .env 中的 SENTRY_DSN

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/UPDATES_AND_SENTRY.md

从项目根目录启动 uvicorn，通过 --env-file 加载 .env 中的 SENTRY_DSN，否则 init_sentry() 不会自动启用。

```bash
venv/bin/python -m uvicorn backend.main:app --env-file .env --host 127.0.0.1 --port 8000
```

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

### Whisper command parameters

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/SPEECH_RECOGNITION_SETUP.md

Example of the Whisper command used in shared/utils/speech_recognizer.py. Modify parameters like --language and --model to adjust recognition.

```python
cmd = [
    'whisper',
    str(video_path),
    '--output_dir', str(output_path.parent),
    '--output_format', 'srt',
    '--language', 'zh',  # 语言：zh(中文), en(英文), auto(自动检测)
    '--model', 'base'    # 模型：tiny, base, small, medium, large
]
```

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

### Upload API: error response example

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/OPTIONAL_SRT_UPLOAD_GUIDE.md

400 error response when speech recognition fails, advising manual subtitle upload or checking the service configuration.

```json
{
    "detail": "语音识别失败: 没有可用的语音识别服务，请安装whisper或配置API密钥。请手动上传字幕文件或检查语音识别服务配置。"
}
```

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

### 运行快速出片基准测试脚本

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/FAST_OUTPUT_BENCHMARK.md

使用 scripts/fast_output_benchmark.py 运行回归测试集。不带 --cases 时跑全部用例；--cases 指定部分用例；--baseline 传入上次报告路径时，表格会给出与上次的差值。

```bash
python scripts/fast_output_benchmark.py --data-dir <dir>                       # 全部
python scripts/fast_output_benchmark.py --data-dir <dir> --cases kojima-wired  # 指定几条
python scripts/fast_output_benchmark.py --data-dir <dir> --baseline benchmarks/fast_output/reports/<上次>.json
```

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

### GET /api/v1/publish/upload-post/jobs/{job_id}

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/PUBLISH_UPLOAD_POST.md

Retrieves the status of a local publish job. Status can be queued, running, submitted, or failed. When submitted, it includes request_id and remote results.

```APIDOC
## GET /api/v1/publish/upload-post/jobs/{job_id}

### Description
Retrieves the status of a local publish job. Status can be queued, running, submitted, or failed. When submitted, it includes request_id and remote results.

### Method
GET

### Endpoint
/api/v1/publish/upload-post/jobs/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the job.

### Response
#### Success Response (200)
- **status** (string) - Job status: queued, running, submitted, or failed.
- **request_id** (string) - Present when status is submitted.
- **remote** (object) - Present when status is submitted, contains per-platform results.

#### Response Example
{
  "status": "submitted",
  "request_id": "req_123",
  "remote": {
    "results": [
      {
        "platform": "tiktok",
        "success": true,
        "url": "https://...",
        "error": null,
        "skipped": false
      }
    ],
    "final": true
  }
}
```

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

### Run backend tests for package 2B-Backend

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/FAST_OUTPUT_REFACTOR_PROGRESS.md

Runs the backend test suite for smart import, studio, and platform strategy modules. Expected output shows 157 tests passing in 82.37 seconds.

```text
/Users/zhoukk/autoclip/venv/bin/pytest \
  backend/tests/test_smart_import.py \
  backend/tests/test_studio.py \
  backend/tests/test_platform_strategy.py -q

157 passed in 82.37s
```

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

### Run tests for local presets and CLI

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/CLI_AND_MCP.md

Runs the test suite for local presets and CLI functionality. Requires the backend directory and Python environment with pytest installed.

```bash
cd backend && python -m pytest tests/test_local_presets.py tests/test_cli.py -q
```

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

### CLI 发布命令示例

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/PUBLISH_UPLOAD_POST.md

展示 `autoclip publish` 命令的多种用法，包括指定切片、平台、预设、用户、标题、描述、额外参数、定时发布、查询状态和 JSON 输出。

```bash
# 把 2 号切片发到 TikTok + YouTube Shorts（自动渲 9:16 shorts 预设，≤ 60 s），并等结果
autoclip publish <project_id> --clip 2 --platform tiktok --platform youtube --wait

# 多个切片、指定预设与 profile、自定义标题
autoclip publish <project_id> --clip 2 --clip 5 --platform instagram --preset douyin --user brand --title "本周最精彩的一段"

# 横屏平台不裁切
autoclip publish <project_id> --clip 3 --platform linkedin,x --preset original --description "完整访谈见主页"

# 先私密试发：平台专属字段用 --extra key=value 透传（字段名见 Upload-Post 文档）
autoclip publish <project_id> --clip 2 --platform tiktok --extra privacy_level=SELF_ONLY
autoclip publish <project_id> --clip 2 --platform youtube --extra privacyStatus=unlisted

# 定时发布
autoclip publish <project_id> --clip 2 --platform tiktok --schedule 2026-10-01T09:00:00 --timezone Asia/Shanghai

# 查结果（提交时打印的 request_id）
autoclip publish --status <request_id>
autoclip publish --status <request_id> --wait

# 给脚本 / agent
autoclip publish <project_id> --clip 2 --platform tiktok --wait --json
```

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

### 本地构建脚本 build_macos_arm.sh

Source: https://github.com/zhouxiaoka/autoclip/blob/main/BUILD_GUIDE.md

在 macOS Apple Silicon 上运行此脚本构建桌面应用。产物为 .app 和 .dmg，分别约 550M 和 260M。首次构建会下载并缓存便携 Python 和 ffmpeg 到 build/ 目录。

```bash
./scripts/build_macos_arm.sh
```

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

### Check speech recognition service status

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/OPTIONAL_SRT_UPLOAD_GUIDE.md

Check the status of speech recognition services with a GET request to /api/v1/speech-recognition/status. The response shows which methods are available, supported languages, Whisper models, and default configuration.

```bash
# 检查可用的语音识别方法
GET /api/v1/speech-recognition/status
```

```json
{
    "available_methods": {
        "whisper_local": true,
        "openai_api": false,
        "azure_speech": false,
        "google_speech": false,
        "aliyun_speech": false
    },
    "supported_languages": ["zh", "en", "ja", "ko", "fr", "de", ...],
    "whisper_models": ["tiny", "base", "small", "medium", "large"],
    "default_config": {
        "method": "whisper_local",
        "language": "auto",
        "model": "base",
        "timeout": 300
    }
}
```

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

### Run backend evaluation

Source: https://github.com/zhouxiaoka/autoclip/blob/main/backend/eval/cases/README.md

Runs the evaluation suite for the backend. Execute from the project root.

```bash
python -m backend.eval
```

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

### Configure Aliyun speech recognition credentials

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/OPTIONAL_SRT_UPLOAD_GUIDE.md

Set the environment variables for the Aliyun speech recognition service, including access key ID, secret, and app key.

```bash
export ALIYUN_ACCESS_KEY_ID="your-access-key"
export ALIYUN_ACCESS_KEY_SECRET="your-secret-key"
export ALIYUN_SPEECH_APP_KEY="your-app-key"
```

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

### Configure Google Speech-to-Text credentials

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/OPTIONAL_SRT_UPLOAD_GUIDE.md

Point the Google Speech-to-Text client to a service account credentials file.

```bash
export GOOGLE_APPLICATION_CREDENTIALS="path/to/credentials.json"
```

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

### 后端架构重构目录结构

Source: https://github.com/zhouxiaoka/autoclip/blob/main/docs/TECHNICAL_ROADMAP.md

规划了后端目录结构，包括app、api、core、models、services、pipeline和utils等模块，用于组织FastAPI应用。

```text
backend/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI应用入口
│   ├── config.py            # 统一配置管理
│   ├── dependencies.py      # 依赖注入
│   └── middleware.py        # 中间件
├── api/
│   ├── __init__.py
│   ├── v1/
│   │   ├── __init__.py
│   │   ├── projects.py      # 项目相关API
│   │   ├── processing.py    # 处理相关API
│   │   ├── files.py         # 文件上传API
│   │   └── settings.py      # 设置相关API
│   └── deps.py              # API依赖
├── core/
│   ├── __init__.py
│   ├── config.py            # 核心配置
│   ├── security.py          # 安全相关
│   └── exceptions.py        # 异常处理
├── models/
│   ├── __init__.py
│   ├── project.py           # 项目模型
│   ├── clip.py              # 切片模型
│   └── collection.py        # 合集模型
├── services/
│   ├── __init__.py
│   ├── project_service.py   # 项目服务
│   ├── processing_service.py # 处理服务
│   ├── file_service.py      # 文件服务
│   └── llm_service.py       # LLM服务
├── pipeline/
│   ├── __init__.py
│   ├── base.py              # 流水线基类
│   ├── steps/               # 处理步骤
│   └── orchestrator.py      # 流水线编排
└── utils/
    ├── __init__.py
    ├── file_utils.py        # 文件工具
    ├── video_utils.py       # 视频工具
    └── text_utils.py        # 文本工具
```

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

### Build production version with npm or yarn

Source: https://github.com/zhouxiaoka/autoclip/blob/main/frontend/README.md

Build the production version using either npm or yarn. The comment '# 或' indicates the alternative command.

```bash
npm run build
# 或
yarn build
```