Spike: FFmpeg vs gstreamer-rs binding decision

[natashaannn]

Context

The native Rust rewrite (RFC 0001) requires a decode/encode binding for the render engine. This decision must be made before any Epic 1 (Native Render Engine) issues are written — the binding choice determines every subsequent API call in the compositor. Deciding mid-epic would force a rewrite of already-written code.

This spike runs in the current repo under spike/rust-decode-spike/ on its own branch. The findings port to the new repo; the spike code does not.

Question to answer

Is a native FFmpeg Rust binding or gstreamer-rs the better foundation for the render engine on the target hardware matrix?

FFmpeg candidate: test ffmpeg-the-third as the primary candidate, not ffmpeg-next. Per community discussion (source), ffmpeg-next is now maintenance-only (upstream compat patches, no meaningful feature work), while ffmpeg-the-third is the actively-developed fork of the same lineage. If ffmpeg-the-third fails the evaluation criteria below, fall back to testing ffmpeg-next or ac-ffmpeg (smaller community, more actively maintained per the same thread) before ruling out the FFmpeg-binding approach entirely.

Target hardware:

• Mac M2 (VideoToolbox)
• Mac M3 (VideoToolbox)
• Windows x64 with NVIDIA GPU (NVENC/NVDEC)

Evaluation criteria

For each candidate binding, test and document:

1. Hardware codec access — can it reach VideoToolbox on Mac and NVENC/NVDEC on Windows without extra shims or a non-Rust native layer?
2. Seek/decode accuracy — frame-accurate seek to an arbitrary timestamp on a real .mp4 fixture (required for jump-cut editing; off-by-one-frame seek is a disqualifier)
3. Build complexity — does it cross-compile cleanly on all three target platforms? Are system dependencies (FFmpeg libs, GStreamer plugins) manageable in CI?
4. Crate maturity — update frequency, known unsoundness issues, community size
5. Redistribution/licensing risk (gstreamer-rs only) — do the codec paths needed (H.264/HEVC decode via VideoToolbox/NVDEC) require any GStreamer plugin that bundles proprietary or non-permissively-licensed codec code? Document any constraint that would affect distributing the compiled app.

Spike scope

Write the minimum Rust code needed to answer the criteria above — not a working compositor, just enough to test the decision surface:

• Decode a frame at an arbitrary timestamp from a real .mp4 file using each candidate
• Verify the decoded frame is pixel-accurate (compare against a known reference frame extracted with ffprobe/ffmpeg CLI)
• Confirm hardware codec path is active (VideoToolbox on Mac, NVENC on Windows) — not silently falling back to software
• Attempt a cross-platform build on Mac and Windows; document any friction
• For the GStreamer path, confirm which plugins/elements are required for the target codecs and whether any are proprietary/non-open-source

Considered and deferred

• Shelling out to the FFmpeg CLI instead of binding to it (e.g. via ffmpeg-sidecar) was raised repeatedly in the source discussion as a lower-risk alternative to fighting binding maturity issues. Deferred for this spike: the render engine's jump-cut compositing needs frame-accurate, in-process seek/decode that subprocess piping can't cleanly provide. Worth one line in FINDINGS.md noting this was considered, in case both binding candidates prove too fragile and this needs revisiting.

Output

A findings doc committed to the spike branch at spike/rust-decode-spike/FINDINGS.md containing:

• Which binding is recommended and why
• The test results for each evaluation criterion on each platform tested
• Any caveats or open questions for the Epic 1 implementation
• The chosen binding becomes the encoderProfile design decision that Epic 1 is built against

Acceptance criteria

• spike/rust-decode-spike/FINDINGS.md exists and addresses all five evaluation criteria
• Frame-accurate decode verified on at least one real .mp4 episode fixture on Mac
• Hardware codec path confirmed active (not software fallback) on at least one Mac target
• Windows/NVIDIA result documented — even if tested on one machine, not CI
• A clear recommendation is stated with rationale; no open decision left for Epic 1 to inherit

Related

• RFC 0001 §Open Questions — FFmpeg vs gstreamer-rs listed explicitly
• Epic Map — pre-epic section; Epic 1 is blocked until this closes
• Epic 1 Feature F1.0 depends on the output of this spike
• r/rust: "State of ffmpeg bindings in Rust" — community input on binding maturity that informs the candidate list above

[natashaannn]

Updated the spike scope based on a r/rust discussion on the state of FFmpeg bindings in Rust:

• Swapped primary FFmpeg candidate from ffmpeg-next to ffmpeg-the-third. Multiple commenters describe ffmpeg-next as maintenance-only (upstream compat patches only, no real feature work), while ffmpeg-the-third is the actively-developed fork. ffmpeg-next and ac-ffmpeg remain documented fallbacks if ffmpeg-the-third underperforms.
• Added a 5th evaluation criterion: redistribution/licensing risk for GStreamer plugins. The thread flagged that some GStreamer codec plugins bundle proprietary/non-open-source code — a real distribution concern given we ship a compiled app, and something the original 4 criteria didn't cover.
• Added a "Considered and deferred" section documenting the CLI-subprocess approach (e.g. ffmpeg-sidecar), which several commenters preferred over fighting binding maturity issues. Deferred here because jump-cut compositing needs in-process frame-accurate seek/decode, but recorded in case both binding candidates prove too fragile.
• One counter-signal worth noting: at least one commenter called ffmpeg-next "perfectly fine, always follows latest ffmpeg releases" — the maintenance-mode framing isn't unanimous, hence keeping it as a documented fallback rather than dropping it entirely.

Also notable from the thread (context, not scope changes): repeated real-world endorsement of gstreamer-rs for production media apps, especially for live/graph-shaped pipelines — relevant since one commenter's team switched away from FFmpeg bindings in prod specifically due to unmaintained-crate pain.

[natashaannn]

Path correction: switched spikes/rust-decode-spike/ → spike/rust-decode-spike/ (singular) to match the established convention from the audio-sync spike (#93–#99) — standalone Cargo.toml per spike under spike/, no root-level workspace. Beginning implementation on branch spike/issue-108-decode-binding.