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: ` or `` element tries to load a media file from your bundled assets, GStreamer cannot resolve the `wails://` URL.
+
+This is a [known upstream WebKit issue](https://bugs.webkit.org/show_bug.cgi?id=146351) that has been open since 2015.
+
+### Symptoms
+
+Without the workaround, you might experience:
+- Video elements showing a black screen or failing to load
+- Audio elements remaining silent
+- Browser console errors about failed media requests
+- Media elements stuck in a "loading" state
+
+## Automatic Workaround
+
+Wails automatically works around this limitation by injecting JavaScript that intercepts media elements and converts their sources to blob URLs. This happens transparently - you don't need to modify your frontend code.
+
+### How It Works
+
+1. When your application loads, Wails injects platform-specific JavaScript
+2. This JavaScript monitors the DOM for `` and `` elements
+3. When a media element is found with a relative or `wails://` URL, the script:
+ - Fetches the media file using the standard `fetch()` API (which works with the Wails asset server)
+ - Creates a blob URL from the response
+ - Replaces the element's `src` with the blob URL
+4. GStreamer can then play the blob URL normally
+
+### What Gets Intercepted
+
+The workaround intercepts:
+- `` elements with `src` attributes
+- `` elements with `src` attributes
+- `` elements inside `` and `` elements
+- Elements added dynamically via JavaScript
+- Elements with `src` set via JavaScript after page load
+
+## Configuration Options
+
+You can configure the GStreamer workaround behavior using `LinuxOptions`:
+
+```go
+app := application.New(application.Options{
+ Name: "My App",
+ Linux: application.LinuxOptions{
+ // Disable the GStreamer workaround entirely
+ DisableGStreamerFix: false,
+
+ // Enable caching of blob URLs for better performance
+ EnableGStreamerCaching: true,
+ },
+})
+```
+
+### DisableGStreamerFix
+
+Set to `true` to disable the automatic media interception. You might want to do this if:
+- You're only using external media URLs (http/https)
+- You're implementing your own media handling solution
+- You're debugging media-related issues
+
+```go
+Linux: application.LinuxOptions{
+ DisableGStreamerFix: true,
+},
+```
+
+### EnableGStreamerCaching
+
+When enabled, blob URLs are cached so that the same media file doesn't need to be fetched and converted multiple times. This improves performance when:
+- The same media is played repeatedly
+- Multiple elements reference the same media file
+- Media elements are recreated (e.g., in a SPA with component remounting)
+
+```go
+Linux: application.LinuxOptions{
+ EnableGStreamerCaching: true,
+},
+```
+
+:::note[Memory Considerations]
+Enabling caching keeps blob URLs in memory for the lifetime of the page. For applications with many large media files, consider whether the memory trade-off is worthwhile for your use case.
+:::
+
+## Working with Media Files
+
+### Bundled Assets
+
+Place media files in your frontend's public or assets directory:
+
+```
+frontend/
+ public/
+ video.mp4
+ audio.ogg
+ src/
+ main.js
+```
+
+Reference them with relative URLs:
+
+```html
+
+
+
+
+
+
+
+```
+
+### Supported Formats
+
+The supported media formats depend on your GStreamer installation. Common formats include:
+- Video: MP4 (H.264), WebM (VP8/VP9), OGG (Theora)
+- Audio: MP3, OGG (Vorbis), WAV, FLAC
+
+To check available codecs on your system:
+
+```bash
+gst-inspect-1.0 --version
+gst-inspect-1.0 | grep -i decoder
+```
+
+### Installing Codecs
+
+On Ubuntu/Debian:
+```bash
+sudo apt install gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly
+```
+
+On Fedora:
+```bash
+sudo dnf install gstreamer1-plugins-good gstreamer1-plugins-bad-free gstreamer1-plugins-ugly-free
+```
+
+On Arch Linux:
+```bash
+sudo pacman -S gst-plugins-good gst-plugins-bad gst-plugins-ugly
+```
+
+## Example Application
+
+See the [audio-video example](https://github.com/wailsapp/wails/tree/v3-alpha/v3/examples/audio-video) for a complete working example that demonstrates:
+- Video playback with bundled MP4 files
+- Audio playback with bundled MP3 files
+- Using the `@wailsio/runtime` npm module
+- Proper project structure for media assets
+
+## Troubleshooting
+
+### Media Not Playing
+
+1. **Check GStreamer installation**: Ensure GStreamer and required plugins are installed
+2. **Check the console**: Look for JavaScript errors or failed network requests
+3. **Verify file paths**: Ensure media files are in the correct location and accessible
+4. **Check codec support**: Verify GStreamer has the necessary decoder for your media format
+
+### Performance Issues
+
+If media playback is sluggish:
+1. Enable caching with `EnableGStreamerCaching: true`
+2. Consider using more efficient codecs (e.g., H.264 instead of VP9)
+3. Reduce media file sizes through compression
+
+### Debugging
+
+To see what the media interceptor is doing, check the browser console. The interceptor logs its actions when media sources are converted.
+
+You can also temporarily disable the fix to compare behavior:
+
+```go
+Linux: application.LinuxOptions{
+ DisableGStreamerFix: true,
+},
+```
diff --git a/docs/src/content/docs/quick-start/installation.mdx b/docs/src/content/docs/quick-start/installation.mdx
index 20bdc51ba..dbfa3df5e 100644
--- a/docs/src/content/docs/quick-start/installation.mdx
+++ b/docs/src/content/docs/quick-start/installation.mdx
@@ -144,18 +144,33 @@ If `wails3 doctor` passes, you're done. [Skip to First App →](/quick-start/fir
sudo apt update
sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.0-dev
```
+
+ **For audio/video playback** (optional but recommended):
+ ```bash
+ sudo apt install gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly
+ ```
```bash
sudo dnf install gcc pkg-config gtk3-devel webkit2gtk4.0-devel
```
+
+ **For audio/video playback** (optional but recommended):
+ ```bash
+ sudo dnf install gstreamer1-plugins-good gstreamer1-plugins-bad-free gstreamer1-plugins-ugly-free
+ ```
```bash
sudo pacman -S base-devel gtk3 webkit2gtk
```
+
+ **For audio/video playback** (optional but recommended):
+ ```bash
+ sudo pacman -S gst-plugins-good gst-plugins-bad gst-plugins-ugly
+ ```
diff --git a/v3/UNRELEASED_CHANGELOG.md b/v3/UNRELEASED_CHANGELOG.md
index 8e4648038..29c625c27 100644
--- a/v3/UNRELEASED_CHANGELOG.md
+++ b/v3/UNRELEASED_CHANGELOG.md
@@ -16,12 +16,15 @@ After processing, the content will be moved to the main changelog and this file
-->
## Added
+- Add `DisableGStreamerFix` and `EnableGStreamerCaching` options to `LinuxOptions` for controlling media playback workaround (#4412) by @leaanthony
+- Add `audio-video` example demonstrating HTML5 media playback with the `@wailsio/runtime` npm module by @leaanthony
## Changed
## Fixed
+- Fix video and audio playback on Linux/WebKitGTK by intercepting media elements and converting wails:// URLs to blob URLs (#4412) by @leaanthony
## Deprecated
diff --git a/v3/examples/audio-video/README.md b/v3/examples/audio-video/README.md
new file mode 100644
index 000000000..ceadb6446
--- /dev/null
+++ b/v3/examples/audio-video/README.md
@@ -0,0 +1,38 @@
+# Audio/Video Example
+
+This example demonstrates HTML5 audio and video playback using the `@wailsio/runtime` npm module.
+
+## Linux Notes
+
+On Linux, WebKitGTK uses GStreamer for media playback. GStreamer doesn't have a URI handler for the `wails://` protocol, which means media files served from the bundled assets won't play directly.
+
+Wails automatically works around this limitation by intercepting media elements and converting their sources to blob URLs. This happens transparently - you don't need to change your code.
+
+See the [Linux-specific documentation](https://wails.io/docs/guides/linux-media) for details on:
+- How the GStreamer workaround works
+- How to disable it if needed (`DisableGStreamerFix`)
+- How to enable caching for better performance (`EnableGStreamerCaching`)
+
+## Building
+
+```bash
+cd frontend
+npm install
+npm run build
+cd ..
+go build
+./audio-video
+```
+
+## Development
+
+For development with hot-reload:
+
+```bash
+# Terminal 1: Run Vite dev server
+cd frontend
+npm run dev
+
+# Terminal 2: Run Go app with dev server URL
+FRONTEND_DEVSERVER_URL=http://localhost:5173 go run .
+```
diff --git a/v3/examples/audio-video/frontend/dist/assets/index-DxRb0nj9.js b/v3/examples/audio-video/frontend/dist/assets/index-DxRb0nj9.js
new file mode 100644
index 000000000..daa86c9a0
--- /dev/null
+++ b/v3/examples/audio-video/frontend/dist/assets/index-DxRb0nj9.js
@@ -0,0 +1,6 @@
+(function(){const t=document.createElement("link").relList;if(t&&t.supports&&t.supports("modulepreload"))return;for(const s of document.querySelectorAll('link[rel="modulepreload"]'))i(s);new MutationObserver(s=>{for(const r of s)if(r.type==="childList")for(const a of r.addedNodes)a.tagName==="LINK"&&a.rel==="modulepreload"&&i(a)}).observe(document,{childList:!0,subtree:!0});function n(s){const r={};return s.integrity&&(r.integrity=s.integrity),s.referrerPolicy&&(r.referrerPolicy=s.referrerPolicy),s.crossOrigin==="use-credentials"?r.credentials="include":s.crossOrigin==="anonymous"?r.credentials="omit":r.credentials="same-origin",r}function i(s){if(s.ep)return;s.ep=!0;const r=n(s);fetch(s.href,r)}})();const G="useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";function X(e=21){let t="",n=e|0;for(;n--;)t+=G[Math.random()*64|0];return t}const Y=window.location.origin+"/wails/runtime",H=Object.freeze({Call:0,Clipboard:1,Application:2,Events:3,ContextMenu:4,Dialog:5,Window:6,Screens:7,System:8,Browser:9,CancelCall:10,IOS:11});let V=X();function B(e,t=""){return function(n,i=null){return $(e,n,t,i)}}async function $(e,t,n,i){var s,r;let a=new URL(Y),f={object:e,method:t};i!=null&&(f.args=i);let d={"x-wails-client-id":V,"Content-Type":"application/json"};n&&(d["x-wails-window-name"]=n);let c=await fetch(a,{method:"POST",headers:d,body:JSON.stringify(f)});if(!c.ok)throw new Error(await c.text());return((r=(s=c.headers.get("Content-Type"))===null||s===void 0?void 0:s.indexOf("application/json"))!==null&&r!==void 0?r:-1)!==-1?c.json():c.text()}B(H.System);const x=function(){var e,t,n,i,s,r;try{if(!((t=(e=window.chrome)===null||e===void 0?void 0:e.webview)===null||t===void 0)&&t.postMessage)return window.chrome.webview.postMessage.bind(window.chrome.webview);if(!((s=(i=(n=window.webkit)===null||n===void 0?void 0:n.messageHandlers)===null||i===void 0?void 0:i.external)===null||s===void 0)&&s.postMessage)return window.webkit.messageHandlers.external.postMessage.bind(window.webkit.messageHandlers.external);if(!((r=window.wails)===null||r===void 0)&&r.invoke)return a=>window.wails.invoke(typeof a=="string"?a:JSON.stringify(a))}catch{}return console.warn(`
+%c⚠️ Browser Environment Detected %c
+
+%cOnly UI previews are available in the browser. For full functionality, please run the application in desktop mode.
+More information at: https://v3.wails.io/learn/build/#using-a-browser-for-development
+`,"background: #ffffff; color: #000000; font-weight: bold; padding: 4px 8px; border-radius: 4px; border: 2px solid #000000;","background: transparent;","color: #ffffff; font-style: italic; font-weight: bold;"),null}();function S(e){x==null||x(e)}function A(){var e,t;return((t=(e=window._wails)===null||e===void 0?void 0:e.environment)===null||t===void 0?void 0:t.OS)==="windows"}function J(){var e,t;return!!(!((t=(e=window._wails)===null||e===void 0?void 0:e.environment)===null||t===void 0)&&t.Debug)}function q(){return new MouseEvent("mousedown").buttons===0}function U(e){var t;return e.target instanceof HTMLElement?e.target:!(e.target instanceof HTMLElement)&&e.target instanceof Node&&(t=e.target.parentElement)!==null&&t!==void 0?t:document.body}document.addEventListener("DOMContentLoaded",()=>{});window.addEventListener("contextmenu",te);const K=B(H.ContextMenu),Q=0;function ee(e,t,n,i){K(Q,{id:e,x:t,y:n,data:i})}function te(e){const t=U(e),n=window.getComputedStyle(t).getPropertyValue("--custom-contextmenu").trim();if(n){e.preventDefault();const i=window.getComputedStyle(t).getPropertyValue("--custom-contextmenu-data");ee(n,e.clientX,e.clientY,i)}else ne(e,t)}function ne(e,t){if(J())return;switch(window.getComputedStyle(t).getPropertyValue("--default-contextmenu").trim()){case"show":return;case"hide":e.preventDefault();return}if(t.isContentEditable)return;const n=window.getSelection(),i=n&&n.toString().length>0;if(i)for(let s=0;s{P=e,P||(M=b=!1,u())};let I=!1;function oe(){var e,t;const n=(t=(e=window._wails)===null||e===void 0?void 0:e.environment)===null||t===void 0?void 0:t.OS;if(n==="ios"||n==="android")return!0;const i=navigator.userAgent||navigator.vendor||window.opera||"";return/android|iphone|ipad|ipod|iemobile|wpdesktop/i.test(i)}function N(){if(!I&&!oe()){window.addEventListener("mousedown",O,{capture:!0}),window.addEventListener("mousemove",O,{capture:!0}),window.addEventListener("mouseup",O,{capture:!0});for(const e of["click","contextmenu","dblclick"])window.addEventListener(e,ie,{capture:!0});I=!0}}N();document.addEventListener("DOMContentLoaded",N,{once:!0});let se=0;const W=window.setInterval(()=>{if(I){window.clearInterval(W);return}N(),++se>100&&window.clearInterval(W)},50);function ie(e){(y||b)&&(e.stopImmediatePropagation(),e.stopPropagation(),e.preventDefault())}const D=0,re=1,F=2;function O(e){let t,n=e.buttons;switch(e.type){case"mousedown":t=D,L||(n=p|1<{if(n.preventDefault(),n.dataTransfer&&n.dataTransfer.types.includes("Files")){t++;const i=document.elementFromPoint(n.clientX,n.clientY),s=j(i);l&&l!==s&&l.classList.remove(g),s?(s.classList.add(g),n.dataTransfer.dropEffect="copy",l=s):(n.dataTransfer.dropEffect="none",l=null)}},!1),e.addEventListener("dragover",n=>{n.preventDefault(),n.dataTransfer&&n.dataTransfer.types.includes("Files")&&(l?(l.classList.contains(g)||l.classList.add(g),n.dataTransfer.dropEffect="copy"):n.dataTransfer.dropEffect="none")},!1),e.addEventListener("dragleave",n=>{n.preventDefault(),n.dataTransfer&&n.dataTransfer.types.includes("Files")&&(t--,(t===0||n.relatedTarget===null||l&&!l.contains(n.relatedTarget))&&(l&&(l.classList.remove(g),l=null),t=0))},!1),e.addEventListener("drop",n=>{n.preventDefault(),t=0,l&&(l.classList.remove(g),l=null)},!1)}typeof window<"u"&&typeof document<"u"&&dt();window._wails=window._wails||{};window._wails.invoke=S;window._wails.handlePlatformFileDrop=Z.HandlePlatformFileDrop.bind(Z);fetch("/wails/platform.js").then(e=>e.text()).then(e=>{if(e&&e.trim().length>0){const t=document.createElement("script");t.textContent=e,document.head.appendChild(t)}}).catch(e=>{console.debug("[Wails] No platform-specific code to load:",e)}).finally(()=>{S("wails:runtime:ready")});const R=document.getElementById("video"),m=document.getElementById("video-status");R.addEventListener("loadeddata",()=>{m.className="status success",m.textContent="Loaded ("+R.duration.toFixed(1)+"s)"});R.addEventListener("error",()=>{m.className="status error",m.textContent="Failed to load"});const _=document.getElementById("audio"),w=document.getElementById("audio-status");_.addEventListener("loadeddata",()=>{w.className="status success",w.textContent="Loaded ("+_.duration.toFixed(1)+"s)"});_.addEventListener("error",()=>{w.className="status error",w.textContent="Failed to load"});setTimeout(()=>{m.classList.contains("pending")&&(m.className="status error",m.textContent="Timeout"),w.classList.contains("pending")&&(w.className="status error",w.textContent="Timeout")},5e3);
diff --git a/v3/examples/audio-video/frontend/dist/index.html b/v3/examples/audio-video/frontend/dist/index.html
new file mode 100644
index 000000000..9cddde2a8
--- /dev/null
+++ b/v3/examples/audio-video/frontend/dist/index.html
@@ -0,0 +1,61 @@
+
+
+
+ Audio/Video Example
+
+
+
+
+
+
Audio/Video Example
+
+
+
Video
+
+
+
+
Loading...
+
+
+
+
Audio
+
+
+
+
Loading...
+
+
Audio/Video Example
+
+
+
+
+
Audio/Video Example
+
+
+
Video
+
+
+
+
Loading...
+
+
+
+
Audio
+
+
+
+
Loading...
+
+