raggedrec/PTX2DAW.project

 # pt2dawproject — Pro Tools session → DAWproject 转换器 读取 Avid Pro Tools session（`.ptx`）并将其导出为 [DAWproject](https://github.com/bitwig/dawproject)，这是由 Bitwig 开发的开放、厂商中立的 DAW 交换格式。秉承 [DawVert](https://github.com/DawVert/DawVert) 的精神，但以 DAWproject 作为 目标格式。 数据流向：**PT → DAWproject（PT 端只读）。** 生成 Pro Tools 能够打开的 `.ptx` 文件是一个更加困难且独立的问题——参见 `docs/02_architecture_and_scope.md`。 ## 状态：v1 可用 转换器可以端到端运行，并生成符合 schema 的 `.dawproject` 文件。它是 针对真实的 Pro Tools 12 / 48 kHz session（**55 条轨道，408 个片段，所有片段位置均在 session 边界内**， 根据 Bitwig 的 `Project.xsd`/`MetaData.xsd` 进行验证）开发和验证的。该 session 是一个 个人音乐项目，**并未包含在内**——请自带 `.ptx` 文件。自动化测试 而是针对一个小型合成测试夹具运行（参见 [测试](#testing)）。 目前映射的内容： - 音频轨道（名称 + 顺序） - 音频片段 → DAWproject `Clip` + `Audio`，具有采样精度（sample-accurate）的 位置 / 长度 / 源偏移 - **Ticks-timebase 轨道** —— Pro Tools 在基于 tick 的轨道上存储位置的方式 不同；libptformat 会读取错误。我们检测并纠正了这些问题（参见 `docs/01_research_findings.md` §7）。由于这依赖于 tempo，因此请传递 `--tempo` 参数。 - 将引用的源音频复制到 `.dawproject` zip 包的 `media/` 文件夹中 （当在 session 旁边找到音频时） 明确不在 v1 版本范围内（参见 `docs/02_architecture_and_scope.md`）： MIDI、automation、plugin 状态、fades/crossfades、ARA/Melodyne 数据、tempo 映射（仅支持平缓 tempo），以及文件夹/编组轨道（libptformat 未暴露 PT10–12 的编组层级）。 ## 快速开始 ``` # 1. 构建 JSON extractor（链接至 vendored zamaudio/ptformat） make build # 2. 转换 session（自带 .ptx） python3 src/ptx2dawproject.py "My Session.ptx" out.dawproject --tempo 120 # 3. 验证结果（schema + 结构检查；无需 flags） python3 src/validate_dawproject.py out.dawproject ``` 环境要求：C++ 编译器（`c++`/`clang++`/`g++`）和 Python 3 —— 仅需 标准库，无需 `pip install`。`xmllint` 为可选（用于启用 XSD 验证）。 转换器会在 `/Audio Files/` 中查找 session 的音频 （使用 `--audio-dir` 添加更多位置）。当音频不存在时，它仍然会生成一个完整且有效的 项目——片段仅引用 `media/`，而不嵌入 数据。请传递 `--tempo` 参数，以便 ticks-timebase 轨道能够正确放置 （session 名称通常会标明 BPM）；如果不提供，则默认使用 120 并弹出警告。 ## 测试 运行测试套件不需要 `.ptx` 文件——它会转换一个合成的测试夹具 （`tests/fixture_session.json`，即 `ptdump_json` 输出的格式），用于测试 基于采样的轨道、一条 ticks-timebase 轨道以及边缘情况，然后验证 输出： ``` make test ``` CI 会在每次推送时运行相同的测试（`.github/workflows/ci.yml`）。 ## 工作原理 ``` .ptx ──[ src/ptdump_json ]──> JSON ──[ src/ptx2dawproject.py ]──> .dawproject (C++, vendored (mapping + ticks-timebase zamaudio/ptformat) correction + media bundling) ``` 1. `src/ptdump_json` (C++) 链接了内置的 `libptformat`，并将解析出的 轨道/区域/音频文件以原生 session 采样的形式输出为 JSON。 它执行了两次遍历加载，因此无论目标采样率如何，输出的位置都是未缩放的。 2. `src/ptx2dawproject.py` 将该 JSON 映射到 DAWproject XML schema 上， 纠正 ticks-timebase 的位置，并写入 zip 文件。 3. `src/validate_dawproject.py` 根据内置的 XSD 检查输出， 并验证轨道 ID/IDREF 的完整性以及媒体引用。 ## 布局 ``` pt2dawproject/ ├── README.md ├── LICENSE <- MIT (original code) ├── THIRD_PARTY_NOTICES.md <- ptformat (LGPL-2.1) + dawproject XSD provenance ├── CONTRIBUTING.md <- architecture, JSON contract, where to expand ├── Makefile <- build / test / convert convenience targets ├── .github/workflows/ci.yml <- builds + runs the test suite on every push ├── docs/ │ ├── 01_research_findings.md <- confirmed .ptx format facts + ticks-timebase finding │ ├── 02_architecture_and_scope.md <- plan, scope, read vs write │ └── 03_next_steps_networked.md <- original bring-up steps (now done) ├── research/ <- archived community format notes ├── schema/ │ ├── Project.xsd <- vendored from bitwig/dawproject (for validation) │ └── MetaData.xsd ├── src/ │ ├── Makefile <- builds ptdump_json │ ├── ptdump_json.cc <- C++ JSON extractor (uses libptformat) │ ├── ptformat_vendor/ <- vendored zamaudio/ptformat (LGPL-2.1) │ ├── ptx2dawproject.py <- the converter │ ├── validate_dawproject.py <- output validator │ └── ptblocks.py <- original standalone block-walker (kept for reference) ├── tests/ │ ├── fixture_session.json <- synthetic ptdump_json output (no real .ptx needed) │ └── test_convert.py <- end-to-end test └── test_data/ <- empty; drop your own .ptx here (see its README) ``` ## 许可证 原始 pt2dawproject 代码采用 MIT 协议（参见 `LICENSE`）。内置的 `src/ptformat_vendor/` 是 [zamaudio/ptformat](https://github.com/zamaudio/ptformat) 的未修改副本， 保持为 **LGPL-2.1**（`src/ptformat_vendor/COPYING.LESSER`）。`schema/` 下的 XSD 来自 [bitwig/dawproject](https://github.com/bitwig/dawproject) (MIT)。完整 详情和再分发说明请参见 `THIRD_PARTY_NOTICES.md`。 ## 贡献 请参阅 `CONTRIBUTING.md` —— 它记录了架构、C++ 和 Python 阶段之间的 JSON 契约、ticks-timebase 的数学计算，以及 一个大致按从易到难排序的扩展方向列表（立体声合并、fades、MIDI、 tempo 映射、编组轨道）。

标签：多媒体工具, 数字音频工作站, 格式转换, 音乐制作, 音频处理