worldmonitor/docs/internal/youtube-desktop.md

YouTube Autoplay on Tauri Desktop (WKWebView) — Cannot Work

Status: Confirmed impossible. All JS/CSS approaches exhausted. Date: February 2026 Affects: Live News panel, Live Webcams panel (macOS desktop app) Root cause: WKWebView blocks programmatic media playback in cross-origin iframes without a direct user gesture.

---

Architecture

tauri://localhost (main webview)
  └── http://localhost:PORT (sidecar youtube-embed handler)
        └── https://www.youtube.com/embed/VIDEO_ID (YouTube IFrame Player)

Three nested origins. The YouTube player sits inside a sidecar-served HTML page, which sits inside the Tauri WKWebView. The user gesture context is lost crossing each origin boundary.

---

What Was Tested (All Failed)

1. allow="autoplay" iframe attribute

What: Set allow="autoplay; encrypted-media" on the sidecar's <iframe> embedding YouTube. Why it fails: WKWebView does not honor the allow attribute for media autoplay policy. This attribute works in Chromium-based browsers but is ignored by WebKit's media policy engine.

2. MutationObserver to patch iframe attributes

What: Used a MutationObserver in the sidecar embed HTML to watch for YT.Player's dynamically-created <iframe> and force allow="autoplay" onto it at creation time. Result: The attribute was successfully added (confirmed via console logs), but WKWebView's autoplay policy operates at a layer below HTML attributes — it checks the media element's playback context, not iframe permissions.

3. Mute-first retry chain

What: After onReady, immediately call player.mute() + player.playVideo(), then retry at 500ms and 1500ms intervals. Why it fails: In Chromium, muted autoplay is always allowed. In WKWebView, even muted playback requires a user gesture in cross-origin iframe contexts. playVideo() silently does nothing — no error thrown, no state change.

4. Permissions-Policy: autoplay=* response header

What: Added Permissions-Policy: autoplay=*, encrypted-media=* to the sidecar's HTTP response for the embed page. Why it fails: Permissions-Policy is a Chromium feature. WebKit/WKWebView does not implement this header for media autoplay decisions.

5. Secure context via http://localhost (vs http://127.0.0.1)

What: Per W3C spec, http://localhost is a secure context while http://127.0.0.1 is not. Changed all sidecar URLs from 127.0.0.1 to localhost hoping secure context would unlock autoplay. Result: No effect. WKWebView's autoplay restriction is orthogonal to secure context status. The policy is about user gesture propagation, not HTTPS/secure origin.

6. YouTube playerVars configuration

What: Set all relevant playerVars: autoplay: 1, mute: 1, playsinline: 1, enablejsapi: 1, plus origin and widget_referrer matching the sidecar origin. Result: YouTube's player respects these in Chromium. In WKWebView, the underlying <video> element's play() call is what gets blocked — playerVars just configure what YouTube attempts to do, not what WKWebView allows.

7. player.playVideo() from various timing contexts

What: Called playVideo() from:

• onReady callback (immediate)
• setTimeout at 500ms, 1500ms, 2000ms
• After player.mute() Why it fails: None of these run in a user gesture context. JavaScript's event loop loses gesture propagation after any async boundary (setTimeout, Promise.then, await). The onReady callback itself is fired asynchronously by YouTube's API.

8. Iframe reload fallback

What: After 2 seconds, if autoplay hasn't started (no YT.PlayerState.PLAYING or BUFFERING event), destroy and recreate the iframe. Result: The fresh iframe loads but still cannot autoplay — same policy applies. Reloading doesn't create a user gesture.

9. wry/WKWebView configuration check

What: Verified that wry 0.54.2 (Tauri's WebKit wrapper) sets mediaTypesRequiringUserActionForPlayback = [] (equivalent to .none), meaning autoplay should be allowed at the WKWebView level. Result: This setting works for same-origin content. It does NOT override the cross-origin iframe media policy. The YouTube embed is cross-origin (youtube.com vs localhost), so the WKWebView-level permission is insufficient.

10. Play overlay with click handler

What: Added a full-screen overlay div inside the sidecar embed. On click, called player.playVideo() + player.unMute(). Result: This DOES work — the click is a genuine user gesture. However, it requires the user to click inside the sidecar iframe first, and the gesture doesn't propagate to the cross-origin YouTube iframe underneath. The overlay approach only works if the overlay itself triggers playVideo() via the JS API (which does work from a user gesture).

---

Why It's a Platform Limitation

WKWebView's media autoplay policy:

1. Same-origin content: Respects mediaTypesRequiringUserActionForPlayback setting. If set to .none, autoplay works.
2. Cross-origin iframes: Requires a user gesture that originates within the iframe's own browsing context. A gesture in the parent frame does NOT propagate. This is a WebKit security decision, not a bug.
3. Gesture propagation: JavaScript loses user gesture context after any async operation (await, setTimeout, Promise). Even onReady is async.

There is an open Tauri issue (#13200) requesting exposure of mediaTypesRequiringUserActionForPlayback per-webview, but even with it exposed, it wouldn't help for cross-origin iframes.

The only way autoplay would work is if YouTube's embed was served from the same origin as the WKWebView — which would mean serving it from tauri://localhost, which is impossible since YouTube's player must load from youtube.com.

---

What Works Instead

Click-to-play (current solution)

• Grid view iframes have pointer-events: auto — user clicks YouTube's native play button directly
• Sidecar overlay starts hidden and non-interactive (pointer-events: none)
• Each grid cell has an expand button (arrow icon) to switch to single/fullscreen view
• YouTube's own play button UI handles the user gesture natively

Why Vercel-hosted embeds worked before

The previous architecture served embeds from https://worldmonitor.app/api/youtube/embed. The parent was also https://worldmonitor.app. Same origin = WKWebView's autoplay policy respected the .none setting. When we moved embeds to the local sidecar (http://localhost:PORT), the parent became tauri://localhost — now cross-origin, breaking autoplay.

Trade-off: Reverting to Vercel-hosted embeds would restore autoplay but adds a cloud dependency for the desktop app (defeats offline/local-first goals) and adds latency.

---

Files Changed

File	Change
src-tauri/sidecar/local-api-server.mjs	MutationObserver, retry chain, overlay fixes, postMessage('*'), Permissions-Policy header
src/styles/main.css	.webcam-iframe { pointer-events: auto } (was none), expand button styles
src/components/LiveWebcamsPanel.ts	Expand button in grid cells, localhost embed URLs
src/components/LiveNewsPanel.ts	localhost embed URLs, embedOrigin getter
index.html	CSP frame-src added http://localhost:*
src-tauri/tauri.conf.json	CSP frame-src added http://localhost:*

---

Future Options (Not Pursued)

1. Tauri custom protocol for YouTube proxy: Serve YouTube embed HTML from tauri:// scheme to make it same-origin. Would require proxying YouTube's iframe API JS — legally and technically complex.
2. Native AVPlayer: Use a native macOS media player instead of WKWebView for video. Would lose YouTube's player UI/controls.
3. Electron migration: Electron uses Chromium where muted autoplay always works. Not viable — Tauri chosen deliberately.
4. Revert to Vercel embeds on desktop: Adds cloud dependency but restores autoplay. Could be a user-toggleable setting.