Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/sakuzypeng/atmosrecorder

一款由 AI 开发的 macOS 命令行工具，可录制系统解码的杜比全景声（Dolby Atmos）并保存为 12 声道 WAV 文件。
https://github.com/sakuzypeng/atmosrecorder

ai-programming audio-recorder avfoundation cli command-line-tool dolby-atmos macos objective-c spatial-audio

Last synced: about 1 month ago
JSON representation

一款由 AI 开发的 macOS 命令行工具，可录制系统解码的杜比全景声（Dolby Atmos）并保存为 12 声道 WAV 文件。

Awesome Lists containing this project

README 

          
> **开发说明**

>

> 本程序由 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+ 上开发和测试，较旧版本可能存在兼容性问题。



## 安装方法



### 方法一：下载预编译版本（推荐）



1. 访问 **Releases** 页面。



2. 下载最新的 `AtmosRecorder-unix.tar.gz`。



3. 解压并运行：



   ```

   tar -xzf AtmosRecorder-unix.tar.gz

   chmod +x AtmosRecorder

   ./AtmosRecorder

   ```



### 方法二：通过 GitHub Actions 下载



1. 访问 **Actions** 页面。

2. 选择最新的成功构建。

3. 下载 `unix-executable-AtmosRecorder` artifact。

4. 解压后即可使用。



### 方法三：从源码编译



1. 克隆仓库：



   ```

   git clone https://github.com/Sakuzy/AtmosRecorder.git

   cd AtmosRecorder

   ```

   

2. 使用 Xcode 打开项目：



   ```

   open AtmosRecorder.xcodeproj

   ```

   

3. 选择目标设备为 "My Mac"。



4. 点击 **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 正确识别为杜比全景声格式。这是一个非常有用的验证方法：

>

> 1. 运行 `AtmosRecorder` 并开始处理一个音频文件。

> 2. 连接您的空间音频耳机（如 AirPods Pro 2）。

> 3. 打开 macOS 的**控制中心**，并点击**声音**模块。

> 4. 如果您看到如下图所示，在音量条旁边明确显示 **“杜比全景声”** 字样，这证明系统已成功激活全景声解码器。

>

> 这表明您的输入文件是有效的全景声音频，并且本工具正在正确地截取解码后的数据。

>

> **注**：本工具默认以**静音模式**在后台处理音频。即使**不连接任何耳机**，录制过程也完全可以正常工作。不过，“杜比全景声”这个视觉提示是 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 自动构建



本项目使用 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                 # 本文档

```



## 贡献



欢迎提交问题报告、功能建议和改进意见。这是一个学习项目，还有很多可以改进的地方。



如需贡献代码：



1. Fork 本仓库

2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)

3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)

4. 推送到分支 (`git push origin feature/AmazingFeature`)

5. 提交 Pull Request



------



**免责声明**：本工具与 Dolby Laboratories 无关。Dolby Atmos 是 Dolby Laboratories 的注册商标。本工具仅是一个学习项目，可能存在各种限制和不足。本程序完全由 AI 开发，作者不对程序的正确性和稳定性做任何保证。