Skip to content

feat(transcode): quality tiers, size estimates, and actual size in the completion notification - #12135

Open
ButtercupRobrts wants to merge 13 commits into
omacom:quattrofrom
ButtercupRobrts:feat/transcode-quality-size-upstream
Open

ButtercupRobrts wants to merge 13 commits into
omacom:quattrofrom
ButtercupRobrts:feat/transcode-quality-size-upstream

Conversation

@ButtercupRobrts

Copy link
Copy Markdown

Summary

omarchy transcode lets the user trade output quality for file size knowingly: pick a tier, see roughly how big the result will be, and get the actual size when it finishes — without slowing down the default path.

Three pieces:

  • Quality tiers for videos. The interactive flow gains a Select quality step after format and resolution, and the CLI gains an optional 4th positional (omarchy transcode in.mov mp4 1080p low). Tiers are locked per-codec: x264 CRF 18/23/28, x265 CRF 20/24/28, gif 15/10/5 fps. medium — and omitting quality — reproduces today's encoder flags byte-for-byte; nothing about the default path changes. Pictures see no quality step and reject a 4th positional. Non-default tiers append -high/-low to the output name; collision dedupe (-2, -3) is unchanged.
  • Size estimates on the quality menu. mp4 rows show CRF N · ~N MB — ffprobe duration × a per-resolution/tier bitrate midpoint + the audio term — rounded to 1–2 significant figures. When the estimate would exceed the source size the row says larger than source; when the probe fails the rows degrade to uniform qualitative labels (Best quality / Balanced / Smallest file). gif rows show fps, never a size — gif output doesn't respond to bitrate, so a number there would lie.
  • Actual size in the completion notification. Saved and copied to clipboard (38 MB). — measured with stat on the final resolved output path (quality suffix and dedupe -N included), same MiB scale the estimates use, so the estimate→actual loop closes. A missing/failed stat degrades to the plain body rather than fabricating a number; a failed encode still sends no completion notification.

Supporting change: omarchy-menu-select accepts --default-index N after --, carried through the select payload to Menu.qml's openDmenu, which initializes selectedIndex from it (clamped, reset to 0 on first keystroke — initial position only). The quality menu uses it to pre-highlight medium. Every existing caller emits a byte-identical payload — the field is absent unless passed. While in that arm, the same non-finite guard now covers --width/--maxheight, closing a path where 1e1000 produced bare Inf/NaN JSON tokens, JSON.parse threw, doneFile was never created, and the script spun forever.

Also fixed along the way: format and resolution positionals now validate before menus and the start notification — omarchy transcode in.mov avi 1080p fails immediately instead of firing a Transcoding video… toast and then dying.

Design notes for reviewers

  • Backward compatibility is the contract: medium/omitted produces identical ffmpeg argv to before this change; interactive menus only engage when an arg is absent; ffprobe runs only inside the interactive mp4 branch — non-interactive callers (keybind, Nautilus extension, menu action) never pay for it.
  • Estimates are deliberately approximate (~, ±2× by design — CRF is content-dependent). The completion notification carries the true size, which is what teaches the user which tier to pick next time.
  • Known overlap: PR Add folder transcoding #6698 touches the same script. Happy to rebase.
  • omarchy-transcode-ascii is untouched (separate binary, transcode ascii route).

Test plan

  • bash test/shell.d/transcode-quality-test.sh — 52 assertions green: tier tables byte-pinned, medium-identical argv, picture rejection, filename suffix + dedupe, estimate rounding, larger than source/probe-failure degrade, foreign-label menu-pick rejection, actual-size notification on both arms, <1 MB band, stat-failure degrade, zero done-notifications on encode failure, ordering (start toast before ffmpeg)
  • bash test/shell.d/menu-select-test.sh — 12 assertions green: --default-index payload, absent-field byte-identity for existing callers, non-finite coercion for all three numeric args, stdin-fed caller intact
  • bash test/shell.d/menu-test.sh green; ./test/cli green
  • Live UAT: Files → Transcode single and multi-select flows, partial positional chain (omarchy transcode clip.mp4 mp4 → resolution then quality prompt), menu renders CRF N · ~N MB rows with medium pre-highlighted, done toast reports real size; estimate↔actual verified on real clips

HerrStolzier added a commit to HerrStolzier/omarchy that referenced this pull request Sep 27, 2026
Address llstrk's review on omacom#13360. Match the completion
message prefix in both positive and negative checks, answer only the
optional quality prompt in a stub, and reject unexpected menu requests.
Stub ffprobe so dummy media stays on the estimate fallback path.

Report named failures for unsuccessful transcodes and verify the injected
failure statuses, so an unrelated early menu error cannot satisfy a
negative test.

The 15 cases pass on the current command and a focused overlay of the
transcode command from omacom#12135 at b9535ec, including open
stdin and PTY runs. Fifteen mutation/error-injection checks are detected.
Full test/all runs before and after retain identical failing and skipped
file sets (31 failing and 23 with skips out of 263 shell test files), plus
the unchanged VS Code CLI assertion. No production code is changed.
@llstrk

llstrk commented Sep 27, 2026

Copy link
Copy Markdown

Automated AI review

Community review: Independent automated community review, unaffiliated with the Omarchy team, intended to help prepare PRs for their review.

Verified: the encoder side matches the description. On a synthetic clip, explicit medium and an omitted quality with medium picked both produce the same ffmpeg argv as the base script, and the output packets are identical. The high/low tiers use the stated CRF and fps values. The omarchy-menu-select guard works: on the base script --width 1e1000 emits "width":Inf and hangs, while at head it emits 0, and defaultIndex is floored and clamped in MenuModel.js. The three changed test files pass at head and fail against the base code, and the full test/shell suite has the same six environment-dependent failures on base and head. The branch merges cleanly onto the current quattro tip.

Two behaviour changes are worth a look: a command that already names format and resolution now stops at a quality menu, and the completion message for small outputs is cut off.

A command that names format and resolution now opens a quality menu

main prompts for quality whenever the input is a video and the 4th positional is empty (bin/omarchy-transcode:411-413). Before this PR, a three-argument video command ran without any menu.

omarchy transcode clip.mp4 mp4 720p Base Head
Menus shown none Select quality (after two ffprobe calls)
Esc on that menu n/a exits non-zero, no output, no notification
Medium picked n/a same argv and file name as base

The PR's own test reflects this: every three-argument video run in transcode-quality-test.sh sets FAKE_PICK.

Impact: the three-argument form is documented as the form for when you already know what you want, and it now blocks until the shell menu answers:

  • The help text says Videos: high, medium, low (default: medium) (bin/omarchy-transcode:31).
  • The manual calls omarchy transcode ~/Videos/demo.mov mp4 1080p the form for when "you already know what you want" and says "leave it off and you get the same file as before".
  • The agent skill line in default/agents/skills/omarchy/capture.md and the omarchy:examples three-argument example point scripts and agents at this form.
  • Open PR Add folder transcoding #6698 asks format and resolution once for a Nautilus batch, then runs omarchy-transcode <path> "$format" "$resolution" per file. With this PR, each video in a multi-file batch would ask for quality separately.

Suggested change: when format and resolution both came from arguments, use medium without a menu, so the prompt appears only in the interactive flow. If the prompt is intended, drop "(default: medium)" from the help text and describe the prompt in the manual and the skill line.

Outputs under 1 MiB show a truncated completion message

output_size_label prints <1 MB (bin/omarchy-transcode:296), so the body becomes Saved and copied to clipboard (<1 MB). The notification card renders bodies with textFormat: Text.StyledText (shell/plugins/notifications/components/NotificationCard.qml), and NotificationLogic.styledBody passes this body through unchanged. Qt's StyledText parser treats < as the start of a tag that runs to the next >, or to the end of the string when there is none, so everything from < on is dropped.

Measured with Qt 6.11.2 (offscreen Text widths):

Body text Width Rendered
Saved and copied to clipboard (<1 MB). 280.98 same width as Saved and copied to clipboard ( alone
Same string as PlainText 351.50 full text
Saved and copied to clipboard (&lt;1 MB). 351.50 full text
Saved and copied to clipboard (38 MB). equal in both formats full text

A real sub-1 MiB encode at head sent exactly the (<1 MB). body. The PR test pins that literal string, so it cannot catch the rendering.

Impact: short clips and small pictures finish with Saved and copied to clipboard (.

Suggested change: prefer wording without <, for example under 1 MB, which renders the same with any notification server (escaping as &lt;1 MB also works in Omarchy's own card). Update the test string to match.

Name collisions now get -2, -3 suffixes, which the description calls unchanged

The base output_path has no collision handling; the suffix loop was added in this PR (commit f523e4d). What changes on a repeat run with the same settings:

Existing output Base Head
Picture magick overwrites it writes -2, keeps the old file
Video, no terminal ffmpeg declines to overwrite and exits 0, so the old file's URI is copied and the toast says "Saved" writes -2, keeps the old file

Impact: for videos this fixes a false success. For pictures, repeat runs now accumulate copies instead of replacing the file.

Suggested change: describe the -N naming in the PR description and the manual, and state the picture behaviour change so maintainers can decide on it.

Smaller notes

  • Validation order: format and resolution are checked after both prompts (bin/omarchy-transcode:379-409). clip.mp4 avi 1080p now fails before any menu or toast, as described, but clip.mp4 avi still shows the resolution menu first. Checking the format right after media_type would close that gap.
  • Pictures with a 4th argument: any 4th positional on a picture now fails with "quality applies to videos only"; base ignored it.
  • Units: estimates and the finished size divide by 1,048,576 but print "MB". Files (Nautilus, via GLib g_format_size) uses 1000-based units, so a 39,845,888-byte file reads 38 MB in the toast and 39.8 MB in Files.
  • Manual wording: it says each video quality choice comes with a size estimate, but gif rows show fps only, and mp4 falls back to qualitative labels when probing fails.
  • Optional test improvement: test/shell.d/menu-select-test.sh:129-134 fails if any other script in bin/ ever passes --default-index, so a legitimate new caller of the flag would break the suite. Asserting only that omarchy-transcode passes the flag keeps the pin without that side effect.
  • Planning references in shipped comments: D-00a, D-04, T-05-01, WR-01 and "Phase 6" in the tests, and "the PR Add folder transcoding #6698 conflict window" in bin/omarchy-transcode, mean nothing outside the author's notes.

Related open PRs


Review information

Test scope: Source review of head b9535ec against the base script, its callers (keybinding, menu action, Nautilus extension), the menu and notification QML, and upstream Qt, FFmpeg and GLib source. The PR tests, related tests, the full test/shell suite and behaviour probes with real ffmpeg, ffprobe and ImageMagick on synthetic media ran in an isolated sandbox, with the menu, notification and clipboard stubbed. StyledText rendering was measured offscreen. The menu pre-highlight and the notification were not viewed on a live desktop. Conflicts with other open PRs are from pairwise merges of the public branches.

AI process: Opus 5.5 Medium coordination and synthesis, Opus 5.5 Xhigh technical review and final fact check, GPT 6 Sol Xhigh search for related issues, Opus 5.5 Medium editorial check.

Opt out: To stop receiving these reviews, reply to this comment saying so.

…load

- bin/omarchy-menu-select parses --default-index N after -- and emits an
  optional defaultIndex integer in the select-mode payload, only when passed
- MenuModel.dmenuDefaultIndex resolves the field into [0, count-1] as a
  node-testable helper; openDmenu initializes selectedIndex from it before
  rebuildDisplay(), so the existing clamp bounds out-of-range values
- typing in the filter still resets the highlight to row 0 (initial-only,
  documented in setFilter and docs/menu.md)
- test/shell.d/menu-select-test.sh proves the field reaches the payload end
  to end via a handshake-satisfying omarchy-shell stub
- perl int() numifies 1e1000/inf/nan to Inf/NaN, which encode_json emits as
  bare tokens — invalid JSON that wedged the CLI on the doneFile wait
- coerce non-finite results to 0, preserving the locked garbage→0 contract;
  regression test runs the real script under timeout so a recurrence fails
  fast instead of hanging
- 4th positional [quality] selects locked tiers: x264 crf 18/23/28,
  x265 crf 20/24/28, gif fps 15/10/5; medium/omitted byte-identical
- high/low append -high/-low to the output name
- output_path dedupes collisions to -2/-3 via [[ -e || -L ]] before
  the Transcoding notification -- no -y/-n, no stdin prompt
- pictures reject a 4th positional pre-notification; strict
  high|medium|low whitelist, empty behaves as omitted
- stub-bin e2e covers the full contract; usage/metadata/docs synced
The Phase-4 sweep pinned "no existing caller passes --default-index" as a
tripwire for the flag's first adoption; omarchy-transcode is that caller, so
the sweep now asserts it is the only one.
- Select quality menu after format+resolution on the interactive video
  path, rows passed as tab-joined label/subtext argv with medium
  pre-highlighted via -- --default-index 1
- mp4 rows carry "CRF N · ~N MB" estimates (ffprobe duration x locked
  resolution/tier bitrate midpoints + audio term, 1-2 sig figs); gif
  rows carry "N fps" subtexts and never probe
- Estimates degrade honestly: per-row "larger than source" past the
  input size, uniform qualitative fallback on probe N/A or failure
- The pick is stripped at the first tab and re-validated high|medium|low
  inside select_quality, before the notification boundary
@ButtercupRobrts
ButtercupRobrts force-pushed the feat/transcode-quality-size-upstream branch from b9535ec to 0886701 Compare September 27, 2026 16:52
@omarchybot omarchybot added the enhancement New feature or request label Sep 27, 2026
@llstrk

llstrk commented Sep 28, 2026

Copy link
Copy Markdown

Automated AI review

Community review: Independent automated community review, unaffiliated with the Omarchy team, intended to help prepare PRs for their review.

Follow-up to the earlier review, checked at head 0886701 on base bf44355.

Outcome: the force-push since the earlier review is a rebase. The 13 commits carry the same changes as the previously reviewed head b9535ec. bin/omarchy-transcode, bin/omarchy-menu-select, the two new test files and the notification card are byte-identical, and the PR's additions to menu-test.sh are unchanged. The earlier findings all still apply. One note is reframed below, and one new interaction with open PR #9031 is added.

Verified again at 0886701:

  • Explicit medium and a menu-picked medium give the same ffmpeg argv and byte-identical output as base on a synthetic clip.
  • --width 1e1000 still hangs on base and emits 0 at head.
  • The three changed test files pass at head and fail against the base code.
  • The full test/shell suite fails the same 11 files on base and head in this sandbox (pre-existing, not caused by this PR). The earlier review counted six in its environment.
  • The branch merges cleanly onto the current quattro tip (3faafba), and the three PR tests pass on the merge result.
Earlier finding At 0886701
Three-argument video command opens a quality menu Still present, see the addition below
(<1 MB). completion body cut off by StyledText Still present
-2, -3 collision suffixes described as unchanged Still present. The suffix loop now comes from commit 8c2e973; f523e4d is no longer on the branch
clip.mp4 avi shows the resolution menu before rejecting the format Still present
A 4th positional on a picture now fails Reframed below
Sizes in MiB labelled "MB" Still present
Manual promises a size estimate for every video quality row Still present
Optional test improvement: --default-index caller sweep (test/shell.d/menu-select-test.sh:129-134) Still present
Planning references in shipped comments Still present
Related open PRs (#6698, #11057, #11877, #12363, #13043, #7320, #7610, #7954, #11580) Still apply. All nine are open, and the conflicts were rechecked against the current tip

Addition to the three-argument finding: the PR description says omitting quality "reproduces today's encoder flags" and that the non-interactive callers (keybinding, Nautilus extension, menu action) "never pay for" ffprobe. Those three callers are interactive: they pass no format or resolution. The three-argument form was the non-interactive shape, and it now waits on Select quality (for mp4, after two ffprobe calls). Open PR #13360 already carries a commit ("Keep transcode clipboard tests compatible with quality prompts") that answers this menu in its own three-argument tests. The earlier suggested change still applies.

Reframed: pictures with a 4th argument. The PR description states that pictures "reject a 4th positional", so this is an intended change rather than an oversight. The earlier note stands as information only.

Combined with open PR #9031, the new menu-select-test.sh fails

#9031 ("Stop menu commands waiting forever…") and this PR merge cleanly in either order. #9031 changes bin/omarchy-menu-select in two ways that matter here:

  • It sources a new omarchy-menu-handshake helper by bare name, so the helper is looked up on PATH.
  • It exits unless a quickshell process serving $OMARCHY_PATH/shell is running.

This PR's new test/shell.d/menu-select-test.sh runs the real omarchy-menu-select and stubs only omarchy-shell. On quattro plus both PRs:

Setup for menu-select-test.sh Result
As written, headless fails at the first assertion: omarchy-menu-handshake: No such file or directory
$ROOT/bin on PATH fails: no running Omarchy shell to show the menu
OMARCHY_PATH=$ROOT, $ROOT/bin on PATH, plus a stand-in process named quickshell whose command line contains $ROOT/shell 12 ok

transcode-quality-test.sh is unaffected because it stubs omarchy-menu-select entirely. The merged menu-test.sh passes. With a stubbed shell, ffmpeg and ffprobe, the combined production path still resolves the highlight to medium (defaultIndex: 1) and passes -crf 23 to ffmpeg.

Impact: whichever of the two PRs lands second leaves menu-select-test.sh failing on headless runs and anywhere no matching Omarchy shell is running. docs/testing.md says tests must not depend on an installed Omarchy and must stay green on headless machines, so relying on a live shell is not an option.

Suggested change: in menu-select-test.sh, set OMARCHY_PATH=$ROOT, put $ROOT/bin on PATH and start a stand-in quickshell process whose command line contains $ROOT/shell, as in the passing row above. Alternatively, coordinate the test change with #9031's author so that it lands with whichever PR merges second.


Review information

Test scope: Source comparison of the old and new commit series and bases, plus source review of head 0886701 and open PR #9031 (head aa732d0). The PR tests, the full test/shell suite and behaviour probes ran in an isolated sandbox with real ffmpeg and ImageMagick on synthetic media. The menu, notification and clipboard were stubbed. StyledText truncation was measured offscreen with a bare Qt Text, not the notification card. The combined #9031 checks used a stand-in quickshell process, a stubbed shell and stubbed ffmpeg and ffprobe, not a real Quickshell. Conflicts come from merges of public branch heads as of 2026-09-28. No live desktop was used, and no real 4K encode was run.

AI process: Opus 5.5 Medium coordination and synthesis, Opus 5.5 Xhigh technical review and final fact check, GPT 6 Sol Xhigh search for related issues, Opus 5.5 Medium editorial check.

Opt out: To stop receiving these reviews, reply to this comment saying so.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants