muku 0.2.2

Local-first Video-to-Markdown for knowledge videos, local audio, and AI-agent workflows.

幕库 Muku

English | 简体中文

把 Bilibili、YouTube、Douyin 等知识视频和本地音频，转换成可检索、可连接、可被 AI 持续使用的 Markdown 知识库。

幕库不是“把视频下载下来就结束”的通用下载器。它关注的是从链接或音频到知识资产的完整链路：优先提取平台字幕，必要时回退音频转写，然后生成逐字稿、解析稿、知识库稿和可追踪的元数据。

项目提供四种入口：CLI、Web UI、Docker 和可供 Codex 等 AI agent 使用的 Skill。

为什么用幕库

• Video-to-Markdown：最终产物是适合 Obsidian、Git、全文检索、RAG 和 agent 工作流的 Markdown
• 字幕优先，转写兜底：能拿平台字幕时避免重复转写；模型拒绝音频时自动回退，不制造假成功
• 本地优先：文件、配置和知识资产保存在自己的电脑或自托管环境
• 批量与断点续跑：支持 URL 文件、标准输入、并发、checkpoint、--resume 和 NDJSON 进度
• 面向自动化：CLI 支持稳定 JSON 和纯路径输出，Skill 不需要驱动网页表单
• 跨平台交付：PyPI wheel 在 Ubuntu、macOS、Windows 上持续验证

60 秒开始

准备条件

• Python 3.10+
• ffmpeg：用于音视频处理
• 一把 OpenRouter API Key：用于音频转写和 AI 整理

安装 ffmpeg：

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

Windows 用户可以先看 Windows 安装指南。

安装 CLI

推荐使用隔离式 Python 工具安装，不依赖仓库，也不需要 npm：

# 二选一
uv tool install muku
pipx install muku

muku --version
muku setup
muku doctor --json

如果电脑上只有 Python 和 pip：

python3 -m venv .muku-venv
source .muku-venv/bin/activate
python -m pip install --upgrade pip muku
muku setup

muku setup 只需输入一把 OpenRouter Key，会同时配置转写、清洗、解析和知识库阶段；完整 Key 不会回显到终端。

生成第一份 Markdown

# 视频 URL -> 逐字稿 + 解析稿 + 知识库稿
muku capture "https://www.bilibili.com/video/BVxxxx" --knowledge --json

# 本地音频 -> 逐字稿 + 解析稿 + 知识库稿
muku audio "/path/to/audio.mp3" --knowledge --json

常见产物：

文件	内容
标题 - 原始逐字稿.txt	未经改写的转录文本
标题 - 逐字稿.md	清洗后的可读逐字稿
标题 - 解析稿.md	按提示词整理的结构化文章
标题 - 知识库.md	适合继续入库和检索的知识稿
标题 - 转写信息.json	来源、模型、处理路径和错误信息

Web UI 与 Docker

想使用图形界面时，克隆仓库后启动 Docker Compose：

git clone https://github.com/qianzhu18/Muku.git
cd Muku
cp .env.example .env
docker compose up -d --build

Windows PowerShell：

git clone https://github.com/qianzhu18/Muku.git
Set-Location Muku
Copy-Item .env.example .env
docker compose up -d --build

访问 http://localhost:5657，在右上角设置中填写 Key、下载目录和平台 Cookies。下载产物默认保存在 ./docker-data/downloads，配置保存在 ./docker-data/config。

更完整的容器说明见 Docker 部署指南。Web 面板适合个人、本地或可信网络，不建议直接暴露为公网多人服务。

工作原理

flowchart LR
    A[视频 URL / 本地音频] --> B{可获得平台字幕?}
    B -->|是| C[提取并规范化字幕]
    B -->|否| D[压缩音频并转写]
    D --> E{模型拒绝音频?}
    E -->|是| F[切换回退模型]
    E -->|否| G[得到原始逐字稿]
    F --> G
    C --> G
    G --> H[清洗逐字稿]
    H --> I[生成解析稿 / 知识库稿]
    I --> J[本地 Markdown + metadata]

平台支持

平台	输入	推荐认证	说明
Bilibili	视频页、分享链接	BILIBILI_COOKIES_PATH	字幕与高知识密度内容是主要场景
YouTube	视频页、分享链接	YOUTUBE_COOKIES_PATH	字幕优先；部分视频需要登录态
Douyin	分享链接、分享文案	DOUYIN_COOKIES_PATH	适合短视频观点和素材沉淀
其他 yt-dlp 平台	完整 URL	COOKIES_PATH	能力取决于 yt-dlp 对目标站点的支持
本地音频	MP3、M4A、WAV 等	不需要平台 Cookies	直接进入音频转写链路

平台策略会随站点规则变化。请先运行 muku doctor --json，再用一条真实链接验证自己的登录态和网络环境。

批量任务

muku capture \
  --input-file ./urls.txt \
  --knowledge \
  --jobs 0 \
  --resume \
  --result-file ./runs/capture.json \
  --output paths

• --jobs 0：自动选择并发数
• --resume：复用 checkpoint 和已有产物
• --result-file：每个任务结束后增量写入结果
• --stream：输出 NDJSON 进度，适合 tail -f、监控和 agent 消费

完整命令见 CLI 文档。

安装 AI Skill

Skill 负责告诉 agent 何时以及如何调用 Muku CLI；运行时仍需先安装上面的 muku Python 包。

git clone https://github.com/qianzhu18/Muku.git
cd Muku
./scripts/install-muku-skill

安装后可直接向支持 Skill 的 agent 提出：

使用 muku-video-to-md，把这个 B 站视频整理成逐字稿、解析稿和知识库 Markdown，并返回产物路径。

公开 Skill 位于 skills/muku-video-to-md，更多说明见 Skill 文档。

配置与安全

• 不要提交 .env、API Key、Cookies 或生成的私密内容
• Docker 优先使用平台专用 cookies.txt；本地调试也可以使用 *_COOKIES_FROM_BROWSER
• 默认转写模型为 google/gemini-2.5-flash，拒绝音频输入时会尝试回退模型
• muku doctor --json 会区分“已配置”和“已验证”，配置存在不等于目标平台一定可用
• 发现安全问题请按 SECURITY.md 私下报告，不要先公开 Issue

验证范围

环境	验证方式
Ubuntu + Python 3.10 / 3.12	单元测试、CLI、自检、wheel 安装
macOS + Python 3.12	单元测试、CLI、自检、wheel 安装
Windows + Python 3.12	单元测试、CLI、自检、wheel 安装
Docker Compose	配置解析与本地部署
PyPI	Trusted Publishing、独立安装烟测

“CI 通过”不代表所有平台链接永远可下载。视频站点的风控、Cookies、地区和网络状态仍会影响真实任务。

开发

git clone https://github.com/qianzhu18/Muku.git
cd Muku
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt -e . pytest
python -m pytest -q

提交改动前请阅读 CONTRIBUTING.md 和 CODE_OF_CONDUCT.md。Bug、功能建议和文档改进都欢迎提交 Issue 或 Pull Request。

文档

• CLI 与自动化
• Docker 部署
• Windows 指南
• 批量采集工作流
• 平台集成评估
• Skill 使用说明
• 安全策略
• 贡献指南

项目边界

• 当前定位是个人、本地、自托管和可信小团队工作流
• 普通网页应先由网页采集工具提取为 Markdown，不要直接塞进视频 capture 命令
• 项目不会绕过平台访问控制；请遵守目标站点条款、版权规则和所在地法律
• 转写与整理会产生第三方 API 成本，使用前请查看所选模型价格和 Key 限额

License

MIT © 2026 qianzhu18