record CLI

一款适用于 macOS 的命令行工具，用于录制音频、屏幕和摄像头输出。专为终端中的人类用户及 AI 代理设计。

输出文件路径打印至 stdout；状态消息输出至 stderr，使该工具天然支持管道操作（pipeline-friendly）。

重要提示：必须获得用户明确授权

在执行任何录制命令前，务必向用户请求明确许可。 录制音频（麦克风）、屏幕或摄像头会捕获敏感数据，且可能令用户感到意外。在执行 record audio、record screen 或 record camera 前，请确认用户是否确实有意录制、将捕获哪些内容，以及录制时长。列出设备（--list-devices、--list-displays、--list-windows、--list-cameras）和截取屏幕快照（--screenshot）侵入性较低，但仍应在未被明确要求的情况下予以确认。

安装

brew install atacan/tap/record

快速参考

# 音频
record audio --duration 10                    # 录制 10 秒音频
record audio --duration 5 --json              # 输出含文件路径的 JSON 格式结果

# 屏幕
record screen --duration 5                    # 录制 5 秒屏幕视频
record screen --screenshot                    # 截取一张屏幕快照
record screen --screenshot --output /tmp/s.png

# 摄像头
record camera --duration 5                    # 录制 5 秒摄像头视频
record camera --photo                         # 拍摄一张照片

子命令

每个子命令均提供独立的 --help 参数，包含完整选项说明。

AI 代理的关键使用模式

获取输出文件路径

该工具将输出文件路径打印至 stdout。可通过命令替换捕获：

FILE=$(record audio --duration 5)
echo "已录制至: $FILE"

使用 --json 获取结构化输出

所有子命令均支持 --json 参数，以机器可读的 JSON 格式向 stdout 输出结果：

record audio --duration 5 --json

使用 --duration 实现非交互式录制

若不指定 --duration，工具将在真实 TTY 环境下等待按键以终止录制。AI 代理应始终显式传入 --duration ，确保命令自动终止。

列出可用设备

record audio --list-devices
record screen --list-displays
record screen --list-windows
record camera --list-cameras

可附加 --json 参数以获得结构化输出。

控制输出位置

record audio --duration 5 --output /tmp/recording.m4a
record screen --screenshot --output /tmp/screen.png --overwrite

若未指定 --output，文件将保存至临时目录。

带音频的屏幕录制

record screen --duration 10 --audio system    # 仅录制系统音频
record screen --duration 10 --audio mic       # 仅录制麦克风音频
record screen --duration 10 --audio both      # 同时录制系统音频与麦克风音频

捕获特定窗口或显示器

record screen --screenshot --window "Safari"
record screen --duration 5 --display primary

macOS 权限设置

终端应用（如 Terminal、iTerm2 等）必须在 系统设置 > 隐私与安全性 中启用对应权限：

• 麦克风 — 用于 record audio 和 record camera --audio
• 屏幕录制 — 用于 record screen
• 摄像头 — 用于 record camera

故障排查

若命令执行失败或行为异常，请运行：

record  --help

--help 输出始终反映当前已安装版本，是权威的参考依据。

详细命令参考

如需完整选项列表与高级用法说明：

• 音频：参见 references/audio.md
• 屏幕：参见 references/screen.md
• 摄像头：参见 references/camera.md