开发说明
本程序由 AI 完成编写和优化工作，开发者仅提供需求和反馈。这是一个探索 AI 辅助编程能力的实验项目。
开发工具
- AI(网页端):
- 主要编写：Claude 4 Opus (Anthropic)
- 辅助优化：Gemini 2.5 Pro Preview (Google)
- 气氛组：ChatGPT o4-mini-high (OpenAI)
- IDE：Xcode 16.4
- 系统：macOS 15.5
Q: 处理时可以使用其他音频应用吗？
A: 通常可以。经测试，播放音乐、视频等不会影响录制。但建议不要在处理过程中切换音频设备或更改设备设置。
Q: 录制的音频会受到系统空间音频设置的影响吗？
A: 不会。本程序直接获取解码后的原始多声道数据，不受头部追踪、个性化空间音频（HRTF）等系统设置的影响。您获得的是纯净的 12 声道解码结果。
一个简单的 macOS 命令行工具，用于录制由系统解码后的多声道音频（如杜比全景声），并将其保存为 12 声道 WAV 文件。
声明：本程序完全由 AI 开发，开发者未参与代码编写。
🎵 基础音频处理：使用 Apple 的 MTAudioProcessingTap API 进行音频提取
🔊 固定输出格式：输出为 12 声道 7.1.4 格式（48kHz, 32-bit Float）
📦 批量处理：支持处理多个文件
📊 进度显示：显示基本的处理进度
🚀 使用方便：支持拖拽文件处理
- macOS 10.15 或更高版本（推荐 macOS 11.0+）
- 支持的输入格式：
.m4a、.ec3
注：在 macOS 15.0+ 上开发和测试，较旧版本可能存在兼容性问题。
-
访问 Releases 页面。
-
下载最新的
AtmosRecorder-unix.tar.gz。 -
解压并运行：
tar -xzf AtmosRecorder-unix.tar.gz chmod +x AtmosRecorder ./AtmosRecorder
- 访问 Actions 页面。
- 选择最新的成功构建。
- 下载
unix-executable-AtmosRecorderartifact。 - 解压后即可使用。
-
克隆仓库：
git clone https://github.com/Sakuzy/AtmosRecorder.git cd AtmosRecorder -
使用 Xcode 打开项目：
open AtmosRecorder.xcodeproj -
选择目标设备为 "My Mac"。
-
点击 Product → Build（或按
⌘B）编译。
自动查找模式
./AtmosRecorder
程序会在当前目录中查找第一个支持的音频文件并处理。
指定文件
./AtmosRecorder /path/to/audio.m4a
处理指定的音频文件。
批量处理
./AtmosRecorder file1.m4a file2.eac3 file3.ec3
一次处理多个文件。
处理整个文件夹
./AtmosRecorder /path/to/folder/
自动查找并处理文件夹中的所有支持格式的音频文件。
拖拽：将文件或文件夹拖到程序图标上，自动处理。
双击：双击程序图标，自动处理同目录下的音频文件。
-
输出格式：WAV 文件
-
声道配置
：12 声道 7.1.4
L,R,C,LFE(前置左右、中置、低音)Ls,Rs(环绕左右)Ltf,Rtf(前置顶部左右)Ltr,Rtr(后置顶部左右)- 备用声道 x2
-
采样率：48,000 Hz
-
位深度：32-bit Float
-
文件命名：
原文件名_atmos_714.wav -
避免覆盖：如果输出文件已存在，会自动添加编号（如
_atmos_714_1.wav）
程序采用简单的声道映射方式：
- 如果解码后的结果少于 12 声道，额外的声道将为静音。
- 如果解码后的结果超过 12 声道，只使用前 12 个声道。
- 尽量保持原始音频的基本特性。
- 处理速度为实时播放速度（1x），这是当前实现的限制。
- 处理过程中音频会静音播放，不会产生声音。
- 输出文件较大，约每分钟 140MB。
- 处理前请确保有足够的磁盘空间。
以下是一次真实的处理记录，可供参考：
- 输入文件：一个
3分58秒的全景声音频 (.ec3, 1024kb/s,30.5 MB) - 峰值内存：约
50 MB(在 Xcode 调试环境下观测) - 输出文件：一个 12 声道的
.wav文件，大小为549.5 MB
版权注意：请确保您有权处理相关音频文件。本工具仅供个人学习和合法用途使用。
文件大小
：输出的 WAV 文件会比原始压缩格式大很多。例如：
- 5 分钟的音频 ≈ 700MB
- 1 小时的音频 ≈ 8.4GB
处理时间：由于采用实时处理，一个 5 分钟的音频文件需要约 5 分钟处理时间。
内存使用：处理大文件时可能占用较多内存，建议关闭其他大型应用。
本程序录制的是纯净的解码结果，不受以下因素影响：
- 头部追踪（Head Tracking）
- 个性化空间音频（Personalized HRTF）
- 系统音效处理
经测试，其他程序的音频播放通常不会影响录制。
重要：处理过程中请避免：
- 切换音频输出设备
- 更改音频设备设置（如 AirPods 的空间音频开关）
- 插拔音频设备
这些操作可能会导致录制中断或产生异常。
在处理文件时，您可以随时检查您的音频文件是否被 macOS 正确识别为杜比全景声格式。这是一个非常有用的验证方法：
- 运行
AtmosRecorder并开始处理一个音频文件。- 连接您的空间音频耳机（如 AirPods Pro 2）。
- 打开 macOS 的控制中心，并点击声音模块。
- 如果您看到如下图所示，在音量条旁边明确显示 “杜比全景声” 字样，这证明系统已成功激活全景声解码器。
这表明您的输入文件是有效的全景声音频，并且本工具正在正确地截取解码后的数据。
注：本工具默认以静音模式在后台处理音频。即使不连接任何耳机，录制过程也完全可以正常工作。不过，“杜比全景声”这个视觉提示是 macOS 空间音频功能的一部分，通常只在使用受支持的耳机时才会显示。因此，如果您使用内置扬声器，将看不到此提示，经测试这不影响最终录制的 12 声道 WAV 文件。
-
问题：程序提示"未找到音频轨道"
- 确保输入文件包含音频数据。
- 检查文件是否损坏。
-
问题：输出文件声道数不正确
- 这通常表示输入文件不是真正的全景声格式。
- 尝试使用其他全景声音频文件。
-
问题：处理速度很慢
- 这是正常的，程序使用实时播放速度以确保质量。
- 确保磁盘有足够的写入速度（建议使用 SSD）。
-
问题：控制台出现系统警告信息
如果看到类似以下的警告信息，这是正常的，不会影响转换结果：
AddInstanceForFactory: No factory registered for id... PlatformUtilities::CopyHardwareModelFullName() returns unknown value... MEMixerChannel:: failed to set kAudioUnitProperty_ChannelLayout... HALC_ProxyIOContext::IOWorkLoop: skipping cycle due to overload这些是 macOS 音频系统的内部警告，可以安全忽略。最后一条关于 "overload" 的警告可能在系统负载较高时出现，但不影响音频质量。
为了尽可能地提升程序的稳定性和可靠性，AtmosRecorder 内部已经实现了一项尝试：程序在启动时，会通过执行
[NSThread setThreadPriority:1.0];这行代码，主动向 macOS 系统申请更高的线程处理优先级。这样做的目的是，当您的电脑比较繁忙时，操作系统会更倾向于将宝贵的 CPU 资源分配给 AtmosRecorder，从而尽力避免因处理超时而产生
overload警告。尽管有这项优化，但
overload警告的出现与整个系统的瞬时负载都有关系，因此可能无法 100% 杜绝。
本工具使用了以下技术：
- MTAudioProcessingTap：Apple 的音频处理 API
- AVFoundation：用于媒体文件的读取
- 非交错音频格式：用于多声道音频处理
工具仍在持续改进中，可能存在一些限制和不足。
Q: 为什么固定为 12 声道输出？
A: 这是基于 Apple 系统解码全景声的常见格式。我们采用了这个配置作为默认输出。
Q: 可以加快处理速度吗？
A: 目前的实现基于实时播放，暂时无法加速。我们正在研究可能的优化方案。
Q: 支持其他输出格式吗？
A: 目前仅支持 WAV 格式。未来可能会考虑支持更多格式。
Q: 可以在 Windows/Linux 上使用吗？
A: 由于依赖 macOS 的音频框架，目前仅支持 macOS 系统。
v1.0 (2025.6.13)
- 初始版本
- 支持基本的多声道音频录制功能
- 支持
.m4a,.ec3格式 - 实现了批量处理和进度显示
本项目仅供学习和研究使用。使用者需自行承担使用本工具的责任。作者不对使用本工具产生的任何后果负责。
本项目基于 MIT 协议开源。详见 LICENSE 文件。
本项目使用 GitHub Actions 实现自动化构建：
- 触发条件：推送到
master分支或 Pull Request - 构建环境：macOS 15 (最新版)
- 构建配置：
- Release 模式
- 无代码签名（方便分发）
- 最低支持 macOS 12.0
- 构建产物：
unix-executable-AtmosRecorder：包含可执行文件和便携式启动脚本release-package：压缩包版本（仅master分支）
查看 .github/workflows/objective-c-xcode.yml 了解构建细节。
AtmosRecorder/
├── AtmosRecorder.xcodeproj # Xcode 项目文件
├── AtmosRecorder/ # 源代码目录
│ ├── main.m # 主程序入口
│ └── TapManager.h/m # MTAudioProcessingTap 实现
├── .github/workflows/ # GitHub Actions 配置
├── LICENSE # MIT 开源协议
└── README.md # 本文档
欢迎提交问题报告、功能建议和改进意见。这是一个学习项目，还有很多可以改进的地方。
如需贡献代码：
- Fork 本仓库
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 提交 Pull Request
免责声明：本工具与 Dolby Laboratories 无关。Dolby Atmos 是 Dolby Laboratories 的注册商标。本工具仅是一个学习项目，可能存在各种限制和不足。本程序完全由 AI 开发，作者不对程序的正确性和稳定性做任何保证。