diff --git a/README.en.md b/README.en.md index c0037b0..cdeeea8 100644 --- a/README.en.md +++ b/README.en.md @@ -102,6 +102,38 @@ with an explanation instead of being ignored. This build adds `--bed` (pre-decod 6-channel float32 PCM, which skips ffmpeg decoding), `--kernels`, `--work-dir`, `--report-json`, `--dry-run` and `--quiet`. +## 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. + +`--speaker-layout` accepts only the eleven names in the table; anything else fails as an unknown +layout. + ## Library integration The engine and the file task are exposed by `joc_core.h`: `joc_task_validate` / diff --git a/README.md b/README.md index 20e8436..09aa7c8 100644 --- a/README.md +++ b/README.md @@ -90,6 +90,33 @@ metadata sidecar(`--metadata-dir`/`--metadata-cache`/`--metadata-backend sidec float32 PCM,给出后不调用 ffmpeg 解码)、`--kernels`(滤波器组表路径)、`--work-dir`、 `--report-json`、`--dry-run`、`--quiet`。 +## 扬声器布局与声道顺序 + +`--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 声道的内容和编号符合上表,不保证下游播放器自动识别杜比扬声器位置。 + +`--speaker-layout` 只接受上表 11 个名字;其它名字按未知布局报错。 + ## 库集成 引擎与文件任务使用 `joc_core.h`:`joc_task_validate` / `joc_task_execute` 跑一个文件任务并 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/src/cli/joc_cli.cpp b/src/cli/joc_cli.cpp index c42be0c..8ea71d0 100644 --- a/src/cli/joc_cli.cpp +++ b/src/cli/joc_cli.cpp @@ -84,7 +84,7 @@ struct Options { }; const char* kLayoutChoices = - "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"; + "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"; void print_usage() { std::printf( diff --git a/src/speaker/speaker_layout_lookup.cpp b/src/speaker/speaker_layout_lookup.cpp index f1dd35b..d38f037 100644 --- a/src/speaker/speaker_layout_lookup.cpp +++ b/src/speaker/speaker_layout_lookup.cpp @@ -15,8 +15,7 @@ struct FrozenLayout { constexpr FrozenLayout kLayouts[kLayoutCount] = { {"2.0", 0, 1}, {"3.1", 3, 7}, - {"4.0 Surround", 0xFF, 35}, - {"4.0 Quad", 0xFF, 9}, + {"4.0", 0xFF, 9}, {"5.1", 7, 15}, {"7.1", 11, 31}, {"5.1.2", 13, 1039}, @@ -27,14 +26,6 @@ constexpr FrozenLayout kLayouts[kLayoutCount] = { {"9.1.6", 20, 3743}, }; -// Spellings accepted in addition to the names above. -constexpr struct { - const char* alias; - const char* name; -} kAliases[] = { - {"4.0", "4.0 Surround"}, -}; - void fill(const FrozenLayout& source, LayoutInfo* out) { out->name = source.name; out->out_ch_config = source.out_ch_config; @@ -62,11 +53,6 @@ bool layout_by_name(const char* name, LayoutInfo* out) { return true; } } - for (const auto& alias : kAliases) { - if (std::strcmp(name, alias.alias) == 0) { - return layout_by_name(alias.name, out); - } - } return false; } diff --git a/src/speaker/speaker_layout_lookup.h b/src/speaker/speaker_layout_lookup.h index d3655a4..bc0b424 100644 --- a/src/speaker/speaker_layout_lookup.h +++ b/src/speaker/speaker_layout_lookup.h @@ -8,7 +8,7 @@ namespace joc::speaker { -inline constexpr int kLayoutCount = 12; +inline constexpr int kLayoutCount = 11; struct LayoutInfo { const char* name = ""; @@ -17,13 +17,13 @@ struct LayoutInfo { std::uint32_t channel_count = 0; }; -// All twelve layouts in the reference's order (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). +// All eleven layouts in the reference's order (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). bool layout_at(int index, LayoutInfo* out); -// False when the name is unknown (case-sensitive, as the reference CLI). The -// legacy spelling "4.0" resolves to 4.0 Surround, which is what that name meant -// before the two 4.0 layouts were told apart. +// False when the name is unknown (case-sensitive, as the reference CLI). "4.0" +// is the quad layout (L R Lrs Rrs); a stored value is normalized by the caller +// before the name is looked up here. bool layout_by_name(const char* name, LayoutInfo* out); bool layout_by_bitfield(std::uint32_t bitfield, LayoutInfo* out); diff --git a/src/speaker/speaker_layouts.h b/src/speaker/speaker_layouts.h index 7cdd6be..e17586c 100644 --- a/src/speaker/speaker_layouts.h +++ b/src/speaker/speaker_layouts.h @@ -39,7 +39,7 @@ struct LayoutGeometry { std::array regions{}; }; -inline constexpr std::array kLayouts{{ +inline constexpr std::array kLayouts{{ LayoutGeometry{ 0x1u, 0, 2, {{0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}}, @@ -136,54 +136,6 @@ inline constexpr std::array kLayouts{{ } }} }, - LayoutGeometry{ - 0x23u, 0xFFu, 4, - {{0, 1, 2, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}}, - {{ - RegionGeometry{ - 4, 2, 2, 0, - {{SpeakerPoint{{0, 0, 0}, 0}, SpeakerPoint{{32767, 0, 0}, 1}, SpeakerPoint{{16384, 0, 0}, 2}, SpeakerPoint{{16384, 32767, 0}, 3}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}}}, - {{AxisGroup{3, {0, 2, 1}}, AxisGroup{1, {3, 0, 0}}, AxisGroup{}, AxisGroup{}}}, - {{AxisGroup{}, AxisGroup{}, AxisGroup{}, AxisGroup{}}} - }, - RegionGeometry{ - 3, 1, 1, 0, - {{SpeakerPoint{{0, 0, 0}, 0}, SpeakerPoint{{32767, 0, 0}, 1}, SpeakerPoint{{16384, 0, 0}, 2}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}}}, - {{AxisGroup{3, {0, 2, 1}}, AxisGroup{}, AxisGroup{}, AxisGroup{}}}, - {{AxisGroup{}, AxisGroup{}, AxisGroup{}, AxisGroup{}}} - }, - RegionGeometry{ - 4, 2, 2, 0, - {{SpeakerPoint{{0, 0, 0}, 0}, SpeakerPoint{{32767, 0, 0}, 1}, SpeakerPoint{{16384, 0, 0}, 2}, SpeakerPoint{{16384, 32767, 0}, 3}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}}}, - {{AxisGroup{3, {0, 2, 1}}, AxisGroup{1, {3, 0, 0}}, AxisGroup{}, AxisGroup{}}}, - {{AxisGroup{}, AxisGroup{}, AxisGroup{}, AxisGroup{}}} - }, - RegionGeometry{ - 2, 2, 2, 0, - {{SpeakerPoint{{16384, 0, 0}, 2}, SpeakerPoint{{16384, 32767, 0}, 3}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}}}, - {{AxisGroup{1, {0, 0, 0}}, AxisGroup{1, {1, 0, 0}}, AxisGroup{}, AxisGroup{}}}, - {{AxisGroup{}, AxisGroup{}, AxisGroup{}, AxisGroup{}}} - }, - RegionGeometry{ - 3, 1, 1, 0, - {{SpeakerPoint{{0, 0, 0}, 0}, SpeakerPoint{{32767, 0, 0}, 1}, SpeakerPoint{{16384, 0, 0}, 2}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}}}, - {{AxisGroup{3, {0, 2, 1}}, AxisGroup{}, AxisGroup{}, AxisGroup{}}}, - {{AxisGroup{}, AxisGroup{}, AxisGroup{}, AxisGroup{}}} - }, - RegionGeometry{ - 1, 1, 1, 0, - {{SpeakerPoint{{16384, 32767, 0}, 3}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}}}, - {{AxisGroup{1, {0, 0, 0}}, AxisGroup{}, AxisGroup{}, AxisGroup{}}}, - {{AxisGroup{}, AxisGroup{}, AxisGroup{}, AxisGroup{}}} - }, - RegionGeometry{ - 3, 1, 1, 0, - {{SpeakerPoint{{0, 0, 0}, 0}, SpeakerPoint{{32767, 0, 0}, 1}, SpeakerPoint{{16384, 0, 0}, 2}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}, SpeakerPoint{}}}, - {{AxisGroup{3, {0, 2, 1}}, AxisGroup{}, AxisGroup{}, AxisGroup{}}}, - {{AxisGroup{}, AxisGroup{}, AxisGroup{}, AxisGroup{}}} - } - }} - }, LayoutGeometry{ 0x9u, 0xFFu, 4, {{0, 1, 2, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}},