The kernel copy follows the new kernel. The renderer has a frame-level state machine (normal, hold, hard cut and passthrough, the 8-plane passthrough, the LFE clipgain ramp and interpolation when no previous state exists), the OAMD parser carries the complete frame state (several blocks, more than 16 objects) and the speaker renderer applies the metadata (gain and inactive flags, zone/elevation, size, snap, divergence, ISF and bed distribution). oamd_math and oamd_params are new modules, the ISF tables are compiled in now that the upstream data/ directory is gone, and the binaural timeline accepts a complete frame state. joc_core.h moves to ABI 6 (frame parameters and EMDF payload info at v2, JOC_FRAME_STATUS_*, raw 5-bit offset_ts) and eac3joc_core.h to EJOC ABI 4 (EJOC_FRAME_STATUS_*, ejoc_frame_input v1, ejoc_renderer_render_frame, EJOC_CORE_OUT_CHANNELS and EJOC_LFE_SLOT; the old ejoc_renderer_process stays). joc_stream.h and joc_version.h are unchanged. joc_kernel.vcxproj lists the two new translation units and the four new headers. The component's layout table gains the kernel's 6.0 layout (L R Ls Rs Lrs Rrs) after 9.1.6, and layout_table_test expects twelve layouts, so the list the preferences page shows and the list the renderer accepts are the same again. README, THIRD_PARTY_NOTICES and the CI comment pin the copy to commit 3f0d5e87fe41b90d9350528d2dca2ca82a637a3f; tag v1.2.0 points at the older a276028 and is not the sync baseline. Builds Release-Static|x64 and |Win32 with no errors. The offline test tools build and pass on both architectures: layout_table_test reports 12 layouts, and channel_swap_test, log_rotation_test and long_path_test pass. scan_crosscheck agrees with the core on the upstream test material, and the render harness delivers 7.1.4 speaker output and binaural output on both architectures, with the speaker-path WAV byte-identical between them. The core is still vendored under kernel/; building it from the upstream checkout at build time is a separate change.
214 lines
13 KiB
Markdown
214 lines
13 KiB
Markdown
# foo_input_joc — foobar2000 input component for E-AC-3 JOC
|
||
|
||
[简体中文](README.md) · [Install](#install) · [Settings](#settings) · [Building](#building) · [Known limitations](#known-limitations)
|
||
|
||
A foobar2000 input component for **E-AC-3 JOC (Dolby Atmos)** files: the JOC object and OAMD
|
||
metadata is taken from the E-AC-3 syncframes and paired with the core PCM that ffmpeg decodes
|
||
(5.1 or 7 channels, following $joc\_dmx\_config\_idx$), then rendered in real time to headphones
|
||
(HRTF) or to a speaker layout from 2.0 up to 9.1.6. The
|
||
rendering core is compiled into the component, so there is nothing to install beside
|
||
`foo_input_joc.dll`.
|
||
|
||
Input is a bare `.eac3` / `.ec3` stream, or an E-AC-3 JOC track inside a container (`.mp4`
|
||
`.m4a` `.m4b` `.m4p` `.m4r` `.mov` `.mkv` `.mka` `.webm`). A file without JOC is not claimed:
|
||
plain AC-3 / E-AC-3, a container whose audio track is AAC, and transport streams are all handed
|
||
back to foobar2000 and play through the decoder it would have used anyway.
|
||
|
||
## Requirements
|
||
|
||
* foobar2000 1.6 (32-bit) or 2.x (32-bit and 64-bit).
|
||
* An `ffmpeg` executable, found on `PATH` by default; the preferences page can name one.
|
||
* For binaural output, an HRTF data file. **This repository does not ship one** — see
|
||
[HRTF data](#hrtf-data).
|
||
|
||
## Install
|
||
|
||
Download the package for your architecture from [Releases](../../releases) — a pushed `v*` tag
|
||
makes CI attach both — or build it yourself as described under [Building](#building) and take the
|
||
result from `dist\`; either way the file is `foo_input_joc-<version>-<arch>.fb2k-component`. Drop
|
||
it onto foobar2000, or use Preferences → Components → Install, and restart. Take `-x86` for
|
||
foobar2000 1.6 and 2.x 32-bit, `-x64` for 2.x 64-bit.
|
||
|
||
To install by hand, copy `foo_input_joc.dll` into the per-component subdirectory of the
|
||
`user-components` folder the running version reads:
|
||
|
||
| foobar2000 | Folder |
|
||
|---|---|
|
||
| 1.6 | `<profile>\user-components\foo_input_joc\` |
|
||
| 2.x | `<app>\user-components\foo_input_joc\` (also in portable mode) |
|
||
|
||
The subdirectory is required — a DLL lying directly in `user-components\` is not scanned — and a
|
||
component placed in the folder the running version does not read, or built for the other
|
||
architecture, is **ignored without a message**.
|
||
|
||
`tools/deploy.ps1 -TestBed <portable foobar2000>` is the scripted form of the manual steps, and
|
||
`tools/run.ps1 -TestBed <path> -Play <file>` plays a file unattended and prints the log. Let
|
||
foobar2000 exit through `/exit`: a force-killed instance leaves a `<profile>\running` marker
|
||
behind, and the next start then refuses to load any user component.
|
||
|
||
### Containers need one look at the decoder list
|
||
|
||
foobar2000 asks the decoders in the order shown in Preferences → **Decoding**, and the built-in
|
||
container readers are in that list. When one of them is offered an MP4 or Matroska file first, it
|
||
takes the file and the JOC objects are lost — such a file then plays as plain E-AC-3.
|
||
|
||
So move **JOC decoder (E-AC-3 JOC)** above **foobar2000 MP4 Demuxer** and **foobar2000
|
||
Matroska/WebM Reader** in that list. Bare `.eac3` / `.ec3` files do not depend on the order.
|
||
|
||
## Settings
|
||
|
||
Preferences → Tools → **JOC decoder**:
|
||
|
||
* **Output** — **Binaural (HRTF)**, or a **Speaker layout** from 2.0 to 9.1.6 (names and channel order
|
||
in the [table below](#speaker-layouts-and-channel-order));
|
||
* **Binaural mode** (near / mid / far) and the room **tail** in seconds;
|
||
* **HRTF** — a **Rosella personalized model**. An empty path means the default
|
||
location, `<component directory>\HRTF\binaural.personalized_headphone`;
|
||
* **Gain** — a switch and a value in dB. Binaural rendering can exceed full scale on material
|
||
that does not clip in the core mix, so attenuation belongs here;
|
||
* **Force 24-bit output (int24)** — off by default, which delivers float32. When on, every sample
|
||
is quantised with the core's own int24 rule (clip to ±1, ×8388607, truncate) before it is handed
|
||
over, the samples that had to be clipped are counted in the log, and the component reports the
|
||
file as 24-bit fixed point. The renderer itself stays float32: this is the precision the decoder
|
||
delivers, not the output device's bit depth, which is set in Preferences → Output. **Reload a
|
||
file's information after flipping this switch** (Properties → *Reload info*, or remove the file
|
||
from the Media Library and add it again): foobar2000 caches technical information per file, and
|
||
until it is reloaded Properties and the Converter still go by the old 32-bit floating-point
|
||
answer, warning that the encoder does not take floating-point input.
|
||
* **Swap side and rear channels** — off by default. When on, `Ls` and `Lrs`, and
|
||
`Rs` and `Rrs`, are exchanged just before the PCM is handed over (5↔7 and 6↔8
|
||
counting from one in 7.1). It only applies to layouts that carry both a side and
|
||
a rear pair — 7.1, 7.1.2, 7.1.4, 9.1.4 and 9.1.6 — so the top channels in the
|
||
last two slots of 5.1.2 and 5.1.4 are never touched. Only the delivered channel
|
||
order changes; decoding, object positions and the layout table are untouched,
|
||
and both the float32 and the int24 delivery carry the swap.
|
||
* the **ffmpeg.exe** executable to use.
|
||
* **Language** — **Follow system** / **简体中文** / **English**. Every string on the page, the status
|
||
lines and the errors a user can see use the selected language, and switching takes effect
|
||
immediately; the choice is stored in the component's own configuration. "Follow system" goes by
|
||
the Windows user-interface language: Chinese (including Traditional) reads the simplified Chinese
|
||
column, everything else reads English. The setting only affects interface text; decoding and
|
||
rendering never read it.
|
||
|
||
No control on the page is disabled, and the status line states what is in effect. The control names
|
||
above are the English ones; the Chinese page names the same controls 输出, 扬声器布局, 双耳模式,
|
||
HRTF 文件, 增益.
|
||
|
||
### HRTF data
|
||
|
||
A SOFA measurement set or a personalised headphone model is supplied by whoever runs the
|
||
component, and is listed in `.gitignore` so it cannot be committed by accident. Speaker layouts
|
||
need none. Binaural rendering without an HRTF fails with a message naming the file it looked for.
|
||
|
||
## Speaker layouts and channel order
|
||
|
||
The PCM this component hands to foobar2000, and the multichannel WAV files the Converter writes,
|
||
follow the renderer's channel order:
|
||
|
||
| 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`): a
|
||
front and a back pair with neither a centre nor an LFE — an object straight ahead is a phantom image
|
||
of the front pair, and the LFE in the input has no output channel in this layout, so by the core's
|
||
rule it is not mixed into the others. Every other layout and channel order follows the Dolby
|
||
specifications.
|
||
|
||
**Channel order and the foobar2000 limitation.** The component hands the renderer's PCM over
|
||
unchanged, in the order of the table above; when that stream is written to WAV (the playback chunk or
|
||
a Converter output), the order of the 1–16 channels follows the Dolby documentation exactly. The
|
||
channel *definitions*, however, are not guaranteed to correspond fully: foobar2000's WAVE writer can
|
||
only declare a Windows speaker mask, which has no slot for top-middle (`Ts`) or wide (`Ww`) and cannot
|
||
express an order such as 7.1's `Ls Rs Lrs Rrs`. This is a foobar2000 limitation, not a problem with
|
||
the rendered order. Properties declares the channel count and no speaker positions; the chunk used
|
||
while playing carries foobar2000's default map for that channel count (an unspecified map is rejected
|
||
as an invalid audio stream specification and playback fails).
|
||
|
||
For a multichannel WAV with `dwChannelMask = 0`, download the CLI from
|
||
[github.com/TheM14/JustOneCacophony](https://github.com/TheM14/JustOneCacophony) and export with it: it
|
||
writes `WAVE_FORMAT_EXTENSIBLE` with `dwChannelMask = 0` and the order above.
|
||
|
||
Mapping the channels to a player, ASIO, a DAW or a device is up to the user; the component guarantees
|
||
the content and numbering of each PCM channel as listed above.
|
||
|
||
Layout names in the configuration follow the table above; a name that cannot be resolved is logged
|
||
and falls back to `7.1`.
|
||
|
||
## Building
|
||
|
||
```powershell
|
||
pwsh -File tools/setup_sdk.ps1 # official SDK into SDK/, pinned to 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 # both, packaged into dist\*.fb2k-component
|
||
```
|
||
|
||
The configuration is fixed at `Release-Static` (static CRT, `/MT`), and `/fp:precise` is what the
|
||
byte-for-byte acceptance rests on, so it must not be changed. `foo_input_joc.vcxproj` builds
|
||
`kernel\joc_kernel.vcxproj` first through a project reference; the rendering core sources in
|
||
`kernel/` are compiled with `JOC_STATIC` / `EJOC_STATIC`, so their entry points are neither
|
||
imported nor exported. `tests\` holds the offline tools (bitstream self-test and cross-check,
|
||
render comparison, speaker-layout table and channel-order check, preferences-page layout check,
|
||
Chinese and English text-width check, container-probe check) and `tools\` the build and test-bed
|
||
scripts. Settings also read `JOC_*`
|
||
environment overrides for one run (development only); the list and what each one does is in
|
||
`src\settings.cpp`.
|
||
|
||
To diagnose a problem, read `joc_decoder.log` beside the DLL: the component writes its own
|
||
version, the core version and the log path there at start-up. The log is capped by **bytes**: a
|
||
file that reaches 16 MiB is rolled to `joc_decoder.log.1` beside it, replacing the previous roll
|
||
rather than accumulating, so the two together never exceed 32 MiB and the newest lines are always
|
||
in `joc_decoder.log`. The version banner is written again after a roll. A Media Library scan logs
|
||
every container in the library, which is where the volume comes from.
|
||
|
||
## Known limitations
|
||
|
||
* ADM BWF output is not implemented.
|
||
* Speaker layouts go up to 9.1.6 (16 channels), the renderer's own output limit; see
|
||
[Speaker layouts and channel order](#speaker-layouts-and-channel-order).
|
||
* A multichannel layout declares no speaker positions in Properties, and the per-chunk map used for
|
||
playback is only foobar2000's default for the channel count; output mapping is up to the user's
|
||
channel assignment (same section).
|
||
* All five $joc\_dmx\_config\_idx$ configurations are supported: the bed is paired per audio
|
||
frame, and its channel count follows the configuration (6 channels for 0/3, 8 for 1/2/4), with
|
||
`-ac 6` passed to ffmpeg only for the 6-channel ones. An AC-3 core plus a dependent substream
|
||
(`strmtyp=1`) and a first audio frame without JOC are both normal cases.
|
||
* A container is only claimed when this component is ahead of the built-in container reader in
|
||
Preferences → Decoding (see [Install](#containers-need-one-look-at-the-decoder-list)); the core
|
||
does not let a decoder ask for a file another entry has already taken. Such a file's tags stay
|
||
that reader's as well.
|
||
* Tags of a bare `.eac3` / `.ec3` (an ID3v2 tag in front of the stream, or an APEv2/ID3v1 tag
|
||
behind it) can be **read but not written**: no component claims raw E-AC-3 for writing, and
|
||
rewriting the whole file to insert a tag is not this component's job.
|
||
* Transport streams (`.ts`, `.m2ts`) are not claimed.
|
||
* **Force 24-bit output** only changes the precision the decoder delivers: foobar2000 converts the
|
||
int24 it receives into its own floating-point samples, and which bit depth the output device runs
|
||
at is still decided in Preferences → Output, not by this component. Samples outside ±1 follow the
|
||
core's `continue` clip policy (binaural rendering can exceed full scale, so use **Gain** when
|
||
attenuation is wanted).
|
||
* Playback length is exactly the file's duration. The binaural renderer still computes its room
|
||
tail, but it is not delivered as playback time the file does not have.
|
||
* A seek re-enters the bitstream at the frame holding the target instead of decoding everything
|
||
in front of it — which is why the cost of a seek does not depend on where it lands. The
|
||
position is exact and does not drift; the samples are the same waveform handed to a decoder
|
||
that started there, so they differ from a straight play-through by a low-level noise floor of
|
||
−59 dBFS or quieter.
|
||
|
||
## Licence
|
||
|
||
`LICENSE` is the upstream MIT licence, copied unchanged; `kernel/` is a copy of the upstream
|
||
rendering core sources, synced to JustOneCacophonyCXX commit
|
||
`3f0d5e87fe41b90d9350528d2dca2ca82a637a3f` (the `v1.2.0` tag points at an older commit and is not
|
||
the sync baseline), and keeps their notices. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|