OrcaSlicer/docs/superpowers/specs/2026-08-14-ffmpeg-player-macos-design.md

FFmpeg Media Player for macOS — Design

Date: 2026-08-14 Branch: dev/ffmpeg-player-macos

Problem

The branch's new FFmpeg-based media player (wxMediaCtrl3 + AVVideoDecoder) is used on Windows and Linux, but macOS still runs the old player: wxMediaCtrl2.mm, an ObjC BambuPlayer class dlsym'd from the Bambu network plugin that renders via CALayer. On macOS, wxMediaCtrl3 is currently aliased to wxMediaCtrl2 and FFmpeg is not linked into the app at all.

Goal: make macOS use the same FFmpeg player as Windows/Linux, linking the static FFmpeg libraries from the deps build instead of dynamic ones.

Current state (verified)

• New player (Win/Linux): GUI/wxMediaCtrl3.cpp + GUI/AVVideoDecoder.cpp. Decodes with FFmpeg (libavcodec/libswscale/libavutil), renders frames into wxImage (non-Windows) / wxBitmap (Windows) drawn in a paintEvent, feeds via the Bambu_* C API (BambuTunnel.h, BAMBU_DYNAMIC) dlsym'd from the network plugin through StaticBambuLib::get() (GUI/Printer/PrinterFileSystem.cpp, compiled on all platforms).
• Old player (macOS): GUI/wxMediaCtrl2.mm uses the ObjC BambuPlayer class found via dlsym(module, "OBJC_CLASS_$_BambuPlayer") in libBambuSource.dylib.
• The macOS network plugin libBambuSource.dylib already exports the full Bambu C API (verified with nm), so the new player needs zero plugin changes.
• FFmpeg linking in src/slic3r/CMakeLists.txt is guarded by if (NOT APPLE) — macOS currently does not link FFmpeg.
• deps/FFMPEG/FFMPEG.cmake: non-MSVC branch builds FFmpeg from source with --enable-shared. The existing arm64 deps build on the dev machine happened to be configured with both static and shared enabled, so libavcodec.a / libswscale.a / libavutil.a are already present at deps/build/arm64/OrcaSlicer_dep/usr/local/lib/.
• EVT_MEDIA_CTRL_STAT is wxDEFINE_EVENT'd in wxMediaCtrl2.cpp (Win/Linux) and wxMediaCtrl2.mm (macOS); the define in wxMediaCtrl3.cpp is commented out.
• wxMediaCtrl2 is never instantiated anywhere on any platform — dead code.
• StatusPanel already creates wxMediaCtrl3; MediaPlayCtrl only uses the wxMediaCtrl3 interface (Load/Play/Stop/GetState/GetVideoSize/GetLastError/SetIdleImage), so no UI-side changes are needed.

Approach (approved)

Reuse the shared player on macOS. Compile the existing wxMediaCtrl3.cpp + AVVideoDecoder.cpp on macOS so all three platforms run one implementation. Rendering uses the existing wxImage → DrawBitmap paint path, identical to Linux. Known trade-off: frames are scaled to the widget's logical (1x) size, so Retina is slightly soft compared to the old CALayer player. Accepted for now; a Retina-aware scaling follow-up is possible later.

Rejected alternative: a native CGImage/CALayer renderer for macOS — faster and Retina-crisp, but adds a second render implementation to maintain.

Changes

1. Enable the FFmpeg player on macOS (source)

• GUI/wxMediaCtrl3.h: remove the #ifdef __WXMAC__ branch (lines 18–22) that aliases wxMediaCtrl3 → wxMediaCtrl2. macOS then compiles the real wxMediaCtrl3 class, including the BAMBU_DYNAMIC BambuTunnel path used on Linux.
• Event symbol fix: move wxDEFINE_EVENT(EVT_MEDIA_CTRL_STAT, wxCommandEvent) into wxMediaCtrl3.cpp (uncomment the existing line) and remove it from wxMediaCtrl2.cpp. One definition total in the lib; all three platforms resolve it.

2. Static FFmpeg linking (deps + app)

• deps/FFMPEG/FFMPEG.cmake: in the non-MSVC branch, pass --disable-shared --enable-static when APPLE. Linux keeps --enable-shared; Windows keeps its prebuilt shared DLL zips. Fresh macOS deps builds install only libavcodec.a / libswscale.a / libavutil.a — no dylibs to bundle, no rpath/install_name handling. (The existing local arm64 deps build already contains the .a files, so no deps rebuild is strictly needed to try the change locally, but a fresh CI deps build must produce them.)
• src/slic3r/CMakeLists.txt:
  • APPLE branch of SLIC3R_GUI_SOURCES: add GUI/wxMediaCtrl3.cpp, GUI/wxMediaCtrl3.h, GUI/AVVideoDecoder.cpp, GUI/AVVideoDecoder.hpp; remove GUI/wxMediaCtrl2.mm and GUI/wxMediaCtrl2.h (the .h stays on disk for the Win/Linux build of wxMediaCtrl2.cpp, but nothing on macOS includes it after this change).
  • Add an APPLE mirror of the NOT APPLE FFmpeg block: find_library for libavcodec.a, libswscale.a, libavutil.a under ${CMAKE_PREFIX_PATH}/lib with NO_DEFAULT_PATH, link them (order avcodec → swscale → avutil), and add ${CMAKE_PREFIX_PATH}/include as a SYSTEM include directory. Deps are built with --disable-zlib and no external codecs, so the three static libs link cleanly.

3. Remove the old player

• Delete GUI/wxMediaCtrl2.mm and GUI/BambuPlayer/BambuPlayer.h (header used only by the .mm; the real BambuPlayer lives inside the network plugin).
• Remove the now-dead __WXMAC__ section of GUI/wxMediaCtrl2.h.
• wxMediaCtrl2.cpp (Win/Linux) stays in the build as-is (dead but harmless; out of scope to remove on this branch).

4. Verification

• Build on macOS: cmake --build build_arm64 (or build/arm64).
• Confirm no dynamic FFmpeg dependency: otool -L on the app binary shows no libav* dylib references.
• Runtime: with the network plugin loaded, the Device tab camera preview streams via the FFmpeg player (check the device page / MediaPlayCtrl).
• macOS ctest still passes — static linking means no test-executable .so copying hacks (unlike the Linux shared-lib setup).

Out of scope

• Linux (shared libs, AppImage/flatpak bundling) and Windows (prebuilt DLL zips) keep their current FFmpeg setup.
• Retina-aware frame scaling / native CGImage rendering (follow-up if visual quality is judged insufficient).
• Audio streaming (neither player plays audio in this UI path).