VidkNot

视频知识提取与研究平台（v0.6.10 通用研究平台框架）。从 11+ 自媒体平台（YouTube、B 站、抖音、小红书、快手、TikTok、Twitter/X、Instagram、微信视频号、微博、Vimeo）提取视频笔记：下载音频、双 ASR 交叉校验、生成结构化笔记，保存到 Obsidian、飞书、Notion、语雀。v0.4.0 新增可插拔存储后端、异步周期调度器、批处理 driver 和凭证注入保护的订阅源加载器；v0.5.0 新增标准 Agent Skill 合规（SKILL.md + --demo 模式 + scripts/install.sh）；v0.6.0 新增统一重试/超时配置、内置 FFmpeg 可选依赖（[bundled-ffmpeg]）、异常修正建议（hint）与 CLI 友好错误、国内镜像安装支持；v0.6.1 修复视频时长格式化崩溃，市场展示信息中文化；v0.6.2 SKILL.md 全文中文化（市场概述页中文展示）；v0.6.3 市场描述通俗化改写，突出「一键提取视频文案」等普通人易懂表述；v0.6.4 文档深度优化：集中反模式章节、MCP 工具文档与实现对齐、错误分类速查、平台限制说明写透；v0.6.5 多源审计修复：CI 恢复全绿、LICENSE 恢复 MIT 识别、f2 测试环境无关化；v0.6.6 修复外部智能体审计发现的三个 Bug（#8/#9/#10）：新增 fw/fw_file 目的地保留 FW 时间戳段、双 ASR 校正失败不再丢失 FW 数据、临时子目录命名规范化并加路径穿越防护。

| 中文 | English |

本次更新（v0.6.10）

抖音第三方兜底取得视频直链后，下载请求补充 Referer 与 User-Agent， 修复部分 CDN 因请求头缺失而返回 403 的问题；免费优先及第三方服务显式启用 策略不变。过期直链与内容授权限制需分别处理，详见 抖音排障说明。

适合什么场景

• 把课程、访谈、播客、行业分析视频整理成可检索的文字笔记
• 将短视频平台上的有效内容沉淀到个人知识库
• 给 Agent / MCP 客户端提供“视频转笔记”工具能力
• 对转写结果做双 ASR 交叉校验，减少专有名词和口播误识别

支持的平台

完整能力地图（含各平台 Cookie 依赖、时长约束、付费内容判断标准）见 docs/PLATFORMS.md。

核心能力

安装

️ 前置依赖：运行前必须有 FFmpeg，否则所有平台都会失败。

macOS: brew install ffmpeg | Ubuntu: sudo apt install ffmpeg | Windows: winget install Gyan.FFmpeg

不想装系统 FFmpeg？ 使用内置静态版本（wheel 自带二进制，离线可用）： pip install "vidknot[bundled-ffmpeg] @ git+https://github.com/suonian/vidknot.git@v0.6.10"

环境自检：python -m vidknot --check-env（会给出缺失项的安装命令）

当前 GitHub 版本为 v0.6.10。从 GitHub 安装：

pip install "vidknot @ git+https://github.com/suonian/vidknot.git@v0.6.10"

🇨🇳 大陆网络提示：如访问 GitHub 缓慢，可给 pip 指定国内镜像加速依赖下载 （Git 仓库本身仍需可达，可用 git clone 镜像站或代理）：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple \
  "vidknot @ git+https://github.com/suonian/vidknot.git@v0.6.10"

清华镜像同样覆盖 yt-dlp、faster-whisper 等海外依赖，无需逐个找源。 本地 ASR 模型默认从 Hugging Face 下载，大陆可改走镜像站： export HF_ENDPOINT=https://hf-mirror.com（首次下载前设置一次即可）。

一键脚本 scripts/install.sh 会自动探测并切换到清华镜像。

开发安装：

git clone https://github.com/suonian/vidknot.git
cd vidknot
pip install -e ".[all]"

运行前确认 FFmpeg 可用：

ffmpeg -version   # 或 python -m vidknot --check-env

选择使用方式

VidkNot 提供四种使用方式，根据你的场景选择：

不确定用哪个？CLI 适合大多数用户，一条命令搞定。

配置

复制 .env.example 为 .env，至少配置转写和笔记生成所需的 API Key：

硅基流动（SiliconFlow）提供免费的语音识别模型（SenseVoice），注册后即可获取免费 API Key。 前往 siliconflow.cn 注册账号，在控制台生成 API Key 即可免费使用。

SILICONFLOW_API_KEY=your_siliconflow_api_key   # 语音转写（硅基流动免费模型）
OPENAI_API_KEY=your_openai_compatible_api_key  # 笔记生成（任意 OpenAI 兼容服务）

# 可选：飞书
FEISHU_APP_ID=your_feishu_app_id
FEISHU_APP_SECRET=your_feishu_app_secret
FEISHU_FOLDER_TOKEN=your_feishu_folder_token

# 可选：Obsidian
OBSIDIAN_VAULT_PATH=/path/to/obsidian/vault

# 可选：Notion
NOTION_TOKEN=your_notion_token
NOTION_PAGE_ID=your_notion_page_id

# 可选：语雀
YUQUE_TOKEN=your_yuque_token
YUQUE_LOGIN=your_yuque_login

# 可选：抖音 Cookie 文件
VIDKNOT_DOUYIN_COOKIE_FILE=/path/to/douyin-cookies.txt

默认配置在 config.yaml 中。双 ASR 校正默认开启：

settings:
  enable_correction: true
  correction_version: v4
faster_whisper:
  model: small
  device: cpu
  compute_type: int8

v4 是默认保守策略，只在证据充分时修改；v3 更激进，适合愿意承担更高误改风险的场景。

使用

命令行：

# 生成笔记并保存到默认目的地 Obsidian
python -m vidknot "https://v.douyin.com/example/"

# 只输出结果，不保存
python -m vidknot "https://v.douyin.com/example/" --destination none

# 保存到飞书
python -m vidknot "https://v.douyin.com/example/" --destination feishu

# 禁用双 ASR 校正
python -m vidknot "https://v.douyin.com/example/" --no-correct

# 检查运行环境
python -m vidknot --check-env

MCP：

python -m vidknot --mcp

FastAPI：

uvicorn vidknot.api:app --reload

Python API：

from vidknot import VideoKnowledgePipeline

pipeline = VideoKnowledgePipeline(destination="none")
result = pipeline.run("https://v.douyin.com/example/")

print(result["markdown"])

输出内容

VidkNot 默认生成 Markdown 笔记，示例如下：

# [视频标题]

> 来源：https://v.douyin.com/example/
> 处理时间：2026-08-24 10:30:00

## 核心主题

本文讨论了...

## 要点

1. **第一个要点**：详细说明...
2. **第二个要点**：详细说明...

## 细节 / 重要引用 / 术语解释 / 完整转写

包含：视频标题、来源链接、核心主题、结构化要点、细节、原文引用、术语解释、带时间戳的完整转写。

更多文档

安全与合规

• 不要提交 .env、Cookie 文件或任何 API Key
• 只处理你有权访问和使用的视频内容
• 遵守视频平台、云服务和笔记平台的服务条款
• 第三方服务的稳定性、价格和权限策略以各平台官方说明为准

联系作者

项目咨询与讨论，请扫描下方二维码添加作者微信：

License

本项目采用 MIT 许可证。

权限

• 商业使用（指本工具软件本身）
• 修改
• 分发
• 专利使用
• 私人使用

条件

• 必须包含版权声明和许可声明

限制

• 无担保
• 无责任

重要说明：本工具仅用于个人学习和研究目的。用户通过本工具下载的视频内容，其版权归原博主或平台所有。将下载内容用于商业用途可能侵犯他人版权，请遵守各平台服务条款及相关法律法规。本工具不对用户的使用行为承担任何责任。

完整许可证文本请查看 LICENSE 文件。