chyinan/OpenJOC

OpenJOC is an independent, clean-room E-AC-3 JOC decoder and spatial renderer written in Rust. It performs E-AC-3 JOC object decoding directly from supported Dolby Atmos streams, extracting in-band EMDF, decoding OAMD object metadata and JOC reconstruction data, and reconstructing carrier-local object signals for speaker, binaural, and ADM workflows.

Decoded JOC Objects are carrier-local reconstruction outputs, not recovery of the original authored Atmos objects or source stems.

Download the latest release. OpenJOC is not affiliated with, endorsed by, or sponsored by Dolby Laboratories.

Read the OpenJOC documentation site · 阅读简体中文文档

• E-AC-3 JOC object decoding from supported in-band EMDF, including the supported OAMD metadata prefix/timeline, JOC reconstruction data, and carrier-local reconstructed object signals;
• supported speaker presets from 2.0 through 22.2 and custom geometry up to 64 output channels;
• two-channel virtual-speaker binaural rendering with SADIE II D1/KU100 (default) and D2/KEMAR built-in profiles, or a supported local SOFA file;
• experimental, device-independent 3DoF head-tracking interface for dynamic binaural rendering, accepting external head orientation through the Rust/C APIs (opt-in);
• reconstructed ADM BWF interoperability export for decoded JOC Objects with supported OAMD movement, within an exact documented profile;
• Rust and versioned C ABI embedding surfaces;
• project-provided FFmpeg, GStreamer, mpv, and Windows DirectShow/LAV integrations.

Read the capability matrix for the evidence boundary behind each claim.

Build or download OpenJOC, then render a JOC programme:

openjoc render-joc input.m4a --layout 7.1.4 --output output.wav
openjoc render-joc input.m4a --binaural --output headphones.wav
openjoc export-adm input.m4a --output reconstructed.wav
openjoc validate-adm reconstructed.wav

Use openjoc inspect input.ec3 to inspect a carrier before rendering. The quick-start guide covers the first render and points to the detailed output contracts.

For custom geometry, use --layout-file LAYOUT.json; the documented limit is 64 output channels.

Inspect ordinary E-AC-3 or JOC without rendering audio:

openjoc inspect input.ec3
openjoc inspect input.mp4 --json
openjoc inspect input.ec3 --aus --objects --emdf

The inspector reports in-band topology, block partitions, JOC profiles, EMDF payload census, strict and deployed compatibility results, and observed object metadata changes. Versioned JSON can be attached to bug reports or consumed by tools. See the Stream Inspector guide for the schema, Rust API, and inspection limits.

In the published 20-probe JOCForge census using OpenJOC commit a52c35d21e68e18dbaa8fa18accfbfea44087367, OpenJOC fully parsed all probes classified SUPPORTED_PASS in JOCForge's modeled public capability space and passed the inspection/render-or-container-decode gate: 19 raw probes rendered and 1 CMAF probe passed container decode. The canonical detailed report is maintained in the JOCForge repository at docs/interop-census.md; this README does not duplicate the corpus table.

The optional Windows package provides an isolated OpenJOC-enabled LAV Audio Decoder. It installs beside stock LAV and does not change PotPlayer automatically:

1. Extract the package from the OpenJOC releases page.
2. Run install.bat, then require verify.bat to report PASS.
3. In PotPlayer, add LAV Audio Decoder (OpenJOC) in Filter Control → Filter Priority (Overall) and set it to Prefer.

The default package keeps this one-click audio-only installation and removal flow. An explicitly selected full package additionally contains LAV Video, LAV Splitter, and QuickSync; it has separate manual registration controls and is not a drop-in replacement for the default installer. See optional full LAV packaging.

The Windows LAV / PotPlayer guide documents the eight fixed PCM policies, including Binaural (Headphones), passthrough behavior, rollback, and hardware boundary.

The JOC speaker/binaural bridge remains experimental and profile-bounded; its codec-domain operator T(t) is unresolved. Reconstructed ADM is an interoperability-oriented representation of the decoded JOC object scene. It is not recovery of the original authored Atmos master. OpenJOC does not recover original authoring identity, source-stem PCM, unquantized automation, Dolby authoring provenance, or a lossless JOC-to-ADM round trip.

The decoded Objects vs authored Objects page explains the identity boundary. The renderer-equivalence limitation explains why a generic ADM renderer is not guaranteed to localize exactly like native JOC playback.

• Rust API — serial OpenJocSession lifecycle and owned interleaved f32 output.
• C ABI — opaque handles, bounded stream decoding, custom geometry, and panic containment.
• Integration overview — current FFmpeg, GStreamer, mpv, player-bundle, and Windows contracts.

Use the Rust toolchain declared in Cargo.toml:

cargo build -p openjoc-cli --release --locked
./target/release/openjoc --version

Contributors should follow CONTRIBUTING.md and run the workspace quality gates before committing.

OpenJOC is usable today, but several research and validation problems remain open. Contributions are especially welcome around native-renderer equivalence, reconstructed-PCM headroom, and physical multichannel hardware validation.

See Open Problems & Contribution Opportunities before starting work on codec or renderer semantics. For difficult research, starting a Discussion first is recommended so work does not repeat an already investigated path.

OpenJOC core code is licensed under Apache-2.0. Integration bundles may include components under additional terms; see THIRD_PARTY_NOTICES.md and package-specific notices. Dolby, Dolby Atmos, SADIE, FFmpeg, GStreamer, mpv, LAV Filters, PotPlayer, Windows, and related names are marks of their respective owners.