轻量开源的 Mac 录屏与提词工具
把屏幕操作、圆形真人头像和讲话录成一个本地视频。
圆镜录屏（CircleCast）是一个原生 macOS 轻量录屏工具，适合软件演示、教程、产品讲解和口播录制。你可以把头像拖到屏幕角落、调整大小，再用独立的半透明提词框辅助讲话。视频保存在自己的 Mac 上，不需要账户、订阅或云端服务。
当前状态：0.1.0 MVP，源码试用版。 已通过自动构建、无设备测试和合成媒体的编码/解码检查；真实摄像头与麦克风的音画同步、提词排除、系统权限和多屏实机流程仍待验证。请先做一段无隐私的短试录，再用于正式内容。
仓库只发布源码和说明，不提供已签名、公证的安装包。下面的构建步骤会在自己的 Mac 上生成 App；使用生成后的 App 不需要命令行。
English: CircleCast is a small native macOS screen recorder with a movable circular camera overlay, microphone audio, and a floating teleprompter. It uses Apple's system frameworks, has no third-party package dependencies, and saves MP4/MOV files locally. This is an early source-only MVP. Synthetic media and offline window tests pass; live capture, permissions, audio/video sync, and teleprompter exclusion still require hands-on validation. Licensed under MIT.
现有桌面 App 和构建产物仍显示「头像录屏」，项目中文展示名为「圆镜录屏」；名称整理不会改变应用行为或数据目录。
| 功能 | 当前实现 |
|---|---|
| 屏幕录制 | 选择一块显示器，录制整个屏幕和鼠标光标；一次只录一块 |
| 圆形头像 | 使用 Mac 内置摄像头；居中裁切、镜像、白色细边；真正合成到导出视频像素中 |
| 移动与缩放 | 拖动圆圈、滚轮缩放、主窗口大小滑块，以及四角快捷位置；头像限制在所选录制屏幕内 |
| 讲话录音 | 使用 macOS 当前默认麦克风，写入 AAC 音轨；不录系统声音 |
| 提词器 | 黑色半透明底、白字；默认在头像下方，可独立移动和缩放，粘贴文稿、滚动/暂停、回顶部、调速及字号 |
| 保存偏好 | 本地保存头像位置/大小、提词框位置/大小、文稿、速度和字号；屏幕变化时尝试恢复到可见区域 |
| 开始与停止 | 点击开始后申请权限，3 秒倒计时；主窗口和菜单栏均可停止 |
| 本地导出 | MP4 或 MOV，H.264 视频 + AAC 单声道音频；取消导出后仍可找回原文件 |
| 中断处理 | 为设备中断、屏幕变化和睡眠提供停止/清理路径；重复开始由状态门拦截 |
浮动头像只是预览：最终视频中的圆形头像由独立图像合成管线生成。提词器、控制窗口和预览浮窗通过“排除整个本应用”的 ScreenCaptureKit 过滤器从屏幕画面移除；提词文字不会作为输入交给合成器。这是代码中的实现策略，真实屏幕捕获时是否完全符合预期仍需试录确认。
| 项目 | 要求 / 验证范围 |
|---|---|
| 系统 | 项目部署目标为 macOS 14 或更新版本 |
| 实测机器架构 | Apple Silicon（arm64）；Intel 尚未测试，也不提供通用二进制 |
| 摄像头 | 枚举内置广角摄像头；本版不自动选手机、USB 或虚拟摄像头 |
| 麦克风 | macOS 默认音频输入设备 |
| 开发工具 | 完整 Xcode，包含 macOS SDK 和 Swift；Package.swift 声明 Swift tools 5.9 |
| 实际构建环境 | macOS 26.6，Xcode 27.0，Swift 6.4；其他工具链组合尚未验证 |
| 外部依赖 | 无 Swift Package 远程依赖，无 Electron、FFmpeg 或额外运行时 |
构建脚本使用系统提供的 swift、iconutil、codesign 和 zsh，不自动下载 SDK，不申请签名证书。缺少 Xcode 时需先自行安装；Xcode 下载体积与 App 本身体积不同。
不熟悉 Git 也可以使用仓库页面的 Code → Download ZIP，解压后继续下面的步骤。
-
安装完整 Xcode，并至少打开一次完成系统要求的初始设置。
-
在终端进入包含
Package.swift的项目文件夹。可以输入cd（末尾有空格），把解压后的文件夹拖进终端，再按回车。 -
执行：
zsh scripts/build.sh
-
构建成功后，在 Finder 打开项目中的
dist文件夹，双击 头像录屏.app。 -
可以把生成的 App 复制到“应用程序”或桌面，再拖到 Dock。建议固定一个位置使用，避免同时打开多份副本。
构建脚本会生成专属图标，创建 App 包，并执行 ad-hoc 本机临时签名。该签名不需要开发者账号，也不等于 Developer ID 签名或 Apple 公证。不会自动安装、启动 App 或开始录制。
这里显式使用 zsh 运行脚本，因此下载 ZIP 或网页上传造成执行权限位缺失时，也无需先修改文件权限。
源码可用 Xcode 打开 Package.swift 查看。进行实际权限试录时，优先运行构建脚本生成的 .app，不要仅运行裸命令行可执行文件，因为 App 包包含权限用途说明。
打开 App 后，选择需要录制的显示器。点击「摆放头像」，先用占位圆圈调整位置：
- 按住圆圈拖动到所选屏幕内的任意位置。
- 用滚轮或主窗口「大小」滑块调整尺寸，也可选择左上、右上、左下、右下。
- 此时不会开启摄像头。点击开始并获得权限后，圆圈才显示摄像头预览。
头像直径的界面范围约为 96–480 点，并受当前屏幕大小限制。录制中调整位置和大小会反映到后续输出帧。
勾选「显示提词器（仅自己可见）」，点击文字区，用 ⌘A 全选、⌘V 粘贴自己的讲稿。
- 拖动顶部标题区域移动整个文字框。
- 拖动边缘调整宽高；提词框可以离开头像独立摆放。
- 点击「滚动」开始自动阅读，「暂停」停止；「回顶部」从头开始。
- 用「速度」滑块调节滚动，用「字号」步进器调整文字大小。
- 编辑文稿会暂停滚动；关闭提词框或停止录制也会暂停。
文稿以明文保存在本机偏好设置中。请勿在公开 Issue、截图或代码提交中贴入个人讲稿。
先结束私人通话，移走不想录入的内容。 本版捕获所选的整个屏幕，其他应用的通知和窗口可能进入视频。
点击「开始录制」，按 macOS 提示允许：
| 权限 | 用途 |
|---|---|
| 摄像头 | 拍摄并合成圆形头像 |
| 麦克风 | 录制讲话 |
| 屏幕录制 / 屏幕与系统音频录制 | 获取选定显示器的屏幕画面；本版仍不采集系统音频 |
系统设置名称可能因 macOS 版本不同而略有变化。拒绝后可前往 系统设置 → 隐私与安全性 的对应分类，开启「头像录屏」。首次授予屏幕录制权限后，系统可能要求退出并重新打开 App；按提示操作后再点开始。
权限完成后会有 3 秒倒计时，然后启动设备和屏幕流。菜单栏显示录制状态。启动过程中可以点「取消启动」；如果系统权限对话框还开着，需要先处理该系统对话框，取消流程才能继续完成。
点击主窗口「停止并导出」，或菜单栏中的「停止录制」。等待文件完成后，选择本地保存位置。
- 开始前选择 MP4（推荐）或 MOV；它们是容器格式，均使用 H.264 视频和 AAC 音频。
- 导出是复制操作。即使取消保存对话框，原始录制也会保留。
- 点击「打开录制暂存文件夹」可在 Finder 中找回、复制或删除原文件。
- 退出 App 会先停止并尝试完成当前录制；退出时没有导出的文件也可从暂存目录找回。
- 录制中关闭主窗口会先停止，完成后可再次关闭；关闭窗口后可从菜单栏重新打开。
停止路径会关闭屏幕流、摄像头/麦克风会话、预览连接与合成定时器。目前尚未实测真实设备指示灯/占用的释放效果，首次试用请一并确认。
App 没有账号系统、遥测、网络上传、云端处理或自动更新代码。权限由系统和本人控制；打开主窗口、摆放占位头像和编辑提词本身不会启动媒体采集。
| 数据 | 保存位置 / 行为 |
|---|---|
| 原始录制 | ~/Library/Application Support/CircleCast/Recordings/ |
| 导出文件 | 你在保存对话框中选择的位置 |
| 文稿与界面偏好 | UserDefaults 域 local.circlecast.recorder；通常由系统管理在用户偏好设置目录 |
| 开发构建与缓存 | 项目内的 .build/ 和 dist/；构建工具也可能使用其标准用户缓存 |
| 自动测试产物 | 项目内 TestArtifacts/，只有合成色块、音调及测试日志 |
导出完成后不会自动删除原始录制，因此可能占用两份磁盘空间；请在确认导出成功后自行清理。删除 App 不会自动删除录制、导出文件和偏好设置。若要清除保存的讲稿，可以在 App 中全选文字并删除；删除其余本地数据前请先退出 App 并备份需要的文件。
仓库不包含真实录屏、照片、录音、个人讲稿、日志、账号凭据、签名证书或构建出来的 App。图标由仓库内的原创绘图脚本生成，不使用第三方人物照片或素材。
运行无真实媒体采集的测试：
zsh scripts/test.sh测试会调用系统视频/音频编解码器，创建少量合成文件，并构造但不显示 App 窗口；不会调用真实屏幕捕获或开启摄像头、麦克风。需要具备可用桌面会话的 Mac，不适合直接当作 Linux / 无图形会话测试运行。
当前基线为 8 项 XCTest：
- 多屏正负原点、四角边界、缩放限制、输出尺寸。
- 100 轮状态转换，以及各启动阶段取消和重复开始拦截。
- MP4 / MOV 生成后重新解码：640×360、60 帧、2 秒；确认圆形遮罩、移动及变大。
- 两种容器的音轨解码：48 kHz 单声道，96,000 个 PCM 样本；RMS 约 0.212，440 Hz 输入音调测得约 439.5 Hz。
- 3 次独立写入/完成、结束后的迟到帧、零帧取消和写入器对象释放。
- 不显示窗口的头像位置/大小方法、主窗口布局、提词框缩放及离屏恢复。
这些结果验证了相应模块及合成文件，不代表真实录屏全流程通过。真实音画同步、提词和控制层排除、鼠标手感、外接屏热插拔、权限拒绝/撤销、停止后的设备释放、长录制性能均仍待实机验证。详见 验证记录与试录清单。
- MVP 只录整块屏幕，不支持选窗口、局部框选、多屏拼接、暂停后续录、剪辑或直播。
- 内置摄像头和默认麦克风为当前设备策略，未提供设备选择器；摄像头或麦克风不可用时，本版不能切换为纯录屏。
- 摄像头优先请求 720p；视频目标 30 fps，输出最长边上限 1920 像素，SDR。它不是 4K/HDR 录制工具。
- 不录系统声音，无背景抠像、美颜、降噪配置或字幕生成。
- 编码繁忙可能丢帧或丢音频段；停止后的状态文字会显示丢弃数量。长时间录制、低磁盘空间和功耗尚未实测。
- 全屏应用、不同 Space、受保护内容、多个 App 副本同时运行和 macOS 自带视频特效的组合效果尚未验证。
- 拒绝权限或设备中断的处理已编写，仍需系统环境实测；不能保证任何异常情况下都能恢复未完成视频。
- 重建或移动本机临时签名 App 后，macOS 可能需要重新确认权限。仓库没有公证安装包、自动更新或正式发布签名。
| 现象 | 可以先做什么 |
|---|---|
swift / SDK 不可用 |
确认已安装并初始化完整 Xcode，xcode-select -p 指向有效开发工具；不要为此关闭系统安全保护 |
| 构建脚本提示权限不足 | 在项目目录使用 zsh scripts/build.sh；确认项目目录可写 |
| 系统阻止 App 打开 | 确认是自己从这份源码构建的 App，再使用 Finder 右键「打开」或系统提供的打开提示；不要禁用 Gatekeeper / SIP |
| 始终没有屏幕画面 | 检查「头像录屏」的屏幕录制授权，并按系统要求退出重开；确认所选显示器仍连接 |
| 没有摄像头 / 麦克风 | 检查隐私权限和系统声音输入设备；结束占用设备的通话后重试；本版只选择内置摄像头 |
| 提词器或头像跑到屏幕外 | 重新选择显示器、再次点「摆放头像」，或关闭后重新显示提词器，让恢复位置逻辑执行 |
| 桌面不动时头像卡住 | 实现使用独立合成定时器刷新；若真实录制仍卡住，请提供无隐私的复现步骤和系统版本 |
| 点导出取消后找不到视频 | 用主窗口「打开录制暂存文件夹」，原始录制仍在本机 |
| 导出无声 / 不同步 | 先确认默认麦克风确实有输入，录 15 秒测试并播放；提交问题前删除个人媒体和路径 |
| 测试提示无法建立 H.264 / AAC 编码器 | 受限自动化沙箱可能禁止访问系统编解码服务；在正常本机开发环境运行无设备测试，勿用关闭系统保护来解决 |
| 授权弹窗还在但已点取消 | 先处理系统对话框，等待 App 完成取消；不要反复点开始 |
Sources/
CircleCast/ 主窗口、浮窗、权限和录制协调、采集管线
CircleCastCore/ 坐标、状态门、Core Image 合成和媒体写入
Tests/
CircleCastCoreTests/ 几何、状态和合成媒体测试
CircleCastAppTests/ 不显示窗口的 AppKit 测试
Resources/Info.plist App 信息和权限用途说明
scripts/
build.sh 生成本机可运行的 App
test.sh 运行无设备测试
make-icon.swift 原创图标绘制
audit-publication.py 对 Git 暂存区/历史做发布前文件检查
check-doc-links.py 检查本地文档链接
docs/ 架构与验证说明
架构说明 · 验证记录 · 更新记录 · 贡献指南 · 安全报告 · 第三方声明
原创代码、说明和图标生成脚本使用 MIT License。Apple 系统框架与 SDK 不随仓库分发，仍遵循各自条款。
欢迎报告问题或提交 Pull Request。提交前请阅读 CONTRIBUTING.md，用合成内容复现，保留“自动测试通过”和“实机通过”的区别。当前没有自动 GitHub Actions 工作流，不会因克隆或提交源码自动启动收费构建任务。