features.md

Framelet 功能全集与取舍

本次整理以当前源码和自动化测试为依据。Framelet 的定位是 macOS 轻量无声录屏工具：选择窗口或区域，录制，预览，裁掉不需要的时间段，再导出 MP4 或 GIF。不以补齐 Snow Shot 的所有功能为目标。

1. 当前保留的功能

选择与录制

功能	范围与限制
任意区域录制	拖出矩形；可选择任一显示器，但一次录制不跨显示器
窗口录制	使用 ScreenCaptureKit 独立窗口捕获；输出尺寸固定，窗口改变大小后由系统适配
菜单、弹出面板选择	菜单级窗口按屏幕区域录制，不依赖独立窗口捕获
非激活选择器	不抢目标的键盘焦点；点击、Return 或录制快捷键确认；Escape、右键取消
倒计时	界面提供 3、5、10 秒；可取消；用户设置跨启动记忆
开始、停止	主窗口、悬浮条、菜单栏和全局快捷键均可操作
暂停、恢复	不重建采集流；通过帧门控和时间戳偏移排除实际暂停时间
保存后重录	保存成功后对当前目标重新倒计时；保存失败时不开始下一条
区域移动	单击「Move area」后在区域内拖动，松开完成，右键退出；也可直接拖手柄，尺寸和显示器不变
移动控制条	普通拖动只移动控制条，不再改变采集区域
鼠标指针	可显示或隐藏
点击提示	可选，默认关闭；使用 macOS 15 ScreenCaptureKit 原生点击反馈，不监听全局键盘
帧率	界面提供 30、60 fps；存储设置进入受支持范围后才传给采集器
编码	H.264 默认，HEVC 可选；长边最多 3840 像素，保持偶数输出尺寸

实际帧率可能受系统采样频率和编码器背压影响。背压时丢帧而不无限缓存整屏图像。HEVC 的体积收益取决于画面与编码器，不保证固定缩小比例。

采集明确请求最佳分辨率。小区域向内对齐像素网格和偶数输出尺寸，避免仅为偶数尺寸而对整幅画面轻微缩放。编码码率按画面像素和帧率计算，最低 2 Mbps；H.264 和 HEVC 仍是有损编码，清晰度优先会增加文件体积。原始尺寸预览以显示器真实像素为单位：Retina 上一个视频像素对应一个显示像素，不对应一个 AppKit 点。

简单标注

功能	范围与限制
画笔、荧光笔、箭头	仅区域录制；显式开启绘制模式后接管鼠标
五色	红、黄、绿、蓝、紫；切换工具或颜色不改变已开始的笔画
撤销、清空	改变后续画面中的标注；不会回写已录制的历史帧
实时预览	已完成的笔画仍显示；预览和视频使用同一套绘制逻辑
静态画面刷新	笔画新增、清空、区域移动或恢复录制时，可用最近一张完整帧重新合成
非激活绘制层	不成为键盘焦点；保持在控制条下方，避免画面覆盖停止按钮

标注直接合成进视频，录制后不能拆出独立图层再编辑。笔画保存在桌面坐标中，区域移走后不再显示落在区域外的笔画。窗口录制不显示区域移动和标注按钮，避免固定坐标与跟随窗口混用；控制条明确提示「跟随窗口，框选区域可标注」。暂停切换期间保持停止入口，不再复用「Starting」状态；控制条不随每次相位变化重建。

预览、裁剪与导出

功能	范围与限制
本地预览	播放、暂停、拖动进度；默认原始像素尺寸，不放大小视频；可切换「适应窗口」，仅改变预览
MP4 全片保存	默认保存整条；无声音频轨时复制原文件，不重新编码
MP4 时间裁剪	设置起点和时长，另存为新文件；使用原生透传导出，边界受媒体结构限制，不承诺所有编码都逐帧精确
GIF 时间选段	默认前 10 秒，短片取全片；最多 60 秒
GIF 帧率、长边	界面提供常用值；内部校验帧率 1–30、长边 64–1920 像素
内容自适应调色板	采样构建共享调色板，以原始 RGB 的加权平均生成颜色；最多 256 色，仍存在量化误差
GIF 抖动	默认开启 Floyd–Steinberg 抖动；关闭可保持填充平坦，不代表无损颜色
GIF 循环与时序	循环播放；按累计边界分配百分之一秒延迟，减少分数帧率造成的时长漂移
导出取消	GIF 显示进度，视频显示进行中状态；取消或失败不替换已有目标文件
原片保护	导出不覆盖源文件，包含源文件的符号链接、硬链接；成功才提交暂存文件

MP4 和 GIF 共用一组「起点／时长」控件，并通过格式选择器切换。切换格式重置为适合该格式的默认范围；范围不跨录制文件记忆。

文件、权限与运行方式

功能	范围与限制
录制库	按时间显示本地录制；选择后预览；可打开录制目录
删除	确认后移到废纸篓；已导出的文件不删除
完成后显示文件	导出成功后可在 Finder 中定位
未完成文件隔离	当前录制先写入 Unfinished 会话目录，通过结束和视频校验后才进入主列表
中断报告	采集流中断后若能结束出可播放文件，保存该文件并保留中断提示，不当作普通成功
中断恢复	下次启动尝试恢复可播放的当前单文件或旧分段；失败保留原文件
谨慎清理	仅删除已确认空目录或零字节视频；不能因读取、解码失败而删除非空文件或未知内容
权限说明	根据实际采集错误显示屏幕录制权限说明；可打开系统设置，不重置系统权限
全局快捷键冲突处理	优先 ⌥⌘R／⌥⌘P，冲突时按顺序尝试备用组合，显示实际生效组合
菜单栏常驻	关闭主窗口不退出；录制、导出、恢复期间避免误退出
设置记忆	帧率、指针、点击提示、编码、倒计时、GIF 参数，以及主窗口尺寸和位置
本机构建、安装、仅打包	Swift Package，无第三方依赖；本机安装使用稳定签名；公开分发仍需单独处理 Developer ID 和公证
许可证	MIT

强制结束进程可能产生无法播放的 MP4。保留非空文件不等于保证能恢复完整录制；当前没有断电恢复承诺。

2. 本次删掉或替换的内容

• 删除全局按键显示和 CGEvent tap。 普通字符也会成为按键标签，与此前「不记录文本」的说明矛盾；还带来输入监控权限、生命周期和隐私负担。Framelet 仍保留 Carbon 注册的明确操作快捷键，它们不读取日常键盘输入。
• 用系统点击提示替代自建点击环。 不再维护全局鼠标监听、自定义点击存储、生命周期和绘制逻辑；默认关闭。
• 删除独立的标注总开关。 区域录制中的画笔按钮已经是明确入口，总开关只会造成两个开启条件。窗口录制不显示无效入口。
• 删除拖动控制条就移动录制区的隐式行为。 改用单独手柄，避免用户整理控制条位置时改变录制内容。
• 合并重复导出入口。 格式选择器、一组范围设置和一个保存按钮取代长期并列的 MP4/GIF 操作；选中格式后显示对应参数。
• 删除遗留 .pausing 分段状态和重复计时器创建逻辑。 暂停由写入队列确认，正常暂停不再产生多个分段；旧分段拼接仍保留给兼容恢复。
• 删除误导性说明。 不再保证「HEVC 固定减半」「GIF 平坦颜色无损」「编码器失败一定抢救成功」。
• 修正窗口名重复与不可用控件。 相同应用名、窗口名不再重复拼接；窗口模式不显示区域标注和移动控件。

3. 本次补齐的欠缺

• 非破坏的 MP4 时间裁剪，保留原片。
• 首条录制在编码器创建前就得到自己的标注存储；每条录制使用新的存储。
• 绘制工具栏使用真实窗口尺寸，所有控件位于窗口内容边界内；窄屏使用菜单。
• 录制区、边框与绘制层只在移动被接受后一起更新。
• 静态画面新增、撤销、清空笔画后的编码刷新；只保留一张最新表面帧，避免无限队列。
• 多次暂停不重复累计偏移；暂停前和恢复后的静态有效时间保留。
• 停止和流错误共用一次终结操作，重复结束共享结果，消除空文件假成功。
• 当前单文件会话也进入恢复目录；解码失败不再自动删除非空文件。
• GIF 原始 RGB 加权、确定性调色板、按行取消检查、两行抖动误差缓冲和时长舍入。
• 模型接线、媒体输出、导出源文件保护、设置持久化与最小窗口布局回归测试。

4. 暂不加入的功能

功能	判断
系统音频、麦克风、摄像头	有价值，但意味着音轨同步、暂停语义、权限和混音；当前明确为无声演示，不在本轮加入
普通截图、滚动截图、OCR、二维码、表格、公式	属于综合截图工具方向，超出录屏核心流程
马赛克、模糊、复杂形状、文字编辑器	需要更多交互与稳定的编辑模型，不为追平参考仓库而增加
录后可编辑标注、多轨时间线、转场	属于视频编辑器，明显超出轻量定位
录制中缩放区域、跨屏移动	会改变画面比例和采集源；当前只移动固定尺寸区域
APNG、动态 WebP、AVI	当前 MP4/GIF 已覆盖主要使用路径，更多格式会扩大编码和兼容测试面
MCP、云同步、分享服务	无明确需求；增加协议、存储或外部服务负担
Homebrew、自动更新、公开安装包	发布前事项；没有合适签名、公证和发布产物时不建立空分发配置

这里的「暂不加入」不等于永远不做。后续只有具体使用需求及可验证的验收目标，才扩大范围。

5. 验证边界

自动化测试使用真实编码/解码的合成视频、直接驱动 AppKit 交互，以及可注入的假采集器验证模型接线。它们覆盖时间线、颜色、裁剪、标注位置、失败文件保留和窗口布局，不需要申请真实屏幕录制权限。

真实屏幕权限、原生点击提示的外观、全屏 Space、多显示器动态变化、目标窗口关闭和长时间录制仍需授权 Mac 上验收。不能把合成帧测试通过描述成这些场景已经验收。