{
}
// fig.2 — 关于这个项目,问点别的
问关于「切片剪辑工具」的细节 —— 技术选型 / 踩坑 / 部署。
试试下面的问题,或直接输入。
从 10 分钟/款的直播 .ts 录制中,自动剪出符合
「停留 → 卖点 → 信任 → 催单」 四段结构的 40-50 秒短视频,
经去重后上架抖音 / 快手 / 视频号 / 小红书。
纯本地运行,不联网、不上云、不依赖任何 SaaS。面向无编程背景的操作员。
技术栈 · 快速开始 · 功能截图 · 常用命令 · 目录结构
左侧逐句字幕(可勾选、行内编辑、AI 四段分类),中间视频帧级播放,右侧导出队列(按四段分类、批量导出)。
剪辑编辑器 · 深色主题
剪辑编辑器 · 浅色主题
同款下批量比对(pHash + 音频指纹),阈值与画面权重可调;并支持单视频防判重处理,降低平台搬运判定命中率。
读取 Excel 商品信息表 + 直播录制根目录,按款号批量解析与切片。
转写 / 合并任务进度跟踪(浏览器本地记录),状态、进度、详情、创建时间一目了然。
ffmpeg / fpcalc / Whisper 模型一键安装与状态展示;支持 CPU / CUDA / GPU 自适应。
短视频四段结构(总长 40-50s):
| 段 | 时长 | 内容 |
|---|---|---|
| 停留 (Hook) | 0-5s | 高光镜头/价格冲击/视觉锚点,留住前 3 秒 |
| 卖点 (Selling Point) | 5-25s | 主播口播 + 实拍材质/工艺/尺寸对比 |
| 信任 (Trust) | 25-40s | 资质证书、品牌背书、用户证言、复购数据 |
| 催单 (CTA) | 40-50s | 限时优惠、库存紧张、价格锚点、购买引导 |
去重(Dedup):候选短视频经感知哈希(pHash) + 音频指纹相似度比对,超阈值剔除,避免平台限流。
| 依赖 | 版本 | 说明 |
|---|---|---|
| Node.js | ≥ 20 | 前端构建 |
| pnpm | ≥ 9 | 前端包管理 |
| uv | ≥ 0.5 | Python 包管理与运行 |
| Python | 3.13 | uv 自动安装 |
| ffmpeg | 任意 | 开发期需在 PATH 中,或在 python/.env 中通过 CLIP_FFMPEG_PATH 指定 |
# 全局工具(若未安装)
npm i -g pnpm
# uv: https://docs.astral.sh/uv/getting-started/installation/
# 1. 安装前端依赖
pnpm install
# 2. 同步后端 Python 依赖
pnpm py:sync
# 3. 启动 Electron(主进程会自动派生 sidecar 到随机端口)
pnpm dev
应用窗口启动后,主进程会把派生 sidecar 的 baseUrl 通过 IPC 传给渲染层,
前端 @hey-api/openapi-ts SDK 自动指向该端口。
如果你要改 Python 代码并享受 uvicorn --reload,跑两个终端:
# 终端 1:固定端口 8765,带 reload
pnpm py:dev
# 终端 2:Electron 不再自己派生,通过 SIDECAR_BASE_URL 复用上面这个
pnpm dev:byo-sidecar
dev:byo-sidecar 会把 SIDECAR_BASE_URL=http://127.0.0.1:8765 注入 Electron
主进程,startSidecar() 检测到后跳过派生,直接复用外部 sidecar。
生产打包后这个环境变量不生效,保证终端用户机器始终自己派生。
健康检查手动验证(双进程模式下):
curl http://127.0.0.1:8765/healthz # → {"status":"ok"}
curl http://127.0.0.1:8765/info # → 应用元信息
| 命令 | 说明 |
|---|---|
pnpm dev | 启动 Electron + Vite,主进程自动派生 sidecar(随机端口) |
pnpm dev:byo-sidecar | 同上,但 Electron 复用 SIDECAR_BASE_URL 已起的外部 sidecar(配合 pnpm py:dev) |
pnpm typecheck | 类型检查 (main + renderer) |
pnpm format | Prettier 格式化 |
pnpm lint | ESLint 检查 |
pnpm api:gen |
| 命令 | 说明 |
|---|---|
pnpm py:sync | 同步 Python 依赖 |
pnpm py:dev | 启动 sidecar (8765 端口,带 reload) |
pnpm py:run | 启动 sidecar (随机端口,Electron 主进程使用) |
pnpm py:test | pytest |
pnpm py:lint | Ruff |
| 命令 | 平台 |
|---|---|
pnpm build:win | Windows 安装包 |
pnpm build:mac | macOS |
pnpm build:linux | Linux |
pnpm build:unpack | 仅打目录(本地调试) |
打包产物输出至 dist/ 与 release/。
clip-tool-next/
├── src/ # Electron 应用(TypeScript)
│ ├── main/ # 主进程,负责窗口与 sidecar 生命周期
│ ├── preload/ # contextBridge 暴露给渲染层
│ └── renderer/ # React 应用(Vite)
├── python/ # FastAPI sidecar(Python)
│ ├── app/
│ │ ├── main.py # FastAPI 入口,/healthz 等
│ │ ├── core/ # ffmpeg / whisper / fingerprint / dedup / merge / sku
│ │ ├── routers/ # 9 个 API 路由
│ │ └── schemas/ # Pydantic 模型
│ └── pyproject.toml
├── docs/ # 开发文档与截图
├── resources/ # 应用图标
├── .claude/skills/ # 项目级 AI skill(随仓库分发)
├── electron.vite.config.ts
├── electron-builder.yml
├── CLAUDE.md # 团队 AI 协作上下文
└── package.json
| FastAPI schema → TS client(后端启动后执行) |