Let the user pick a container and codecs independently, and remux without re-encoding #3

2026-08-22T12:09:47Z

JMR-dev commented

2026-08-22 12:09:47 +00:00

(Migrated from github.com)

Stacked on #2. Based on fix/media3-honours-output-format so the diff shows only this change. GitHub will retarget to main once #2 merges.

OutputFormat was a closed enum of twelve (container, videoCodec, audioCodec) triples, defended on the grounds that a closed set was what made routing decidable. Two things it could not express: changing the container while copying the streams, and choosing codecs per track.

OutputSpec replaces it as the vocabulary; OutputFormat stays as presets over it. Decidability moves to ContainerCapabilities, which is explicit and unit-tested rather than implicit in whichever combinations somebody enumerated.

The matrix has a mode axis

Indexed by (container, codec, trackType, mode), not one boolean. "Can MP4 carry AV1" and "can this app encode AV1" have different answers, and copy is where the difference shows: a single flag would either refuse a legitimate remux or promise an encode neither engine can deliver.

COPY is a codec value rather than a flag, so every exhaustive when in the codebase had to say what it does about copying. CopyPlanner resolves it before anything else reads the request, and inherits ConcatPlanner's rule that an unproven match is never a copy — a needless re-encode costs time, a wrong stream copy costs a file that will not play.

A matching codec is upgraded to a copy only when the container is changing. If container and codec both already match, the only reason to run the job is to re-encode it, most likely to compress — silently copying would hand back a byte-identical file and call it done. That assumption needs revisiting if bitrate or resolution controls are ever added.

Routing asks the plan, never the request

COPY belongs to none of the capability sets, so testing the request directly sends every remux to FFmpeg on the first check — and nothing notices, because -c copy produces a correct file, just on the CPU. ConversionRouterTest asserts the engine for that reason.

The router also learns what Media3 can carry as opposed to encode: its MP4 muxer takes AAC, Opus, Vorbis and PCM but neither MP3 nor FLAC, so remuxing an MP3 track into MP4 leaves the hardware path. Before remuxing existed nothing could reach that combination.

Containers became load-bearing

Container now drives -f, the extension and the SAF MIME type, so Matroska without video is .mka and MP4 without video is .m4a without a preset for each. FLAC was declared as Container.MKV with a .flac extension — inert only while nothing read the container; it now has its own. Six added: MOV, MKA, MPEG-TS, AVI, FLV, WMV/ASF.

Probing

MediaProbe separates "no video track" from "could not parse" and reports the source container, which MediaExtractor cannot supply at all. FFprobe runs on every pick for that reason, not as a fallback. Matroska and WebM share a demuxer and report identical format names, so the codec is used to disambiguate — documented, with the residual ambiguity shown to be safe for the planner.

UI

Presets stay the one-tap path. The Advanced drawer shows the whole matrix and lets an impossible combination be selected on purpose, then explains it and offers one-tap alternatives; Convert is what blocks the job. ConversionWorker validates too, so a stale queued spec fails with the reason rather than being coerced into something else.

Verification

:app:testDebugUnitTest — 133 tests green, up from 71.
New: ContainerCapabilitiesTest, CopyPlannerTest, CodecNamesTest, MediaProbeFormatTest; extended router, builder and format tests.
New instrumented RemuxTest plus four committed fixtures (sample_h264.mkv, sample_aac.m4a, sample_vp9.webm, sample_still.png), recipes recorded in KDoc per the HardwareFallbackTest convention.

Three bugs were caught by tests written for this change: suggestions repaired only the failing axis (offering VP9-in-WebM with AAC still attached); the MP3-in-MP4 muxer gap above, where a test asserted the opposite of the truth; and FFmpegCommandBuilder's else -> libx264, which would silently hand back H.264 for a VP8/AV1 request — structurally the same defect #2 fixes.

⚠️ The instrumented tests have not been executed locally — the emulator segfaults on my machine. CI is the first real exercise of RemuxTest. Unproven until it runs: MKV→MP4 landing on MEDIA3, WAV/Ogg output, and InputKind classification against the real fixtures.

🤖 Generated with Claude Code

> **Stacked on #2.** Based on `fix/media3-honours-output-format` so the diff shows only this change. GitHub will retarget to `main` once #2 merges. `OutputFormat` was a closed enum of twelve `(container, videoCodec, audioCodec)` triples, defended on the grounds that a closed set was what made routing decidable. Two things it could not express: changing the container while copying the streams, and choosing codecs per track. `OutputSpec` replaces it as the vocabulary; `OutputFormat` stays as presets over it. Decidability moves to `ContainerCapabilities`, which is explicit and unit-tested rather than implicit in whichever combinations somebody enumerated. ## The matrix has a mode axis Indexed by `(container, codec, trackType, mode)`, not one boolean. "Can MP4 carry AV1" and "can this app encode AV1" have different answers, and copy is where the difference shows: a single flag would either refuse a legitimate remux or promise an encode neither engine can deliver. `COPY` is a codec value rather than a flag, so every exhaustive `when` in the codebase had to say what it does about copying. `CopyPlanner` resolves it before anything else reads the request, and inherits `ConcatPlanner`'s rule that an unproven match is never a copy — a needless re-encode costs time, a wrong stream copy costs a file that will not play. A matching codec is upgraded to a copy **only when the container is changing**. If container and codec both already match, the only reason to run the job is to re-encode it, most likely to compress — silently copying would hand back a byte-identical file and call it done. That assumption needs revisiting if bitrate or resolution controls are ever added. ## Routing asks the plan, never the request `COPY` belongs to none of the capability sets, so testing the request directly sends every remux to FFmpeg on the first check — and nothing notices, because `-c copy` produces a correct file, just on the CPU. `ConversionRouterTest` asserts the **engine** for that reason. The router also learns what Media3 can *carry* as opposed to encode: its MP4 muxer takes AAC, Opus, Vorbis and PCM but neither MP3 nor FLAC, so remuxing an MP3 track into MP4 leaves the hardware path. Before remuxing existed nothing could reach that combination. ## Containers became load-bearing `Container` now drives `-f`, the extension and the SAF MIME type, so Matroska without video is `.mka` and MP4 without video is `.m4a` without a preset for each. `FLAC` was declared as `Container.MKV` with a `.flac` extension — inert only while nothing read the container; it now has its own. Six added: MOV, MKA, MPEG-TS, AVI, FLV, WMV/ASF. ## Probing `MediaProbe` separates "no video track" from "could not parse" and reports the source container, which `MediaExtractor` cannot supply at all. FFprobe runs on every pick for that reason, not as a fallback. Matroska and WebM share a demuxer and report identical format names, so the codec is used to disambiguate — documented, with the residual ambiguity shown to be safe for the planner. ## UI Presets stay the one-tap path. The Advanced drawer shows the whole matrix and **lets an impossible combination be selected on purpose**, then explains it and offers one-tap alternatives; Convert is what blocks the job. `ConversionWorker` validates too, so a stale queued spec fails with the reason rather than being coerced into something else. ## Verification - `:app:testDebugUnitTest` — **133 tests green**, up from 71. - New: `ContainerCapabilitiesTest`, `CopyPlannerTest`, `CodecNamesTest`, `MediaProbeFormatTest`; extended router, builder and format tests. - New instrumented `RemuxTest` plus four committed fixtures (`sample_h264.mkv`, `sample_aac.m4a`, `sample_vp9.webm`, `sample_still.png`), recipes recorded in KDoc per the `HardwareFallbackTest` convention. Three bugs were caught by tests written for this change: suggestions repaired only the failing axis (offering VP9-in-WebM with AAC still attached); the MP3-in-MP4 muxer gap above, where a test asserted the opposite of the truth; and `FFmpegCommandBuilder`'s `else -> libx264`, which would silently hand back H.264 for a VP8/AV1 request — structurally the same defect #2 fixes. ⚠️ **The instrumented tests have not been executed locally** — the emulator segfaults on my machine. CI is the first real exercise of `RemuxTest`. Unproven until it runs: MKV→MP4 landing on `MEDIA3`, WAV/Ogg output, and `InputKind` classification against the real fixtures. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: JMR-dev/LibreMediaConverter#3