Skip to content

v1.6.0

Choose a tag to compare

@TheBluWiz TheBluWiz released this 17 Aug 20:18
· 15 commits to main since this release

[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-rename streaming and dv-archival profile names — two of its six menu options, and all five --profile streaming command examples in DOCKER_WINDOWS_GUIDE.md. These are deprecated aliases, not invalid names: _is_valid_profile accepts them and PROFILE_ALIASES maps them to streaming-hevc/archive, so those options did run — each greeting a first-time layperson with a Profile 'streaming' is deprecated warning instead of a clean encode. The genuinely broken one was dv-archival, whose menu description no longer matched what archive actually does. Both menus now list all ten canonical VALID_PROFILES entries, and a new tests/test_docker_parity.sh (wired into the docs suite beside the man-page/completions parity guards) cross-checks every profile name embedded under docker/ against VALID_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 .muxmrc files still pass them); PROFILE_ALIASES is live compatibility surface, not dead code.
    • Missing .dockerignore created: setup.bat and 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 but muxm from the build context, so a rebuild after media has accumulated in input//output/ no longer uploads gigabytes to the Docker daemon.
    • macOS/Linux helpers added (setup.sh, encode.sh): same guided UX as the .bat pair (numbered file pick, ten-profile menu, per-profile output container, batch "A = all files" mode). setup.sh auto-copies the repo-root muxm next to the Dockerfile (the copy is gitignored), and encode.sh runs the container as the invoking uid/gid on Linux so outputs aren't root-owned. docker/README.md is 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_tool is 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 installs tesseract-lang, so this restores parity — ARG TESSERACT_LANG_PACKAGES slims custom builds). muxm is chmod 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 the zscale+tonemap filters, and runs muxm --version as 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 .muxmrc mount 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.sh zips the flat Windows bundle (refusing to bundle if the parity guard fails), and .github/workflows/docker-publish.yml builds the image as a PR gate and publishes multi-arch (amd64+arm64) images to GHCR on release tags. A root .gitattributes pins muxm/*.sh to LF and *.bat to CRLF (both .bat helpers were LF-only on disk, which cmd.exe can misparse).
    • Verified end-to-end on the built image: universal and streaming-hevc encodes of a spaces-in-name source, plus a non-root (--user) universal encode, all via the mounted input//output/ volumes.

Security

  • Root no longer sources an unprivileged user's ~/.muxmrc when $HOME ownership is undeterminable (2026-07-06 review, Finding #4) — the M-13 elevation guard (v1.5.1) decides whether to skip the $HOME/.muxmrc tier by stat'ing $HOME's owner uid and comparing it to root. Its predicate _muxm_user_tier_is_elevation_risk treated an undeterminable owner (empty stat result) as "best-effort, don't block" and sourced the config anyway. Because the same commit removed the old SUDO_USER/SUDO_UID proxy entirely, a root session with a preserved unprivileged $HOME (sudo -E, env_keep += HOME, su without -) 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 when EUID == 0, an undeterminable owner is treated as a risk and the tier is skipped (a genuine root login whose own $HOME is 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). The config regression test's truth table was updated accordingly (root + undeterminable owner now asserts SKIP, not SOURCE). Note this hardens only the root/$HOME elevation tier — the accepted same-privilege CWD ./.muxmrc model (H1) is untouched, as always.

Fixed

  • SDR/SDR-TONEMAP encodes left colour_primaries/transfer_characteristics Unspecified in the encoded HEVC bitstream, producing visibly muted/flat colour on strict decoders (e.g. Apple TV Direct Play) — decide_color_and_pixfmt correctly computes COLOR_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 libx265 AVCodecContext bridge only reliably carries -colorspace through to matrix_coefficients in the encoded SPS VUI — -color_primaries/-color_trc were silently dropped, leaving colour_primaries/transfer_characteristics at 2 (Unspecified) in the actual bitstream regardless of what COLOR_ARGS requested. Confirmed via ffmpeg -bsf:v trace_headers on 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. The HDR10/HLG branches of build_x265_params already avoided this by baking colorprim/transfer/colormatrix directly into -x265-params (which does reach the VUI correctly); the SDR/SDR-TONEMAP branch 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 lands colour_primaries=1/transfer_characteristics=1, and a genuinely re-tagged non-default source (smpte240m on all three fields) passes through correctly as 7/7/7.

    x265's --colorprim/--transfer/--colormatrix do not share ffmpeg's full H.273 name vocabulary, though — verified empirically against x265 4.2: ffmpeg's transfer names gamma22/gamma28 are bt470m/bt470bg in x265, ffmpeg's unspecified is rejected outright in every field, and colormatrix additionally rejects rgb/reserved. An unrecognized name is not a parse error: ffmpeg still exits 0, but the SPS VUI field is then written as 0 (Reserved) — a non-conformant value, silently worse than the pre-fix Unspecified (2) state. A new _x265_knows_color_name allowlist 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 path build_x265_params already targets); hevc_videotoolbox/h264_videotoolbox/libx264 are not covered by this fix. New hdr-suite regression test (sdr-vui-colour) and unit-suite test (unit-x265-color-allowlist) read the SPS VUI directly via -bsf:v trace_headers / extract _x265_knows_color_name + build_x265_params in isolation, since this ffmpeg build's own container-level color_primaries/color_transfer reporting 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 via ffprobe; only the bt709 case is swallowed at the container-report layer) — probe_video alone 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 a case statement.

  • 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 #N markers 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)" — under set -eEuo pipefail, in Section 6 before the Section-18 ERR/EXIT traps exist. On GNU coreutils stat -f means filesystem status and treats '%u' as a bad file operand, so the command substitution exits non-zero, errexit fires, and every invocation (including muxm --help/--version) died silently with exit 1 and no output on any Linux host. The sibling _muxm_tier_is_trusted documents this exact BSD-vs-GNU stat hazard and guards its dual-dialect probe with &&-lists; the M-13 call site had copied the probe but dropped that protection (the GNU -c fallback 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 -c form 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>.*.srt and mv -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 *.srt beside 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. New unit regression test reproduces the ara < en sort-order case.
    • Empty --preset "" bypassed all validation (Finding #3): M-16 (v1.5.1) rewrote the -p/--preset parse arm to accept negative SVT-AV1 presets and, in doing so, dropped the old parse-time is_valid_preset check — 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, cryptic die 40 mid-encode on x264/x265 (AV1 was rescued by ${PRESET_VALUE:-6}). The parse arm now rejects an empty value with die 11 immediately, 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_source recover space-containing df filesystem names for the "are the workdir and output on the same volume?" check, but left-to-right df -P parsing still truncates at the first purely-numeric token, so //nas/Season 2 and //nas/Season 3 both collapse to //nas/Season. disk_free_warn then 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_dev helper that returns the filesystem device number (stat's st_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_source was removed; _df_avail_kb (still df-based, still space-robust) is unchanged. unit coverage updated: the output-volume test drives identity through mocked _fs_dev, and _fs_dev gains numeric/empty assertions.
    • --dry-run --keep-log silently 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-log run wrote no log anywhere and gave no indication the explicit flag had been dropped — while the man page's --keep-log entry 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-log skipped under --dry-run" note instead of silently dropping the flag, and the MANPAGE_EOF --keep-log entry gained a dry-run carve-out sentence (docs/muxm.1 regenerated via tools/gen-docs.sh).
    • The disk preflight's AV1 4K-CRF prediction was a drift-prone shadow copy (Finding #7): the disk_free_warn size 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/>=2160 4K 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 with libx265), 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_4k helpers 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_count invoked dovi_tool info -i "$RPU_FINAL" --summary once per grep-pattern fallback (three byte-identical invocations differing only in the pattern), re-parsing a feature-length RPU each time on older dovi_tool builds. 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.