ViNote

<div align="center">

ViNote = Video + Note

视记AI · 让每个视频成为你的知识资产

ViNoter · 超级视记Agent

Video to Everything：笔记、问答、文章、字幕、卡片、导图，一应俱全

</div>

---

✨ 核心特性

🤖 ViNoter 超级智能体 🔥

• 对话式操作: 通过自然语言对话完成所有视频处理任务
• 智能意图理解: 自动识别用户需求，无需手动切换功能
• 跨平台搜索: 支持 B站、YouTube 等多平台视频检索
• 流程自动化: 搜索→转录→笔记→翻译，一气呵成
• 基于 ANP 协议: 全球领先开源的去中心化 Agent 协作标准

🎯 智能视频处理

• 多平台支持: YouTube, Bilibili等主流视频平台
• 本地视频支持: 支持本地视频文件路径输入（MP4, AVI, MOV, MKV等格式）
• 高质量转录: 基于 Faster-Whisper 的本地音频转录
• 智能优化: AI驱动的文本优化和格式化
• 多语言支持: 自动检测语言并支持翻译

📝 笔记生成

• 结构化输出: 自动生成大纲、要点和总结
• Markdown格式: 完美支持各类笔记软件
• 实时进度: SSE实时推送处理进度

🤖 视频问答

• 智能问答: 基于视频内容的AI问答系统
• 上下文理解: 深度理解视频内容
• 流式输出: 实时响应，提升用户体验

🎬 视频下载

• 多格式支持: 支持多种视频格式和分辨率
• 预览功能: 下载前预览视频信息
• 进度跟踪: 实时显示下载进度

🃏 知识卡片

• 一键生成: 从视频笔记自动提取核心知识点
• 多种风格: 支持概念卡、要点卡、对比卡等多种卡片类型
• AI 提炼: 智能提炼关键信息，适合快速复习

🧠 思维导图

• 自动生成: 从笔记内容自动构建思维导图
• 交互式浏览: 基于 Markmap 的可缩放、可折叠导图
• 一键导出: 支持导出为图片

📂 笔记分类与标签

• 分类管理: 17 个预置系统分类 + 自定义分类，笔记一目了然
• 标签系统: AI 自动打标签 + 手动编辑，灵活组织知识
• 交叉筛选: 按分类、标签、关键词多维度快速检索

💾 SQLite 持久化存储

• 可靠存储: 已完成笔记存入 SQLite，告别 JSON 文件丢失风险
• 自动迁移: 首次启动自动将旧 JSON 数据迁移到 SQLite
• 服务端分页: 历史记录支持分页、排序、筛选，大量笔记也不卡顿

🗄️ 存储管理

• 可视化统计: 一键查看笔记、音频缓存、下载文件占用空间
• 分类清理: 按类型清理缓存，释放磁盘空间

---

🚀 快速开始

🐳 方式一：Docker 部署（推荐）

无需安装 Python、Node.js、FFmpeg，一键搞定！

# 1. 克隆项目
git clone https://github.com/zrt-ai-lab/ViNote.git
cd ViNote

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，填入 OPENAI_API_KEY 等必要配置

# 3. 构建并启动
docker compose up -d

# 4. 查看日志
docker compose logs -f

# 5. 访问应用
open http://localhost:8999

可选配置：

# 自定义端口（修改 .env 中的 APP_PORT）
APP_PORT=9000 docker compose up -d

# 挂载 B站 cookies（编辑 docker-compose.yml 取消注释）
# - ./bilibili_cookies.txt:/app/bilibili_cookies.txt:ro

# 停止服务
docker compose down

# 重新构建（代码更新后）
docker compose up -d --build

---

🛠️ 方式二：本地安装

前置要求

• Python 3.10+
• FFmpeg（音视频处理）
• uv 包管理器

安装步骤

1. 克隆项目

git clone https://github.com/zrt-ai-lab/ViNote.git
cd ViNote

2. 安装 uv 包管理器

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 安装 FFmpeg

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ffmpeg

# Windows
# 从 https://ffmpeg.org/download.html 下载并安装

4. 安装依赖

# 使用 uv 安装依赖（会自动创建 .venv 虚拟环境）
uv pip install -e .

# 或使用 uv sync（推荐）
uv sync

5. 配置环境变量和 Cookies

# 复制环境配置文件
cp .env.example .env
# 编辑 .env 文件，填入你的配置

# 复制 cookies 配置（可选，B站需要）
cp cookies.txt.example bilibili_cookies.txt
# 如果需要下载B站视频，请编辑 bilibili_cookies.txt
# 详见下方"🍪 Cookies 配置"章节

6. 启动服务

🚀 一键启动（推荐）

# macOS / Linux
chmod +x start.sh   # 首次运行设置权限
./start.sh

# Windows
start.bat

脚本会自动完成：

• ✅ 检查依赖（Python、FFmpeg、Node.js）
• ✅ 安装后端依赖（uv sync）
• ✅ 构建前端（npm run build）
• ✅ 启动 ViNote 主应用（端口 8999）
• ✅ 启动 ANP 服务（如已配置）

手动启动（高级）

如果你更喜欢手动分别启动服务：

💡 使用 ViNoter 超级智能体: 需要启动 3 个服务，分别在不同终端运行：

终端 1 - DID 认证服务器：

cd backend/anp
python client_did_server.py

终端 2 - 视频搜索服务端：

cd backend/anp
python search_server_agent.py

终端 3 - ViNote 主应用：

# 从项目根目录
uv run uvicorn backend.main:app --reload --port 8999

基本使用（不使用 ViNoter 超级智能体），有两种方式启动服务：

方式 1：使用 uv run（推荐，无需激活虚拟环境）

# 开发模式（自动重载）
uv run uvicorn backend.main:app --reload --port 8999

# 生产模式
uv run uvicorn backend.main:app --host 0.0.0.0 --port 8999 --workers 4

方式 2：激活虚拟环境后运行

# 先激活虚拟环境
source .venv/bin/activate  # macOS/Linux
# 或
.venv\Scripts\activate     # Windows

# 然后启动服务
uvicorn backend.main:app --reload --port 8999

8. 访问应用 打开浏览器访问: http://localhost:8999

---

📖 使用指南

使用方式

1. 打开应用首页，选择 "ViNoter 超级智搜" 标签
2. 在对话框中输入你的需求，例如：

场景 1：搜索视频

你: "帮我在 B站搜索 Python 教程"
ViNoter: "为您找到 10 个相关视频：
1. 【黑马程序员】Python 零基础入门
2. 【清华大学】Python 数据分析
...
请问您想选择哪一个？"

场景 2：视频转录

你: "选第一个，帮我转录"
ViNoter: "好的，正在为您处理：
✓ 下载视频
✓ 提取音频
✓ 转录中... (进度 45%)
✓ 转录完成！
已为您保存转录文本，是否需要生成笔记？"

场景 3：多平台搜索

你: "帮我在 YouTube 和 B站上同时搜索机器学习教程"
ViNoter: "正在跨平台搜索...
YouTube 结果：5 个视频
B站结果：8 个视频
为您展示最相关的 10 个..."

ViNoter 的优势

• 🗣️ 自然对话：像和朋友聊天一样，说出你的需求
• 🤖 智能理解：自动理解意图，无需手动切换功能
• 🔄 流程串联：搜索→转录→笔记→翻译，一气呵成
• 📊 实时反馈：流式输出，进度实时可见
• 🌐 跨平台：同时支持 B站、YouTube 等多平台

💡 提示：ViNoter 基于 ANP（Agent Network Protocol）协议，这是开源的去中心化 Agent 协作标准。详细了解请查看 backend/anp/README.md

视频转笔记

1. 打开应用首页，选择"视频笔记"
2. 在输入框中粘贴视频链接（YouTube, Bilibili 等）或本地文件路径
   • 系统自动识别在线 URL 或本地文件，无需手动切换
3. 点击"预览"查看视频信息
4. 选择摘要语言（中文/英文/日语等11种语言）
5. 点击"生成笔记"
6. 等待处理完成（可查看实时进度）
7. 下载生成的 Markdown 笔记

💡 支持的视频格式：MP4, AVI, MOV, MKV, MP3, WAV 等

💡 批量模式：切换到"批量"模式，可扫描本地目录或粘贴多个链接，批量生成笔记

视频问答

1. 打开应用首页，选择"视频问答"
2. 在输入框中粘贴视频链接或本地文件路径
3. 点击"预览"查看视频信息
4. 点击"开始预处理"按钮
5. 等待AI预处理完成（提取音频并转录）
6. 在输入框中输入您的问题
7. AI将基于视频内容实时回答

💡 提示：预处理完成后，您可以针对视频内容提出任意问题，AI会基于完整的视频内容给出准确回答

视频下载

1. 选择"视频下载"标签
2. 粘贴视频链接并点击"预览"
3. 选择想要的视频质量
4. 点击"开始下载"
5. 下载完成后保存文件

---

🔧 配置说明

环境变量

| 变量名 | 说明 | 默认值 | 必需 | |--------|------|-----------------------------|------| | OPENAI_API_KEY | OpenAI API密钥 | - | ✅ | | OPENAI_BASE_URL | OpenAI API地址 | https://api.openai.com/v1 | ✅ | | OPENAI_MODEL | 使用的模型 | gpt-4o | ✅ | | WHISPER_MODEL_SIZE | Whisper模型大小 | base | ✅ | | APP_HOST | 服务监听地址 | 0.0.0.0 | ❌ | | APP_PORT | 服务端口 | 8999 | ❌ |

Whisper 模型选择

| 模型 | 参数量 | GPU 显存需求 (fp16) | CPU 内存需求 (int8) | 相对速度 | 质量 | 推荐场景 | |------|--------|---------------------|---------------------|----------|------|----------| | tiny | 39M | ~1GB | ~600MB | ⚡⚡⚡⚡⚡ | ⭐⭐ | 快速测试、实时转录 | | base | 74M | ~1GB | ~800MB | ⚡⚡⚡⚡ | ⭐⭐⭐ | 平衡首选 ✅ | | small | 244M | ~2GB | ~1.5GB (1477MB) | ⚡⚡⚡ | ⭐⭐⭐⭐ | 中等质量 | | medium | 769M | ~3-4GB | ~2.5GB | ⚡⚡ | ⭐⭐⭐⭐ | 高质量 | | large-v1 | 1550M | ~4.5GB | ~3GB | ⚡ | ⭐⭐⭐⭐⭐ | 最高质量 (旧版) | | large-v2 | 1550M | ~4.5GB (4525MB) | ~2.9GB (2926MB int8) | ⚡ | ⭐⭐⭐⭐⭐ | 最高质量 | | large-v3 / large | 1550M | ~4.5GB | ~3GB | ⚡ | ⭐⭐⭐⭐⭐ | 最高质量 (推荐) |

🍪 Cookies 配置（B站专用）

B站有反爬虫机制，需要登录凭证才能访问。如果遇到下载失败（如 HTTP 412 错误），需要配置 cookies 文件。

为什么需要 Cookies？

• ✅ 绕过B站平台的反爬虫验证
• ✅ 支持下载需要登录才能观看的视频
• ✅ 提升下载成功率和稳定性

💡 重要说明：

• YouTube 视频无需 cookies：系统会自动以公开方式访问
• B站视频需要 cookies：按以下步骤配置

配置步骤

方法1：使用 yt-dlp 命令（推荐 ⭐⭐⭐⭐⭐）

# 1. 确保已安装 yt-dlp
pip install yt-dlp

# 2. 导出 B站 Cookies
yt-dlp --cookies-from-browser chrome --cookies bilibili_cookies.txt https://www.bilibili.com

# 注意：
# - chrome 可替换为 firefox, edge, safari, brave 等
# - macOS 系统会要求输入系统密码（Mac 登录密码）来访问钥匙串

方法2：手动复制示例文件

# 1. 复制示例文件
cp cookies.txt.example bilibili_cookies.txt

# 2. 编辑 bilibili_cookies.txt，填入真实的 cookie 值（转为 Netscape 格式）
# 参考文件中的注释说明

方法3：使用浏览器插件

1. 安装浏览器插件（如 EditThisCookie 或 Cookie-Editor）
2. 登录 bilibili.com
3. 导出 cookies 为 Netscape 格式
4. 保存为 bilibili_cookies.txt

文件格式示例

bilibili_cookies.txt 文件格式（Netscape HTTP Cookie File）：

# Netscape HTTP Cookie File
# B站 Cookies

.bilibili.com	TRUE	/	FALSE	1893456000	SESSDATA	你的SESSDATA值（必需）
.bilibili.com	TRUE	/	FALSE	1893456000	bili_jct	你的bili_jct值
.bilibili.com	TRUE	/	FALSE	1893456000	DedeUserID	你的用户ID
.bilibili.com	TRUE	/	FALSE	1893456000	buvid3	设备指纹
.bilibili.com	TRUE	/	FALSE	1893456000	sid	会话ID

⚠️ 安全提示

• 🔒 bilibili_cookies.txt 包含登录凭证。
• 🔄 Cookies 通常 3-6 个月过期，需要定期更新

---

📋 版本更新

v1.4.0 (2026-03-09) 🚀 SQLite 持久化 + 分类管理 + UI 大优化

💾 SQLite 持久化存储

• ✅ 已完成笔记迁移到 SQLite: 告别 JSON 文件，数据更可靠
• ✅ 自动迁移: 首次启动自动将 tasks.json + tags.json 迁移到 SQLite
• ✅ 4 张表设计: notes, categories, tags, note_tags（多对多）
• ✅ 服务端分页/筛选/排序: 历史记录 API 全面升级

📂 分类与标签系统

• ✅ 笔记分类页面: 独立的分类管理页面，左侧分类列表 + 右侧关联笔记
• ✅ 17 个预置系统分类: 开箱即用的笔记分类体系
• ✅ 分类 CRUD: 新建、重命名、删除分类
• ✅ 标签系统: AI 自动打标签 + 手动编辑，标签芯片可跳转筛选
• ✅ 交叉筛选: 按分类、标签、关键词多维度快速检索

🗄️ 存储管理

• ✅ 存储统计面板: 可视化查看笔记、音频缓存、下载文件、备份占用空间
• ✅ 分类清理: 按类型一键清理缓存，释放磁盘空间
• ✅ 单条删除: 支持删除单条笔记及其关联文件

🎨 UI 优化

• ✅ 输入框合并: 视频笔记/问答/思维导图页面去掉"在线/本地"切换，合并为单输入框，自动识别
• ✅ 批量处理: 视频笔记支持批量模式，可扫描本地目录或粘贴多个链接
• ✅ 历史记录重写: 服务端分页、行内分类下拉、行内标签编辑
• ✅ short_id 修复: 修复历史记录内容查看/跳转卡片/导图失败的问题
• ✅ 启动时自动修复: repair_note_file_links() 修复历史数据中的文件链接

🔧 修复

• ✅ 修复 short_id 双源不匹配导致历史记录功能异常
• ✅ 修复 ai_config.openai_model 属性访问错误
• ✅ 本地路径防御统一到 3 个路由（tasks/qa/mindmap）

---

v1.3.1 (2026-02-26) 🚀 字幕优先 + Docker 部署

⚡ 性能优化

• ✅ 字幕优先策略: 视频处理时优先提取平台字幕（B站AI字幕、内嵌字幕等），跳过音频下载和ASR转录
• ✅ 处理速度大幅提升: 有字幕的视频从 3-5 分钟缩短到 10 秒内完成
• ✅ 节省资源: 无需下载音频文件，无需 GPU/CPU 进行语音识别

🐳 Docker 部署

• ✅ Docker 支持: 新增 Dockerfile 多阶段构建（前端+后端）
• ✅ Docker Compose: 一键部署，自动管理卷和健康检查
• ✅ 优化镜像: .dockerignore 排除敏感文件和无关文件

🎨 前端优化

• ✅ 智能进度展示: 字幕流程和转录流程显示不同的步骤标签
• ✅ 步骤自动切换: 自动识别后端字幕提取成功信号，切换进度展示

🔧 修复

• ✅ 修复 SearchAgent 页面变量声明顺序 ESLint 错误
• ✅ 统一所有视频入口（笔记/问答/思维导图）的字幕优先逻辑

---

v1.3.0 (2026-02-14) 🎉 架构重构 + 新功能

🏗️ 架构重构

• 后端模块化: 拆分 1600+ 行 main.py → routers/ + core/ 分层架构
• 前端工程化: 从原生 HTML/JS 迁移至 React + TypeScript + Vite
• 搜索架构: 重构为可配置多源搜索（local / ANP），通过 .env 切换

🚀 新功能

• ✅ 知识卡片: 从笔记一键生成知识卡片，支持多种卡片风格
• ✅ 思维导图: 基于 Markmap 的交互式思维导图，从笔记自动生成
• ✅ 历史记录: 笔记任务历史查看与管理
• ✅ 优化一键启动脚本: start.sh / start.bat 自动安装依赖、构建前端、检测端口

v1.2.0 (2025-11-03) 🎉 重大更新

🚀 新功能