From cb377cc29f3f0f9fecc242e191da63f73b7cfd6b Mon Sep 17 00:00:00 2001 From: Lea Anthony Date: Sat, 13 Dec 2025 22:00:27 +1100 Subject: [PATCH] fix(linux): fix video and audio playback on WebKitGTK (#4412) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit On Linux, WebKitGTK uses GStreamer for media playback. GStreamer doesn't have a URI handler for the wails:// protocol, causing video and audio elements to fail loading from bundled assets. This fix automatically intercepts media elements and converts wails:// URLs to blob URLs by fetching content through fetch() (which works via WebKit's URI scheme handler) and creating object URLs. Changes: - Add platform-specific JS injection via /wails/platform.js endpoint - Move /wails/* route handling from BundledAssetServer to main AssetServer so it works regardless of user's asset handler choice - Add DisableGStreamerFix and EnableGStreamerCaching options to LinuxOptions - Update runtime to fetch /wails/platform.js before emitting ready event - Add audio-video example demonstrating media playback with npm runtime - Add Linux media playback documentation - Add GStreamer codec dependencies to installation docs See: https://bugs.webkit.org/show_bug.cgi?id=146351 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/src/content/docs/guides/linux-media.mdx | 189 ++++ .../content/docs/quick-start/installation.mdx | 15 + v3/UNRELEASED_CHANGELOG.md | 3 + v3/examples/audio-video/README.md | 38 + .../frontend/dist/assets/index-DxRb0nj9.js | 6 + .../audio-video/frontend/dist/index.html | 61 ++ .../audio-video/frontend/dist/wails.mp3 | Bin 0 -> 81020 bytes .../audio-video/frontend/dist/wails.mp4 | Bin 0 -> 999162 bytes v3/examples/audio-video/frontend/index.html | 61 ++ .../audio-video/frontend/package-lock.json | 965 ++++++++++++++++++ v3/examples/audio-video/frontend/package.json | 16 + .../audio-video/frontend/public/wails.mp3 | Bin 0 -> 81020 bytes .../audio-video/frontend/public/wails.mp4 | Bin 0 -> 999162 bytes v3/examples/audio-video/frontend/src/main.js | 40 + .../audio-video/frontend/vite.config.js | 8 + v3/examples/audio-video/main.go | 35 + v3/internal/assetserver/assetserver.go | 57 ++ .../assetserver/assetserver_android.go | 3 + v3/internal/assetserver/assetserver_darwin.go | 3 + v3/internal/assetserver/assetserver_ios.go | 3 + v3/internal/assetserver/assetserver_linux.go | 8 +- v3/internal/assetserver/assetserver_linux.js | 166 +++ .../assetserver/assetserver_windows.go | 5 + .../assetserver/bundled_assetserver.go | 13 - .../desktop/@wailsio/runtime/src/index.ts | 18 +- v3/pkg/application/application_linux.go | 7 + v3/pkg/application/application_options.go | 11 + 27 files changed, 1716 insertions(+), 15 deletions(-) create mode 100644 docs/src/content/docs/guides/linux-media.mdx create mode 100644 v3/examples/audio-video/README.md create mode 100644 v3/examples/audio-video/frontend/dist/assets/index-DxRb0nj9.js create mode 100644 v3/examples/audio-video/frontend/dist/index.html create mode 100644 v3/examples/audio-video/frontend/dist/wails.mp3 create mode 100644 v3/examples/audio-video/frontend/dist/wails.mp4 create mode 100644 v3/examples/audio-video/frontend/index.html create mode 100644 v3/examples/audio-video/frontend/package-lock.json create mode 100644 v3/examples/audio-video/frontend/package.json create mode 100644 v3/examples/audio-video/frontend/public/wails.mp3 create mode 100644 v3/examples/audio-video/frontend/public/wails.mp4 create mode 100644 v3/examples/audio-video/frontend/src/main.js create mode 100644 v3/examples/audio-video/frontend/vite.config.js create mode 100644 v3/examples/audio-video/main.go create mode 100644 v3/internal/assetserver/assetserver_linux.js diff --git a/docs/src/content/docs/guides/linux-media.mdx b/docs/src/content/docs/guides/linux-media.mdx new file mode 100644 index 000000000..5786c0b32 --- /dev/null +++ b/docs/src/content/docs/guides/linux-media.mdx @@ -0,0 +1,189 @@ +--- +title: Linux Media Playback +sidebar: + order: 12 +--- + +import {Badge} from '@astrojs/starlight/components'; + +Relevant Platforms: +
+ +On Linux, Wails applications use WebKitGTK for rendering web content. WebKitGTK delegates media playback (video and audio) to GStreamer, which handles the actual decoding and rendering of media files. + +## The GStreamer Protocol Issue + +GStreamer operates independently from WebKit's custom URI scheme handling. While Wails registers a `wails://` protocol handler with WebKit for serving your application's assets, GStreamer doesn't have access to this handler. This means when an HTML `