Skip to content

Media Codecs

Jump to bottom
Ángel Guzmán Maeso edited this page Aug 3, 2026 · 1 revision

Media codecs (H.264 / MP4 video)

The problem

WhatsApp needs the proprietary H.264 / AAC codecs to process and send MP4 videos. Qt WebEngine only has those codecs when it is built with -webengine-proprietary-codecs (a compile-time flag). They are off by default in the official Qt binaries — including the ones from aqtinstall that the CI uses for the portable builds — because H.264/AAC are patent-encumbered (MPEG-LA / Via LA), which carries redistribution/licensing obligations.

Consequences:

  • The AppImage and the .deb/.rpm built in CI (aqt Qt) cannot send MP4 video. WhatsApp rejects it as "not supported". This also fails through WhatsApp's own + button, because it is the browser engine, not Whatly.
  • Photos work (no codec needed) and WebM/VP8/VP9 videos work (open codecs).
  • A source build against a system Qt that ships the codecs works fully. Many distros enable them (e.g. Arch's qt6-webengine; some Ubuntu builds too), which is why the AUR whatly (source) package can send MP4.

Whatly detects this at runtime (video.canPlayType('video/mp4; …')) and shows a one-time notice when H.264 is missing, so a failed MP4 attach is explained.

Why there is no downloadable codec plugin. Qt WebEngine links FFmpeg statically into libQt6WebEngineCore; unlike Electron/Chromium it has no loadable libffmpeg.so hook. A separate codec pack cannot be dropped in — the codecs must be present in the engine at build time.

Checking whether an engine has the codecs

Run the app and, in a JS console (or a quick page), evaluate:

document.createElement('video').canPlayType('video/mp4; codecs="avc1.42E01E"')

"probably"/"maybe" = H.264 present; "" = missing (MP4 will be rejected).

Enabling the codecs on your own machine

Project stance. Whatly's official releases deliberately do not ship the H.264/AAC codecs, to keep the maintainer clear of the MPEG-LA patent licensing that redistributing them would involve (see Licensing note below). The steps here are for building/enabling the codecs on your own machine for your own use, where that licensing situation does not apply the same way. If you rebuild and then redistribute the result, the licensing responsibility becomes yours.

Option A — package against a system Qt that has the codecs (recommended, light)

If your distro's Qt WebEngine already ships the codecs (verify with the snippet above against the system Qt), you do not need to rebuild Qt at all: build Whatly against the system Qt and bundle that Qt into the AppImage/.deb, instead of the codec-less aqt Qt the CI uses.

  1. Install the system Qt 6.10+ WebEngine dev packages for your distro and confirm they include the codecs (canPlayType returns "probably").

  2. Build against the system Qt (no -DCMAKE_PREFIX_PATH pointing at an aqt Qt):

    cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build --parallel
DESTDIR="$PWD/AppDir" cmake --install build

  3. Bundle the system Qt with linuxdeploy (point QMAKE at the system qmake), as the release-artifacts.yml workflow does but with the system Qt, then build the AppImage / repack the .deb. The bundled libQt6WebEngineCore then carries the codecs.

This is only a few GB and minutes. The trade-off is the licensing note below: you are now redistributing H.264/AAC if you share the result.

Option B — build Qt WebEngine from source with the codecs (heavy, full control)

Only if no suitable system Qt is available. This is a Chromium-scale build: roughly 80–120 GB of disk, lots of RAM, and hours of CPU — not feasible on GitHub-hosted runners, and it needs plenty of free space locally too.

# Match your Qt version exactly (e.g. 6.10.3).
git clone --depth 1 --branch v6.10.3 https://github.com/qt/qtwebengine.git
cmake -S qtwebengine -B qtwebengine-build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="$QT_ROOT_DIR" \
  -DCMAKE_INSTALL_PREFIX="$QT_ROOT_DIR" \
  -DQT_FEATURE_webengine_proprietary_codecs=ON
cmake --build qtwebengine-build --parallel
cmake --install qtwebengine-build

Then bundle that Qt WebEngine as in Option A.

Licensing note

H.264 and AAC are covered by patents (MPEG-LA / Via LA pools). This is why the official Qt binaries and most distributions ship without them, and why Whatly's CI portable builds do too — and why the project does not distribute codec-enabled binaries: as the distributor, the maintainer would take on the licensing obligations. Building or enabling the codecs for your own use is a different matter; redistributing a codec-enabled binary makes those obligations yours. Whatly ships WebM/VP9 support (royalty-free) out of the box and leaves MP4 to a codec-enabled system Qt.

This document is engineering guidance, not legal advice; consult the actual licence terms (or a lawyer) before redistributing.

Clone this wiki locally