Call Copilot

Call Copilot

专注一件事，并把它做好。录制会议。保存转录稿。不影响音频。

Call Copilot 是一个终端命令（rec），可录制会议音频；停止录制后，它会在本地转录并保存为整洁的 Markdown 转录稿。所有操作都在你的设备上运行——无需云服务、API 密钥或账号。音频和转录稿绝不会离开这台电脑。

$ rec setup         # one-time: verify macOS + grant capture permission
$ rec start         # starts recording, you keep working
$ rec stop          # stops, transcribes, saves markdown
$ rec list          # shows past recordings

音频采集方式（无需 BlackHole 或 Multi-Output Device）

默认情况下，rec 会同时采集麦克风（你的声音）和系统音频（其他参会者／应用播放的任何音频）——因此，录制的是真正的会议，包括你说的话，而不只是扬声器播放的音频。它通过 Apple 的 Core Audio taps API（macOS 14.2+），借助 audiotap 库直接采集这两路音频。你不需要：

• 安装虚拟音频驱动（例如 BlackHole）；
• 在 Audio MIDI Setup 中创建Multi-Output Device；
• 切换和恢复系统输出设备；
• 因此也不会遇到旧式驱动方案在路由中断时导致的录音无声故障。

麦克风和系统音频会分别录制为两个独立的 WAV 文件（各自采用实际采样率），并分别转录，再合并为一份转录稿，同时标注 [Mic]／[System]，方便你分辨是谁说了什么。只想采集其中一路？使用 rec start --mic-only 或 --system-only。

授予采集权限（每个终端应用只需设置一次）

macOS 会将采集权限关联到你运行 rec 的应用（Terminal、iTerm、Warp、VS Code 等）。你需要授予两项权限：

1. 麦克风（你的声音）：前往“系统设置”→“隐私与安全性”→“麦克风”→启用你的终端应用。
2. 系统音频（在 macOS 14.2+ 上归类为“屏幕录制”）：前往“系统设置”→“隐私与安全性”→“屏幕录制”→启用你的终端应用，然后退出并重新打开应用（必须这样做才能使更改生效）。

在授予麦克风权限之前，rec start 只会录制系统音频并跳过麦克风（它会告知你这一点）。rec setup 会检查当前的麦克风权限状态。

执行 rec stop（或在运行 rec start 时按 Ctrl+C）后，录音会通过 faster-whisper 在本地转录（使用 CPU、int8——无需 API，数据不会离开你的设备），并写入 Markdown 转录稿。

recording.wav ──> faster-whisper (local, free) ──> transcript.md

系统要求

• macOS 14.2 或更高版本（Sonoma——rec 所用的 Core Audio 进程 taps API 是在 14.2 中引入的）。推荐使用 Apple Silicon。Intel 也可以运行。
• 仅在通过 pipx 安装时需要 Python 3.11+；Homebrew formula 自带 Python。

无需虚拟音频驱动（例如 BlackHole），无需 Multi-Output Device，也无需手动配置 Audio MIDI Setup。该 tap 会直接读取系统输出。rec 会自行检查 macOS 版本；低于 14.2 时会显示一行提示并拒绝运行，无需你自行判断。

安装

Homebrew（推荐——无需管理 Python）：

brew install AnisurRahmann/tap/call-copilot

pipx（如果你希望直接安装 Python 包，不使用 Homebrew）：

pipx install call-copilot

无论采用哪种方式，你都会在 PATH 中获得 rec 命令。然后请参阅一次性设置。

在低于 macOS 14.2 的设备上运行 rec，会显示 Error: rec requires macOS 14.2 or later ... 并退出——不会输出回溯，也不会让你摸不着头脑。若要自行设置 tap，请参阅 docs/HOMEBREW.md。

录音同意与隐私

Call Copilot 会录制会议音频，其中可能包含其他参与者的声音。各司法管辖区的录音法律各不相同，许多地区要求取得所有被录音者的同意（一方同意制与全体同意制）。获取同意由你负责——录音前请查看当地法律和所在组织的政策。

在技术层面，你的数据不会离开本机：

• 使用 faster-whisper 在本地 100% 运行转录（CPU，int8）——不使用 API，也不上云。
• 音频和转录文本绝不会离开你的设备。 唯一的网络访问发生在首次运行某个 Whisper 模型时，届时会从 Hugging Face 下载模型权重；此后即可完全离线运行。
• 录音保存在 ~/.local/share/rec/sessions/（XDG 数据目录）下，不会放在任何代码仓库中。

一次性设置

rec setup

此命令会验证 macOS 版本，检查 audiotap 库及其捆绑的 dylib 是否能加载，保存配置，并告知你首次捕获权限提示的相关信息。

录制会议

rec start                          # mic + system (default); Ctrl+C to stop & transcribe
rec start --system-only            # just what apps play (not your voice)
rec start --mic-only               # just your voice (not system audio)
rec list                           # browse past sessions
rec transcribe 2026-07-27_14-30-00 --model medium    # re-transcribe at higher quality
rec diagnose 2026-07-27_14-30-00                      # bundle debug info for an AI agent

默认情况下，rec start 会同时录制麦克风和系统音频；转录文本会在每行标注 [Mic] 或 [System]。使用 --system-only / --mic-only 可缩小录制范围。

rec start 会在录制期间显示实时指示器：

● REC  2026-07-28_14-30-00
elapsed 03:47   size 18.2 MB
press Ctrl+C to stop & transcribe

会议结束时按 Ctrl+C——它会停止录制并在同一条命令中进行转录，然后打印转录文件的路径。一条命令，从开始到完成。

想恢复旧的后台行为？使用 rec start --detach 启动录制器后立即退出；之后可在另一个终端中使用 rec stop 停止录制（或使用 rec status 查看进度）。

提示： 如果转录结果为空，说明录音没有声音——当时没有声音播放，或者捕获权限已被撤销。rec start（和 rec stop）会立即对此发出警告，而 rec diagnose <session> 会汇总音频电平和日志。

在 Claude Code 中使用会议记录

rec 附带一个 MCP 服务（这是 Claude Code、Cursor、Zed、Cline 和其他 AI 工具使用的开放协议）。将任意 MCP 客户端连接到本地录制的转录文本，然后就可以向它提问——回答会附上引用的会话 ID，方便你核对具体时间点。数据不会离开你的设备：该服务严格只读，不会发起网络请求。

rec mcp install     # writes the server entry into Claude Code's config

然后重启 Claude Code，并尝试提问，例如：

• “客户在周二的通话中到底提出了什么要求？”——它会搜索转录文本，找到对应内容，并引用带时间戳的会话 ID（例如 2026-07-28_12-25-20）。
• “列出我上周的会议及各自时长。”——它会按日期筛选并列出会话。
• “显示我们讨论 API 迁移时那场站会的完整转录文本。”——它会找到对应会话，然后读取完整转录文本。

此服务提供三个工具：list_sessions（按日期查找会议）、get_session（读取完整转录文本）和 search_transcripts（在较长的转录文本中查找特定行——传入 pricing discount 这类关键词，不要传入完整句子）。搜索索引位于 ~/.local/share/rec/index.db；首次搜索时会按需创建，且属于可随时丢弃的缓存——rec index 可刷新索引，rec index --rebuild 可从头重建索引。

其他 MCP 客户端（Cursor、Zed、Cline 等）

rec mcp install 会打印一段可用于任何 MCP 客户端的配置。对于 Cursor，将它粘贴到 .cursor/mcp.json；对于 Zed，将它粘贴到 settings.json 中的 mcp_servers 下。配置如下：

{
  "call-copilot": {
    "type": "stdio",
    "command": "rec",
    "args": ["mcp"]
  }
}

如果客户端需要原始命令，你也可以直接运行 rec mcp（stdio 传输）来启动服务。

官方 MCP Registry

Call Copilot 已列入官方 MCP Registry，条目为 io.github.AnisurRahmann/call-copilot。任何支持该 registry 的 MCP 客户端都可以从中发现并添加它。该 registry 条目会使用以下命令运行服务：

uvx --from call-copilot rec mcp

（PyPI 包名为 call-copilot；安装的命令是 rec，因此服务会通过 rec mcp 启动。）

浏览器界面

rec web 会打开一个本地浏览器标签页，这是一个以查看为主的界面，用于查看已录制的会话，并提供开始／停止控件。它的设计参考了 qBittorrent／Transmission Web 界面：本地回环 HTTP 服务会提供一个单页应用，操作 CLI 使用的同一会话存储。终端无法显示实时录制计量器、无法在文字稿旁边提供可拖动进度的音频播放器，也无法让你一眼浏览会话列表；浏览器可以，因此这个界面正是为这三件事而设计的。

rec setup            # one-time, in a terminal (the UI can't grant capture permission)
rec web              # opens a browser tab at http://127.0.0.1:7717

你可以在标签页中浏览会话、播放音频并拖动进度，同时查看文字稿、搜索所有文字稿，以及开始／停止录音。开始操作会调用与 CLI 相同的录音器；停止操作会将转录任务加入队列，页面会持续轮询，直到文字稿准备就绪。如果没有找到配置，开始按钮会提示你先在终端中运行 rec setup。

服务仅绑定到 127.0.0.1——主机地址无法配置，这是有意为之（本地工具不能变成开放的文字稿服务）。--port 可覆盖默认端口；--no-open 可跳过自动打开浏览器标签页。

本工具不是什么。 这个界面仍不是实时转录界面——与 CLI 一样，只有停止后才会生成文字稿；它也仍然没有云服务、同步或账户。浏览器中的每项操作都对应一个已有命令；如果某项功能没有对应的 CLI 功能，就不会出现在界面中。

配置

配置存储在 ~/.config/rec/config.json（XDG）。录音存储在 ~/.local/share/rec/sessions/{id}/ 下。如有需要，可使用 XDG_CONFIG_HOME／XDG_DATA_HOME 覆盖 XDG 根目录。

{
  "sample_rate": 16000,
  "channels": 1,
  "whisper_model": "base",
  "capture": "system",
  "sessions_dir": "~/.local/share/rec/sessions"
}

16 kHz 单声道 float32 是 Whisper 的原生输入格式——无需重采样，文件最小（约 7.5 MB／分钟），转录准确度最高。

关于采样率的说明（为什么录音能以正确速度播放）

audiotap 的 sample_rate 参数不会生效——无论我们请求什么采样率，tap 始终以输出设备的原生采样率（通常为 48 kHz）传送音频。rec 会透明地处理这一点：录音器会在 tap 启动时测量实际采集率，并以该采样率写入 WAV（确保播放速度正确）；转录器则会在输入 Whisper 前重采样至 16 kHz（确保转录准确）。你无需进行任何操作；本节旨在说明 session.json 中的 capture_sample_rate 字段（其值可能与配置中的 sample_rate 不同）。

关于 VAD（语音活动检测）的说明

默认情况下，转录运行时不会使用 faster-whisper 的 Silero VAD 预过滤器。VAD 针对近讲麦克风语音进行了调优，会积极过滤系统音频采集（通过 tap 捕获的扬声器／耳机音频，其特性不同）——我们发现，它曾丢弃一段清晰可听的录音中的 100% 内容，并返回空文字稿。Whisper 自身的 no_speech_threshold 足以处理静音，且不会带来这类风险。

如果你使用干净的近讲麦克风输入，并希望跳过长时间静音（速度更快，输出更整洁），可以在每次运行时启用：

rec stop --vad              # VAD on for this transcription
rec transcribe <id> --vad   # re-transcribe with VAD

技术栈

工具	用途
audiotap	Core Audio taps → 直接采集系统音频（macOS 14.2+）
soundfile	将 WAV 数据块流式写入磁盘（内存占用恒定）
faster-whisper	本地语音转文字（CPU int8）
rich + click	终端界面 + CLI

所有工具均免费且开源。转录完全在本地运行——无需 API 费用，数据不会离开设备。（首次运行某个 whisper 模型时，会从 Hugging Face 下载其权重；之后即可离线使用。）

日志与调试

每项活动——音频 tap 的生命周期、分块写入、转录、格式化以及每项 CLI 决策——都会记录日志。日志会发送到以下三个位置：

目标	路径	级别	用途
控制台（stderr）	你的终端	WARNING*	面向用户；默认保持简洁
全局日志	~/.local/share/rec/logs/rec.log	DEBUG	监控界面——对它运行 tail -f
会话日志	~/.local/share/rec/sessions/<id>/recorder.log	DEBUG	单个会话的事后分析

* 默认级别为 WARNING：-v → INFO，-vv → DEBUG，--quiet → CRITICAL，REC_LOG_LEVEL=DEBUG。

每条命令失败都会以 ERROR 级别记录原因和退出代码；意外崩溃会附带完整的回溯信息。

将会话交给 AI Agent 进行调试

rec list                                 # find the session id
rec diagnose 2026-07-27_14-30-00        # → writes sessions/<id>/diagnose.md
rec diagnose 2026-07-27_14-30-00 --stdout | <your-ai-tool>   # pipe straight to an agent

该捆绑包包含会话元数据、守护进程的 recorder.log、带有该会话标记的全局日志行（如果存在，还包括转录文本和配置），以及一份调试检查清单。（rec diagnose 也接受唯一前缀，例如 2026-07-27。）

**关于录制循环的说明：**音频回调在 Core Audio 的实时线程上运行，并且刻意不记录任何日志——它会将每个分块复制到队列中，由写入线程执行磁盘 I/O。守护进程只会在 tap 启动、停止以及收到信号时记录日志。

开发

只有在你要修改 rec 本身时才需要了解这些内容。最终用户应使用上文的 安装 命令。

git clone https://github.com/AnisurRahmann/call-copilot.git && cd call-copilot
make install          # creates .venv and installs `rec` in editable mode + dev deps
make test             # unit tests (offline — no audio device or model download needed)
make run              # rec start, using the dev venv's rec

make install 要求你的 PATH 中有 Python 3.11+（它会为虚拟环境固定使用 python3.11）。有关其他内容——发布、Homebrew tap、代码风格——请参阅 CONTRIBUTING.md 和 docs/HOMEBREW.md。

贡献

欢迎在 github.com/AnisurRahmann/call-copilot 提交问题和拉取请求。 提交 PR 前请阅读 CONTRIBUTING.md，并按照 SECURITY.md 中的说明私下报告安全问题。

本项目不是什么

• 不是实时转录工具（转录会在你停止后进行）。
• 不是会议总结工具（只提供转录文本）。
• 不是 Zoom/Meet 插件（它会通用地捕获系统音频）。
• 不是跨平台软件（仅支持 macOS 14.2+）。

许可证

MIT——请参阅 LICENSE。© Anisur Rahman。