{"id":28794175,"url":"https://github.com/sakuzypeng/atmosrecorder","last_synced_at":"2026-04-28T13:39:10.731Z","repository":{"id":298847270,"uuid":"1000982058","full_name":"SakuzyPeng/AtmosRecorder","owner":"SakuzyPeng","description":"一款由 AI 开发的 macOS 命令行工具，可录制系统解码的杜比全景声（Dolby Atmos）并保存为 12 声道 WAV 文件。","archived":false,"fork":false,"pushed_at":"2025-06-13T07:21:53.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-13T08:27:28.344Z","etag":null,"topics":["ai-programming","audio-recorder","avfoundation","cli","command-line-tool","dolby-atmos","macos","objective-c","spatial-audio"],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SakuzyPeng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-12T16:11:08.000Z","updated_at":"2025-06-13T07:21:57.000Z","dependencies_parsed_at":"2025-06-13T08:28:50.462Z","dependency_job_id":"a10c3214-c2d5-4378-9667-862cc73f13c8","html_url":"https://github.com/SakuzyPeng/AtmosRecorder","commit_stats":null,"previous_names":["sakuzypeng/atmosrecorder"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/SakuzyPeng/AtmosRecorder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SakuzyPeng%2FAtmosRecorder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SakuzyPeng%2FAtmosRecorder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SakuzyPeng%2FAtmosRecorder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SakuzyPeng%2FAtmosRecorder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SakuzyPeng","download_url":"https://codeload.github.com/SakuzyPeng/AtmosRecorder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SakuzyPeng%2FAtmosRecorder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260471635,"owners_count":23014255,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-programming","audio-recorder","avfoundation","cli","command-line-tool","dolby-atmos","macos","objective-c","spatial-audio"],"created_at":"2025-06-18T02:04:56.983Z","updated_at":"2026-04-28T13:39:10.722Z","avatar_url":"https://github.com/SakuzyPeng.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **开发说明**\n\u003e\n\u003e 本程序由 AI 完成编写和优化工作，开发者仅提供需求和反馈。这是一个探索 AI 辅助编程能力的实验项目。\n\u003e\n\u003e **开发工具**\n\u003e\n\u003e - **AI**(网页端):\n\u003e   - 主要编写：Claude 4 Opus (Anthropic)\n\u003e   - 辅助优化：Gemini 2.5 Pro Preview (Google)\n\u003e   - 气氛组：ChatGPT o4-mini-high (OpenAI)\n\u003e - **IDE**：Xcode 16.4\n\u003e - **系统**：macOS 15.5\n\u003e\n\u003e **Q: 处理时可以使用其他音频应用吗？**\n\u003e\n\u003e A: **通常可以**。经测试，播放音乐、视频等不会影响录制。但建议不要在处理过程中切换音频设备或更改设备设置。\n\u003e\n\u003e **Q: 录制的音频会受到系统空间音频设置的影响吗？**\n\u003e\n\u003e A: **不会**。本程序直接获取解码后的原始多声道数据，不受头部追踪、个性化空间音频（HRTF）等系统设置的影响。您获得的是纯净的 12 声道解码结果。\n\n# 全景声音频录制工具\n\n一个简单的 macOS 命令行工具，用于录制由系统解码后的多声道音频（如杜比全景声），并将其保存为 12 声道 WAV 文件。\n\n**声明**：本程序完全由 AI 开发，开发者未参与代码编写。\n\n## 功能特点\n\n🎵 基础音频处理：使用 Apple 的 MTAudioProcessingTap API 进行音频提取\n\n🔊 固定输出格式：输出为 12 声道 7.1.4 格式（48kHz, 32-bit Float）\n\n📦 批量处理：支持处理多个文件\n\n📊 进度显示：显示基本的处理进度\n\n🚀 使用方便：支持拖拽文件处理\n\n## 系统要求\n\n- macOS 10.15 或更高版本（推荐 macOS 11.0+）\n- 支持的输入格式：`.m4a`、`.ec3`\n\n**注**：在 macOS 15.0+ 上开发和测试，较旧版本可能存在兼容性问题。\n\n## 安装方法\n\n### 方法一：下载预编译版本（推荐）\n\n1. 访问 **Releases** 页面。\n\n2. 下载最新的 `AtmosRecorder-unix.tar.gz`。\n\n3. 解压并运行：\n\n   ```\n   tar -xzf AtmosRecorder-unix.tar.gz\n   chmod +x AtmosRecorder\n   ./AtmosRecorder\n   ```\n\n### 方法二：通过 GitHub Actions 下载\n\n1. 访问 **Actions** 页面。\n2. 选择最新的成功构建。\n3. 下载 `unix-executable-AtmosRecorder` artifact。\n4. 解压后即可使用。\n\n### 方法三：从源码编译\n\n1. 克隆仓库：\n\n   ```\n   git clone https://github.com/Sakuzy/AtmosRecorder.git\n   cd AtmosRecorder\n   ```\n   \n2. 使用 Xcode 打开项目：\n\n   ```\n   open AtmosRecorder.xcodeproj\n   ```\n   \n3. 选择目标设备为 \"My Mac\"。\n\n4. 点击 **Product → Build**（或按 `⌘B`）编译。\n\n## 使用方法\n\n### 基本用法\n\n**自动查找模式**\n\n```\n./AtmosRecorder\n```\n\n程序会在当前目录中查找第一个支持的音频文件并处理。\n\n**指定文件**\n\n```\n./AtmosRecorder /path/to/audio.m4a\n```\n\n处理指定的音频文件。\n\n**批量处理**\n\n```\n./AtmosRecorder file1.m4a file2.eac3 file3.ec3\n```\n\n一次处理多个文件。\n\n**处理整个文件夹**\n\n```\n./AtmosRecorder /path/to/folder/\n```\n\n自动查找并处理文件夹中的所有支持格式的音频文件。\n\n### 快捷用法\n\n**拖拽**：将文件或文件夹拖到程序图标上，自动处理。\n\n**双击**：双击程序图标，自动处理同目录下的音频文件。\n\n## 输出说明\n\n- **输出格式**：WAV 文件\n\n- 声道配置\n\n  ：12 声道 7.1.4\n\n  - `L`, `R`, `C`, `LFE` (前置左右、中置、低音)\n  - `Ls`, `Rs` (环绕左右)\n  - `Ltf`, `Rtf` (前置顶部左右)\n  - `Ltr`, `Rtr` (后置顶部左右)\n  - 备用声道 x2\n\n- **采样率**：48,000 Hz\n\n- **位深度**：32-bit Float\n\n- **文件命名**：`原文件名_atmos_714.wav`\n\n- **避免覆盖**：如果输出文件已存在，会自动添加编号（如 `_atmos_714_1.wav`）\n\n### 声道映射\n\n程序采用简单的声道映射方式：\n\n- 如果解码后的结果少于 12 声道，额外的声道将为静音。\n- 如果解码后的结果超过 12 声道，只使用前 12 个声道。\n- 尽量保持原始音频的基本特性。\n\n## 性能说明\n\n- 处理速度为实时播放速度（1x），这是当前实现的限制。\n- 处理过程中音频会静音播放，不会产生声音。\n- 输出文件较大，约每分钟 **140MB**。\n- 处理前请确保有足够的磁盘空间。\n\n#### 实际案例参考\n\n以下是一次真实的处理记录，可供参考：\n\n- **输入文件**：一个 `3分58秒` 的全景声音频 (`.ec3`, 1024kb/s, `30.5 MB`)\n- **峰值内存**：约 `50 MB` (在 Xcode 调试环境下观测)\n- **输出文件**：一个 12 声道的 `.wav` 文件，大小为 `549.5 MB`\n\n## 注意事项\n\n\u003e #### ⚠️ 重要提醒\n\u003e\n\u003e - **版权注意**：请确保您有权处理相关音频文件。本工具仅供个人学习和合法用途使用。\n\u003e\n\u003e - 文件大小\n\u003e\n\u003e   ：输出的 WAV 文件会比原始压缩格式大很多。例如：\n\u003e\n\u003e   - 5 分钟的音频 ≈ 700MB\n\u003e   - 1 小时的音频 ≈ 8.4GB\n\u003e\n\u003e - **处理时间**：由于采用实时处理，一个 5 分钟的音频文件需要约 5 分钟处理时间。\n\u003e\n\u003e - **内存使用**：处理大文件时可能占用较多内存，建议关闭其他大型应用。\n\u003e\n\u003e #### 音频设备注意事项：\n\u003e\n\u003e 本程序录制的是纯净的解码结果，**不受**以下因素影响：\n\u003e\n\u003e - 头部追踪（Head Tracking）\n\u003e - 个性化空间音频（Personalized HRTF）\n\u003e - 系统音效处理\n\u003e\n\u003e 经测试，其他程序的音频播放通常不会影响录制。\n\u003e\n\u003e **重要**：处理过程中请**避免**：\n\u003e\n\u003e - 切换音频输出设备\n\u003e - 更改音频设备设置（如 AirPods 的空间音频开关）\n\u003e - 插拔音频设备\n\u003e\n\u003e 这些操作可能会导致录制中断或产生异常。\n\u003e\n\u003e #### 如何验证输入文件为全景声？\n\u003e\n\u003e 在处理文件时，您可以随时检查您的音频文件是否被 macOS 正确识别为杜比全景声格式。这是一个非常有用的验证方法：\n\u003e\n\u003e 1. 运行 `AtmosRecorder` 并开始处理一个音频文件。\n\u003e 2. 连接您的空间音频耳机（如 AirPods Pro 2）。\n\u003e 3. 打开 macOS 的**控制中心**，并点击**声音**模块。\n\u003e 4. 如果您看到如下图所示，在音量条旁边明确显示 **“杜比全景声”** 字样，这证明系统已成功激活全景声解码器。\n\u003e\n\u003e 这表明您的输入文件是有效的全景声音频，并且本工具正在正确地截取解码后的数据。\n\u003e\n\u003e **注**：本工具默认以**静音模式**在后台处理音频。即使**不连接任何耳机**，录制过程也完全可以正常工作。不过，“杜比全景声”这个视觉提示是 macOS 空间音频功能的一部分，通常只在使用受支持的耳机时才会显示。因此，如果您使用内置扬声器，将看不到此提示，经测试这不影响最终录制的 12 声道 WAV 文件。\n\n## 故障排除\n\n- **问题：程序提示\"未找到音频轨道\"**\n\n  - 确保输入文件包含音频数据。\n  - 检查文件是否损坏。\n\n- **问题：输出文件声道数不正确**\n\n  - 这通常表示输入文件不是真正的全景声格式。\n  - 尝试使用其他全景声音频文件。\n\n- **问题：处理速度很慢**\n\n  - 这是正常的，程序使用实时播放速度以确保质量。\n  - 确保磁盘有足够的写入速度（建议使用 SSD）。\n\n- 问题：控制台出现系统警告信息\n\n  如果看到类似以下的警告信息，这是正常的，不会影响转换结果：\n\n  ```\n  AddInstanceForFactory: No factory registered for id...\n  PlatformUtilities::CopyHardwareModelFullName() returns unknown value...\n  MEMixerChannel:: failed to set kAudioUnitProperty_ChannelLayout...\n  HALC_ProxyIOContext::IOWorkLoop: skipping cycle due to overload\n  ```\n\n  这些是 macOS 音频系统的内部警告，可以安全忽略。最后一条关于 \"overload\" 的警告可能在系统负载较高时出现，但不影响音频质量。\n  \n  为了尽可能地提升程序的稳定性和可靠性，**AtmosRecorder 内部已经实现了一项尝试**：程序在启动时，会通过执行 `[NSThread setThreadPriority:1.0];` 这行代码，主动向 macOS 系统申请更高的线程处理优先级。\n  \n  这样做的目的是，当您的电脑比较繁忙时，操作系统会更倾向于将宝贵的 CPU 资源分配给 AtmosRecorder，从而尽力避免因处理超时而产生 `overload` 警告。\n  \n  尽管有这项优化，但 `overload` 警告的出现与整个系统的瞬时负载都有关系，因此可能无法 100% 杜绝。\n\n## 技术细节\n\n本工具使用了以下技术：\n\n- **MTAudioProcessingTap**：Apple 的音频处理 API\n- **AVFoundation**：用于媒体文件的读取\n- **非交错音频格式**：用于多声道音频处理\n\n工具仍在持续改进中，可能存在一些限制和不足。\n\n## 常见问题\n\nQ: 为什么固定为 12 声道输出？\n\nA: 这是基于 Apple 系统解码全景声的常见格式。我们采用了这个配置作为默认输出。\n\nQ: 可以加快处理速度吗？\n\nA: 目前的实现基于实时播放，暂时无法加速。我们正在研究可能的优化方案。\n\nQ: 支持其他输出格式吗？\n\nA: 目前仅支持 WAV 格式。未来可能会考虑支持更多格式。\n\nQ: 可以在 Windows/Linux 上使用吗？\n\nA: 由于依赖 macOS 的音频框架，目前仅支持 macOS 系统。\n\n## 更新日志\n\n**v1.0 (2025.6.13)**\n\n- 初始版本\n- 支持基本的多声道音频录制功能\n- 支持 `.m4a`, `.ec3` 格式\n- 实现了批量处理和进度显示\n\n## 许可证\n\n本项目仅供学习和研究使用。使用者需自行承担使用本工具的责任。作者不对使用本工具产生的任何后果负责。\n\n## 开源信息\n\n### 开源协议\n\n本项目基于 **MIT** 协议开源。详见 `LICENSE` 文件。\n\n### GitHub Actions 自动构建\n\n本项目使用 GitHub Actions 实现自动化构建：\n\n- **触发条件**：推送到 `master` 分支或 Pull Request\n- **构建环境**：macOS 15 (最新版)\n- 构建配置：\n  - Release 模式\n  - 无代码签名（方便分发）\n  - 最低支持 macOS 12.0\n- 构建产物：\n  - `unix-executable-AtmosRecorder`：包含可执行文件和便携式启动脚本\n  - `release-package`：压缩包版本（仅 `master` 分支）\n\n查看 `.github/workflows/objective-c-xcode.yml` 了解构建细节。\n\n### 项目结构\n\n```\nAtmosRecorder/\n├── AtmosRecorder.xcodeproj   # Xcode 项目文件\n├── AtmosRecorder/            # 源代码目录\n│   ├── main.m                # 主程序入口\n│   └── TapManager.h/m        # MTAudioProcessingTap 实现\n├── .github/workflows/        # GitHub Actions 配置\n├── LICENSE                   # MIT 开源协议\n└── README.md                 # 本文档\n```\n\n## 贡献\n\n欢迎提交问题报告、功能建议和改进意见。这是一个学习项目，还有很多可以改进的地方。\n\n如需贡献代码：\n\n1. Fork 本仓库\n2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 提交 Pull Request\n\n------\n\n**免责声明**：本工具与 Dolby Laboratories 无关。Dolby Atmos 是 Dolby Laboratories 的注册商标。本工具仅是一个学习项目，可能存在各种限制和不足。本程序完全由 AI 开发，作者不对程序的正确性和稳定性做任何保证。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsakuzypeng%2Fatmosrecorder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsakuzypeng%2Fatmosrecorder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsakuzypeng%2Fatmosrecorder/lists"}