Files
foo_input_joc/README.md
T
TheM14 dc3372be27
build / windows (push) Has been cancelled
build / release (push) Has been cancelled
Support the two 4.0 layouts and localize the preferences page
2026-10-27 23:51:57 +08:00

168 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# foo_input_joc — foobar2000 的 E-AC-3 JOC 输入组件
[English](README.en.md) · [安装](#安装) · [设置](#设置) · [构建](#构建) · [已知限制](#已知限制)
foobar2000 输入组件,播放 **E-AC-3 JOC(Dolby Atmos)** 文件:从 E-AC-3 同步帧里取出 JOC
对象与 OAMD 元数据,与 ffmpeg 解出的核心 PCM(按 $joc\_dmx\_config\_idx$ 为 5.1 或 7 通道)配对后实时渲染,输出双耳(HRTF)或
2.0 到 9.1.6 的扬声器布局。渲染内核直接编译进组件,除 `foo_input_joc.dll` 之外不需要安装任何东西。
输入是裸流 `.eac3` / `.ec3`,或容器里的 E-AC-3 JOC 轨道(`.mp4` `.m4a` `.m4b` `.m4p`
`.m4r` `.mov` `.mkv` `.mka` `.webm`)。文件里没有 JOC 就不接管:普通 AC-3 / E-AC-3、音频轨道
是 AAC 的容器、传输流都交还 foobar2000,由它原本的解码器播放。
## 环境要求
* foobar2000 1.6(32 位)或 2.x(32 位与 64 位)。
* 一个 `ffmpeg` 可执行文件,默认从 `PATH` 找,设置页可以指定路径。
* 双耳输出需要一份 HRTF 数据文件。**本仓库不附带**,见 [HRTF 数据](#hrtf-数据)。
## 安装
从 [Releases](../../releases) 下载对应架构的包(`v*` 标签触发的 CI 会把两个架构都附上去),
或按[构建](#构建)自行打出 `dist\` 下的产物;文件名都是
`foo_input_joc-<版本>-<架构>.fb2k-component`。把它拖到 foobar2000 上,或用
Preferences → Components → Install 安装,然后重启。1.6 和 2.x 32 位用 `-x86`,2.x 64 位用
`-x64`。
手工安装就把 `foo_input_joc.dll` 放进当前版本会读取的 `user-components` 子目录:
| foobar2000 | 目录 |
|---|---|
| 1.6 | `<profile>\user-components\foo_input_joc\` |
| 2.x | `<app>\user-components\foo_input_joc\`(portable 模式同样如此) |
子目录是必须的——DLL 直接躺在 `user-components\` 下不会被扫描;放进当前版本不读的目录,或
架构不对,都会**静默忽略**,不会有任何提示。
`tools/deploy.ps1 -TestBed <portable foobar2000>` 是上面手工步骤的脚本版;
`tools/run.ps1 -TestBed <路径> -Play <文件>` 可以无人值守播放并把日志打出来。让 foobar2000
通过 `/exit` 正常退出:被强杀的实例会在 `<profile>\running` 留下标记,下次启动会拒绝加载任何
用户组件。
### 容器需要调一次解码器顺序
foobar2000 按 Preferences → **Decoding** 里的顺序询问解码器,内置的容器读取器也在那张表里。
如果它排在前面接到 MP4 / Matroska 文件,文件就被它拿走,JOC 对象随之丢失——于是听起来只是
普通 E-AC-3。
所以要把 **JOC decoder (E-AC-3 JOC)** 提到 **foobar2000 MP4 Demuxer** 与 **foobar2000
Matroska/WebM Reader** 之前。裸流 `.eac3` / `.ec3` 不受这个顺序影响。
## 设置
Preferences → Tools → **JOC 解码器**:
* **输出** —— **双耳(HRTF)**,或 **扬声器布局**:2.0 到 9.1.6,布局名与声道顺序见[下表](#扬声器布局与声道顺序);
* **双耳模式**(near / mid / far)与房间**尾音**秒数;
* **HRTF** —— **SOFA 文件**或 **Rosella 个性化模型**。路径留空表示
用默认位置 `<组件目录>\HRTF\` 下的 `binaural.sofa` 或 `binaural.personalized_headphone`;
* **增益** —— 开关加 dB 值。双耳渲染在核心混音不削顶的素材上也可能超过满刻度,衰减放在这里;
* **强制 24bit 输出(int24)** —— 默认关闭,交付 float32。打开后,交付前按内核写 WAV 的 int24
规则量化(截到 ±1 → ×8388607 → 截断),超范围的样本被截断到边缘、次数记进日志;组件同时把该
文件的技术信息报成 24bit 定点。渲染本身仍是 float32,这一项说的是交付给 foobar2000 的采样精度,
不是输出设备的位深(那个在 Preferences → Output 里设置)。**切换这个开关后要刷新文件信息**
(Properties → Reload info,或把文件从媒体库移除后重新加入):foobar2000 按文件缓存技术信息,
缓存没刷新时 Properties 与转换器仍按旧的 32bit 浮点判断,会提示"编码器不支持浮点输入"。
* **ffmpeg.exe** 可执行文件路径。
* **界面语言** —— **跟随系统** / **简体中文** / **English**。设置页的全部文字、状态行和用户可见的
错误信息都用这一项选定的语言,切换后立刻生效;选择存在组件自己的配置里。"跟随系统"按 Windows 的
界面语言决定:中文(含繁体)用简体中文,其它语言用英文。这一项只影响界面文字,解码与渲染不读它。
页面上的控件都不禁用,状态行会说明当前生效的是什么。中文页面的控件名与上表一致,英文页面是同一些
控件的译文(例如 **Output**、**Speaker layout**、**Binaural mode**、**HRTF file**、**Apply gain**)。
### 扬声器布局与声道顺序
| 布局 | 声道 | 通道掩码 | 交付顺序(声明的声道位置) |
|---|---|---|---|
| 2.0 | 2 | `0x3` | FL FR |
| 3.1 | 4 | `0xF` | FL FR FC LFE |
| 4.0 Surround | 4 | `0x107` | FL FR FC BC |
| 4.0 Quad | 4 | `0x33` | FL FR BL BR |
| 5.1 | 6 | `0x3F` | FL FR FC LFE BL BR |
| 7.1 | 8 | `0x63F` | FL FR FC LFE BL BR SL SR |
| 5.1.2 | 8 | `0x560F` | FL FR FC LFE SL SR TFL TFR |
| 5.1.4 | 10 | `0x2D60F` | FL FR FC LFE SL SR TFL TFR TBL TBR |
| 7.1.2 | 10 | `0x563F` | FL FR FC LFE BL BR SL SR TFL TFR |
| 7.1.4 | 12 | `0x2D63F` | FL FR FC LFE BL BR SL SR TFL TFR TBL TBR |
| 9.1.4 | 14 | `0x2D6FF` | FL FR FC LFE BL BR FCL FCR SL SR TFL TFR TBL TBR |
| 9.1.6 | 16 | `0x3F6FF` | FL FR FC LFE BL BR FCL FCR SL SR TFL TFC TFR TBL TBC TBR |
**4.0 有两个布局,它们是不同的扬声器集合,不是同一个布局的两种叫法。** **4.0 Surround** 是前置
三声道加一只后中(`FL FR FC BC`,渲染内核里的名字是 `L R C Cs`);**4.0 Quad** 是前后各一对
(`FL FR BL BR`,内核里是 `L R Lrs Rrs`),既没有中置也没有 LFE——对象在正前方时由左右两只音箱
合成幻像中置,输入里的 LFE 在这种布局下没有输出声道,按内核规则不混入其它声道。旧版本只有 `4.0`
一个名字,含义一直是 Surround,因此读到 `4.0` 时按 `4.0 Surround` 处理(设置页显示为
`4.0 Surround`,应用一次设置后存的就是显式名字);要 Quad 必须写 `4.0 Quad`。
渲染内核按参考实现的顺序产生声道(9.1.4 是 L R C LFE Lrs Rrs Ls Rs Ltf Rtf Ltr Rtr Lw Rw),
而 foobar2000 规定"帧内声道顺序 = 通道掩码中声道位的升序"。两者对 2.0 到 7.1.4(含两种 4.0)恰好
一致;9.1.4 与 9.1.6 的宽声道排在后面,所以交付前按掩码顺序重排(日志里写 `channels permuted into
mask order`)。上表就是这个顺序;Properties 里能看到对应的 `WAVEFORMATEXTENSIBLE_CHANNEL_MASK`,
转换器写文件时也按同一个顺序落盘。
掩码取 ffmpeg 对同名布局的定义(`5.1` 是 BL/BR,`5.1.2` 起是 SL/SR,宽声道是 FCL/FCR,`4.0` 是
FL FR FC BC),这样同一个布局名在组件、转换产物与其它工具里含义一致。**9.1.6 的顶层中间声道对
(Ltm/Rtm)在 WAVE 的 18 个声道位里没有对应位置**(ffmpeg 用 32 位掩码之外的 TSL/TSR),因此按
TFL/TFC/TFR/TBL/TBC/TBR 中剩下的两个居中位置 TFC 与 TBC 交付:掩码仍然是一位声道一个位,顺序如
上表,代价是这两路在 foobar2000 的声道列表里显示为顶前排中、顶后排中。
**Windows 自己只有 2.0 / 5.1 / 7.1 三种扬声器配置,其余布局(3.1、两种 4.0、所有带高度或宽声道的
布局)的共享与独占输出都需要 ASIO(或接受该布局的独占输出)。** 高度声道、宽声道、后中与超过 8
声道的布局 ASIO 没有限制,声道按组件交付的顺序对应到设备的输出通道(用 fb2k 的 ASIO 声道映射按名称
分配)。用这样的布局而输出仍走系统配置时,核心会把多出来的声道下混——能听到声音,但听不到那几路;
转换器(Converter)不受输出设备限制,可以按布局写出 4/14/16 声道的文件。设置页的状态行在选中这类
布局时会写"需要 ASIO 输出"。
### HRTF 数据
SOFA 测量集或个性化耳机模型由使用组件的人自己提供,并且写在 `.gitignore` 里,避免误提交。
扬声器布局不需要 HRTF。双耳渲染缺少 HRTF 时会报错并指出它找的是哪个文件。
## 构建
```powershell
pwsh -File tools/setup_sdk.ps1 # 官方 SDK 拉进 SDK/,固定到 target 1.5/1.6
pwsh -File tools/build.ps1 # Win32 -> build\Win32\foo_input_joc.dll
pwsh -File tools/build.ps1 -Platform x64
pwsh -File tools/package.ps1 # 两个架构,打包到 dist\*.fb2k-component
```
配置固定为 `Release-Static`(静态 CRT,`/MT`);`/fp:precise` 是逐字节验收的前提,不要改。
`foo_input_joc.vcxproj` 通过项目引用先构建 `kernel\joc_kernel.vcxproj`;`kernel/` 里的渲染内核
源码以 `JOC_STATIC` / `EJOC_STATIC` 编译,入口既不导入也不导出。`tests\` 是离线工具(码流
自检与交叉核对、渲染比对、布局表与频道顺序检查、设置页布局检查、中英文文字宽度检查、容器探测
检查),`tools\` 是构建与测试床脚本。设置项另有 `JOC_*` 环境变量覆盖(仅用于开发运行),清单与含义在 `src\settings.cpp`。
排查问题看 DLL 旁边的 `joc_decoder.log`;组件启动时会把自己的版本、核心版本、日志路径写在
里面。日志按**字节**封顶:单个文件写满 16 MiB 就滚到同目录的 `joc_decoder.log.1`(覆盖上一次
滚动,不累积),所以两份加起来不超过 32 MiB,最新的内容始终在 `joc_decoder.log`。滚动之后版本
信息会重写一遍。媒体库扫描会给库里每个容器写日志,体量主要来自这里。
## 已知限制
* 不实现 ADM BWF 输出。
* 扬声器布局到 9.1.6(16 声道)为止;内核输出上限就是 16 声道,没有 22.2。2.0/5.1/7.1 之外的
布局需要 ASIO(或接受该布局的独占输出),见[扬声器布局与声道顺序](#扬声器布局与声道顺序)。
* 9.1.6 的顶层中间声道对在 WAVE 的声道位里没有对应位置,按 TFC/TBC 交付(同上)。
* $joc\_dmx\_config\_idx$ 全部五个档位都支持:取床按音频帧配对,床通道数由档位决定(0/3
为 6 通道,1/2/4 为 8 通道),ffmpeg 只在 6 通道档位传 `-ac 6`。AC-3 核心 + 依赖子流
(`strmtyp=1`)与"首个音频帧没有 JOC"都按正常情况处理。
* 容器只有在它排在内置容器读取器之前时才会被接管(见[安装](#容器需要调一次解码器顺序));核心
不允许某个解码器去要一个已经被别的条目拿走的文件。这类文件的标签也仍旧归那个读取器。
* 裸流 `.eac3` / `.ec3` 的标签(流前面的 ID3v2,或后面的 APEv2/ID3v1)**能读不能写**:没有
组件声明可以写裸 E-AC-3,为插入标签重写整个文件也不是本组件该做的事。
* 传输流(`.ts`、`.m2ts`)不接管。
* **强制 24bit 输出**只改变解码器交付的采样精度:交付的 int24 会被 foobar2000 转成它内部的
浮点,输出设备用什么位深仍由 Preferences → Output 决定,组件不能替它选。超出 ±1 的样本按内核
的 `continue` 策略截断(双耳渲染可能超过满刻度,需要衰减时用 **Gain**)。
* 播放长度严格等于文件时长。双耳渲染器仍会算出房间尾音,但它不作为文件本身没有的播放时间交付。
* 跳转会从包含目标位置的那个帧重新进入码流,而不是把前面的内容全部解码一遍——这是跳转代价与
目标位置无关的原因。位置精确、不漂移;样本是同一段波形交给了从该处开始的解码器,与从头播放
相比差一个很低的噪声底(−59 dBFS 或更低)。
## 许可
`LICENSE` 是上游 MIT 许可,原样复制;`kernel/` 是上游渲染内核源码的副本,保留其声明。见
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。