TextCut - AI 视频剪辑助手

TextCut 是一款基于 "文稿即剪辑" 理念的 AI 视频编辑工具。通过自动转录和 AI 理解，让你像编辑 Word 文档一样编辑视频。

功能特性

• 自动转录：上传视频后自动生成带时间戳的文稿（基于 WhisperX）
• 文稿编辑：删除文字 = 删除视频片段，所见即所得
• AI 剪辑：通过自然语言指令完成剪辑（如"删除静音"、"提取精华"、"做一个鬼畜视频"）
• 实时预览：剪辑后直接在时间线上预览效果
• 导出支持：导出 XML 工程文件（兼容 Premiere/Final Cut Pro）

技术栈

后端

• Python 3.10+
• FastAPI
• SQLite（默认）/ PostgreSQL
• Redis + Celery
• WhisperX（语音转文字）
• DeepSeek（AI 剪辑）
• FFmpeg + MoviePy（视频处理）

前端

• React 18 + TypeScript
• Vite
• Tailwind CSS
• Zustand（状态管理）
• Wavesurfer.js（波形显示）

快速开始

环境要求

• Python 3.10+
• Node.js 18+
• Redis 6+
• FFmpeg

方式一：一键启动（推荐）

# 克隆项目
git clone https://github.com/uttgeorge/textcut.git
cd textcut

# 复制并编辑环境变量
cp backend/.env.example backend/.env
# 编辑 backend/.env，填入 DEEPSEEK_API_KEY 和 HF_TOKEN

# 一键启动所有服务
./start.sh

启动脚本会自动：

1. 检查系统依赖（Python、Node.js、Redis、FFmpeg）
2. 创建 Python 虚拟环境并安装依赖
3. 安装前端 Node.js 依赖
4. 初始化数据库
5. 启动 Redis、后端 API、Celery Worker、前端开发服务器

启动完成后访问：http://localhost:5173

其他命令：

./start.sh stop     # 停止所有服务
./start.sh status   # 查看服务状态
./start.sh restart  # 重启所有服务

方式二：手动启动

1. 克隆项目

git clone https://github.com/uttgeorge/textcut.git
cd textcut

2. 后端配置

cd backend

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 复制环境变量配置
cp .env.example .env

# 编辑 .env 文件，填入你的配置
# - DEEPSEEK_API_KEY: DeepSeek API 密钥（必填）
# - HF_TOKEN: HuggingFace Token（说话人分离功能需要）

# 创建存储目录
mkdir -p storage/videos storage/audio storage/renders

# 初始化数据库
python init_db.py

3. 前端配置

cd ../frontend

# 安装依赖
npm install

4. 启动服务

需要启动 4 个服务：

终端 1 - Redis

redis-server

终端 2 - 后端 API

cd backend
source venv/bin/activate
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

终端 3 - Celery Worker（处理转录任务）

cd backend
source venv/bin/activate
python start_celery.py

终端 4 - 前端

cd frontend
npm run dev

5. 访问应用

打开浏览器访问 http://localhost:5173

环境变量说明

后端 (.env)

变量	说明	必填	默认值
DEEPSEEK_API_KEY	DeepSeek API 密钥	✅	-
DEEPSEEK_BASE_URL	DeepSeek API 地址	❌	https://api.deepseek.com
DEEPSEEK_MODEL	使用的模型	❌	deepseek-chat
HF_TOKEN	HuggingFace Token（说话人分离）	❌	-
WHISPERX_MODEL	WhisperX 模型	❌	large-v2
WHISPERX_DEVICE	运行设备	❌	cpu（可选 cuda）
REDIS_URL	Redis 连接地址	❌	redis://localhost:6379/0
CELERY_BROKER_URL	Celery Broker	❌	redis://localhost:6379/1
CELERY_RESULT_BACKEND	Celery Backend	❌	redis://localhost:6379/2

项目结构

TextCut/
├── backend/
│   ├── app/
│   │   ├── main.py           # FastAPI 入口
│   │   ├── config.py         # 配置管理
│   │   ├── database.py       # 数据库连接
│   │   ├── models.py         # SQLAlchemy 模型
│   │   ├── schemas.py        # Pydantic 模式
│   │   ├── routers/          # API 路由
│   │   │   ├── projects.py   # 项目管理
│   │   │   ├── ai.py         # AI 剪辑
│   │   │   └── export.py     # 导出功能
│   │   ├── services/         # 业务逻辑
│   │   │   ├── ai_agent.py   # AI 剪辑代理
│   │   │   └── export_service.py
│   │   └── tasks/            # Celery 任务
│   │       └── transcribe.py # 转录任务
│   ├── storage/              # 本地文件存储
│   ├── requirements.txt
│   ├── start_celery.py       # Celery 启动脚本
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── components/       # React 组件
│   │   │   ├── editor/       # 编辑器组件
│   │   │   └── ...
│   │   ├── pages/            # 页面
│   │   ├── store/            # Zustand 状态
│   │   ├── lib/              # 工具函数
│   │   └── App.tsx
│   ├── package.json
│   └── vite.config.ts
└── README.md

使用指南

1. 创建项目并上传视频

1. 点击"新建项目"
2. 上传 MP4/MOV 格式视频
3. 等待转录完成（约为视频时长的 1/6）

2. 编辑文稿

• 删除片段：选中文字后按 Delete 键
• 恢复片段：点击已删除（灰色）的文字
• 定位播放：点击任意文字跳转到对应时间点

3. AI 剪辑

在 AI 面板输入指令，例如：

• "删除所有静音片段"
• "提取最精彩的30秒内容"
• "做一个鬼畜视频，把有节奏感的句子重复几次"

AI 会自动分析文稿内容，选择合适的时间段进行剪辑。

4. 预览与导出

• 点击播放按钮预览剪辑效果
• 点击"导出"下载 XML 工程文件

常见问题

Q: 转录速度很慢？

A: 首次运行需要下载 WhisperX 模型（约 3GB）。如果有 NVIDIA GPU，可以在 .env 中设置 WHISPERX_DEVICE=cuda 加速。

Q: AI 剪辑没有响应？

A: 检查 DEEPSEEK_API_KEY 是否正确配置，以及网络是否能访问 DeepSeek API。

Q: 视频播放卡顿？

A: 建议使用 H.264 编码的 MP4 文件，其他格式可能需要转码。

Q: 说话人分离不工作？

A: 需要在 HuggingFace 同意模型使用协议，并配置 HF_TOKEN。

开发说明

运行测试

# 后端测试
cd backend
pytest

# 前端测试
cd frontend
npm test

代码检查

# 前端 lint
cd frontend
npm run lint

License

MIT License