diff --git a/README.en.md b/README.en.md index 870cd33..039f23a 100644 --- a/README.en.md +++ b/README.en.md @@ -15,9 +15,9 @@ This is research code, not a complete, standards-compliant, or production-grade - Parse ID11 OAMD position updates and build object trajectories. - Reconstruct LFE plus 15 object channels through analysis QMF, parameter interpolation, the object matrix, and inverse QMF. - Write a 25-channel ADM BWF: a 10-channel 7.1.2 bed (silent except for LFE) plus 15 objects. -- Render directly to `2.0`, `3.1`, `4.0 Surround`, `4.0 Quad`, `5.1`, `7.1`, `5.1.2`, `5.1.4`, - `7.1.2`, `7.1.4`, `9.1.4`, or `9.1.6` (the two 4.0 layouts are different speaker sets: Surround is a - front trio plus a back centre, Quad is a front and a back pair). +- Render directly to `2.0`, `3.1`, `4.0`, `5.1`, `7.1`, `5.1.2`, `5.1.4`, `7.1.2`, `7.1.4`, `9.1.4` + or `9.1.6` (`4.0` is the quad layout, a front and a back pair; see + [Speaker layouts and channel order](#speaker-layouts-and-channel-order)). - Run public SOFA binaural rendering directly from `pcm16 + ID11/OAMD`, without a temporary ADM BWF. - Keep the binaural DSP in float64/complex128, including 961-sample latency compensation, cross-frame state, and the room tail. - Use a shared float32/PCM24 WAV writer and explicit PCM24 clipping policy for direct outputs. @@ -230,6 +230,38 @@ python main.py --help Without `-o`, output still goes to `output/` at the repository root. The directory move intentionally preserves this behavior. +## Speaker layouts and channel order + +`--speaker-layout` accepts the eleven layouts below, and the PCM/WAV channel order is the order in +the table: + +| Layout | Channel order | +|---|---| +| 2.0 | L, R | +| 3.1 | L, R, C, LFE | +| 4.0 | L, R, Lrs, Rrs | +| 5.1 | L, R, C, LFE, Ls, Rs | +| 7.1 | L, R, C, LFE, Ls, Rs, Lrs, Rrs | +| 5.1.2 | L, R, C, LFE, Ls, Rs, Ltm, Rtm | +| 5.1.4 | L, R, C, LFE, Ls, Rs, Ltf, Rtf, Ltr, Rtr | +| 7.1.2 | L, R, C, LFE, Ls, Rs, Lrs, Rrs, Ltm, Rtm | +| 7.1.4 | L, R, C, LFE, Ls, Rs, Lrs, Rrs, Ltf, Rtf, Ltr, Rtr | +| 9.1.4 | L, R, C, LFE, Ls, Rs, Lrs, Rrs, Lw, Rw, Ltf, Rtf, Ltr, Rtr | +| 9.1.6 | L, R, C, LFE, Ls, Rs, Lrs, Rrs, Lw, Rw, Ltf, Rtf, Ltm, Rtm, Ltr, Rtr | + +`4.0` is the quad layout this project adds (the traditional `FL FR BL BR`, here `L R Lrs Rrs`); it is +not part of the Dolby layout set. Every other layout and channel order follows the Dolby +specifications. + +Multichannel WAV files use `WAVE_FORMAT_EXTENSIBLE` with `dwChannelMask = 0`: the file declares no +Windows speaker positions, and the PCM channel order is exactly the table above, never rearranged +into mask-bit order. Players, ASIO, DAWs and other devices have to map the channel numbers +themselves; this project guarantees the content and numbering of each PCM channel, not that a +downstream player recognises Dolby speaker positions on its own. + +The command line accepts only the eleven names in the table; anything else is rejected as an unknown +layout. + ## Repository layout ```text diff --git a/README.md b/README.md index 0848301..9ea41f5 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,8 @@ - 解析 ID11 OAMD 位置更新并生成对象轨迹; - 通过 analysis QMF、参数插值、对象矩阵和 inverse QMF 重建 LFE + 15 路对象 PCM; - 输出 25 声道 ADM BWF:10 声道 7.1.2 bed(除 LFE 外静音)+ 15 个对象; -- 直接渲染 `2.0`、`3.1`、`4.0 Surround`、`4.0 Quad`、`5.1`、`7.1`、`5.1.2`、`5.1.4`、`7.1.2`、 - `7.1.4`、`9.1.4`、`9.1.6`(两种 4.0 是不同的扬声器集合:Surround 是前置三声道加后中,Quad 是前后各一对); +- 直接渲染 `2.0`、`3.1`、`4.0`、`5.1`、`7.1`、`5.1.2`、`5.1.4`、`7.1.2`、`7.1.4`、`9.1.4`、 + `9.1.6`(`4.0` 是 Quad 布局,前后各一对;声道排列见[扬声器布局与声道顺序](#扬声器布局与声道顺序)); - 从 `pcm16 + ID11/OAMD` 直接运行公开 SOFA 双耳渲染,不生成临时 ADM BWF; - 双耳 DSP 全程使用 float64/complex128,并保留 961-sample latency compensation、跨帧状态和 room 尾声; - 直接输出统一支持 float32 或 PCM24 WAV,并在 PCM24 削波前提供明确处理策略; @@ -200,6 +200,33 @@ python main.py --help 未指定 `-o` 时,输出仍写入仓库根目录的 `output/`。这是文件移动后特意保持的原有行为。 +## 扬声器布局与声道顺序 + +`--speaker-layout` 只接受下表 11 个布局,PCM/WAV 的声道顺序就是表里的顺序: + +| 布局 | 声道顺序 | +|---|---| +| 2.0 | L, R | +| 3.1 | L, R, C, LFE | +| 4.0 | L, R, Lrs, Rrs | +| 5.1 | L, R, C, LFE, Ls, Rs | +| 7.1 | L, R, C, LFE, Ls, Rs, Lrs, Rrs | +| 5.1.2 | L, R, C, LFE, Ls, Rs, Ltm, Rtm | +| 5.1.4 | L, R, C, LFE, Ls, Rs, Ltf, Rtf, Ltr, Rtr | +| 7.1.2 | L, R, C, LFE, Ls, Rs, Lrs, Rrs, Ltm, Rtm | +| 7.1.4 | L, R, C, LFE, Ls, Rs, Lrs, Rrs, Ltf, Rtf, Ltr, Rtr | +| 9.1.4 | L, R, C, LFE, Ls, Rs, Lrs, Rrs, Lw, Rw, Ltf, Rtf, Ltr, Rtr | +| 9.1.6 | L, R, C, LFE, Ls, Rs, Lrs, Rrs, Lw, Rw, Ltf, Rtf, Ltm, Rtm, Ltr, Rtr | + +`4.0` 是本项目补充的 Quad 布局(传统 Quad 的 `FL FR BL BR`),声道为 `L R Lrs Rrs`,不在杜比 +文档的布局列表里;除它以外的布局及声道顺序均依据杜比相关规范定义。 + +多声道 WAV 使用 `WAVE_FORMAT_EXTENSIBLE`,`dwChannelMask = 0`:文件不声明 Windows 扬声器位置, +PCM 声道顺序严格按上表,不按掩码位序重排。播放器、ASIO、DAW 或其他设备需要按声道编号自行完成 +输出映射;本项目保证各 PCM 声道的内容和编号符合上表,不保证下游播放器自动识别杜比扬声器位置。 + +命令行只接受上表 11 个名字;其它名字按未知布局拒绝。 + ## 目录结构 ```text diff --git a/docs/math.en.md b/docs/math.en.md index 60ded1d..fb7d1f0 100644 --- a/docs/math.en.md +++ b/docs/math.en.md @@ -446,8 +446,7 @@ $$ $$ For layouts with one horizontal surround pair rather than separate side and rear pairs (the 5.1 -family, and layouts such as 4.0 Quad and 4.0 Surround that carry one rear pair only), the -longitudinal coordinate is +family, and 4.0, which carries one rear pair only), the longitudinal coordinate is $$ v_{\mathrm{floor}}= diff --git a/docs/math.md b/docs/math.md index fbf3763..84ccf77 100644 --- a/docs/math.md +++ b/docs/math.md @@ -442,8 +442,8 @@ $$ \mathbf h(u)\odot\mathbf v(v). $$ -对于只有一对水平环绕、没有独立 side/rear 两对的布局(5.1 系列,以及 4.0 Quad 与 -4.0 Surround 这类只有一对后置声道的布局),纵向坐标使用 +对于只有一对水平环绕、没有独立 side/rear 两对的布局(5.1 系列,以及 4.0 这类 +只有一对后置声道的布局),纵向坐标使用 $$ v_{\mathrm{floor}}= diff --git a/main.py b/main.py index b0bbc71..8764249 100644 --- a/main.py +++ b/main.py @@ -518,12 +518,7 @@ def render(index, bed_path, frame_count, raw_path, gain, progress_every, def _layout_choice(value: str) -> str: - """Canonical layout name for a --speaker-layout value. - - Legacy spellings resolve here rather than being listed as choices, so "4.0" - still means the layout that name has always meant while the help text shows - the two 4.0 layouts by their own names. - """ + """Canonical layout name for a --speaker-layout value.""" return speaker_layout_display_name(get_speaker_layout(value)) @@ -540,7 +535,7 @@ def build_parser(): direct_mode = parser.add_mutually_exclusive_group() direct_mode.add_argument("--speaker-layout", type=_layout_choice, choices=SPEAKER_LAYOUT_CHOICES, - help="直接扬声器渲染布局,例如 2.0、4.0 Quad、5.1、7.1.2") + help="直接扬声器渲染布局,例如 2.0、4.0、5.1、7.1.2") direct_mode.add_argument("--binaural", action="store_true", help="直接 SOFA 双耳渲染;不生成临时 ADM BWF") parser.add_argument("--speaker-format", choices=("float32", "int24"), default="float32", diff --git a/src/speaker_layouts.py b/src/speaker_layouts.py index 63e26fd..29e9095 100644 --- a/src/speaker_layouts.py +++ b/src/speaker_layouts.py @@ -109,84 +109,45 @@ _RAW_LAYOUTS = {'20': {'out_ch_config': 0, 'axis0_groups': ((0, 2, 1),), 'axis1_groups': (), 'mode': 1})}, - '40surround': {'out_ch_config': 255, - 'speaker_bitfield': 35, - 'channels': ('L', 'R', 'C', 'Cs'), - 'internal_to_standard': (0, 1, 2, 3), - 'regions': ({'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (16384, 0, 0), (16384, 32767, 0)), - 'speaker_ids': (0, 1, 2, 3), - 'axis0_groups': ((0, 2, 1), (3,)), - 'axis1_groups': (), - 'mode': 2}, - {'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (16384, 0, 0)), - 'speaker_ids': (0, 1, 2), - 'axis0_groups': ((0, 2, 1),), - 'axis1_groups': (), - 'mode': 1}, - {'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (16384, 0, 0), (16384, 32767, 0)), - 'speaker_ids': (0, 1, 2, 3), - 'axis0_groups': ((0, 2, 1), (3,)), - 'axis1_groups': (), - 'mode': 2}, - {'coordinates_q15': ((16384, 0, 0), (16384, 32767, 0)), - 'speaker_ids': (2, 3), - 'axis0_groups': ((0,), (1,)), - 'axis1_groups': (), - 'mode': 2}, - {'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (16384, 0, 0)), - 'speaker_ids': (0, 1, 2), - 'axis0_groups': ((0, 2, 1),), - 'axis1_groups': (), - 'mode': 1}, - {'coordinates_q15': ((16384, 32767, 0),), - 'speaker_ids': (3,), - 'axis0_groups': ((0,),), - 'axis1_groups': (), - 'mode': 1}, - {'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (16384, 0, 0)), - 'speaker_ids': (0, 1, 2), - 'axis0_groups': ((0, 2, 1),), - 'axis1_groups': (), - 'mode': 1})}, - '40quad': {'out_ch_config': 255, - 'speaker_bitfield': 9, - 'channels': ('L', 'R', 'Lrs', 'Rrs'), - 'internal_to_standard': (0, 1, 2, 3), - 'regions': ({'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (0, 32767, 0), (32767, 32767, 0)), - 'speaker_ids': (0, 1, 2, 3), - 'axis0_groups': ((0, 1), (2, 3)), - 'axis1_groups': (), - 'mode': 2}, - {'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (0, 32767, 0), (32767, 32767, 0)), - 'speaker_ids': (0, 1, 2, 3), - 'axis0_groups': ((0, 1), (2, 3)), - 'axis1_groups': (), - 'mode': 2}, - {'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (0, 32767, 0), (32767, 32767, 0)), - 'speaker_ids': (0, 1, 2, 3), - 'axis0_groups': ((0, 1), (2, 3)), - 'axis1_groups': (), - 'mode': 2}, - {'coordinates_q15': ((0, 32767, 0), (32767, 32767, 0)), - 'speaker_ids': (2, 3), - 'axis0_groups': ((0, 1),), - 'axis1_groups': (), - 'mode': 1}, - {'coordinates_q15': ((0, 0, 0), (32767, 0, 0)), - 'speaker_ids': (0, 1), - 'axis0_groups': ((0, 1),), - 'axis1_groups': (), - 'mode': 1}, - {'coordinates_q15': ((0, 32767, 0), (32767, 32767, 0)), - 'speaker_ids': (2, 3), - 'axis0_groups': ((0, 1),), - 'axis1_groups': (), - 'mode': 1}, - {'coordinates_q15': ((0, 0, 0), (32767, 0, 0)), - 'speaker_ids': (0, 1), - 'axis0_groups': ((0, 1),), - 'axis1_groups': (), - 'mode': 1})}, + '40': {'out_ch_config': 255, + 'speaker_bitfield': 9, + 'channels': ('L', 'R', 'Lrs', 'Rrs'), + 'internal_to_standard': (0, 1, 2, 3), + 'regions': ({'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (0, 32767, 0), (32767, 32767, 0)), + 'speaker_ids': (0, 1, 2, 3), + 'axis0_groups': ((0, 1), (2, 3)), + 'axis1_groups': (), + 'mode': 2}, + {'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (0, 32767, 0), (32767, 32767, 0)), + 'speaker_ids': (0, 1, 2, 3), + 'axis0_groups': ((0, 1), (2, 3)), + 'axis1_groups': (), + 'mode': 2}, + {'coordinates_q15': ((0, 0, 0), (32767, 0, 0), (0, 32767, 0), (32767, 32767, 0)), + 'speaker_ids': (0, 1, 2, 3), + 'axis0_groups': ((0, 1), (2, 3)), + 'axis1_groups': (), + 'mode': 2}, + {'coordinates_q15': ((0, 32767, 0), (32767, 32767, 0)), + 'speaker_ids': (2, 3), + 'axis0_groups': ((0, 1),), + 'axis1_groups': (), + 'mode': 1}, + {'coordinates_q15': ((0, 0, 0), (32767, 0, 0)), + 'speaker_ids': (0, 1), + 'axis0_groups': ((0, 1),), + 'axis1_groups': (), + 'mode': 1}, + {'coordinates_q15': ((0, 32767, 0), (32767, 32767, 0)), + 'speaker_ids': (2, 3), + 'axis0_groups': ((0, 1),), + 'axis1_groups': (), + 'mode': 1}, + {'coordinates_q15': ((0, 0, 0), (32767, 0, 0)), + 'speaker_ids': (0, 1), + 'axis0_groups': ((0, 1),), + 'axis1_groups': (), + 'mode': 1})}, '51': {'out_ch_config': 7, 'speaker_bitfield': 15, 'channels': ('L', 'R', 'C', 'LFE', 'Ls', 'Rs'), @@ -816,8 +777,7 @@ SPEAKER_LAYOUTS = {name: _make_layout(name, item) for name, item in _RAW_LAYOUTS SPEAKER_LAYOUT_ALIASES = { "2.0": "20", "3.1": "31", - "4.0 Surround": "40surround", - "4.0 Quad": "40quad", + "4.0": "40", "5.1": "51", "7.1": "71", "5.1.2": "512", @@ -827,18 +787,12 @@ SPEAKER_LAYOUT_ALIASES = { "9.1.4": "914", "9.1.6": "916", } -# Spellings accepted for compatibility only: "4.0" has always meant the layout -# with a front trio and one back-centre speaker, which is now called 4.0 Surround. -SPEAKER_LAYOUT_LEGACY_ALIASES = { - "4.0": "40surround", -} SPEAKER_LAYOUT_CHOICES = tuple(SPEAKER_LAYOUT_ALIASES) SPEAKER_LAYOUT_DISPLAY_NAMES = {value: key for key, value in SPEAKER_LAYOUT_ALIASES.items()} def get_speaker_layout(name: str) -> SpeakerLayout: key = SPEAKER_LAYOUT_ALIASES.get(name, name) - key = SPEAKER_LAYOUT_LEGACY_ALIASES.get(key, key) try: return SPEAKER_LAYOUTS[key] except KeyError as exc: