fix: implement AirPlay support via WebKit's native picker

sozercan · claude · sozercan · commit 7ee67090294a · 2026-01-23T21:20:56.000-08:00
Replace non-functional AVRoutePickerView with WebKit's native webkitShowPlaybackTargetPicker() which actually routes WebView audio. Changes: - Add showAirPlayPicker() to SingletonPlayerWebView+PlaybackControls - Add AirPlay state tracking via webkitcurrentplaybacktargetiswirelesschanged - Replace AVRoutePickerView with custom button in PlayerBar - Add AirPlay-related properties to PlayerService - Add ADR-0010 documenting the implementation and known limitations Known limitations (documented in ADR): - AirPlay disconnects on track change (WebKit limitation) - Picker appears top-left due to hidden video element Closes #42 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/Core/Services/Player/PlayerService.swift b/Core/Services/Player/PlayerService.swift
@@ -125,6 +125,12 @@ final class PlayerService: NSObject, PlayerServiceProtocol {
     /// the detection can be unreliable when video mode CSS is active.
     var showVideo: Bool = false
 
+    /// Whether AirPlay is currently connected (playing to a wireless target).
+    private(set) var isAirPlayConnected: Bool = false
+
+    /// Whether the user has requested AirPlay this session (for persistence across track changes).
+    private(set) var airPlayWasRequested: Bool = false
+
     // MARK: - Internal Properties (for extensions)
 
     let logger = DiagnosticsLogger.player
@@ -694,6 +700,20 @@ final class PlayerService: NSObject, PlayerServiceProtocol {
         self.duration = 0
     }
 
+    /// Show the AirPlay picker for selecting audio output devices.
+    func showAirPlayPicker() {
+        self.airPlayWasRequested = true
+        SingletonPlayerWebView.shared.showAirPlayPicker()
+    }
+
+    /// Updates the AirPlay connection status from the WebView.
+    func updateAirPlayStatus(isConnected: Bool, wasRequested: Bool = false) {
+        self.isAirPlayConnected = isConnected
+        if wasRequested {
+            self.airPlayWasRequested = true
+        }
+    }
+
     // MARK: - Private Methods
 
     /// Legacy method for evaluating player commands - now delegates to SingletonPlayerWebView.
diff --git a/Core/Utilities/AccessibilityIdentifiers.swift b/Core/Utilities/AccessibilityIdentifiers.swift
@@ -32,6 +32,7 @@ enum AccessibilityID {
         static let lyricsButton = "playerBar.lyrics"
         static let queueButton = "playerBar.queue"
         static let videoButton = "playerBar.video"
+        static let airplayButton = "playerBar.airplayButton"
         static let volumeSlider = "playerBar.volumeSlider"
         static let trackTitle = "playerBar.trackTitle"
         static let trackArtist = "playerBar.trackArtist"
diff --git a/Core/Utilities/DiagnosticsLogger.swift b/Core/Utilities/DiagnosticsLogger.swift
@@ -38,4 +38,7 @@ enum DiagnosticsLogger {
 
     /// Logger for AppleScript scripting events.
     static let scripting = Logger(subsystem: "com.sertacozercan.Kaset", category: "Scripting")
+
+    /// Logger for AirPlay-related events.
+    static let airplay = Logger(subsystem: "com.sertacozercan.Kaset", category: "AirPlay")
 }
diff --git a/Views/macOS/MiniPlayerWebView.swift b/Views/macOS/MiniPlayerWebView.swift
@@ -296,6 +296,8 @@ final class SingletonPlayerWebView {
     }
 
     /// Load a video, stopping any currently playing audio first.
+    /// Note: This uses full page navigation which destroys the video element.
+    /// AirPlay connections will be lost but the auto-reconnect picker will appear.
     func loadVideo(videoId: String) {
         guard let webView else {
             self.logger.error("loadVideo called but webView is nil")
@@ -341,10 +343,25 @@ final class SingletonPlayerWebView {
 
         func userContentController(_: WKUserContentController, didReceive message: WKScriptMessage) {
             guard let body = message.body as? [String: Any],
-                  let type = body["type"] as? String,
-                  type == "STATE_UPDATE"
+                  let type = body["type"] as? String
             else { return }
 
+            // Handle AirPlay status updates
+            if type == "AIRPLAY_STATUS" {
+                let isConnected = body["isConnected"] as? Bool ?? false
+                let wasRequested = body["wasRequested"] as? Bool ?? false
+
+                Task { @MainActor in
+                    self.playerService.updateAirPlayStatus(
+                        isConnected: isConnected,
+                        wasRequested: wasRequested
+                    )
+                }
+                return
+            }
+
+            guard type == "STATE_UPDATE" else { return }
+
             let isPlaying = body["isPlaying"] as? Bool ?? false
             let progress = body["progress"] as? Int ?? 0
             let duration = body["duration"] as? Int ?? 0
@@ -396,6 +413,7 @@ final class SingletonPlayerWebView {
                             "trackChanged to '\(title)' while video shown - closing video window")
                         self.playerService.showVideo = false
                     }
+
                 }
             }
         }
diff --git a/Views/macOS/PlayerBar.swift b/Views/macOS/PlayerBar.swift
@@ -1,4 +1,3 @@
-import AVKit
 import SwiftUI
 
 // MARK: - PlayerBar
@@ -382,8 +381,18 @@ struct PlayerBar: View {
             self.actionButtons
 
             // AirPlay button
-            AirPlayButton()
-                .frame(width: 20, height: 20)
+            Button {
+                HapticService.toggle()
+                self.playerService.showAirPlayPicker()
+            } label: {
+                Image(systemName: "airplayaudio")
+                    .font(.system(size: 15, weight: .medium))
+                    .foregroundStyle(.primary.opacity(0.85))
+            }
+            .buttonStyle(.pressable)
+            .accessibilityIdentifier(AccessibilityID.PlayerBar.airplayButton)
+            .accessibilityLabel("AirPlay")
+            .disabled(self.playerService.currentTrack == nil)
 
             Divider()
                 .frame(height: 20)
@@ -538,22 +547,6 @@ struct PlayerBar: View {
     }
 }
 
-// MARK: - AirPlayButton
-
-/// A SwiftUI wrapper for AVRoutePickerView to show AirPlay destinations.
-@available(macOS 26.0, *)
-struct AirPlayButton: NSViewRepresentable {
-    func makeNSView(context _: Context) -> AVRoutePickerView {
-        let routePickerView = AVRoutePickerView()
-        routePickerView.isRoutePickerButtonBordered = false
-        return routePickerView
-    }
-
-    func updateNSView(_: AVRoutePickerView, context _: Context) {
-        // No updates needed
-    }
-}
-
 @available(macOS 26.0, *)
 #Preview {
     PlayerBar()
diff --git a/Views/macOS/SingletonPlayerWebView+ObserverScript.swift b/Views/macOS/SingletonPlayerWebView+ObserverScript.swift
@@ -47,6 +47,40 @@ extension SingletonPlayerWebView {
                     video.addEventListener('waiting', () => sendUpdate()); // Buffer state
                     video.addEventListener('seeked', () => sendUpdate()); // Seek completed
 
+                    // AirPlay state tracking
+                    video.addEventListener('webkitcurrentplaybacktargetiswirelesschanged', () => {
+                        const isWireless = video.webkitCurrentPlaybackTargetIsWireless;
+                        const wasConnected = window.__kasetAirPlayConnected;
+                        window.__kasetAirPlayConnected = isWireless;
+
+                        bridge.postMessage({
+                            type: 'AIRPLAY_STATUS',
+                            isConnected: isWireless,
+                            wasConnected: wasConnected,
+                            wasRequested: window.__kasetAirPlayRequested || false
+                        });
+                    });
+
+                    // Check initial AirPlay state
+                    const initialWireless = video.webkitCurrentPlaybackTargetIsWireless;
+                    if (initialWireless) {
+                        window.__kasetAirPlayConnected = true;
+                        bridge.postMessage({
+                            type: 'AIRPLAY_STATUS',
+                            isConnected: true,
+                            wasConnected: false,
+                            wasRequested: window.__kasetAirPlayRequested || false
+                        });
+                    } else if (window.__kasetAirPlayRequested && window.__kasetAirPlayConnected) {
+                        window.__kasetAirPlayConnected = false;
+                        bridge.postMessage({
+                            type: 'AIRPLAY_STATUS',
+                            isConnected: false,
+                            wasConnected: true,
+                            wasRequested: true
+                        });
+                    }
+
                     // Volume enforcement: listen for external volume changes with debounce
                     // This catches YouTube's attempts to change volume and reverts to our target
                     video.addEventListener('volumechange', () => {
diff --git a/Views/macOS/SingletonPlayerWebView+PlaybackControls.swift b/Views/macOS/SingletonPlayerWebView+PlaybackControls.swift
@@ -152,4 +152,43 @@ extension SingletonPlayerWebView {
             }
         }
     }
+
+    /// Show the native AirPlay picker for the WebView's video element.
+    func showAirPlayPicker() {
+        guard let webView else { return }
+
+        let script = """
+            (function() {
+                const video = document.querySelector('video');
+                if (!video) return 'no-video';
+                if (typeof video.webkitShowPlaybackTargetPicker !== 'function') return 'unsupported';
+
+                window.__kasetAirPlayRequested = true;
+                video.webkitShowPlaybackTargetPicker();
+                return 'picker-shown';
+            })();
+        """
+        webView.evaluateJavaScript(script, completionHandler: nil)
+    }
+
+    /// Check if AirPlay is currently connected (playing to a wireless target).
+    func checkAirPlayStatus(completion: @escaping (Bool) -> Void) {
+        guard let webView else {
+            completion(false)
+            return
+        }
+
+        let script = """
+            (function() {
+                const video = document.querySelector('video');
+                if (video && video.webkitCurrentPlaybackTargetIsWireless) {
+                    return true;
+                }
+                return false;
+            })();
+        """
+        webView.evaluateJavaScript(script) { result, _ in
+            completion(result as? Bool ?? false)
+        }
+    }
 }
diff --git a/docs/adr/0010-airplay-fix.md b/docs/adr/0010-airplay-fix.md
@@ -0,0 +1,155 @@
+# ADR-0010: Fix AirPlay for WebView-Based Playback
+
+## Status
+
+Implemented (with known limitations)
+
+## Context
+
+**Issue:** [GitHub Issue #42](https://github.com/sozercan/kaset/issues/42) - AirPlay does not work
+
+The in-app AirPlay button shows available devices and allows selection, but audio continues playing from the Mac instead of the selected AirPlay device. System-wide AirPlay settings work correctly.
+
+### Root Cause
+
+**Architectural mismatch between the AirPlay UI control and the audio playback system:**
+
+1. **Current Implementation**: Uses `AVRoutePickerView` (AVKit) which only controls routing for AVFoundation-based playback (AVPlayer, AVAudioSession)
+2. **Audio Source**: App uses WKWebView to play YouTube Music (required for Widevine DRM per ADR-0001)
+3. **The Disconnect**: `AVRoutePickerView` has no connection to WebKit's audio output
+
+## Decision
+
+Replace `AVRoutePickerView` with WebKit's native AirPlay picker triggered via JavaScript injection using `webkitShowPlaybackTargetPicker()`.
+
+This follows the existing pattern used for play/pause, volume, seek, and other playback controls in `SingletonPlayerWebView+PlaybackControls.swift`.
+
+## Implementation
+
+### Files to Modify
+
+1. **`Views/macOS/SingletonPlayerWebView+PlaybackControls.swift`** - Add `showAirPlayPicker()` method
+2. **`Views/macOS/PlayerBar.swift`** - Replace `AVRoutePickerView` with custom button
+3. **`Core/Services/Player/PlayerService.swift`** - Add `showAirPlayPicker()` method to call through to SingletonPlayerWebView
+
+### Step 1: Add JavaScript injection method
+
+**File:** `Views/macOS/SingletonPlayerWebView+PlaybackControls.swift`
+
+```swift
+/// Show the native AirPlay picker for the WebView's video element.
+func showAirPlayPicker() {
+    guard let webView else { return }
+
+    let script = """
+        (function() {
+            const video = document.querySelector('video');
+            if (video && typeof video.webkitShowPlaybackTargetPicker === 'function') {
+                video.webkitShowPlaybackTargetPicker();
+                return 'picker-shown';
+            }
+            return 'no-video-or-unsupported';
+        })();
+    """
+    webView.evaluateJavaScript(script) { [weak self] result, error in
+        if let error {
+            self?.logger.error("showAirPlayPicker error: \(error.localizedDescription)")
+        } else if let result = result as? String {
+            self?.logger.debug("showAirPlayPicker: \(result)")
+        }
+    }
+}
+```
+
+### Step 2: Add PlayerService method
+
+**File:** `Core/Services/Player/PlayerService.swift`
+
+```swift
+/// Show the AirPlay picker for selecting audio output devices.
+func showAirPlayPicker() {
+    SingletonPlayerWebView.shared.showAirPlayPicker()
+}
+```
+
+Note: No `Task` wrapper needed since `PlayerService` is already `@MainActor`.
+
+### Step 3: Replace AirPlayButton in PlayerBar
+
+**File:** `Views/macOS/PlayerBar.swift`
+
+Replace the `AVRoutePickerView`-based `AirPlayButton` with:
+
+```swift
+Button {
+    HapticService.toggle()
+    self.playerService.showAirPlayPicker()
+} label: {
+    Image(systemName: "airplayaudio")
+        .font(.system(size: 15, weight: .medium))
+        .foregroundStyle(.primary.opacity(0.85))
+}
+.buttonStyle(.pressable)
+.accessibilityIdentifier(AccessibilityID.PlayerBar.airplayButton)
+.accessibilityLabel("AirPlay")
+.disabled(self.playerService.currentTrack == nil)
+```
+
+Notes:
+- `HapticService.toggle()` matches other PlayerBar buttons
+- `self.` prefix per SwiftFormat `--self insert` rule
+- Disabled when no track to avoid silent failures (requires video element)
+
+### Step 4: Add accessibility identifier constant
+
+**File:** Wherever `AccessibilityID.PlayerBar` is defined (likely `Core/Constants/AccessibilityID.swift` or similar)
+
+```swift
+static let airplayButton = "playerBar.airplayButton"
+```
+
+### Step 5: Clean up unused code
+
+- Remove the `AirPlayButton` struct (lines 541-555)
+- Remove `import AVKit` from PlayerBar.swift if no longer used
+
+## Consequences
+
+### Positive
+
+- **Actually works** - AirPlay will route WebView audio to selected devices
+- **Consistent pattern** - Uses same JavaScript injection approach as other playback controls
+- **Native picker** - Shows WebKit's native AirPlay UI which matches system behavior
+
+### Negative
+
+- **Availability detection unreliable** - `webkitplaybacktargetavailabilitychanged` may not fire in WKWebView, so button visibility can't be conditional on AirPlay device availability
+- **Requires active playback** - Picker needs video element to exist; button is disabled until a track is playing
+- **Minor UX change** - Current `AVRoutePickerView` shows devices even without playback (though they don't work). New approach disables button until playback starts, which is more honest but slightly different behavior
+
+## Verification
+
+1. Build the app - ensure no compilation errors
+2. Start playing a song
+3. Click the AirPlay button
+4. Verify native WebKit AirPlay picker appears
+5. Select an AirPlay device (Sonos, HomePod, Apple TV)
+6. Verify audio routes to selected device
+
+## Known Limitations
+
+### AirPlay Connection Lost on Track Change
+
+**Problem:** When a track changes (skip, song ends), YouTube Music destroys and recreates the `<video>` element. This breaks the AirPlay connection because WebKit ties the AirPlay session to the specific video element instance.
+
+**Why This Can't Be Fixed:** WebKit does not provide a programmatic API to connect to an AirPlay device. The user must manually click the AirPlay button and select a device after each track change. There is no way to automatically reconnect to the previously selected device.
+
+### Picker Position
+
+The AirPlay picker's position is determined by the video element's location in the viewport. Since YouTube Music hides the video element (0x0 at position 0,0), the picker appears in the top-left corner. Attempts to reposition the video element via CSS have been unsuccessful due to YouTube's CSS hierarchy. This is a cosmetic issue - the picker still functions correctly.
+
+## References
+
+- [Apple: Adding an AirPlay button to Safari media controls](https://developer.apple.com/documentation/webkitjs/adding_an_airplay_button_to_your_safari_media_controls)
+- [Apple Developer Forums: AirPlay inside a webview](https://developer.apple.com/forums/thread/30179)
+- ADR-0001: WebView-Based Playback

Original file line number	Diff line number	Diff line change
`@@ -38,4 +38,7 @@ enum DiagnosticsLogger {`
`38`	`38`
`39`	`39`	`/// Logger for AppleScript scripting events.`
`40`	`40`	`static let scripting = Logger(subsystem: "com.sertacozercan.Kaset", category: "Scripting")`
	`41`	`+`
	`42`	`+ /// Logger for AirPlay-related events.`
	`43`	`+ static let airplay = Logger(subsystem: "com.sertacozercan.Kaset", category: "AirPlay")`
`41`	`44`	`}`