OpenJOC

OpenJOC is an independent, clean-room, research-grade E-AC-3 JOC metadata and reconstruction-basis decoder. It implements behavior from public ETSI specifications and controlled, permitted evidence; it does not copy Dolby private implementations.

OpenJOC is not affiliated with, endorsed by, or sponsored by Dolby Laboratories. Dolby, Dolby Atmos, and related marks are trademarks of their respective owners.

The immutable v0.2.0 release contract is deliberately narrow:

• scene.json is metadata-only;
• diagnostics/reconstruction_rows/row_NNN.wav contains diagnostic ReconstructionBasis rows, not verified authored-object PCM;
• SemanticBindingState remains Unresolved;
• ETSI_STRICT was the historical no-profile default and is never silently downgraded;
• OBSERVED_VENDOR_COMPAT is explicit, partial, and preserves opaque observed continuation without assigning vendor semantics.

OpenJOC 0.7.0 is the current release line: Library Integration & Output Fidelity. It makes the decode/render engine embeddable through a headless Rust session API and an experimental versioned C ABI, while completing important stereo, speaker-headroom, and calibrated dialnorm behavior. Ordinary rendering assembles bridge control from decoded JOC/OAMD state; --topology remains an optional complete override/test input.

The selectable 5.1, 5.1.2, 5.1.4, 7.1, 7.1.2, 7.1.4, 7.1.6, 9.1, 9.1.2, 9.1.4, 9.1.6, and native 22.2 workflows are documented in JOC speaker rendering. The same workflow can virtualize all public virtual binaural layouts through the built-in SADIE II generic HRIR or a user-supplied strict SOFA HRIR bank when directions are exact or safely interpolatable. The default virtual layout is 7.1.4. The underlying public SpatialLayout plus JocSpatialBridge API remains a generic N-channel library interface for caller-defined layouts; the CLI names are convenience presets, not the renderer's fundamental maximum.

OpenJOC 0.3.0 was the local release candidate. It added an explicit spatial-rendering foundation for caller-supplied mono sources: validated 2D and 3D speaker layouts, sample-accurate trajectories, direct-FIR and uniform partitioned binaural rendering, and a strict supported SOFA import path. These renderer workflows are independent of unresolved JOC authored-object binding.

User-facing decode and decode-payload commands default to observable AUTO profile selection. AUTO tries ETSI_STRICT first and can select only the existing whitelisted OBSERVED_VENDOR_COMPAT policy when every blocking deviation is admitted. Explicit ETSI_STRICT never falls back.

The opt-in JocSpatialBridge provides the codec-coordinate spatial projection function. Its current maturity is experimental, its semantic binding remains unresolved, and its official runtime validation oracle is not independently confirmed. These states are documented separately from the stable function name.

Read the canonical documentation:

• Capabilities — current 0.7.0 capability status.
• JOC speaker rendering — the 0.7.0 real-input workflow.
• Known limitations — what remains out of scope.
• Architecture — production data flow and boundaries.
• Spatial portability — 22.2 geometry, built-in HRTF, and platform-independence policy.
• Third-party data notices — SADIE II license, attribution, and citation.
• Library API — headless Rust packet/session contract.
• C API — versioned C/C++ ABI and ownership rules.
• GStreamer integration — experimental automatic selection for admitted E-AC-3 JOC while ordinary E-AC-3 stays on the normal decoder path; applications can select binaural or native multichannel speaker rendering while OpenJOC retains the spatial DSP.
• FFmpeg-facing external bridge — experimental libavformat/AVFrame integration for applications embedding FFmpeg. It does not modify stock FFmpeg binaries or register an out-of-tree decoder plugin.
• Future player adapters — next integration assessment.
• Roadmap — future priorities only.

Build from source

OpenJOC requires Rust 1.85 or newer. The application dependency graph is recorded in Cargo.lock.

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

An offline build is supported when all locked registry dependencies are already present in the selected Cargo cache:

cargo build -p openjoc-cli --release --locked --offline

This is not a claim that a brand-new machine can build without first obtaining the Rust toolchain and dependencies. The repository declares a minimum Rust version but does not pin one exact compiler release.

Embed the decode/render engine

OpenJOC 0.7.0 provides OpenJocSession and OpenJocConfig for headless Rust integration. A push supplies one complete E-AC-3 JOC access unit; receive returns owned interleaved f32 PCM with sample-domain timestamps and semantic channel labels. Sessions support push/receive, drain, flush, reset/discontinuity, and report the public output delay (609 samples for speaker output, 577 for binaural). The API does not parse CLI arguments, open files, or use global decoder state.

The experimental C ABI is distributed with the platform archives as include/openjoc.h plus static/shared libraries. It uses opaque handles, numeric statuses, struct_size forward compatibility, instance-owned errors, and panic containment. The C surface is ABI 1.1-experimental; compatibility may evolve during OpenJOC 0.x; framework adapters are documented separately.

OpenJOC also provides an experimental FFmpeg-facing libavformat/AVFrame bridge for applications embedding FFmpeg. It uses FFmpeg for demux and packet transport, while the same OpenJocSession owns JOC decode and spatial rendering. Build it explicitly with -p openjoc-ffmpeg --features ffmpeg; see the focused integration document for the FFmpeg 9 development dependencies and proof executable.

Install into a prefix

From a clean source checkout or source archive:

cargo install --path crates/openjoc-cli --locked --root /path/to/prefix
/path/to/prefix/bin/openjoc --help

Binary distribution is handled by the human-created GitHub Release workflow after a stable version tag. The historical OpenJOC 0.2.0 release contains the prior published assets; this source tree does not advertise a Homebrew formula or crates.io installation. The source installation path remains the workspace source tree.

Basic CLI

openjoc inspect input.ec3
openjoc decode input.ec3 -o output/ --internal-base
openjoc decode input.mp4 -o output/ --internal-base --streaming
openjoc decode input.ec3 -o output/ --internal-base --validation-profile etsi-strict
# Calibrated speaker render (Default dialnorm is implicit)
openjoc render-joc input.m4a \
  --layout 7.1.4 -o output.wav
# Convenient offline file level (static post-render sample peak)
openjoc render-joc input.m4a \
  --layout 7.1.4 --normalize-peak -0.1 -o output-loud.wav
# Binaural with the same optional offline file-level step
openjoc render-joc input.m4a \
  --binaural --sofa listener.sofa --normalize-peak -0.1 -o headphones.wav
# Semantic CAF output for the 9.1.6 speaker layout
openjoc render-joc input.m4a \
  --layout 9.1.6 -o render-9.1.6.caf
openjoc render-joc input.m4a --binaural --sofa listener.sofa \
  --virtual-layout 9.1.6 -o binaural-9.1.6.wav
# Optional complete explicit override/test input:
openjoc render-joc input.m4a --topology bridge-control.json --layout 7.1.4 --output render.wav
openjoc diagnose-tools input.ec3 --vector-id ID --json tools.json

For normal decoding and playback, OpenJOC's default calibrated dialnorm policy is recommended; basic examples intentionally omit --dialnorm default because it is already the engine default. For an offline file that should be conveniently loud, add --normalize-peak -0.1 (or another chosen dBFS target). This does not change decoder dynamics.

2.0 is speaker stereo and is separate from binaural output. Select the standards-based stereo policy with --downmix auto, --downmix loro, or --downmix ltrt.

Advanced decoder/output policies

--drc disabled|line|rf|custom controls encoded E-AC-3 dynamic-range metadata; custom mode accepts --drc-boost and --drc-cut percentages from 0 through 100. DRC changes program dynamics; it is not a generic compressor or volume normalization.

--dialnorm default uses calibrated default behavior and is recommended for normal playback/decoding. --dialnorm digital explicitly selects encoded digital program-level calibration. --dialnorm analog uses unity dialnorm gain; it is an advanced compatibility/diagnostic policy. On hot material, unity dialnorm can present a substantially hotter level to downstream headroom processing, so it may make FinalLinkedGain engage more heavily. Do not choose Analog merely because it is louder; it is not a higher-quality, uncompressed, lossless, raw, or mastering mode.

--normalize-peak TARGET_DBFS is an optional file-export transform. It performs one canonical render while spooling bounded, renderer-native PCM and measuring the sample peak, then sequentially applies one common scalar after FinalLinkedGain (and after binaural convolution when selected) before WAV/CAF conversion. It is disabled by default, supports both boost and attenuation, and is sample-peak based and post-render. It is not dialnorm, DRC, a limiter, a compressor, LUFS normalization, or true-peak normalization; an inter-sample true peak may exceed the sample-peak target.

Recommended offline signal flow:

DRC -> calibrated dialnorm -> JOC rendering -> FinalLinkedGain
    -> optional static sample-peak normalization -> file

Analog instead uses unity dialnorm before JOC rendering and FinalLinkedGain. Post-render normalization is applied after FinalLinkedGain, so it preserves the already-rendered dynamic shape with one static linked scalar. Analog changes the level entering FinalLinkedGain and may therefore change its gain-reduction behavior. FinalLinkedGain is internal renderer headroom behavior, not a user mastering control. For 2.0 JOC rendering, Base channels use the selected stereo downmix while reconstructed JOC objects use generic spatial projection to physical FL/FR.

render-joc selects the output container from the destination extension: .wav uses WAVEFORMATEXTENSIBLE where the semantic layout is exactly representable, and .caf uses Core Audio Format channel-layout metadata. The 9.1 family is semantic-CAF-only: its Wide identities are not exactly representable by standard WAVEFORMATEXTENSIBLE and WAV requests fail closed. The renderer’s semantic channel order is independent of that container choice.

decode and decode-payload use AUTO when no profile is supplied: they evaluate ETSI_STRICT first and select OBSERVED_VENDOR_COMPAT only when the existing compatibility validator admits the complete deviation set. An explicit --validation-profile etsi-strict never falls back. The selected profile and reason are written to the bounded validation diagnostics.

Interactive render-joc progress is written to stderr and is automatically disabled for non-TTY output; use --no-progress to opt out. Add --performance-report FILE.json to capture versioned stage timings and realtime diagnostics. Use --overwrite for authorized replacement of existing render outputs in scripts or other non-interactive runs. See Experimental JOC speaker rendering for the report schema, synthetic harness, and real-media qualification boundary.

Raw EC3 parsing and internal-base decoding run in-process. Some seekable MP4/M4A and compatible-base paths use ffprobe and/or ffmpeg; see the capability matrix for the exact boundary.

Assemble the 0.7.0 Apple-Silicon release bundle

On an Apple-silicon macOS host with Python 3.12+, Rust, and the locked Cargo dependencies already cached, a clean committed tree can assemble the release bundle locally before publication:

python3 scripts/build-local-release.py --output /path/to/empty/output
cd /path/to/empty/output
shasum -a 256 -c openjoc-0.7.0-aarch64-apple-darwin.SHA256SUMS
tar -xzf openjoc-0.7.0-aarch64-apple-darwin.tar.gz
cd openjoc-0.7.0-aarch64-apple-darwin
./verify.sh

The bundle includes the canonical docs/ tree, uses git archive HEAD, builds with the locked dependency set, includes openjoc.h and the macOS C ABI static/shared libraries, and refuses tracked worktree/index changes. It is not Developer-ID signed and is not notarized. The script derives the artifact version from the workspace package metadata.

CI and tagged releases

Pull requests and pushes to master run the public GitHub Actions CI matrix. It checks the documented Rust 1.85 MSRV, Linux quality gates, and platform-neutral builds/tests on Windows x64 and macOS arm64. CI results are build/test evidence; a CI result alone does not admit a published binary release for a platform.

Only a human-created stable tag can start release automation (the historical v0.1.0 tag is preserved). The workflow requires the tag to match the Cargo package version exactly, then builds and verifies macOS arm64, Windows x86_64, and GNU/Linux x86_64 release archives. Each archive carries the CLI, public docs, openjoc.h, and the platform C ABI static/shared libraries (including the Windows import library). Per-platform manifests remain internal workflow artifacts. The aggregation job recomputes archive hashes and publishes only the three binary archives plus one unified SHA256SUMS file. The workflow never creates or pushes tags, and refuses to overwrite an existing GitHub Release. Artifact attestation is not currently enabled; aggregate SHA-256, per-platform manifest checks, and the macOS bundle's verify.sh remain release verification surfaces.

Platform scope

The 0.7.0 release workflow targets Apple-silicon macOS (aarch64-apple-darwin), Windows x86_64 (x86_64-pc-windows-msvc), and GNU/Linux x86_64 (x86_64-unknown-linux-gnu). The local bundle command and the candidate in this worktree validate only the Apple-silicon macOS path; Windows and Linux release results come from their native CI jobs and must not be inferred from a macOS build. The macOS bundle is ad-hoc signed and is not Developer-ID signed or notarized.

Contributing and provenance

Before changing codec behavior, read CONTRIBUTING.md and the release-facing capability and limitation documents. The project treats public normative sources and behavioral clean-room specifications as separate claim classes; neither is a claim of Dolby endorsement, certification, or bit-identical Reference Player output.

License

Licensed under Apache-2.0. The source archive includes the complete license text, and Cargo package metadata carries the SPDX license identifier.