从首次启动到最终导出，全程使用 Luxel。

安装 Luxel

1. 安装并启动 Luxel。
2. 授予权限前，请将应用放在一个固定位置。
3. 从 Finder 或启动台打开 Luxel。
4. 在 macOS 菜单栏中找到 Luxel 状态项。

Luxel 需要 macOS 26.0 或更高版本。Luxel 从菜单栏运行，因此菜单栏项目是开始捕捉和打开设置的主要入口。

首次捕捉

1. 从菜单栏打开 Luxel。
2. 从“目标”中选择一个目标，或使用“区域”绘制自定义范围。
3. 仅在录制需要时启用系统音频、麦克风或摄像头。
4. 点按“录制来源”、“录制区域”或“录制音频”。
5. 通过菜单栏状态控制、活跃录制控制或快捷键停止录制。

启用提示

1. 打开“设置”>“录制”。
2. 打开“检测到语音时通知”。
3. 阅读说明，然后选择“启用”以表示同意。
4. 先允许通知，再允许访问麦克风。
5. 选择“系统默认”或特定麦克风。

如果希望登录后可以使用此功能，请打开“登录时启动”。检测仅在 Luxel 打开时有效。

选择后续操作

Luxel 检测到信号后，通知会提供“开始录制”和“关闭”。“开始录制”会使用所选麦克风开始一次纯音频录制。“关闭”不会执行任何操作；仅打开通知会激活 Luxel，但不会录制。

专注模式和其他 macOS 通知设置可能会延迟或隐藏提示。提示只是一项辅助功能，并不保证 Luxel 能识别对话。

设置回放缓冲区

1. 打开“设置”>“回放缓冲区”。
2. 启用回放缓冲区，并批准首次使用同意提示。
3. 选择时长：30 秒、1 分钟、2 分钟或 5 分钟。
4. 选择 24 FPS 或 30 FPS。
5. 只有片段需要 Mac 音频时才打开“包含系统音频”。
6. 选择片段是在编辑器中打开，还是使用快速导出目标。

从菜单使用

1. 通过菜单栏控制启动回放缓冲区。
2. 等待状态从“正在启动”变为“正在缓冲”。
3. 点按“导出”保存所选的最近时长。
4. 使用“开始”和“停止”启用或停用缓冲区。
5. 使用“截取回放缓冲区”快捷键或 luxel clip 执行相同操作。

绘制选区

点按“区域”打开全屏选择叠层。拖动以绘制区域，使用控制柄调整大小，或使用“全显示器”选择显示器。最小选区为 32 × 32 像素。

大小预设包括 1280 × 720、1920 × 1080 和 800 × 600。宽高比选项包括自由、16:9、4:3、1:1、9:16 和 21:9。

实用控制

• 选择倒计时、停止计时、音频、摄像头、比例和大小控制。
• 权限允许时切换麦克风和摄像头。
• 使用放大镜精确定位边缘。
• 在“预设”设置中调暗其他显示器或恢复上次选区。
• 如果希望减少打扰，可从通知提醒中打开“专注模式”设置。

在编辑器中

1. 在编辑器中打开带音频的录制。
2. 使用转录预览生成或查看转录文本。
3. 搜索转录文本，或选择转录片段以跳转播放。
4. 保持启用“分段转录轮次”，以自动进行轮次分组。
5. 对于较长录制，如需更快生成原始转录，可在“设置”>“转录”中关闭此功能。

识别和管理说话人

1. 在“设置”>“转录”中启用“识别说话人”。
2. 生成转录，以在本地分离并标记每个检测到的声音。
3. 在“说话人”卡片中使用自动检测，或设置精确人数或范围，然后重新运行检测。
4. 播放声音示例、命名检测到的说话人、将其保存为已知说话人、关联到现有资料，或忽略它。
5. 今后的转录可以自动匹配已保存的已知说话人。

声音资料和说话人处理都保留在你的 Mac 上。

从命令行

luxel transcribe demo.m4a > demo.txt
luxel transcribe demo.mp4 --output demo.json --format json --overwrite
luxel transcribe demo.mp4 --locale en_US --semantic-turns --diarize

默认将纯文本打印到 stdout。使用 --format json 获取完整的按轮次分段转录数据；启用以下选项时还会包含说话人标签： --diarize 。

与 Luxel 配对

luxel pair
luxel doctor

配对会在 Luxel 中打开可见的批准提示。应用和 CLI 分别在 macOS 钥匙串中存储凭据副本。你可以随时在“设置”>“命令行”中停用命令行控制或撤销已配对客户端。

常见示例

luxel record --display main --fps display --countdown 3
luxel record --active-window --fps 120
luxel toggle --last-area
luxel stop
luxel clip --seconds 30
luxel latest --reveal
luxel preferences

媒体示例

luxel record --active-window --preset "Default" --save-to ~/Movies/Luxel
luxel editor ~/Movies/demo.mp4
luxel convert demo.mp4 demo.webm
luxel convert demo.mp4 demo-av1.mp4 --format av1
luxel convert demo.mp4 demo.gif --start 2 --duration 5 --fps 15 --width 800 --height 450
luxel convert demo.mp4 demo.mov --format prores422 --quality high
luxel export request.json output.webm --overwrite --json
luxel transcribe demo.m4a > demo.txt
luxel transcribe demo.mp4 --output demo.json --format json --diarize --overwrite

智能体技能

安装 Luxel Skills，让兼容的编程智能体能够使用完整 CLI，或为评审创建聚焦的 WebM 证据。

npx skills add https://github.com/rawcontext/luxel-skills
npx skills add https://github.com/rawcontext/luxel-skills --skill luxel
npx skills add https://github.com/rawcontext/luxel-skills --skill luxel-evidence

选择 luxel 以查询命令并执行操作；选择 luxel-evidence 以使用有明确目的的录制和附件工作流。

在 GitHub 上查看 Luxel Skills。

文件夹访问

Luxel 可以使用你的“影片”文件夹、已配置的录制文件夹，以及你在应用中批准的文件夹。终端路径绝不会绕过 App Sandbox。

luxel access add ~/Desktop/Exports
luxel access check ~/Desktop/Exports/demo.mp4
luxel access list
luxel access revoke <grant-id>

access add 会打开 Luxel 的文件夹选择器。你在其中选择的文件夹就是应用获得使用权限的文件夹。

安全与隐私

每次调用都会在以下位置使用经过身份验证的短期连接：127.0.0.1。Luxel 会拒绝未配对客户端、过期请求、重复使用的随机数、已修改的请求正文和非回环端点。CLI 永远不会收到 Luxel 的安全范围书签，也不会自行处理媒体。

URL 方案

Luxel 注册了 luxel:// URL 方案。开始捕捉和截取回放缓冲区可能需要确认，除非调用方已获授权；stop、preferences 和 latest 等命令默认允许。

luxel://record?target=display&display=main&fps=display&countdown=3
luxel://record?target=activeWindow&preset=Default
luxel://toggle
luxel://stop
luxel://clip?seconds=30
luxel://preferences
luxel://latest?reveal=true

x-callback URL

自动化命令接受 x-success 和 x-error 回调 URL。成功生成文件的命令会附加 filePath，录制开始会附加 recordingID，失败会附加 errorMessage。

直接使用 URL 方案进行 x-callback 自动化。

快速预设

可以添加、复制、删除和重命名导出预设，并将其指定为“快速录制”预设。预设支持格式、大小规则、帧率、目标和后续操作。预设目标可以是“录制”文件夹或剪贴板。快速预设提供 GIF、MP4、HEVC MP4、ProRes 422 MOV、ProRes 4444 MOV 和 APNG；WebM 和 AV1 仍可从编辑器和 CLI 导出。

回放缓冲区

回放缓冲区设置控制启用开关、片段长度、24 或 30 FPS、是否包含系统音频、启动时继续，以及片段是在编辑器中打开还是发送到快速导出目标。

命令行

命令行设置可启用外部控制、打开 CLI 仓库、撤销已配对客户端，以及管理应用可用于命令行请求的文件夹。

系统行为

系统设置涵盖菜单栏计时器、通知提醒、登录时启动、更新和致谢。

支持的区域设置

• 英语
• 德语（德国）
• 欧洲西班牙语
• 法语（法国）
• 意大利语（意大利）
• 日语（日本）
• 韩语（韩国）
• 越南语
• 简体中文
• 巴西葡萄牙语
• 葡萄牙语（葡萄牙）

权限提示

摄像头、麦克风、屏幕捕捉和语音识别提示会以所选语言显示。Luxel 仅在启用相应功能或开始录制时请求各项权限。

Luxel 会自动遵循你的 macOS 语言设置。