翻译说明
中文文档是持续维护中的翻译版本，可能会略滞后于英文文档；如有技术差异，以英文版为准。
开放问题与贡献方向¶
OpenJOC 目前已经可以使用。在文档规定的范围内，它能够解码支持的 E-AC-3/JOC 输入，生成扬声器或双耳输出，并导出面向互操作的 ADM 表示。
本页只列出少数仍然值得投入的方向：补充公开证据、做严谨的验证，或完成 范围明确的工程工作。它不是 bug 清单，不是 v0.14 的愿望列表，也不是对未来 功能的承诺。每个条目的状态都单独写清楚，目的是让贡献者不必重复已经有过 明确结论的研究。
一览¶
| 主题 | 类型 | 难度 |
|---|---|---|
| 重建 ADM 与原生渲染器的等价性 | 开放研究 / 已知限制 | 极高 |
| 重建 PCM 的余量与 ADM 存储 | 工程 / 标准互操作 | 高 |
| 实体多声道硬件验证 | 需要验证 | 中 |
重建 ADM 与原生渲染器的等价性¶
状态：开放研究 / 已知限制
难度： 极高
为什么值得研究¶
OpenJOC 重建的是解码后 JOC 对象场的 ADM 表示，目的是让它能够检查、交换， 并交给通用 ADM 工具链继续渲染。它不是原始 Dolby Atmos 创作母版的恢复副本。
通用 ADM 渲染器播放重建文件时，最终听感上的定位不保证与原生 JOC 渲染器 相同。如果要缩小这个差距，需要先获得当前公开约定尚未覆盖的渲染语义证据。
当前证据和边界¶
在当前测试范围内，OpenJOC 已经验证了：
- 解码后的对象 PCM；
- 在受支持的载体内部配置组合中，解码 JOC Object ↔ OAMD 的绑定；
- OAMD 到 ADM 的坐标转换；
- 动态位置的时序与插值；
- 已测试素材中的增益和状态处理；
- BW64、
chna与 TrackUID 的映射；以及 - 公共的逐对象渲染状态覆盖范围，记录为
COMPLETE_WITH_SCOPE。
这些检查可以建立解码场景和 ADM 文件结构的约定，但不能证明通用 ADM 渲染器 与原生 JOC 渲染器最终定位等价。至少有一个由维护者制作的真实节目，在相关 检查全部通过后仍出现了残余定位差异。这个结果只针对该素材，不能写成“人声 在左侧 30 度”之类的普遍结论。
什么样的贡献有价值¶
以下几类工作都可能有很高价值：
- 找到能够补上最终渲染语义缺口的公开规范证据；
- 设计范围严格、可复现的实验，用来区分两个明确的渲染器假设；
- 为已经证实缺失的语义找到有标准依据的 ADM 表示；或
- 做可复现的跨渲染器测试，实质性缩小剩余候选范围。
有价值的结果不一定要包含生产代码修复。如果一个严谨的否定性结果证明 公开规范并没有定义某个猜测中的语义，或者受控实验排除了某个假设，它同样 值得保留。
什么才算取得进展¶
进展必须是别人能够独立重复的结果，包含准确的问题描述、明确的证据边界， 以及可以被证伪的结论。结果应说明：哪个可观察行为发生了变化，支持或排除了 哪个渲染器假设，以及为什么结论不依赖某一个节目。
不要提交什么¶
以下内容不能单独作为语义修复提交：
- 凭经验添加位置偏移；
- 随意调整增益；
- 针对某一首歌写死补偿值；
- “所有声音统一移动 X 度”；
- 按素材特征做指纹识别；
- 没有公开依据的厂商公式；或
- 复制专有实现代码。
“让这个样本听起来居中”不能作为生产修改的充分证据。任何渲染语义改动， 都必须能独立于单个测试节目得到论证，并遵守清洁室方法。
建议从哪里开始¶
如果问题涉及原生渲染器，建议先在 GitHub Discussion 中写清楚可观察的问题、 使用的公开资料、相互竞争的假设，以及最小可复现实验，再投入大型实现或拉取 请求。
重建 PCM 的余量与 ADM 存储¶
状态：开放工程问题 / 标准互操作问题
难度： 高
为什么值得研究¶
JOC 重建在浮点域中进行。一些合法的重建采样值可能超出有符号 24 位 PCM 能够直接表示的归一化范围。项目需要在不擅自改变节目的前提下保留信号含义。
当前证据和边界¶
当前 ADM 导出路径遇到非有限值，或遇到超出有符号 24 位范围的采样值时，会 拒绝写入。它不会裁剪、饱和、归一化、限幅，也不会悄悄降低整个节目的电平。 这是有意为之：重建采样值超出范围，本身并不能证明解码器生成了损坏音频。
PCM24 余量页面记录了当前行为。真正尚未 解决的问题是：如何在符合标准、并且经过实际工具验证的 ADM/BW64 流程中表示 这样的合法浮点重建结果。不要因为某个文件扩展名、某个元数据字段，或者某个 工具能够打开文件，就直接认定互操作已经成立。
什么样的贡献有价值¶
有价值的工作应当证明一种存储策略能够：
- 保留重建信号的含义；
- 避免静默裁剪和静默归一化；
- 继续符合所需的 ADM/BWF 配置；并且
- 在真实 ADM 工具中验证，而不只是通过写入器自己的解析器。
可以比较标准允许的采样或容器表示，但不要在公开规范和目标工具行为尚未 支持之前，预先指定解决方案。
什么才算取得进展¶
进展需要公开的标准/配置论证、可复现的测试素材、写入和读回验证，以及目标 工具链的互操作结果。报告还应说明绝对电平、对象关系和 ADM 结构是否保持， 以及哪些情况仍然不支持。
不要提交什么¶
以下改动如果没有额外证据，都不应单独提交：
- 把所有采样值限制在
[-1, 1]； - 每次导出都做归一化；或
- 固定降低电平，只为让文件写成功。
这些做法会静默改变信号，除非有独立证明的标准/配置语义能够支持它们。与其 悄悄改动输出，当前遇到范围错误就拒绝导出的策略更安全。
建议从哪里开始¶
先写一份公开的标准与互操作报告，说明测试中的采样/容器表示、目标工具、 预期的读回结果，以及最小可复现的测试素材。在存储问题得到证据支持前，不要改变 默认的 PCM24 策略。
实体多声道硬件验证¶
状态：需要验证
难度： 中
为什么值得做¶
这是不需要研究编解码或渲染器语义的低门槛贡献方向。OpenJOC 已经有相当多 的 Windows 传输和端点路径验证，但实体多声道和高度声道扬声器的覆盖仍不完整。 软件协商成功，或虚拟端点能够工作，都不能证明实体扬声器系统使用了相同的 声道映射。
当前文档没有声称每一种 Linux 或 Windows 设备、驱动、宿主程序或输出 API 都 支持实体多声道播放。请不要把某一套成功配置扩大成整个平台的支持结论。
什么样的贡献有价值¶
验证报告最好包含以下信息：
| 项目 | 记录内容 |
|---|---|
| 系统 | 操作系统和版本 |
| OpenJOC | 发布版本、commit 或软件包构建信息 |
| 硬件 | 音频接口、功放/接收机或声卡 |
| 驱动 | 驱动名称和版本 |
| 宿主程序 | 播放器或应用程序 |
| 输出 API | WASAPI、DirectSound、ALSA 或其他 API |
| 配置 | 选择的布局和声道映射 |
| 实体连接 | 扬声器数量和摆位 |
| 测试素材 | 确定性的逐声道信号或扫频信号，以及来源类型 |
| 结果 | 预期行为和实际行为 |
| 证据 | 日志、协商出的格式，以及必要时的截图 |
验证声道时，优先使用确定性的声道映射信号或可重复的测试音，而不是只说 “听起来没问题”。即使结论是某个设备或 API 拒绝了请求，只要验证过程可复现， 这种验证也有价值。
什么才算取得进展¶
进展是一份别人能够复现并进行对照的报告。报告应明确究竟是哪一环通过了： 格式协商、PCM 传输、声道顺序、实体路由，还是全部通过。设备或 API 的失败 同样有价值，只要失败现象准确且可重复。
不要提交什么¶
不要根据一次主观听音、一个端点名称，或一条虚拟设备路径的成功结果，就声称 普遍支持某类硬件。不要省略布局、声道顺序、驱动或宿主程序。不要提交无法安全 公开的私人节目素材或只适用于某台机器的私有证据。
建议从哪里开始¶
选定一个明确布局和一种确定性的测试信号，按上面的格式记录完整配置，然后在 Discussion 中分享结果，或提交一个范围清楚的文档/验证 PR。涉及宿主或传输层的 较大改动，仍然需要完整的证据和回归测试。
需要保留的边界¶
“把 Base 全频带 PCM 直接加进最终场景”这个简单假设目前还没有被证实。当前 公开结论仍是：它对最终场景的贡献尚无定论，也没有确认存在遗漏 bug。 如果没有新的公开证据，以及能够区分重复计数、场景组装等因素的受控实验，不要 把这个假设重新包装成一个很可能正确的修复方案。
同样，ResolvedWithinCarrier 只表示在限定范围内，载体内部的解码 JOC/OAMD
绑定成立。它不表示已经恢复原始创作身份、源分轨 PCM，或专有渲染器的行为。
证据与清洁室要求¶
OpenJOC 不接受复制专有源代码，或直接照抄专有实现逻辑得到的生产实现。研究 编解码或渲染器语义前，请先阅读清洁室方法。
对于语义改动或高风险工程改动，一份有价值的贡献通常应包含：
- 可复现的测试；
- 对可观察问题的准确描述；
- 证据的适用边界；
- 能找到时提供公开规范依据；
- 必要时提供独立推导的行为证据；以及
- 针对所声称行为的回归覆盖。
受控观察可以帮助发现问题，但它本身不是复制专有实现的许可，也不能把厂商 行为直接包装成公开标准。
困难研究先开 Discussion¶
对于困难的研究问题，建议在开始大型实现或拉取请求之前先开 GitHub Discussion。 这样可以尽早发现已有的停止条件，避免重复研究，对齐证据要求，也能让后续审查 集中在真正的问题上。
错别字、直接的文档修改，或带有明确回归测试的小型确定性 bug，不需要先取得许可。 “先开 Discussion”只针对高风险语义研究，不针对日常维护。
一份有价值的 PR 应该说明什么¶
研究类或语义类 PR 至少应回答：
- 要修复的可观察问题是什么？
- 什么证据确定了预期行为？
- 这次改动关闭了哪个已有假设或限制？
- 哪个回归测试证明了改动？
- 这次改动没有声称什么？
没有解释的大型补丁，以及没有证据支撑的调参常数，都很难审查。项目不排斥 AI 辅助贡献；但无论使用什么工具，证据、来源和可复现性都必须达到同样的标准。
否定性结果同样有价值¶
一项工作不必“修好某个东西”才有意义。严谨的否定性结果可以证明：
- 公开规范没有定义所缺失的语义；
- 某个候选假设在受控测试中失败；或
- 某个设备或 API 明确拒绝一种格式。
请清楚记录测试条件、证据边界和如何证伪。这样的结果能够避免下一位贡献者 重复一条已经证明没有收获的路线。
日常贡献流程和仓库规则请参阅参与贡献。