内容
<div align="center">
# 🎬 Zegplayer
**将任何视频转化为带有时间戳的、AI生成的笔记 — 完全在您的机器上运行。**
一个本地优先、尊重隐私的桌面应用程序，可以在本地转录任何视频，并让您自己的AI代理编写屏幕上内容的带时间戳的笔记。非常适合学习、研究、会议、讲座、教程或查看您观看的任何内容。
[](LICENSE)
[](docs/wiki/Platform-Support.md)
[](https://github.com/megz2020/zegplayer/stargazers)
[](https://github.com/megz2020/zegplayer/issues)
[](CONTRIBUTING.md)
</div>
---
Zegplayer 加载一个视频 — 一个本地文件或 YouTube URL — 并在本地使用 `whisper-cli` 转录其音频，然后由已安装的 AI CLI 代理（Claude Code、Codex、OpenCode）或本地 HTTP 模型服务器（LM Studio、Ollama）生成带有时间戳的笔记。您可以导出笔记（例如，作为 Markdown 导出到 Obsidian），并让您的 AI 代理通过内置的 **只读 MCP 服务器** 查询您的转录和笔记。
所有操作都在您的机器上运行。应用程序本身从不将您的视频或音频上传到任何地方 — 所有 AI 调用都通过您配置的 CLI 或本地模型服务器进行。
**[⬇ 下载最新版本](https://github.com/megz2020/zegplayer/releases/latest)** — macOS (`.dmg`)，Windows (`.exe`)，Linux (`.AppImage` / `.deb`)。参见 [安装](#安装) 以获取首次启动的步骤，以及 [要求](#要求) 以获取您需要在 `PATH` 上安装的工具。
## 工作原理
```mermaid
flowchart LR
A[📹 本地文件<br/>或 YouTube URL] --> B[ffmpeg<br/>提取音频]
B --> C[whisper-cli<br/>本地转录]
C --> D[(SQLite<br/>转录 + 帧)]
D --> E{您的 AI<br/>代理}
E -->|CLI: claude / codex / opencode| F[📝 带时间戳的笔记]
E -->|本地服务器: LM Studio / Ollama| F
F --> G[📤 导出<br/>Markdown / Obsidian / Logseq]
F --> H[🔌 只读 MCP<br/>代理查询您的数据]
style A fill:#2d6cdf,color:#fff
style C fill:#0e8a16,color:#fff
style F fill:#d4a017,color:#fff
style D fill:#6f42c1,color:#fff
```
该流程中没有任何内容离开您的机器：转录是本地的，数据库是本地的，AI 调用由您运行的代理/模型服务器执行。
## 功能
- **加载任何视频** — 打开本地视频文件或粘贴 YouTube URL。
- **本地转录** — 使用 `whisper-cli` （whisper.cpp）在您的机器上转录音频。无需云转录服务。
- **AI 生成的笔记** — 使用已安装的 AI CLI 代理（Claude Code、Codex、OpenCode）或本地 HTTP 模型服务器（LM Studio、Ollama）生成带有时间戳的笔记。
- **导出您的笔记** — 导出到 Markdown 等格式，适用于 Obsidian 和 Logseq 等工具。
- **只读 MCP 服务器** — 暴露您的视频转录和笔记，以便相同的 AI 代理可以查询它们。
- **本地优先和私密** — 您的数据存储在本地 SQLite 数据库中；应用程序不会上传视频或音频。
- **跨平台** — 今日 macOS（Apple Silicon）和 Windows x64；Linux 运行 [一些已知差距](docs/wiki/Platform-Support.md)。
## 架构
```mermaid
flowchart TB
subgraph UI[" "]
R[渲染器<br/>vanilla TS + template HTML]
end
subgraph Bridge[" "]
P[预加载<br/>contextBridge · typed DesktopApi]
end
subgraph Core[" "]
M[主进程<br/>生命周期 · 作业 · 工具]
end
R <-->|IPC| P
P <-->|ipcMain.handle| M
M -->|spawn| T[ffmpeg · whisper-cli · yt-dlp<br/>AI CLI · 模型服务器]
M --> S[(SQLite<br/>better-sqlite3)]
S -.read-only.-> MCP[MCP 服务器<br/>代理查询转录/笔记]
style R fill:#2d6cdf,color:#fff
style M fill:#0e8a16,color:#fff
style S fill:#6f42c1,color:#fff
style MCP fill:#d4a017,color:#fff
```
- **主进程** — 应用程序生命周期、窗口管理和外部工具的协调（`ffmpeg`、`whisper-cli`、`yt-dlp`、AI CLI/模型服务器）。
- **预加载** — 暴露一个受限 API 给渲染器的安全桥梁。
- **渲染器** — 您加载视频、查看转录和管理的 UI。
- **MCP 服务器** — 一个单独的进程，暴露一个只读的 Model Context Protocol 服务器（[@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol)，带有 `zod` 进行模式验证），以便 AI 代理可以查询您的数据。
- **SQLite 存储** — 通过 `better-sqlite3` 进行本地持久化。
参见 **[wiki](docs/wiki/Home.md)** 以获取更深入的了解： [架构](docs/wiki/Architecture.md) · [连接服务](docs/wiki/Connected-Services.md) · [MCP 服务器](docs/wiki/MCP-Server.md) · [平台支持](docs/wiki/Platform-Support.md) · [故障排除](docs/wiki/Troubleshooting.md)。
## 要求
Zegplayer 调用几个外部命令行工具，您必须单独安装这些工具。确保它们在您的 `PATH` 上可用。
| 工具 | 目的 |
| --- | --- |
| `ffmpeg` / `ffprobe` | 音频/视频处理和检查 |
| `whisper-cli` | 本地转录（来自 [whisper.cpp](https://github.com/ggerganov/whisper.cpp)) |
| `yt-dlp` | 从 YouTube URL 加载视频 |
| AI CLI **或** 本地模型服务器 | 至少一个 `claude` / `codex` / `opencode`，**或** 本地模型服务器如 LM Studio / Ollama |
### 安装提示
**macOS**
```bash
brew install ffmpeg yt-dlp
brew install whisper-cpp # 提供 whisper-cli
```
然后安装至少一个 AI CLI（`claude`、`codex` 或 `opencode`）或运行本地模型服务器（LM Studio / Ollama）。
**Windows**
只有 `ffmpeg` 需要您自己安装 — Zegplayer 会在第一次启动时自动下载 `yt-dlp.exe` 和 `whisper-cli.exe` 到其数据目录中。对于 `ffmpeg`：
```powershell
winget install Gyan.FFmpeg
# 或，使用 scoop：
scoop install ffmpeg
# 或，使用 chocolatey：
choco install ffmpeg
```
安装至少一个 AI CLI 或本地模型服务器。如果您已经安装了 Python 的 `openai-whisper`（`pip install -U openai-whisper`），则应用程序将使用它作为备用，当 `whisper-cli` 不可用时 — 但 whisper.cpp 更快（在 CPU 上快 4-5 倍），自动安装程序将无论如何都获取它。
如果您的机器运行的防病毒软件拦截 HTTPS（AVG、Avast、Kaspersky、ESET、公司代理），则 `yt-dlp` 的内置 `certifi` 包将不信任拦截的证书。Zegplayer 通过在 Windows 上为 yt-dlp 传递 `--no-check-certificates` 来自动处理此问题。
**Linux**
使用您的发行版的包管理器：
```bash
# Debian / Ubuntu
sudo apt install ffmpeg
sudo apt install yt-dlp # 或：pipx install yt-dlp
```
从 [whisper.cpp](https://github.com/ggerganov/whisper.cpp) 构建或下载 `whisper-cli`。安装至少一个 AI CLI 或本地模型服务器。
## 安装
macOS、Windows 和 Linux 的预构建安装程序发布在 [GitHub Releases](../../releases) 页面上。下载适合您平台的安装程序并运行它。
> **注意：** 已发布的应用程序是 **未签名的**。您需要在第一次打开应用程序时绕过操作系统的安全门。
**Windows 上的首次启动会自动下载** `yt-dlp.exe` 和 `whisper-cli.exe` 到 `%APPDATA%\Zegplayer\bin\`。您不需要自己安装它们。您仍然需要在 PATH 上安装 `ffmpeg` — 自动安装程序会跳过它，因为它更大。
**macOS — 绕过 Gatekeeper**
要么右键单击应用程序并选择 **打开**（然后确认），要么删除 quarantine 属性：
```bash
xattr -dr com.apple.quarantine "/Applications/Zegplayer.app"
```
**Windows — 绕过 SmartScreen**
当 SmartScreen 出现时，点击 **更多信息 → 仍然运行**。
## 从源代码构建
```bash
git clone https://github.com/megz2020/zegplayer.git
cd zegplayer
npm install # 安装依赖；postinstall 重建 better-sqlite3 以适用于 Electron
npm run dev # 在开发模式下运行应用程序
```
要为当前操作系统生成可分发的安装程序：
```bash
npm run package:mac # macOS
npm run package:win # Windows
npm run package:linux # Linux
```
> 每个 `package:*` 脚本都必须 **在其匹配的操作系统上** 运行（或通过 CI）。诸如 `better-sqlite3` 之类的原生模块无法跨编译。
## 连接 MCP 服务器
应用程序自带一个 **只读 MCP 服务器**，允许您的 AI 代理查询您的视频转录和笔记。
1. 在应用程序中选择您的 AI 代理。
2. 点击 **连接 MCP**。
单击一次即可将只读 MCP 服务器注册到您选择的代理（`claude`、`codex` 或 `opencode`）。然后，代理可以读取您的转录和笔记 — 它不能修改它们。有关详细信息，请参见 [MCP 服务器 wiki 页面](docs/wiki/MCP-Server.md)。
## 开发
```bash
npm install # 安装依赖
npm run dev # 在开发模式下启动应用程序
npm run check # 使用 tsc 进行类型检查
npm test # 运行 vitest 测试套件
npm run build # 构建渲染器/主进程并打包 MCP 服务器
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取项目约定和贡献工作流程。
## 版本控制
该项目遵循 [Semantic Versioning](https://semver.org/)（`MAJOR.MINOR.PATCH`）。所有值得注意的变化都记录在 [CHANGELOG.md](CHANGELOG.md) 中，该文件遵循 [Keep a Changelog](https://keepachangelog.com/) 格式。
通过增加版本号并推送匹配的标签来发布：
```bash
npm version patch # 或：minor / major — 更新 package.json 并创建 vX.Y.Z 标签
git push --follow-tags
```
推送 `v*` 标签会触发 CI 工作流程，该工作流程会构建 macOS/Windows/Linux 安装程序，并用它们创建一个 GitHub Release。
## 贡献
欢迎贡献！请在打开问题或拉取请求之前阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和我们的 [行为准则](CODE_OF_CONDUCT.md)。 [下一阶段的路线图](https://github.com/megz2020/zegplayer/milestones) 存在于问题跟踪器中。
## 许可证
该项目是 **源代码可用且非商业** 的。它在 [PolyForm 非商业许可证 1.0.0](LICENSE) 下获得许可 — 您可以免费使用、修改和分享它用于任何 **非商业** 目的，但 **商业用途需要作者的先前批准**。
© 2026 Zegplayer 贡献者
