内容
# Vocateca 开放核心
**本地优先、设备端转录引擎、命令行界面和MCP服务器，适用于播客、YouTube和Instagram — [Vocateca](https://vocateca.com) 的开放核心。**
将此工具指向播客源、YouTube频道或Instagram账户，它会下载、转录并组织输出 — 完全在您的Mac上进行。没有任何音频或转录文本会离开您的机器。
## 本仓库包含什么
本仓库包含运行无头转录、脚本编写或与代理集成的所有必要内容 — **无专有代码，无授权检查**：
| 目标 | 它是什么 |
|---|---|
| [`VocatecaCore`](Sources/VocatecaCore) | 域层：订阅/源管理、下载 + 转录管道、状态（SQLite via GRDB）、说话人 diarization、专有名词校正、集成（webhooks、Notion、Obsidian导出）和诊断。无头 — 无UI。 |
| [`VocatecaQwen`](Sources/VocatecaQwen) | 可选 [Qwen3-ASR](https://github.com/soniqo/speech-swift) 引擎（MLX、Apple Silicon、macOS 15+）。 |
| [`VocatecaParakeet`](Sources/VocatecaParakeet) | 可选 [Parakeet-TDT](https://github.com/FluidInference/FluidAudio) 引擎（CoreML / Apple Neural Engine）。 |
| [`vocateca-cli`](Sources/vocateca-cli) | 核心上的可脚本命令行界面，具有 `--json` 输出，并内置 **模型上下文协议** 服务器（`vocateca-cli mcp`），以便AI助手可以直接驱动它。 |
WhisperKit（Whisper）作为默认的、始终可用的转录引擎内置于 `VocatecaCore` 中；Parakeet 和 Qwen3-ASR 是可选的、更快的替代引擎，您可以按节目选择。
## Vocateca（应用程序）是什么
[Vocateca](https://vocateca.com) 是在此核心基础上构建的本地macOS应用程序：精致的SwiftUI界面、用于自动订阅的计划自动化守护进程，以及用于付费Pro层的账户/授权系统（自动下载、每日摘要、更深集成）。这些 — 应用程序UI、自动化运行器或账户/计费后端 — 不存在于此仓库中。
## 开放核心模型
Vocateca 是 **开放核心**，沿一条线清晰分割： **引擎是开放的，产品不是。**
- **开放（此仓库）：** 转录管道、状态层、ASR引擎绑定和CLI/MCP表面。这是信任至关重要的部分 — 您应该能够准确读取音频处理方式，验证没有任何电话回家，并根据需要自动化它。
- **不开放：** macOS应用程序的UI、Pro自动化运行器和账户/授权/计费后端。这是我们出售的产品，用于资助开发。
- **为什么这样分割：** 应用程序是人们付费使用的；引擎和工具让任何人都可以验证我们的本地优先声明、在Vocateca基础上构建或在服务器/代理上无人值守运行，而无需触摸GUI。CLI故意 **不** 被Pro-gated — 此处的每个功能（webhooks、引擎选择、监视列表、重试、通知）都无需授权检查。Pro门控完全存在于应用程序中，不在引擎中。
如果您决定某件事情属于此处还是属于应用程序：如果它与 *转录方式* 有关，则是开放的；如果它与 *包装产品体验或我们如何获得报酬* 有关，则不开放。
## 功能
- **三个设备端ASR引擎** — WhisperKit（默认）、Parakeet-TDT（CoreML/ANE）和Qwen3-ASR（MLX）— 按节目选择，无云调用。
- **多源摄入** — 播客RSS源、YouTube频道/视频和Instagram账户（卷轴/帖子/故事）。
- **YouTube转录提取** — `vocateca-cli transcript <url>` 拉取视频、播放列表或频道的转录字幕优先（本地引擎备用用于说话人标签），无需将其导入队列。
- **完整管道，而不仅仅是ASR** — 下载、转录、说话人 diarization、专有名词校正和结构化导出（Markdown/SRT/VTT/CSV + 侧车元数据）。
- **集成** — webhooks（带有HMAC签名）、Notion导出和Obsidian风味前置元数据导出。
- **可脚本设计** — 每个CLI命令都支持 `--json` 以获得稳定的、蛇形大小写的机器输出，变异命令支持 `--dry-run` 以在写入前预览更改。
- **真正的MCP服务器** — `vocateca-cli mcp` 通过stdio以换行分隔的JSON-RPC 2.0进行通信，因此Claude（或任何MCP客户端）可以列出节目、触发转录并读取结果作为工具调用。
- **自我文档** — `vocateca-cli docs` 直接从为 `--help` 和MCP工具列表提供支持的同一目录中渲染完整的命令参考，因此文档不会与代码分离。
## 要求
- macOS 15或更新版本（推荐Apple Silicon；Qwen3-ASR引擎需要它）
- Swift 6工具链（Xcode 16+或匹配的开源Swift工具链）
- 用于下载媒体的 `PATH` 上的运行时工具： [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) 和 [`ffmpeg`](https://ffmpeg.org/) （`brew install yt-dlp ffmpeg`）
## 构建
```sh
swift build --product vocateca-cli
```
第一次构建解决并编译ML依赖图（WhisperKit、FluidAudio、speech-swift/Qwen3ASR — 1600+编译步骤），因此需要几分钟。后续构建是增量进行的。
您也可以单独构建库，例如嵌入到您自己的工具中：
```sh
swift build --product VocatecaCore
swift build --product VocatecaParakeet
swift build --product VocatecaQwen
```
## 运行
```sh
# 完整的命令参考（从CLI自己的目录中自我生成）
swift run vocateca-cli help
# 以JSON格式显示队列/状态
swift run vocateca-cli status --json
# 列出订阅的节目
swift run vocateca-cli shows
# 订阅/管理源（播客源、YouTube频道、Instagram账户）
swift run vocateca-cli sources
# 直接转录单个URL（播客剧集、YouTube视频等）
swift run vocateca-cli transcribe "https://example.com/episode.mp3"
# 检查或驱动下载/转录队列
swift run vocateca-cli queue
# 浏览已生成的转录
swift run vocateca-cli library
# 健康检查（依赖项、模型固定、磁盘空间）
swift run vocateca-cli health
```
顶级命令：`status`、`shows`、`episodes`、`failed`、`stats`、`health`、`feed-health`、`ig-doctor`、`sources`、`transcribe`、`queue`、`library`、`integrations`、`settings`、`engine`、`retry`、`notifications`、`docs`、`mcp`。每个命令都接受 `--json`；运行 `vocateca-cli docs` 以按需重新生成完整的Markdown参考。
Vocateca将其数据存储在 `~/Library/Application Support/Vocateca` 下，将日志存储在 `~/Library/Caches/Vocateca/logs` 下。
### 模型上下文协议（MCP）
```sh
swift run vocateca-cli mcp
```
通过stdin/stdout以换行分隔的JSON-RPC 2.0进行通信（协议版本 `2024-11-05`），将CLI的命令作为MCP工具暴露给任何兼容的客户端 — Claude Desktop、IDE或您自己的代理框架。工具定义从与 `--help` 和 `vocateca-cli docs` 相同的命令目录中生成，因此MCP表面、CLI帮助和生成的文档永远不会分离。stdout严格保留用于协议消息；诊断信息发送到stderr。
## 测试
```sh
swift test
```
一些引擎测试在第一次运行时会下载模型；一些测试在 `VOCATECA_RUN_NETWORK_TESTS` 环境变量后面受到网络限制，默认情况下会跳过这些测试。
## 本地优先和私有
此仓库中的所有内容都在 **您的机器上运行，离线能力在模型下载后具备**。此代码永远不会将音频上传到任何地方；转录在进程内进行（WhisperKit）或通过设备端CoreML/MLX引擎进行（Parakeet，Qwen3-ASR）。开放核心中没有遥测或电话回家 — 唯一的网络调用是您预期的那些（获取您订阅的源/媒体，并下载引擎的模型权重时）。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取开发设置、编码约定和拉取请求流程。简而言之：此仓库保持无头和本地优先 — 引入应用UI、Pro-gating或账户/计费逻辑的贡献将被重定向，因为这些存在于专有应用中。
## 许可证
在 [Apache License 2.0](LICENSE) 下许可。
## 商标和非关联
"Vocateca"和Vocateca徽标是m4ma GmbH的商标。YouTube、Instagram和播客名称归其各自所有者所有；Vocateca是独立的，与Apple、Spotify、Apple Podcasts、YouTube/Google、Instagram/Meta、OpenAI或您选择使用它处理的任何播客、频道或创作者无关。所有产品名称、徽标和品牌是其各自所有者的财产，仅用于识别目的。您有责任确保您的使用符合您转录的内容的服务条款和版权。
