Skip to content

Install

From the .deb (pre-release, experimental)

Releases are marked pre-release on the releases page. Download the .deb and SHA256SUMS from one release, check, then install:

sha256sum -c --ignore-missing SHA256SUMS
sudo apt install ./mpv-object-audio_0.1.0_all.deb
mpv-object-audio-install --dry-run   # then: mpv-object-audio-install install

This package contains only the mpv-object-audio wrapper and the installer. It does not include or download mpv-omniphony, Omniphony or harletty-bridge; the installer runs only when you ask it to, and you should read it first (/usr/lib/mpv-object-audio/object-audio-install.sh). See the main repository's docs/rebuild-checklist.md.

The package puts files under /usr only. Its install and remove scripts do not enable or start services, do not write into any home folder, and do not touch CamillaDSP or PipeWire configuration; the setup command above does the per-user part, and --dry-run shows what it would do first. Details, the other repositories' packages, and the one-command installer are in the main repository's packaging notes.

What was checked: written with an AI assistant; checked against simulated rooms and REW exports; used and checked by the author in his own room (one room, one author). No external or second-person validation yet. The packages are unsigned. CI installs and removes them in clean Ubuntu 24.04; the packaging itself has not been run on the author's own rig.

From source

git clone https://github.com/praveenchandrahas/mpv-object-audio && cd mpv-object-audio
./scripts/object-audio-install.sh deps      # prints one apt line (mpv's build dependencies); run what it prints
./scripts/object-audio-install.sh           # engine and bridges: prebuilt releases; mpv-omniphony has no releases, so mpv is built from source (minutes)
mpv-object-audio film.mkv                   # or right-click a film in Dolphin -> mpv-object-audio

Files: scripts/object-audio-install.sh (install, update, status, remove, deps), scripts/mpv-object-audio (the wrapper; --oa-info, --oa-check), scripts/mpv-atmos and scripts/mpv-atmos-overlay-off.lua (the earlier wrapper of the author's rig, kept for comparison), docs/omniphony-debugging.md (how the stack was built and debugged).

It works alone. Optionally it calls eq ensure / eq prepare FILE from linux-theater-dsp before playback (skipped when eq is not installed, or with OBJECT_AUDIO_DSP=0), and seekthumbs can add seek-bar thumbnails.

How the installer works

mpv-object-audio architecture: audio data path, video data path, installer and integration

Conceptual diagram. This repository installs and wraps upstream decoding and rendering components (Omniphony, mpv-omniphony, harletty-bridge); it does not implement a new Atmos or DTS:X decoder or renderer. The DSP step (eq ensure, eq prepare FILE from linux-theater-dsp) is optional: set OBJECT_AUDIO_DSP=0 to disable it.

scripts/object-audio-install.sh installs the latest engine and bridges as prebuilt releases (liborender-<tag>-linux-x86_64.zip from mgth/Omniphony, harletty-bridge-<tag>-linux-x86_64.zip from harletty/harletty-bridge) and builds only mpv-omniphony from source, because it publishes no releases (main of mgth/mpv-omniphony, which pins the mpv fork tag: mpv 0.41.x plus the ad_orender patches; the build needs no engine). Everything goes into ~/.local/opt/mpv-object-audio, and the installer refuses to install the command unless the new mpv loads the engine. It is independent of mpv-atmos: separate mpv binary, engine and bridges, and its own mpv config folder ~/.config/mpv-object-audio (a one-time copy of ~/.config/mpv: keys, uosc, the overlay script). The wrapper scripts/mpv-object-audio carries the same video settings as mpv-atmos (VAAPI, gpu-next on Vulkan, BT.709/BT.1886, peak 60, bt.2390, mitchell with linear downscaling, debanding, 512 MiB demuxer cache).

scripts/object-audio-install.sh deps      # prints the apt line (mpv's build dependencies)
scripts/object-audio-install.sh           # install or update (a re-run takes the latest releases)
scripts/object-audio-install.sh status
scripts/object-audio-install.sh remove

The DSP hooks (eq ensure, eq prepare) and the IPC socket are shared with mpv-atmos on purpose, so the router and the automatic profile switching work unchanged; OBJECT_AUDIO_DSP=0 turns them off. The bridge pairing: the latest engine and the latest bridge release should match (the bridge notes say which Omniphony they require); pin with OA_OMNIPHONY_TAG / OA_BRIDGE_TAG if they do not.

Run on the rig 2026-10-25 (laptop away from the DAC): the asset names matched, the build finished, the engine (v0.7.0, ABI 0.12) and the three bridges (v0.9.0, bridge_api 0.6.0, Omniphony 55af2c5) loaded, and an Atmos TrueHD clip and a DTS:X clip played with sound. Not yet checked with the DAC: routing through CamillaDSP (preflight playing) and the level against mpv-atmos (preflight compare FILE: the new engine logs a -8 dB dialogue normalisation on the Atmos clip). The engine config ~/.config/omniphony/config.yaml is shared with mpv-atmos, so layout and render settings are common to both players. The installed router was updated the same day with install-autoroute.sh (it was older than the repository's and lacked eq prepare). The download step needs GitHub's API, which a rate limit can refuse: set GITHUB_TOKEN.

Adapting it to your system

Paths and user names in the docs and in scripts/mpv-atmos are from the author's machine, and the video settings in the wrapper target a 1080p projector (60 nit peak, BT.1886). Change them for your display and install folder (OA_HOME).

Third-party licences

The installer downloads other projects; they keep their own licences (this repository contains none of their code, and its Apache-2.0 licence does not change theirs):

Component Licence (as stated by the project; check the version you install)
Omniphony engine GPL-3.0-or-later (its README); decoder bridges are loaded at run time and "may be licensed separately"
harletty-bridge checked 2026-11-04 — more than its top-level LICENSE suggests. The repository's own LICENSE file is Apache-2.0, and most of its source is, but the actual bridge libraries it ships (libharletty_{dolby,dts,iamf}_bridge.*, including the one this installer loads) are GPL-3.0-or-later (see the repo's LICENSES/binary-bridge.txt): they link Omniphony's GPL bridge_api crate, which makes each library a combined GPL work, and the DTS bridge also statically links dca (LGPL-2.1-or-later, based on FFmpeg's DCA decoder). The repo's own text: "Linking these libraries into a proprietary program is not permitted." So the thing actually loaded at runtime is GPL, not Apache, despite the top-level badge.
mpv-omniphony checked 2026-11-04: GPL-3.0-or-later (its README and THIRD-PARTY-NOTICES.md; a GPL-2.0-or-later mpv fork combined with GPL-3.0-or-later Omniphony code, which the project's own notice resolves to GPL-3.0-or-later overall for the built binary)
truehdd (the decoder harletty's is a fork of) Apache-2.0
mpv GPL-2.0-or-later by default, LGPL-2.1-or-later when built that way (mpv's documentation)

This repository's own licence is Apache License 2.0 (see also NOTICE). Dolby, Dolby Atmos, DTS and DTS:X are trademarks of their owners; this project is not affiliated with or endorsed by them. It contains no media files and no decoder code.