Repository navigation
v1.6.0
[1.6.0] - 2026-08-17
Added
- Docker distribution overhauled and made publishable (Windows accessibility) — the
docker/directory is now a complete, tested, cross-platform distribution channel rather than a Windows-only draft:- Stale profile names fixed (the headline bug):
encode.bat's menu and every guide example still used the pre-renamestreaminganddv-archivalprofile names — two of its six menu options, and all five--profile streamingcommand examples inDOCKER_WINDOWS_GUIDE.md. These are deprecated aliases, not invalid names:_is_valid_profileaccepts them andPROFILE_ALIASESmaps them tostreaming-hevc/archive, so those options did run — each greeting a first-time layperson with aProfile 'streaming' is deprecatedwarning instead of a clean encode. The genuinely broken one wasdv-archival, whose menu description no longer matched whatarchiveactually does. Both menus now list all ten canonicalVALID_PROFILESentries, and a newtests/test_docker_parity.sh(wired into thedocssuite beside the man-page/completions parity guards) cross-checks every profile name embedded underdocker/againstVALID_PROFILES, requires both encode menus to cover the full set, and enforces line-ending policy — so a future rename fails the suite instead of shipping another stale menu. The aliases themselves are deliberately retained (old bundles, scripts, and.muxmrcfiles still pass them);PROFILE_ALIASESis live compatibility surface, not dead code. - Missing
.dockerignorecreated:setup.batand the Windows guide both listed it as a required bundle file, but it never existed — a layperson following the guide verbatim stalled at "make sure it's present". It also matters functionally: it excludes everything butmuxmfrom the build context, so a rebuild after media has accumulated ininput//output/no longer uploads gigabytes to the Docker daemon. - macOS/Linux helpers added (
setup.sh,encode.sh): same guided UX as the.batpair (numbered file pick, ten-profile menu, per-profile output container, batch "A = all files" mode).setup.shauto-copies the repo-rootmuxmnext to the Dockerfile (the copy is gitignored), andencode.shruns the container as the invoking uid/gid on Linux so outputs aren't root-owned.docker/README.mdis the new cross-platform entry point (macOS/Linux quickstart + pointer to the Windows guide); the main README gains a Docker install section and a Windows platform badge. - Dockerfile hardened:
dovi_toolis now a pinned direct download (ARG DOVI_TOOL_VERSION) instead of an unauthenticated GitHub-API "latest" query that rate-limits in CI — and a failed download now fails the build instead of warning and shipping an image whose DV features silently do nothing (pgsrip install: same). pgsrip is installed system-wide (PIPX_BIN_DIR=/usr/local/bin, not/root/.local) so non-root runs keep OCR. Full tesseract language data is installed by default (English-only data silently degraded OCR of every non-English PGS track; muxm's own brew path installstesseract-lang, so this restores parity —ARG TESSERACT_LANG_PACKAGESslims custom builds). muxm ischmod 755'd explicitly (COPY preserves host modes; a world-unreadable mode broke non-root runs with a bare "Permission denied"). The build-time verification layer now probes every profile-required ffmpeg encoder (libx264/libx265/libsvtav1/libopus/eac3/aac) and thezscale+tonemapfilters, and runsmuxm --versionas a Linux can-it-even-start canary — the exact class of the Finding #1 startup crash, caught at image build instead of on a user's box. - Config mount corrected: the optional compose
.muxmrcmount now targets/media/.muxmrc(muxm's project-tier, honored by every uid) instead of/root/.muxmrc, which non-root runs silently ignored. - Release tooling:
tools/gen-docker-bundle.shzips the flat Windows bundle (refusing to bundle if the parity guard fails), and.github/workflows/docker-publish.ymlbuilds the image as a PR gate and publishes multi-arch (amd64+arm64) images to GHCR on release tags. A root.gitattributespinsmuxm/*.shto LF and*.batto CRLF (both.bathelpers were LF-only on disk, which cmd.exe can misparse). - Verified end-to-end on the built image:
universalandstreaming-hevcencodes of a spaces-in-name source, plus a non-root (--user)universalencode, all via the mountedinput//output/volumes.
- Stale profile names fixed (the headline bug):
Security
- Root no longer sources an unprivileged user's
~/.muxmrcwhen$HOMEownership is undeterminable (2026-07-06 review, Finding #4) — the M-13 elevation guard (v1.5.1) decides whether to skip the$HOME/.muxmrctier by stat'ing$HOME's owner uid and comparing it to root. Its predicate_muxm_user_tier_is_elevation_risktreated an undeterminable owner (empty stat result) as "best-effort, don't block" and sourced the config anyway. Because the same commit removed the oldSUDO_USER/SUDO_UIDproxy entirely, a root session with a preserved unprivileged$HOME(sudo -E,env_keep += HOME,suwithout-) on a mount where both stat dialects fail or return non-numeric (exotic FUSE/network mounts) would fall through and execute that user's shell as root — the exact RV3-04 vector M-13 was meant to close, reopened in the stat-failure corner. The predicate now fails closed for root: since it is only reached whenEUID == 0, an undeterminable owner is treated as a risk and the tier is skipped (a genuine root login whose own$HOMEis un-stat-able — rare — loses only its optional~/.muxmrc, a safe degradation versus code-exec). This deliberately reverses the documented v1.5.1 "undeterminable → don't block" behavior for the root case only; non-root invocations are unaffected (they short-circuit as same-privilege before the ownership check). Theconfigregression test's truth table was updated accordingly (root + undeterminable owner now asserts SKIP, not SOURCE). Note this hardens only the root/$HOMEelevation tier — the accepted same-privilege CWD./.muxmrcmodel (H1) is untouched, as always.
Fixed
-
SDR/SDR-TONEMAP encodes left
colour_primaries/transfer_characteristicsUnspecified in the encoded HEVC bitstream, producing visibly muted/flat colour on strict decoders (e.g. Apple TV Direct Play) —decide_color_and_pixfmtcorrectly computesCOLOR_ARGS=(-color_primaries bt709 -color_trc bt709 -colorspace bt709)for an untagged SDR source (or carries a tagged source's own values through), and these reach ffmpeg on every libx265 encode. But ffmpeg's libx265AVCodecContextbridge only reliably carries-colorspacethrough tomatrix_coefficientsin the encoded SPS VUI —-color_primaries/-color_trcwere silently dropped, leavingcolour_primaries/transfer_characteristicsat 2 (Unspecified) in the actual bitstream regardless of what COLOR_ARGS requested. Confirmed viaffmpeg -bsf:v trace_headerson real output:colour_description_present_flag=1,colour_primaries=2,transfer_characteristics=2,matrix_coefficients=1, despite all three being requested as bt709. Every real decoder parses colour from the SPS VUI, not container-level tags, so Direct-Play/hardware playback rendered with an incomplete colour description — a muted/desaturated picture versus the source — even though muxm's own color decision was correct. TheHDR10/HLGbranches ofbuild_x265_paramsalready avoided this by bakingcolorprim/transfer/colormatrixdirectly into-x265-params(which does reach the VUI correctly); theSDR/SDR-TONEMAPbranch now does the same, re-stating COLOR_ARGS' own primaries/transfer/matrix values via-x265-params. Verified end-to-end through the real pipeline (not just isolated ffmpeg calls): an untagged source now landscolour_primaries=1/transfer_characteristics=1, and a genuinely re-tagged non-default source (smpte240mon all three fields) passes through correctly as7/7/7.x265's
--colorprim/--transfer/--colormatrixdo not share ffmpeg's full H.273 name vocabulary, though — verified empirically against x265 4.2: ffmpeg's transfer namesgamma22/gamma28arebt470m/bt470bgin x265, ffmpeg'sunspecifiedis rejected outright in every field, and colormatrix additionally rejectsrgb/reserved. An unrecognized name is not a parse error: ffmpeg still exits 0, but the SPS VUI field is then written as0(Reserved) — a non-conformant value, silently worse than the pre-fix Unspecified (2) state. A new_x265_knows_color_nameallowlist gates the append per-field on x265's own verified vocabulary; any COLOR_ARGS value outside it falls through to no append (the pre-fix, incomplete-but-safe behavior) rather than reaching x265 and corrupting the VUI.Scoped to
libx265(the software-encode pathbuild_x265_paramsalready targets);hevc_videotoolbox/h264_videotoolbox/libx264are not covered by this fix. Newhdr-suite regression test (sdr-vui-colour) andunit-suite test (unit-x265-color-allowlist) read the SPS VUI directly via-bsf:v trace_headers/ extract_x265_knows_color_name+build_x265_paramsin isolation, since this ffmpeg build's own container-levelcolor_primaries/color_transferreporting does not surface a value of 1 (bt709) even when correctly present in the bitstream (verified: an HDR10 encode's bt2020/smpte2084 values DO surface viaffprobe; only the bt709 case is swallowed at the container-report layer) —probe_videoalone could not have caught either the original defect or the vocabulary-mismatch hazard. Verified RED on the pre-fix binary (got '2') and GREEN after; the allowlist gate was verified against the real x265 CLI parser (not guessed) before being encoded as acasestatement. -
Post-release logic-bug sweep (2026-07-06 code review of the v1.5.1 logic-fix batch) — seven fixes (plus the Security item above) from a focused review of the changes made between the v1.5.1 pre-release backups; each was reproduced, then re-verified fixed against the full suite. Finding numbers match the
review Finding #Nmarkers left in the source.- Startup crash on Linux (Finding #1): the M-13
$HOME-owner probe was a bare top-level assignment —_home_owner_uid="$(stat -f '%u' "$HOME" 2>/dev/null)"— underset -eEuo pipefail, in Section 6 before the Section-18 ERR/EXIT traps exist. On GNU coreutilsstat -fmeans filesystem status and treats'%u'as a bad file operand, so the command substitution exits non-zero, errexit fires, and every invocation (includingmuxm --help/--version) died silently with exit 1 and no output on any Linux host. The sibling_muxm_tier_is_trusteddocuments this exact BSD-vs-GNUstathazard and guards its dual-dialect probe with&&-lists; the M-13 call site had copied the probe but dropped that protection (the GNU-cfallback on the next line was therefore unreachable). The probe now mirrors the sibling: each dialect is the head of an&&list (so a non-zero exit is errexit-exempt) and is validated^[0-9]+$independently, BSD form first with the GNU-cform as fallback. Verified by matching the proven sibling pattern (the abort is GNU-stat-only; it does not reproduce on the macOS dev host). - External-sidecar OCR could delete a user's pre-existing subtitle (Finding #2):
_ocr_ext_subtitle's L-17 relocation globbed the source directory for any<stem>.*.srtandmv -f'd the first non-empty match into the workdir as "the OCR result". Because pgsrip writes its output under the alpha-2 code (movie.eng.sup→movie.en.srt) while an unrelated user sidecar can share the stem and sort earlier (movie.ara.srt<movie.en.srt), the glob could adopt the user's pre-existing file — moving it out of the source directory (destroyed with the temp workdir) and shipping its wrong-language text tagged as the OCR'd track. The function now snapshots every*.srtbeside the source before OCR runs, and both mv-eligible paths (the exact-name check and the glob) refuse any file present in that snapshot, so only a file OCR actually produced is ever adopted. Newunitregression test reproduces theara < ensort-order case. - Empty
--preset ""bypassed all validation (Finding #3): M-16 (v1.5.1) rewrote the-p/--presetparse arm to accept negative SVT-AV1 presets and, in doing so, dropped the old parse-timeis_valid_presetcheck — which had also rejected an empty value. Every downstream codec-aware re-check (Section 15,--print-effective-config) is gated on[[ -n "${PRESET_VALUE:-}" ]], so--preset ""(realistic via--preset "$UNSET_VAR") slipped past every gate and reached ffmpeg as-preset ''— a late, crypticdie 40mid-encode on x264/x265 (AV1 was rescued by${PRESET_VALUE:-6}). The parse arm now rejects an empty value withdie 11immediately, matching the old fail-fast behavior. - Two distinct NAS shares could defeat the output-volume disk preflight (Finding #5): M-7 (v1.5.1) made
_df_sourcerecover space-containingdffilesystem names for the "are the workdir and output on the same volume?" check, but left-to-rightdf -Pparsing still truncates at the first purely-numeric token, so//nas/Season 2and//nas/Season 3both collapse to//nas/Season.disk_free_warnthen judged two different shares to be one volume and skipped the output-volume free-space check (fail-open), letting a full output volume pass and fail after a multi-hour encode. Volume identity now uses a new_fs_devhelper that returns the filesystem device number (stat'sst_dev, the canonical primitive for same-volume detection, immune to source-string ambiguity), itself written set-e-safe with the same dual-dialect&&-list guard as Finding #1. The now-unused_df_sourcewas removed;_df_avail_kb(stilldf-based, still space-robust) is unchanged.unitcoverage updated: the output-volume test drives identity through mocked_fs_dev, and_fs_devgains numeric/empty assertions. --dry-run --keep-logsilently ignored the flag and contradicted the man page (Finding #6): L-14 (v1.5.1) narrowed the log-persistence gate to also require(( ! DRY_RUN )), so a--dry-run --keep-logrun wrote no log anywhere and gave no indication the explicit flag had been dropped — while the man page's--keep-logentry still read "On a clean run, copy the run log…" (a completed dry run is a clean run). The gating is correct (dry runs create nothing durable), so the run now emits an explicit "--keep-logskipped under--dry-run" note instead of silently dropping the flag, and theMANPAGE_EOF--keep-logentry gained a dry-run carve-out sentence (docs/muxm.1regenerated viatools/gen-docs.sh).- The disk preflight's AV1 4K-CRF prediction was a drift-prone shadow copy (Finding #7): the
disk_free_warnsize estimate hardcoded its own copy of_apply_av1_resolution_crf's profile→4K-CRF table (streaming-av1→ 28,av1-hq→AV1_HQ_HDR_CRF) and its>=3840/>=21604K predicate. No shared helper and no drift guard covered the copy (the AV1-CRF unit test exercises only the real function; the disk unit tests run withlibx265), so a future recalibration could update one site and silently reintroduce the under-warn on the largest encodes — exactly what this preflight branch was added to prevent. Both the table and the predicate are now factored into shared_av1_resolution_crf_target/_dimensions_are_4khelpers called from both sites; the AV1-CRF unit test extracts the helpers alongside the function so it stays runnable in isolation. Behavior is unchanged. - Dolby Vision frame-count verify re-parsed the RPU up to three times (Finding #8):
_dv_verify_frame_countinvokeddovi_tool info -i "$RPU_FINAL" --summaryonce per grep-pattern fallback (three byte-identical invocations differing only in the pattern), re-parsing a feature-length RPU each time on olderdovi_toolbuilds. The summary is now captured once into a variable and the three patterns grep against it; exit-status handling (|| true,2>/dev/null) is preserved.
- Startup crash on Linux (Finding #1): the M-13