talkthru

talkthru

talkthru.dev · npm · @dr_edon · MIT

适用于任何应用的自动化反馈循环。 在手机上录制应用屏幕，并在使用时讲话。将录制内容发送到你的电脑，编码 Agent 就能获取你说的所有内容，以及你说话时正在查看的屏幕画面。

you:    *tapping through checkout* "this button is too small, I keep missing it"
                                  "and this error doesn't say what went wrong"

agent:  sees both screens, finds both components, fixes them.

完全在你的电脑上运行。无需账号、无需上传、无需 API 密钥。

支持使用 mac 屏幕录制（⌘⇧5）、通过 AirDrop 传输的 iPhone 屏幕录制，或 Windows Game Bar。任何带声音的视频都能使用——让监视程序监视某个文件夹即可。

70 秒演示——安装、录制，以及 Agent 获取录制内容。

---

安装

npx talkthru doctor --fix

会下载 ffmpeg、whisper.cpp 和语音模型。无需进行其他设置。

启动监视程序

npx talkthru watch

让它保持运行。它只会处理名称类似屏幕录制文件的文件——你的 Downloads 文件夹中的其他内容对它不可见。

连接你的 Agent

talkthru 是 MCP 服务，因此任何 MCP 客户端都能使用——Cursor、Windsurf、Cline、Zed、Claude Desktop。将它添加到客户端配置中：

{
  "mcpServers": {
    "talkthru": {
      "command": "npx",
      "args": ["talkthru-mcp"]
    }
  }
}

Claude Code 也可以通过一条命令完成相同操作：

claude mcp add --scope user talkthru -- npx talkthru-mcp

之后重启客户端，让它加载该服务。

本项目针对 Claude Code 构建并经过测试。其他 MCP 客户端应该也能使用——如果你的客户端不行，请告诉我。

---

设置你的 mac

只需设置一次。按下 ⌘⇧5，选择一种录制模式（带 ◉ 圆点的图标），然后打开选项，将存储到 → Downloads 和麦克风设置好。这些设置会保留。

1 · 2. 按下 ⌘⇧5，选择一种录制模式，然后打开选项
3. 存储到 → Downloads — talkthru watch 监视的文件夹	4. 在麦克风下选择你的麦克风
5. 点击录制，并在使用应用时讲话

未选择麦克风就会录制无声视频，也就没有内容可供转录。开始首次录制前，最好先检查一下。

---

设置你的手机

可选——仅当你想录制手机应用而非桌面应用时才需要设置。

只需设置一次。打开控制中心 → + → 添加控制项 → 屏幕录制。然后按住它，并打开麦克风。

1. 轻点 +	2. 添加控制项	3. 选择“屏幕录制”
4. 按住 ◉	5. 麦克风已开启	6. 轻点 ◉ 并讲话

---

录制 Web 应用

可选——一个即插即用的脚本，可将你指向的元素交给 Agent，而不只是给它看元素的图片。

<script src="/talkthru-dom.js"></script>

录制完成后，在控制台运行 talkthru.stop()，即可下载 hierarchy.json。将两者一起处理：

talkthru process ~/Downloads/screen-recording.mov --hierarchy ~/Downloads/hierarchy.json

脚本及其捕获的内容： clients/web。

---

使用方法

1. 录制你的应用，同时进行讲解
2. 将视频传到你的设备上（AirDrop 最方便）
3. 向你的 Agent 提问：“检查我上一次 talkthru 会话中的反馈，并实现它”

大约 20 秒即可就绪。原始视频保存在 ~/.talkthru/archive/ 中。

如果你的应用会说话，请将其静音。 它的语音会和你的语音一起出现在转录文本中，而 whisper 无法分辨你们。

---

输出

你说的话会关联到当时显示的屏幕：

## 00:34 · f11 — `frames/f11.jpg`
- [00:39] "this button is too small, I keep missing it"

## 00:52 · f13 — `frames/f13.jpg`
- [00:55] "and this error doesn't say what actually went wrong"

此外还有视频帧。两分钟的会话大约占用 600 个 token。

---

元素上下文（可选）

将 talkthru 指向 UI 层级文件后，你的 Agent 就能获取元素类型、标签和稳定的测试 ID，不必从像素中猜测你指的是哪个组件：

talkthru process recording.mp4 --hierarchy hierarchy.json

## 00:34 · f11 — `frames/f11.jpg`
ui: button#checkout-submit "Place order" @24,680 342x48
- [00:39] "this button is too small, I keep missing it"

这是应用写入的带时间戳的辅助文件——这里不会生成它，其格式为纯 JSON，不依赖 iOS：

{ "snapshots": [
  { "tMs": 1200, "nodes": [
    { "type": "button", "testId": "checkout-submit", "label": "Place order",
      "rect": [24, 680, 342, 48], "depth": 4 }
  ] }
] }

常见的替代拼写（tag、id、text、bounds、elements 等）都可以直接使用，因此 DOM 客户端通常可以按其自然格式输出。格式错误的文件会被忽略并发出警告，而不会导致录制失败。

完整格式：docs/hierarchy.md——包含字段、别名、排序规则，以及如何编写客户端。

---

网络和控制台（可选）

在录制文件旁放置一个 events.json，失败的请求就会显示在你当时查看的帧下方：

## 00:34 · f11 — `frames/f11.jpg`
ui: button#checkout-submit "Place order" @24,680 342x48
net: POST https://api.example.com/checkout 500 340ms
- [00:39] "I tapped place order and nothing happened"

{ "events": [
  { "tMs": 12400, "kind": "network", "method": "POST",
    "url": "https://api.example.com/checkout", "status": 500, "durationMs": 340 },
  { "tMs": 12450, "kind": "console", "level": "error", "text": "TypeError: ..." }
] }

不包含标头和正文——身份验证令牌位于标头中，而这个工具的宗旨是让你的数据留在自己的设备上。解析时，类似机密信息的查询参数值会被替换为 REDACTED。所有发送的内容都会被存储；默认情况下，只有失败事件以及 error/warn 会传给 Agent，因为两分钟的 XHR 文本量比视频帧和讲解加起来还多。

完整格式：docs/events.md

---

Windows

Win+Alt+R（Game Bar）会将录制内容保存到 Videos\Captures，这是监视程序默认查找的位置——此处不按名称筛选，因为该文件夹里不会有其他内容：

winget install -e --id Gyan.FFmpeg
npx talkthru watch

whisper.cpp 没有 winget 安装包。请从 ggml-org/whisper.cpp 构建，并将 TALKTHRU_WHISPER 指向该二进制文件。

已针对 Windows 编写并通过单元测试，但尚未在 Windows 计算机上运行——我没有 Windows 设备。如果你尝试了，无论结果如何，都欢迎提交 issue。

---

命令

talkthru watch                  # watch ~/Downloads for screen recordings
talkthru watch ~/some-folder    # watch your own folder, any video
talkthru process video.mp4      # process one file
talkthru list                   # recent sessions
talkthru show latest            # print one
talkthru doctor                 # check the setup
talkthru compact                # reclaim disk: drops old originals, keeps every frame + transcript
talkthru prune                  # delete old sessions entirely

也可以使用 tt。

---

工作原理

ffmpeg 会提取屏幕实际发生变化时的视频帧。whisper.cpp 会在本地转录你的语音，并根据句子之间的实际静音将语音分段，这样你说的每句话都会对应到你当时查看的屏幕。MCP 服务会将其交给你的 Agent。

需要 Node 20.11+。

---

原因

我每天都会在手机上测试自己的应用，却总是在回到编辑器的过程中丢失反馈——截图、裁剪、努力描述自己指的是哪个屏幕。现在我只需录制并讲解，Claude Code 就能接手。分享出来，希望能帮你省去同样的麻烦。