🎬 vmarker

让视频结构可见化

视频标记工具集 - 从 SRT 字幕自动生成透明章节进度条，提升长视频完播率

快速开始 · 功能特性 · 在线演示

English | 简体中文

---

📖 简介

vmarker 是一个开源的视频标记工具集，通过 AI 智能分段和可视化进度条，让观众一眼看清视频结构，显著提升长视频的完播率。

核心特点：

• 🎨 透明通道输出 - RGBA 格式，可完美叠加到任意视频
• 🤖 AI 智能分段 - 自动识别章节边界，无需手动标记
• ⚡ 快速生成 - 10-40 秒完成，传统手动制作需 30-60 分钟
• 🖥️ Web + CLI 双模式 - 可视化界面 + 命令行工具
• 🔒 本地处理 - 视频文件不上传云端，隐私优先

---

🎯 解决的问题

长视频（课程、直播、评测）完播率低的核心原因：

• 结构不清晰 - 观众不知道视频讲什么，容易中途离开
• 平台限制 - 原生章节功能只在播放器内有效
• 制作成本高 - 手动制作章节条需要 30-60 分钟

vmarker 的解决方案：

传统方式：30-60 分钟手动制作
           ↓
vmarker：30 秒命令 / 1 次点击
           ↓
        10-40 秒自动生成
           ↓
    专业级透明视频输出

---

🎬 效果展示

自动生成的章节进度条

┌────────────────────────────────────────────────────────────────┐
│ 00:00        02:30            05:45        10:20       14:00   │
│ 开场介绍      背景说明          核心内容      实战演示    总结回顾  │
└────────────────────────────────────────────────────────────────┘

章节列表：
00:00  开场介绍
02:30  背景说明
05:45  核心内容  ← 当前播放
10:20  实战演示
14:00  总结回顾

生成透明背景视频 (MOV)，可直接叠加到你的视频上

特点：

• 自动识别章节边界（AI 语义理解）
• 动态文字布局（自适应长度）
• 多套配色主题（10+ 预设）
• 透明通道输出（RGBA 格式）

---

✨ 核心功能

1. Chapter Bar - 章节进度条 ⭐

从 SRT 字幕自动生成带透明通道的章节进度条视频。

使用方式：

# CLI 命令（AI 智能分段）
acb input.srt

# 自动分段（每 60 秒一段，无需 AI）
acb input.srt --mode auto --interval 60

# Web 界面（可视化编辑）
cd web && npm run dev  # 访问 http://localhost:3000

---

2. Progress Bar - 播放进度条

生成简洁的播放进度条视频。

vmarker progress --duration 360 --color blue

---

3. Show Notes - AI 视频大纲

从字幕自动生成结构化大纲（摘要 + 时间轴）。

vmarker shownotes input.srt -o notes.md

输出示例：

## 视频大纲

### 开场介绍 (00:00 - 02:30)
- 项目背景和动机
- 核心问题陈述

### 功能演示 (02:30 - 08:45)
- Chapter Bar 功能展示
- AI 智能分段效果

---

4. Subtitle - AI 字幕润色

修正 ASR 识别的"空耳"错误，提升可读性。

vmarker subtitle input.srt -o polished.srt

---

5. Video Process - 全流程处理

上传视频 → ASR 语音识别 → 生成章节条 → 合成到原视频。

使用方式：Web 界面完整流程

---

🛠️ 安装

前置要求

• Python >= 3.13
• Node.js >= 20
• FFmpeg (系统安装)

安装 FFmpeg

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt-get update && sudo apt-get install ffmpeg

Windows: 下载 https://www.gyan.dev/ffmpeg/builds/ 并添加到 PATH

克隆仓库

git clone https://github.com/bbruceyuan/vmarker.git
cd vmarker

---

🚀 快速开始

方式一：Web 界面（推荐）

1. 启动后端

cd backend

# 安装依赖（使用 UV）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# 配置 API Key（AI 功能需要）
cp .env.example .env
# 编辑 .env 填入 OpenAI API Key 或兼容服务

# 启动后端
uv run uvicorn vmarker.api:app --reload --port 8000

2. 启动前端

cd web

# 安装依赖
npm install

# 启动开发服务器
npm run dev

访问 http://localhost:3000

---

方式二：CLI 命令行

开发模式（推荐）

在 backend/ 目录内使用 uv run 前缀：

cd backend

# Chapter Bar 快捷命令
uv run acb input.srt
uv run acb input.srt --theme tech-blue

# 通用命令
uv run vmarker chapter input.srt
uv run vmarker progress --duration 360
uv run vmarker shownotes input.srt
uv run vmarker subtitle input.srt
uv run vmarker themes  # 列出配色方案

---

方式三：Docker

docker compose up --build

打开 **http://localhost:3000**。

环境变量说明（最简）：

• 后端读取 backend/.env（需要 API_KEY 才能使用 AI 分段）。
• 前端读取 web/.env.local，其中 NEXT_PUBLIC_API_URL 必须是浏览器可访问的地址，本机就是 http://localhost:8000。

改完 web/.env.local 后需要重新构建前端镜像：
docker compose build vmarker-web

安装模式（全局使用）

cd backend
uv pip install -e .

# 之后可在任何位置运行
acb input.srt
vmarker chapter input.srt --theme sunset-orange

详细 CLI 文档：backend/CLI_USAGE.md

---

💡 使用场景

知识课程视频

60 分钟教学视频，需要清晰的章节划分：

acb course.srt --mode ai

AI 自动识别知识模块边界，生成语义连贯的章节。

---

直播回放

2 小时直播，需要快速分段：

acb live.srt --mode auto --interval 600  # 每 10 分钟一段

无需 AI，快速按时间分段。

---

产品评测

10 分钟评测，需要精确控制章节：

使用 Web 界面可视化编辑章节时间和标题。

---

会议录像

自动生成会议大纲 + 章节条：

vmarker shownotes meeting.srt -o meeting_notes.md
acb meeting.srt --mode ai
vmarker subtitle meeting.srt -o meeting_polished.srt

---

📦 在视频编辑软件中使用

Adobe Premiere Pro

1. 导入原视频到时间线
2. 导入生成的 chapter_bar.mov
3. 将章节条拖入最上层视频轨道
4. 调整位置（通常放在顶部）
5. 导出最终视频

剪映 (CapCut)

1. 添加原视频到主轨道
2. 新增画中画轨道
3. 导入章节条视频
4. 调整位置和大小
5. 导出视频

DaVinci Resolve

1. 导入两个视频文件
2. 将章节条放在最上层轨道
3. 调整合成模式和位置
4. 渲染输出

---

📁 项目结构

vmarker/
├── backend/          # Python 后端 (FastAPI + CLI)
│   ├── src/vmarker/  # 核心模块
│   └── tests/        # 单元测试
├── web/              # Next.js 前端
│   ├── src/app/      # App Router 页面
│   └── src/components/  # UI 组件
├── task/             # 项目文档
└── .claude/          # Claude 配置

---

🔧 开发指南

环境配置

AI 功能需要在 backend/.env 配置：

# AI 配置（章节分段、大纲生成、字幕润色）
API_KEY=your-api-key
API_BASE=https://api.openai.com/v1
API_MODEL=gpt-4o-mini

# ASR 配置（可选）
ASR_API_BASE=https://api.openai.com/v1
ASR_MODEL=whisper-1

Supabase 登录需要配置后端 JWT 和前端环境变量：

# backend/.env
SUPABASE_JWT_SECRET=your-jwt-secret-here
SUPABASE_URL=https://xxx.supabase.co

# web/.env.local
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

.env / .env.local 配置流程

1. 在 Supabase 控制台获取参数：

   • Project Settings → API → Project URL → 填到 SUPABASE_URL 和 NEXT_PUBLIC_SUPABASE_URL
   • Project Settings → API → API Keys → anon/public key → 填到 NEXT_PUBLIC_SUPABASE_ANON_KEY
   • Project Settings → JWT Keys → Legacy JWT Secret → 填到 SUPABASE_JWT_SECRET

2. 在 backend/.env 写入（示例）：

   SUPABASE_JWT_SECRET=your-jwt-secret-here
   SUPABASE_URL=https://xxx.supabase.co

3. 在 web/.env.local 写入（示例）：

   # 后端 API 地址
   NEXT_PUBLIC_API_URL=http://localhost:8000
   NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

4. 重启前后端进程使环境变量生效。

注意：SUPABASE_JWT_SECRET 仅用于后端验证 JWT。当前后端使用 HS256（Legacy JWT Secret）；如果项目已切换到新的 JWT Signing Keys（P-256），需要先改后端验签方式。

测试

cd backend
pytest tests/

代码检查

ruff check src/
ruff format src/

性能基准

对比串行/并行合成耗时与资源占用：

python scripts/benchmark-compose.py \
  --source /path/to/source.mp4 \
  --bar /path/to/bar.mp4 \
  --output-dir ./benchmark-output

脚本烟雾测试：

bash scripts/benchmark-compose-smoke.sh

---

📄 许可证

本项目采用 Apache License 2.0 开源。

• ✅ 允许商业使用
• ✅ 允许修改和分发
• ✅ 需保留版权声明

详见 LICENSE 文件。

---

🙏 致谢

• FFmpeg - 视频处理
• Next.js - React 框架
• FastAPI - Python Web 框架
• shadcn/ui - UI 组件库
• UV - Python 包管理器
• OpenAI - Whisper ASR 和 GPT 模型

---

📮 联系方式

• Author - Chaofa Yuan (@bbruceyuan)
• Website - https://yuanchaofa.com
• GitHub - https://github.com/bbruceyuan/vmarker
• Email - bruceyuan123@gmail.com

---

⭐ 如果觉得这个项目有帮助，请给个 Star！

Built with ❤️ by Chaofa Yuan