From 3c8d897dd5742a0f30ee55784851cd4cc8fc30f5 Mon Sep 17 00:00:00 2001
From: Brad Taylor <brad.taylor@gmail.com>
Date: Mon, 29 Jun 2026 17:51:32 -0700
Subject: [PATCH 1/3] feat: introduce pluggable AudioBackend abstraction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the single shared <audio> element in player.tsx with a typed
AudioBackend interface backed by HTMLAudioBackend (HTMLAudioElement +
Web Audio API). AudioBackendProvider manages three dedicated backends
(song, radio, podcast) and owns all playback logic — load, play/pause,
ReplayGain, loop, playback rate. Consumer components access backends via
useActiveAudioBackend() / useAudioBackend() hooks.

Also fixes two Chromium-specific bugs: calling pause() on a NETWORK_EMPTY
element triggers an unexpected error event, and React Strict Mode's
cleanup cycle was firing the radio error toast through listeners that
hadn't been detached before destroy() reset the audio element. The latter
is fixed by using AbortController to remove all listeners as the first
step of destroy().

This lays the groundwork for a future AVPlayerBackend on macOS.
---
 src/app/components/fullscreen/lyrics.tsx    |  11 +-
 src/app/components/fullscreen/progress.tsx  |  10 +-
 src/app/components/mini-player/progress.tsx |  10 +-
 src/app/components/player/audio.tsx         | 157 --------
 src/app/components/player/controls.tsx      |  12 +-
 src/app/components/player/player.tsx        | 229 +-----------
 src/app/components/player/progress.tsx      |  16 +-
 src/app/components/player/volume.tsx        |  12 +-
 src/app/hooks/use-audio-context.tsx         | 117 ------
 src/app/layout/base.tsx                     |  33 +-
 src/lib/audio/audio-backend-context.tsx     |  28 ++
 src/lib/audio/audio-backend-provider.tsx    | 384 ++++++++++++++++++++
 src/lib/audio/backend.ts                    |  23 ++
 src/lib/audio/html-audio-backend.ts         | 172 +++++++++
 src/store/player.store.ts                   |  14 -
 src/types/playerContext.ts                  |   2 -
 16 files changed, 657 insertions(+), 573 deletions(-)
 delete mode 100644 src/app/components/player/audio.tsx
 delete mode 100644 src/app/hooks/use-audio-context.tsx
 create mode 100644 src/lib/audio/audio-backend-context.tsx
 create mode 100644 src/lib/audio/audio-backend-provider.tsx
 create mode 100644 src/lib/audio/backend.ts
 create mode 100644 src/lib/audio/html-audio-backend.ts

diff --git a/src/app/components/fullscreen/lyrics.tsx b/src/app/components/fullscreen/lyrics.tsx
index 3a5393e0f..4887e0bcb 100644
--- a/src/app/components/fullscreen/lyrics.tsx
+++ b/src/app/components/fullscreen/lyrics.tsx
@@ -10,7 +10,8 @@ import {
 } from '@/app/components/ui/scroll-area'
 import { subsonic } from '@/service/subsonic'
 import { useLang } from '@/store/lang.store'
-import { usePlayerRef, usePlayerSonglist } from '@/store/player.store'
+import { useAudioBackend } from '@/lib/audio/audio-backend-context'
+import { usePlayerSonglist } from '@/store/player.store'
 import { ILyric } from '@/types/responses/song'
 import { queryKeys } from '@/utils/queryKeys'
 
@@ -62,13 +63,13 @@ export function LyricsTab() {
 }
 
 function SyncedLyrics({ lyrics }: LyricProps) {
-  const playerRef = usePlayerRef()
+  const { songBackend } = useAudioBackend()
   const { langCode } = useLang()
   const [progress, setProgress] = useState(0)
   const resolvedLang = resolveLyricsLang(lyrics.lang, langCode)
 
   setTimeout(() => {
-    let newProgress = (playerRef?.currentTime || 0) * 1000
+    let newProgress = songBackend.getCurrentTime() * 1000
 
     if (newProgress === progress) {
       newProgress += 1 // Prevents the lyrics from getting stuck when the audio is still loading
@@ -78,9 +79,7 @@ function SyncedLyrics({ lyrics }: LyricProps) {
   }, 50)
 
   const skipToTime = (timeMs: number) => {
-    if (playerRef) {
-      playerRef!.currentTime = timeMs / 1000
-    }
+    songBackend.seek(timeMs / 1000)
   }
 
   return (
diff --git a/src/app/components/fullscreen/progress.tsx b/src/app/components/fullscreen/progress.tsx
index e28c606f2..82ce4271a 100644
--- a/src/app/components/fullscreen/progress.tsx
+++ b/src/app/components/fullscreen/progress.tsx
@@ -1,10 +1,10 @@
 import { useCallback, useState } from 'react'
 import { ProgressSlider } from '@/app/components/ui/slider'
+import { useAudioBackend } from '@/lib/audio/audio-backend-context'
 import {
   usePlayerActions,
   usePlayerDuration,
   usePlayerProgress,
-  usePlayerRef,
 } from '@/store/player.store'
 import { convertSecondsToTime } from '@/utils/convertSecondsToTime'
 
@@ -13,18 +13,16 @@ let isSeeking = false
 export function FullscreenProgress() {
   const progress = usePlayerProgress()
   const [localProgress, setLocalProgress] = useState(progress)
-  const audioPlayerRef = usePlayerRef()
+  const { songBackend } = useAudioBackend()
   const currentDuration = usePlayerDuration()
   const { setProgress } = usePlayerActions()
 
   const updateAudioCurrentTime = useCallback(
     (value: number) => {
       isSeeking = false
-      if (audioPlayerRef) {
-        audioPlayerRef.currentTime = value
-      }
+      songBackend.seek(value)
     },
-    [audioPlayerRef],
+    [songBackend],
   )
 
   const handleSeeking = useCallback((amount: number) => {
diff --git a/src/app/components/mini-player/progress.tsx b/src/app/components/mini-player/progress.tsx
index 85e6ff82d..259b3d2ed 100644
--- a/src/app/components/mini-player/progress.tsx
+++ b/src/app/components/mini-player/progress.tsx
@@ -1,10 +1,10 @@
 import { useCallback, useState } from 'react'
 import { Slider } from '@/app/components/ui/slider'
+import { useAudioBackend } from '@/lib/audio/audio-backend-context'
 import {
   usePlayerActions,
   usePlayerDuration,
   usePlayerProgress,
-  usePlayerRef,
 } from '@/store/player.store'
 import { convertSecondsToTime } from '@/utils/convertSecondsToTime'
 
@@ -13,18 +13,16 @@ let isSeeking = false
 export function MiniPlayerProgress() {
   const progress = usePlayerProgress()
   const [localProgress, setLocalProgress] = useState(progress)
-  const audioPlayerRef = usePlayerRef()
+  const { songBackend } = useAudioBackend()
   const currentDuration = usePlayerDuration()
   const { setProgress } = usePlayerActions()
 
   const updateAudioCurrentTime = useCallback(
     (value: number) => {
       isSeeking = false
-      if (audioPlayerRef) {
-        audioPlayerRef.currentTime = value
-      }
+      songBackend.seek(value)
     },
-    [audioPlayerRef],
+    [songBackend],
   )
 
   const handleSeeking = useCallback((amount: number) => {
diff --git a/src/app/components/player/audio.tsx b/src/app/components/player/audio.tsx
deleted file mode 100644
index 324428b8a..000000000
--- a/src/app/components/player/audio.tsx
+++ /dev/null
@@ -1,157 +0,0 @@
-import {
-  ComponentPropsWithoutRef,
-  RefObject,
-  useCallback,
-  useEffect,
-  useMemo,
-  useState,
-} from 'react'
-import { useTranslation } from 'react-i18next'
-import { toast } from 'react-toastify'
-import { useAudioContext } from '@/app/hooks/use-audio-context'
-import {
-  usePlayerActions,
-  usePlayerIsPlaying,
-  usePlayerMediaType,
-  usePlayerVolume,
-  useReplayGainActions,
-  useReplayGainState,
-} from '@/store/player.store'
-import { logger } from '@/utils/logger'
-import { calculateReplayGain, ReplayGainParams } from '@/utils/replayGain'
-
-type AudioPlayerProps = ComponentPropsWithoutRef<'audio'> & {
-  audioRef: RefObject<HTMLAudioElement>
-  replayGain?: ReplayGainParams
-}
-
-export function AudioPlayer({
-  audioRef,
-  replayGain,
-  ...props
-}: AudioPlayerProps) {
-  const { t } = useTranslation()
-  const [previousGain, setPreviousGain] = useState(1)
-  const { replayGainEnabled, replayGainError } = useReplayGainState()
-  const { isSong, isRadio, isPodcast } = usePlayerMediaType()
-  const { setPlayingState } = usePlayerActions()
-  const { setReplayGainEnabled, setReplayGainError } = useReplayGainActions()
-  const { volume } = usePlayerVolume()
-  const isPlaying = usePlayerIsPlaying()
-
-  const gainValue = useMemo(() => {
-    const audioVolume = volume / 100
-
-    if (!replayGain || !replayGainEnabled) {
-      return audioVolume * 1
-    }
-    const gain = calculateReplayGain(replayGain)
-
-    return audioVolume * gain
-  }, [replayGain, replayGainEnabled, volume])
-
-  const { resumeContext, setupGain } = useAudioContext(audioRef.current)
-
-  const ignoreGain = !isSong || replayGainError
-
-  useEffect(() => {
-    if (ignoreGain || !audioRef.current) return
-
-    if (gainValue === previousGain) return
-
-    setupGain(gainValue, replayGain)
-    setPreviousGain(gainValue)
-  }, [audioRef, ignoreGain, gainValue, previousGain, replayGain, setupGain])
-
-  const handleSongError = useCallback(() => {
-    const audio = audioRef.current
-    if (!audio) return
-
-    logger.error('Audio load error', {
-      src: audio.src,
-      networkState: audio.networkState,
-      readyState: audio.readyState,
-      error: audio.error,
-    })
-
-    toast.error(t('warnings.songError'))
-
-    if (replayGainEnabled || !replayGainError) {
-      setReplayGainEnabled(false)
-      setReplayGainError(true)
-      window.location.reload()
-    }
-  }, [
-    audioRef,
-    replayGainEnabled,
-    replayGainError,
-    setReplayGainEnabled,
-    setReplayGainError,
-    t,
-  ])
-
-  const handleRadioError = useCallback(() => {
-    const audio = audioRef.current
-    if (!audio) return
-
-    toast.error(t('radios.error'))
-    setPlayingState(false)
-  }, [audioRef, setPlayingState, t])
-
-  useEffect(() => {
-    async function handleSong() {
-      const audio = audioRef.current
-      if (!audio) return
-
-      try {
-        if (isPlaying) {
-          if (isSong) await resumeContext()
-          await audio.play()
-        } else {
-          audio.pause()
-        }
-      } catch (error) {
-        logger.error('Audio playback failed', error)
-        handleSongError()
-      }
-    }
-    if (isSong || isPodcast) handleSong()
-  }, [audioRef, handleSongError, isPlaying, isSong, isPodcast, resumeContext])
-
-  useEffect(() => {
-    async function handleRadio() {
-      const audio = audioRef.current
-      if (!audio) return
-
-      if (isPlaying) {
-        audio.load()
-        await audio.play()
-      } else {
-        audio.pause()
-      }
-    }
-    if (isRadio) handleRadio()
-  }, [audioRef, isPlaying, isRadio])
-
-  const handleError = useMemo(() => {
-    if (isSong) return handleSongError
-    if (isRadio) return handleRadioError
-
-    return undefined
-  }, [handleRadioError, handleSongError, isRadio, isSong])
-
-  const crossOrigin = useMemo(() => {
-    if (!isSong || replayGainError) return undefined
-
-    return 'anonymous'
-  }, [isSong, replayGainError])
-
-  return (
-    <audio
-      ref={audioRef}
-      {...props}
-      crossOrigin={crossOrigin}
-      onError={handleError}
-    />
-  )
-}
diff --git a/src/app/components/player/controls.tsx b/src/app/components/player/controls.tsx
index 57c9faa98..9ee22118d 100644
--- a/src/app/components/player/controls.tsx
+++ b/src/app/components/player/controls.tsx
@@ -11,7 +11,6 @@ import {
 } from 'lucide-react'
 import {
   ComponentPropsWithoutRef,
-  RefObject,
   useCallback,
   useEffect,
 } from 'react'
@@ -20,6 +19,7 @@ import RepeatOne from '@/app/components/icons/repeat-one'
 import { Button } from '@/app/components/ui/button'
 import { SimpleTooltip } from '@/app/components/ui/simple-tooltip'
 import { usePlayerHotkeys } from '@/app/hooks/use-audio-hotkeys'
+import { useActiveAudioBackend } from '@/lib/audio/audio-backend-context'
 import { cn } from '@/lib/utils'
 import {
   usePlayerActions,
@@ -39,14 +39,12 @@ interface PlayerControlsProps {
   song: ISong
   radio: Radio
   podcast: EpisodeWithPodcast
-  audioRef: RefObject<HTMLAudioElement>
 }
 
 export function PlayerControls({
   song,
   radio,
   podcast,
-  audioRef,
 }: PlayerControlsProps) {
   const { t } = useTranslation()
   const { isSong, isPodcast } = usePlayerMediaType()
@@ -63,6 +61,7 @@ export function PlayerControls({
     playNextSong,
   } = usePlayerActions()
   const { useAudioHotkeys } = usePlayerHotkeys()
+  const backend = useActiveAudioBackend()
 
   useAudioHotkeys('space', togglePlayPause)
   useAudioHotkeys('mod+left', playPrevSong)
@@ -72,12 +71,9 @@ export function PlayerControls({
 
   const handleSeekAction = useCallback(
     (value: number) => {
-      const audio = audioRef.current
-      if (!audio) return
-
-      audio.currentTime += value
+      backend.seek(backend.getCurrentTime() + value)
     },
-    [audioRef],
+    [backend],
   )
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: isPlaying needed to trigger
diff --git a/src/app/components/player/player.tsx b/src/app/components/player/player.tsx
index c16a37e19..2803a8705 100644
--- a/src/app/components/player/player.tsx
+++ b/src/app/components/player/player.tsx
@@ -1,28 +1,13 @@
-import { memo, useCallback, useEffect, useMemo, useRef } from 'react'
-import { getSongStreamUrl } from '@/api/httpClient'
-import { getProxyURL } from '@/api/podcastClient'
+import { memo } from 'react'
 import { MiniPlayerButton } from '@/app/components/mini-player/button'
 import { RadioInfo } from '@/app/components/player/radio-info'
 import { TrackInfo } from '@/app/components/player/track-info'
-import { podcasts } from '@/service/podcasts'
-import { useAppMediaCache, useAppStore } from '@/store/app.store'
+import { useAppStore } from '@/store/app.store'
 import {
-  getVolume,
-  usePlayerActions,
-  usePlayerIsPlaying,
-  usePlayerLoop,
   usePlayerMediaType,
-  usePlayerRef,
   usePlayerSonglist,
-  usePlayerStore,
-  useReplayGainState,
 } from '@/store/player.store'
-import { LoopState } from '@/types/playerContext'
-import { ensureSupportForAlac } from '@/utils/alac'
 import { hasPiPSupport } from '@/utils/browser'
-import { logger } from '@/utils/logger'
-import { ReplayGainParams } from '@/utils/replayGain'
-import { AudioPlayer } from './audio'
 import { PlayerClearQueueButton } from './clear-queue-button'
 import { PlayerControls } from './controls'
 import { PlayerExpandButton } from './expand-button'
@@ -50,166 +35,14 @@ const MemoMiniPlayerButton = memo(MiniPlayerButton)
 
 export function Player() {
   const hideFavoritesSection = useAppStore().pages.hideFavoritesSection
-  const audioRef = useRef<HTMLAudioElement>(null)
-  const radioRef = useRef<HTMLAudioElement>(null)
-  const podcastRef = useRef<HTMLAudioElement>(null)
-  const {
-    setAudioPlayerRef,
-    setCurrentDuration,
-    setProgress,
-    setPlayingState,
-    handleSongEnded,
-    getCurrentProgress,
-    getCurrentPodcastProgress,
-  } = usePlayerActions()
   const { currentList, currentSongIndex, radioList, podcastList } =
     usePlayerSonglist()
-  const isPlaying = usePlayerIsPlaying()
   const { isSong, isRadio, isPodcast } = usePlayerMediaType()
-  const loopState = usePlayerLoop()
-  const audioPlayerRef = usePlayerRef()
-  const currentPlaybackRate = usePlayerStore().playerState.currentPlaybackRate
-  const { replayGainType, replayGainPreAmp, replayGainDefaultGain } =
-    useReplayGainState()
 
   const song = currentList[currentSongIndex]
   const radio = radioList[currentSongIndex]
   const podcast = podcastList[currentSongIndex]
 
-  const mediaCacheEnabled = useAppMediaCache()
-  const songId = song?.id
-
-  const songStreamUrl = useMemo(() => {
-    if (!songId) return ''
-
-    const cacheBustToken = mediaCacheEnabled ? undefined : Date.now().toString()
-
-    return getSongStreamUrl(
-      songId,
-      undefined,
-      ensureSupportForAlac(song.suffix),
-      cacheBustToken,
-    )
-  }, [songId, song, mediaCacheEnabled])
-
-  const getAudioRef = useCallback(() => {
-    if (isRadio) return radioRef
-    if (isPodcast) return podcastRef
-
-    return audioRef
-  }, [isPodcast, isRadio])
-
-  // biome-ignore lint/correctness/useExhaustiveDependencies: audioRef needed
-  useEffect(() => {
-    if (!isSong && !song) return
-
-    if (audioPlayerRef === null && audioRef.current)
-      setAudioPlayerRef(audioRef.current)
-  }, [audioPlayerRef, audioRef, isSong, setAudioPlayerRef, song])
-
-  useEffect(() => {
-    const audio = podcastRef.current
-    if (!audio || !isPodcast) return
-
-    audio.playbackRate = currentPlaybackRate
-  }, [currentPlaybackRate, isPodcast])
-
-  const setupDuration = useCallback(() => {
-    const audio = getAudioRef().current
-    if (!audio) return
-
-    const audioDuration = Math.floor(audio.duration)
-    const infinityDuration = audioDuration === Infinity
-
-    if (!infinityDuration) {
-      setCurrentDuration(audioDuration)
-    } else if (isSong && song?.duration) {
-      setCurrentDuration(song.duration)
-    }
-
-    if (isPodcast && infinityDuration && podcast) {
-      setCurrentDuration(podcast.duration)
-    }
-
-    if (isPodcast) {
-      const podcastProgress = getCurrentPodcastProgress()
-
-      logger.info('[Player] - Resuming episode from:', {
-        seconds: podcastProgress,
-      })
-
-      setProgress(podcastProgress)
-      audio.currentTime = podcastProgress
-    } else {
-      const progress = getCurrentProgress()
-      audio.currentTime = progress
-    }
-  }, [
-    getAudioRef,
-    isPodcast,
-    isSong,
-    song,
-    podcast,
-    setCurrentDuration,
-    getCurrentPodcastProgress,
-    setProgress,
-    getCurrentProgress,
-  ])
-
-  const setupProgress = useCallback(() => {
-    const audio = getAudioRef().current
-    if (!audio) return
-
-    const currentProgress = Math.floor(audio.currentTime)
-    setProgress(currentProgress)
-  }, [getAudioRef, setProgress])
-
-  const setupInitialVolume = useCallback(() => {
-    const audio = getAudioRef().current
-    if (!audio) return
-
-    audio.volume = getVolume() / 100
-  }, [getAudioRef])
-
-  const sendFinishProgress = useCallback(() => {
-    if (!isPodcast || !podcast) return
-
-    podcasts
-      .saveEpisodeProgress(podcast.id, podcast.duration)
-      .then(() => {
-        logger.info('Complete progress sent:', podcast.duration)
-      })
-      .catch((error) => {
-        logger.error('Error sending complete progress', error)
-      })
-  }, [isPodcast, podcast])
-
-  const trackReplayGain = useMemo<ReplayGainParams>(() => {
-    const preAmp = replayGainPreAmp
-    const defaultGain = replayGainDefaultGain
-
-    if (!song || !song.replayGain) {
-      return { gain: defaultGain, peak: 1, preAmp }
-    }
-
-    if (replayGainType === 'album') {
-      let { albumGain = defaultGain, albumPeak = 1 } = song.replayGain
-
-      if (albumGain === 0) {
-        albumGain = defaultGain
-      }
-
-      return { gain: albumGain, peak: albumPeak, preAmp }
-    }
-
-    let { trackGain = defaultGain, trackPeak = 1 } = song.replayGain
-
-    if (trackGain === 0) {
-      trackGain = defaultGain
-    }
-    return { gain: trackGain, peak: trackPeak, preAmp }
-  }, [song, replayGainDefaultGain, replayGainPreAmp, replayGainType])
-
   return (
     <footer className="border-t h-[--player-height] w-full flex items-center fixed bottom-0 left-0 right-0 z-40 bg-background">
       <div className="w-full h-full grid grid-cols-player gap-2 px-4">
@@ -225,12 +58,9 @@ export function Player() {
             song={song}
             radio={radio}
             podcast={podcast}
-            audioRef={getAudioRef()}
           />
 
-          {(isSong || isPodcast) && (
-            <MemoPlayerProgress audioRef={getAudioRef()} />
-          )}
+          {(isSong || isPodcast) && <MemoPlayerProgress />}
         </div>
         {/* Remain Controls and Volume */}
         <div className="flex items-center w-full justify-end">
@@ -251,64 +81,13 @@ export function Player() {
               <MemoPlayerClearQueueButton disabled={!radio && !podcast} />
             )}
 
-            <MemoPlayerVolume
-              audioRef={getAudioRef()}
-              disabled={!song && !radio && !podcast}
-            />
+            <MemoPlayerVolume disabled={!song && !radio && !podcast} />
 
             {isSong && <MemoPlayerExpandButton disabled={!song} />}
             {isSong && hasPiPSupport && <MemoMiniPlayerButton />}
           </div>
         </div>
       </div>
-
-      {isSong && song && (
-        <AudioPlayer
-          replayGain={trackReplayGain}
-          src={songStreamUrl}
-          autoPlay={isPlaying}
-          audioRef={audioRef}
-          loop={loopState === LoopState.One}
-          onPlay={() => setPlayingState(true)}
-          onPause={() => setPlayingState(false)}
-          onLoadedMetadata={setupDuration}
-          onTimeUpdate={setupProgress}
-          onEnded={handleSongEnded}
-          onLoadStart={setupInitialVolume}
-          data-testid="player-song-audio"
-        />
-      )}
-
-      {isRadio && radio && (
-        <AudioPlayer
-          src={radio.streamUrl}
-          autoPlay={isPlaying}
-          audioRef={radioRef}
-          onPlay={() => setPlayingState(true)}
-          onPause={() => setPlayingState(false)}
-          onLoadStart={setupInitialVolume}
-          data-testid="player-radio-audio"
-        />
-      )}
-
-      {isPodcast && podcast && (
-        <AudioPlayer
-          src={getProxyURL(podcast.audio_url)}
-          autoPlay={isPlaying}
-          audioRef={podcastRef}
-          preload="auto"
-          onPlay={() => setPlayingState(true)}
-          onPause={() => setPlayingState(false)}
-          onLoadedMetadata={setupDuration}
-          onTimeUpdate={setupProgress}
-          onEnded={() => {
-            sendFinishProgress()
-            handleSongEnded()
-          }}
-          onLoadStart={setupInitialVolume}
-          data-testid="player-podcast-audio"
-        />
-      )}
     </footer>
   )
 }
diff --git a/src/app/components/player/progress.tsx b/src/app/components/player/progress.tsx
index 787f88bff..20b9287f6 100644
--- a/src/app/components/player/progress.tsx
+++ b/src/app/components/player/progress.tsx
@@ -1,6 +1,7 @@
 import clsx from 'clsx'
-import { RefObject, useCallback, useEffect, useMemo, useState } from 'react'
+import { useCallback, useEffect, useMemo, useState } from 'react'
 import { ProgressSlider } from '@/app/components/ui/slider'
+import { useActiveAudioBackend } from '@/lib/audio/audio-backend-context'
 import { podcasts } from '@/service/podcasts'
 import {
   usePlayerActions,
@@ -12,13 +13,9 @@ import {
 import { convertSecondsToTime } from '@/utils/convertSecondsToTime'
 import { logger } from '@/utils/logger'
 
-interface PlayerProgressProps {
-  audioRef: RefObject<HTMLAudioElement>
-}
-
 let isSeeking = false
 
-export function PlayerProgress({ audioRef }: PlayerProgressProps) {
+export function PlayerProgress() {
   const progress = usePlayerProgress()
   const [localProgress, setLocalProgress] = useState(progress)
   const currentDuration = usePlayerDuration()
@@ -26,17 +23,16 @@ export function PlayerProgress({ audioRef }: PlayerProgressProps) {
   const { isSong, isPodcast } = usePlayerMediaType()
   const { setProgress, setUpdatePodcastProgress, getCurrentPodcastProgress } =
     usePlayerActions()
+  const backend = useActiveAudioBackend()
 
   const isEmpty = isSong && currentList.length === 0
 
   const updateAudioCurrentTime = useCallback(
     (value: number) => {
       isSeeking = false
-      if (audioRef.current) {
-        audioRef.current.currentTime = value
-      }
+      backend.seek(value)
     },
-    [audioRef],
+    [backend],
   )
 
   const handleSeeking = useCallback((amount: number) => {
diff --git a/src/app/components/player/volume.tsx b/src/app/components/player/volume.tsx
index 486523e43..4880ade12 100644
--- a/src/app/components/player/volume.tsx
+++ b/src/app/components/player/volume.tsx
@@ -1,7 +1,6 @@
 import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
-  RefObject,
   useEffect,
   useRef,
   WheelEvent,
@@ -12,28 +11,27 @@ import { Button } from '@/app/components/ui/button'
 import { SimpleTooltip } from '@/app/components/ui/simple-tooltip'
 import { Slider } from '@/app/components/ui/slider'
 import { usePlayerHotkeys } from '@/app/hooks/use-audio-hotkeys'
+import { useActiveAudioBackend } from '@/lib/audio/audio-backend-context'
 import { cn } from '@/lib/utils'
 import { usePlayerVolume, useVolumeSettings } from '@/store/player.store'
 import { PopoverVolume } from './popover-volume'
 
 interface PlayerVolumeProps {
   disabled: boolean
-  audioRef: RefObject<HTMLAudioElement>
 }
 
-export function PlayerVolume({ disabled, audioRef }: PlayerVolumeProps) {
+export function PlayerVolume({ disabled }: PlayerVolumeProps) {
   const { t } = useTranslation()
   const { volume, handleVolumeWheel } = usePlayerVolume()
   const { useAudioHotkeys } = usePlayerHotkeys()
+  const backend = useActiveAudioBackend()
 
   useAudioHotkeys('mod+up', () => handleVolumeWheel(false))
   useAudioHotkeys('mod+down', () => handleVolumeWheel(true))
 
   useEffect(() => {
-    if (!audioRef.current) return
-
-    audioRef.current.volume = volume / 100
-  }, [audioRef, volume])
+    backend.setVolume(volume / 100)
+  }, [backend, volume])
 
   const tooltipText =
     volume === 0
diff --git a/src/app/hooks/use-audio-context.tsx b/src/app/hooks/use-audio-context.tsx
deleted file mode 100644
index 394d1194f..000000000
--- a/src/app/hooks/use-audio-context.tsx
+++ /dev/null
@@ -1,117 +0,0 @@
-import { useCallback, useEffect, useRef } from 'react'
-import {
-  AudioContext,
-  type IAudioContext,
-  type IGainNode,
-  type IMediaElementAudioSourceNode,
-} from 'standardized-audio-context'
-import { usePlayerMediaType, useReplayGainState } from '@/store/player.store'
-import { logger } from '@/utils/logger'
-import { ReplayGainParams } from '@/utils/replayGain'
-
-type IAudioSource = IMediaElementAudioSourceNode<IAudioContext>
-
-export function useAudioContext(audio: HTMLAudioElement | null) {
-  const { isSong } = usePlayerMediaType()
-  const { replayGainError, replayGainEnabled } = useReplayGainState()
-
-  const audioContextRef = useRef<IAudioContext | null>(null)
-  const sourceNodeRef = useRef<IAudioSource | null>(null)
-  const gainNodeRef = useRef<IGainNode<IAudioContext> | null>(null)
-
-  const setupAudioContext = useCallback(() => {
-    if (!audio || !isSong || replayGainError) return
-
-    if (!audioContextRef.current) {
-      audioContextRef.current = new AudioContext()
-    }
-
-    const audioContext = audioContextRef.current
-
-    if (!sourceNodeRef.current) {
-      sourceNodeRef.current = audioContext.createMediaElementSource(audio)
-    }
-
-    if (!gainNodeRef.current) {
-      gainNodeRef.current = audioContext.createGain()
-      // First we need to connect the sourceNode to the gainNode
-      sourceNodeRef.current.connect(gainNodeRef.current)
-      // And then we can connect the gainNode to the destination
-      gainNodeRef.current.connect(audioContext.destination)
-    }
-  }, [audio, isSong, replayGainError])
-
-  const resumeContext = useCallback(async () => {
-    const audioContext = audioContextRef.current
-    if (!audioContext || !isSong) return
-
-    logger.info('AudioContext State', { state: audioContext.state })
-
-    if (audioContext.state === 'suspended') {
-      await audioContext.resume()
-    }
-    if (audioContext.state === 'closed') {
-      setupAudioContext()
-    }
-  }, [isSong, setupAudioContext])
-
-  const setupGain = useCallback(
-    (gainValue: number, replayGain?: ReplayGainParams) => {
-      setupAudioContext()
-
-      if (!audioContextRef.current || !gainNodeRef.current) {
-        return
-      }
-
-      if (!gainValue || Number.isNaN(gainValue)) {
-        logger.error('Invalid gain value', { gainValue })
-        return
-      }
-
-      const currentTime = audioContextRef.current.currentTime
-
-      logger.info('Replay Gain Status', {
-        enabled: replayGainEnabled,
-        gainValue,
-        ...replayGain,
-      })
-
-      gainNodeRef.current.gain.setValueAtTime(gainValue, currentTime)
-    },
-    [replayGainEnabled, setupAudioContext],
-  )
-
-  const resetRefs = useCallback(() => {
-    if (sourceNodeRef.current) {
-      sourceNodeRef.current.disconnect()
-      sourceNodeRef.current = null
-    }
-    if (gainNodeRef.current) {
-      gainNodeRef.current.disconnect()
-      gainNodeRef.current = null
-    }
-    if (audioContextRef.current) {
-      audioContextRef.current.close()
-      audioContextRef.current = null
-    }
-  }, [])
-
-  useEffect(() => {
-    if (replayGainError) resetRefs()
-  }, [replayGainError, resetRefs])
-
-  // biome-ignore lint/correctness/useExhaustiveDependencies: clear state after unmount
-  useEffect(() => {
-    return () => resetRefs()
-  }, [])
-
-  return {
-    audioContextRef,
-    sourceNodeRef,
-    gainNodeRef,
-    setupAudioContext,
-    resumeContext,
-    setupGain,
-    resetRefs,
-  }
-}
diff --git a/src/app/layout/base.tsx b/src/app/layout/base.tsx
index 9e2e0ad59..bdd5d7080 100644
--- a/src/app/layout/base.tsx
+++ b/src/app/layout/base.tsx
@@ -10,6 +10,7 @@ import {
   MainSidebarInset,
   MainSidebarProvider,
 } from '@/app/components/ui/main-sidebar'
+import { AudioBackendProvider } from '@/lib/audio/audio-backend-provider'
 import { Header } from '@/app/layout/header'
 import { MainRoutes } from './main'
 
@@ -22,20 +23,22 @@ const MemoFullscreenMode = memo(FullscreenMode)
 
 export default function BaseLayout() {
   return (
-    <div className="h-screen w-screen overflow-hidden">
-      <MainSidebarProvider>
-        <MemoHeader />
-        <AppSidebar />
-        <MainSidebarInset>
-          <MainRoutes />
-        </MainSidebarInset>
-        <MemoPlayer />
-      </MainSidebarProvider>
-      <MemoSongInfoDialog />
-      <MemoRemovePlaylistDialog />
-      <MemoMainDrawerPage />
-      <CreatePlaylistDialog />
-      <MemoFullscreenMode />
-    </div>
+    <AudioBackendProvider>
+      <div className="h-screen w-screen overflow-hidden">
+        <MainSidebarProvider>
+          <MemoHeader />
+          <AppSidebar />
+          <MainSidebarInset>
+            <MainRoutes />
+          </MainSidebarInset>
+          <MemoPlayer />
+        </MainSidebarProvider>
+        <MemoSongInfoDialog />
+        <MemoRemovePlaylistDialog />
+        <MemoMainDrawerPage />
+        <CreatePlaylistDialog />
+        <MemoFullscreenMode />
+      </div>
+    </AudioBackendProvider>
   )
 }
diff --git a/src/lib/audio/audio-backend-context.tsx b/src/lib/audio/audio-backend-context.tsx
new file mode 100644
index 000000000..6fe8c5fc3
--- /dev/null
+++ b/src/lib/audio/audio-backend-context.tsx
@@ -0,0 +1,28 @@
+import { createContext, useContext } from 'react'
+import { usePlayerMediaType } from '@/store/player.store'
+import { AudioBackend } from './backend'
+
+interface AudioBackendContextValue {
+  songBackend: AudioBackend
+  radioBackend: AudioBackend
+  podcastBackend: AudioBackend
+}
+
+export const AudioBackendContext =
+  createContext<AudioBackendContextValue | null>(null)
+
+export function useAudioBackend(): AudioBackendContextValue {
+  const ctx = useContext(AudioBackendContext)
+  if (!ctx)
+    throw new Error('useAudioBackend must be used within AudioBackendProvider')
+  return ctx
+}
+
+export function useActiveAudioBackend(): AudioBackend {
+  const { songBackend, radioBackend, podcastBackend } = useAudioBackend()
+  const { isRadio, isPodcast } = usePlayerMediaType()
+
+  if (isRadio) return radioBackend
+  if (isPodcast) return podcastBackend
+  return songBackend
+}
diff --git a/src/lib/audio/audio-backend-provider.tsx b/src/lib/audio/audio-backend-provider.tsx
new file mode 100644
index 000000000..2f4d94a65
--- /dev/null
+++ b/src/lib/audio/audio-backend-provider.tsx
@@ -0,0 +1,384 @@
+import { ReactNode, useCallback, useEffect, useMemo, useRef } from 'react'
+import { useTranslation } from 'react-i18next'
+import { toast } from 'react-toastify'
+import { getSongStreamUrl } from '@/api/httpClient'
+import { getProxyURL } from '@/api/podcastClient'
+import { podcasts } from '@/service/podcasts'
+import { useAppMediaCache } from '@/store/app.store'
+import {
+  getVolume,
+  usePlayerActions,
+  usePlayerIsPlaying,
+  usePlayerLoop,
+  usePlayerMediaType,
+  usePlayerSonglist,
+  usePlayerStore,
+  usePlayerVolume,
+  useReplayGainActions,
+  useReplayGainState,
+} from '@/store/player.store'
+import { LoopState } from '@/types/playerContext'
+import { ensureSupportForAlac } from '@/utils/alac'
+import { logger } from '@/utils/logger'
+import { calculateReplayGain, ReplayGainParams } from '@/utils/replayGain'
+import { AudioBackendContext } from './audio-backend-context'
+import { HTMLAudioBackend } from './html-audio-backend'
+
+export function AudioBackendProvider({ children }: { children: ReactNode }) {
+  const { t } = useTranslation()
+  const {
+    setCurrentDuration,
+    setProgress,
+    setPlayingState,
+    handleSongEnded,
+    getCurrentProgress,
+    getCurrentPodcastProgress,
+  } = usePlayerActions()
+  const { setReplayGainEnabled, setReplayGainError } = useReplayGainActions()
+  const { currentList, currentSongIndex, radioList, podcastList } =
+    usePlayerSonglist()
+  const isPlaying = usePlayerIsPlaying()
+  const { isSong, isRadio, isPodcast } = usePlayerMediaType()
+  const loopState = usePlayerLoop()
+  const currentPlaybackRate = usePlayerStore().playerState.currentPlaybackRate
+  const {
+    replayGainType,
+    replayGainPreAmp,
+    replayGainDefaultGain,
+    replayGainEnabled,
+    replayGainError,
+  } = useReplayGainState()
+  const { volume } = usePlayerVolume()
+  const mediaCacheEnabled = useAppMediaCache()
+
+  const song = currentList[currentSongIndex]
+  const radio = radioList[currentSongIndex]
+  const podcast = podcastList[currentSongIndex]
+  const songId = song?.id
+
+  const songStreamUrl = useMemo(() => {
+    if (!songId) return ''
+
+    const cacheBustToken = mediaCacheEnabled ? undefined : Date.now().toString()
+
+    return getSongStreamUrl(
+      songId,
+      undefined,
+      ensureSupportForAlac(song.suffix),
+      cacheBustToken,
+    )
+  }, [songId, song, mediaCacheEnabled])
+
+  const trackReplayGain = useMemo<ReplayGainParams>(() => {
+    const preAmp = replayGainPreAmp
+    const defaultGain = replayGainDefaultGain
+
+    if (!song || !song.replayGain) {
+      return { gain: defaultGain, peak: 1, preAmp }
+    }
+
+    if (replayGainType === 'album') {
+      let { albumGain = defaultGain, albumPeak = 1 } = song.replayGain
+
+      if (albumGain === 0) {
+        albumGain = defaultGain
+      }
+
+      return { gain: albumGain, peak: albumPeak, preAmp }
+    }
+
+    let { trackGain = defaultGain, trackPeak = 1 } = song.replayGain
+
+    if (trackGain === 0) {
+      trackGain = defaultGain
+    }
+    return { gain: trackGain, peak: trackPeak, preAmp }
+  }, [song, replayGainDefaultGain, replayGainPreAmp, replayGainType])
+
+  const handlersRef = useRef({
+    setupDuration: () => {},
+    setupProgress: () => {},
+    setupInitialVolume: () => {},
+    handleSongEnded: () => {},
+    sendFinishProgress: () => {},
+    handleSongError: () => {},
+    handleRadioError: () => {},
+  })
+
+  const songBackend = useRef<HTMLAudioBackend | null>(null)
+  const radioBackend = useRef<HTMLAudioBackend | null>(null)
+  const podcastBackend = useRef<HTMLAudioBackend | null>(null)
+
+  if (!songBackend.current) {
+    songBackend.current = new HTMLAudioBackend(
+      {
+        onPlay: () => setPlayingState(true),
+        onPause: () => setPlayingState(false),
+        onLoadedMetadata: () => handlersRef.current.setupDuration(),
+        onTimeUpdate: () => handlersRef.current.setupProgress(),
+        onEnded: () => handlersRef.current.handleSongEnded(),
+        onLoadStart: () => handlersRef.current.setupInitialVolume(),
+        onError: () => handlersRef.current.handleSongError(),
+      },
+      !replayGainError,
+    )
+  }
+
+  if (!radioBackend.current) {
+    radioBackend.current = new HTMLAudioBackend({
+      onPlay: () => setPlayingState(true),
+      onPause: () => setPlayingState(false),
+      onLoadStart: () => handlersRef.current.setupInitialVolume(),
+      onError: () => handlersRef.current.handleRadioError(),
+    })
+  }
+
+  if (!podcastBackend.current) {
+    podcastBackend.current = new HTMLAudioBackend({
+      onPlay: () => setPlayingState(true),
+      onPause: () => setPlayingState(false),
+      onLoadedMetadata: () => handlersRef.current.setupDuration(),
+      onTimeUpdate: () => handlersRef.current.setupProgress(),
+      onEnded: () => {
+        handlersRef.current.sendFinishProgress()
+        handlersRef.current.handleSongEnded()
+      },
+      onLoadStart: () => handlersRef.current.setupInitialVolume(),
+    })
+    podcastBackend.current.preload = 'auto'
+  }
+
+  useEffect(() => {
+    return () => {
+      songBackend.current?.destroy()
+      radioBackend.current?.destroy()
+      podcastBackend.current?.destroy()
+    }
+  }, [])
+
+  const getActiveBackend = useCallback((): HTMLAudioBackend => {
+    if (isRadio) return radioBackend.current!
+    if (isPodcast) return podcastBackend.current!
+    return songBackend.current!
+  }, [isPodcast, isRadio])
+
+  const setupDuration = useCallback(() => {
+    const backend = getActiveBackend()
+    const audioDuration = Math.floor(backend.getDuration())
+    const infinityDuration = audioDuration === Infinity
+
+    if (!infinityDuration) {
+      setCurrentDuration(audioDuration)
+    } else if (isSong && song?.duration) {
+      setCurrentDuration(song.duration)
+    }
+
+    if (isPodcast && infinityDuration && podcast) {
+      setCurrentDuration(podcast.duration)
+    }
+
+    if (isPodcast) {
+      const podcastProgress = getCurrentPodcastProgress()
+
+      logger.info('[Player] - Resuming episode from:', {
+        seconds: podcastProgress,
+      })
+
+      setProgress(podcastProgress)
+      backend.seek(podcastProgress)
+    } else {
+      const progress = getCurrentProgress()
+      backend.seek(progress)
+    }
+  }, [
+    getActiveBackend,
+    isPodcast,
+    isSong,
+    song,
+    podcast,
+    setCurrentDuration,
+    getCurrentPodcastProgress,
+    setProgress,
+    getCurrentProgress,
+  ])
+
+  const setupProgress = useCallback(() => {
+    const currentProgress = Math.floor(getActiveBackend().getCurrentTime())
+    setProgress(currentProgress)
+  }, [getActiveBackend, setProgress])
+
+  const setupInitialVolume = useCallback(() => {
+    getActiveBackend().setVolume(getVolume() / 100)
+  }, [getActiveBackend])
+
+  const sendFinishProgress = useCallback(() => {
+    if (!isPodcast || !podcast) return
+
+    podcasts
+      .saveEpisodeProgress(podcast.id, podcast.duration)
+      .then(() => {
+        logger.info('Complete progress sent:', podcast.duration)
+      })
+      .catch((error) => {
+        logger.error('Error sending complete progress', error)
+      })
+  }, [isPodcast, podcast])
+
+  const handleSongError = useCallback(() => {
+    toast.error(t('warnings.songError'))
+
+    if (replayGainEnabled || !replayGainError) {
+      setReplayGainEnabled(false)
+      setReplayGainError(true)
+      window.location.reload()
+    }
+  }, [
+    replayGainEnabled,
+    replayGainError,
+    setReplayGainEnabled,
+    setReplayGainError,
+    t,
+  ])
+
+  const handleRadioError = useCallback(() => {
+    toast.error(t('radios.error'))
+    setPlayingState(false)
+  }, [setPlayingState, t])
+
+  handlersRef.current = {
+    setupDuration,
+    setupProgress,
+    setupInitialVolume,
+    handleSongEnded,
+    sendFinishProgress,
+    handleSongError,
+    handleRadioError,
+  }
+
+  const gainValue = useMemo(() => {
+    const audioVolume = volume / 100
+
+    if (!trackReplayGain || !replayGainEnabled) {
+      return audioVolume
+    }
+
+    return audioVolume * calculateReplayGain(trackReplayGain)
+  }, [trackReplayGain, replayGainEnabled, volume])
+
+  // Load song src when it changes
+  useEffect(() => {
+    if (!songId || !songStreamUrl) return
+    songBackend.current!.load(songStreamUrl)
+  }, [songStreamUrl, songId])
+
+  // Load radio src when stream changes
+  useEffect(() => {
+    if (!radio?.streamUrl) return
+    radioBackend.current!.load(radio.streamUrl)
+  }, [radio?.streamUrl])
+
+  // Load podcast src when episode changes
+  useEffect(() => {
+    if (!podcast?.audio_url) return
+    podcastBackend.current!.load(getProxyURL(podcast.audio_url))
+  }, [podcast?.audio_url])
+
+  // Pause backends that are not active when media type switches
+  useEffect(() => {
+    if (!isSong) songBackend.current?.pause()
+    if (!isRadio) radioBackend.current?.pause()
+    if (!isPodcast) podcastBackend.current?.pause()
+  }, [isSong, isRadio, isPodcast])
+
+  // Song loop
+  useEffect(() => {
+    songBackend.current!.loop = loopState === LoopState.One
+  }, [loopState])
+
+  // Podcast playback rate
+  useEffect(() => {
+    if (!isPodcast) return
+    podcastBackend.current!.playbackRate = currentPlaybackRate
+  }, [currentPlaybackRate, isPodcast])
+
+  // Reset Web Audio nodes when replayGain errors
+  useEffect(() => {
+    if (replayGainError) songBackend.current?.resetWebAudio()
+  }, [replayGainError])
+
+  // Apply ReplayGain
+  useEffect(() => {
+    if (!isSong || replayGainError) return
+    songBackend.current!.setGain(gainValue, trackReplayGain)
+  }, [gainValue, isSong, replayGainError, trackReplayGain])
+
+  // Play/pause — song
+  // biome-ignore lint/correctness/useExhaustiveDependencies: songStreamUrl re-triggers play on track change
+  useEffect(() => {
+    async function handle() {
+      try {
+        if (isPlaying) {
+          await songBackend.current!.play()
+        } else {
+          songBackend.current!.pause()
+        }
+      } catch (error) {
+        logger.error('Audio playback failed', error)
+        handlersRef.current.handleSongError()
+      }
+    }
+    if (isSong) handle()
+  }, [isPlaying, isSong, songStreamUrl])
+
+  // Play/pause — radio (reloads stream each play for fresh connection)
+  useEffect(() => {
+    async function handle() {
+      const backend = radioBackend.current!
+      try {
+        if (isPlaying && radio?.streamUrl) {
+          backend.load(radio.streamUrl)
+          await backend.play()
+        } else {
+          backend.pause()
+        }
+      } catch (error) {
+        logger.error('Radio playback failed', error)
+        handlersRef.current.handleRadioError()
+      }
+    }
+    if (isRadio) handle()
+  }, [isPlaying, isRadio, radio?.streamUrl])
+
+  // Play/pause — podcast
+  // biome-ignore lint/correctness/useExhaustiveDependencies: podcast?.audio_url re-triggers play on episode change
+  useEffect(() => {
+    async function handle() {
+      try {
+        if (isPlaying) {
+          await podcastBackend.current!.play()
+        } else {
+          podcastBackend.current!.pause()
+        }
+      } catch (error) {
+        logger.error('Podcast playback failed', error)
+      }
+    }
+    if (isPodcast) handle()
+  }, [isPlaying, isPodcast, podcast?.audio_url])
+
+  const contextValue = useMemo(
+    () => ({
+      songBackend: songBackend.current!,
+      radioBackend: radioBackend.current!,
+      podcastBackend: podcastBackend.current!,
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+
+  return (
+    <AudioBackendContext.Provider value={contextValue}>
+      {children}
+    </AudioBackendContext.Provider>
+  )
+}
diff --git a/src/lib/audio/backend.ts b/src/lib/audio/backend.ts
new file mode 100644
index 000000000..d231f9591
--- /dev/null
+++ b/src/lib/audio/backend.ts
@@ -0,0 +1,23 @@
+import { ReplayGainParams } from '@/utils/replayGain'
+
+export interface AudioBackendCallbacks {
+  onPlay?: () => void
+  onPause?: () => void
+  onLoadedMetadata?: () => void
+  onTimeUpdate?: () => void
+  onEnded?: () => void
+  onLoadStart?: () => void
+  onError?: () => void
+}
+
+export interface AudioBackend {
+  load(src: string): void
+  play(): Promise<void>
+  pause(): void
+  seek(seconds: number): void
+  getCurrentTime(): number
+  getDuration(): number
+  setVolume(value: number): void
+  setGain?(linearGain: number, replayGain?: ReplayGainParams): void
+  destroy(): void
+}
diff --git a/src/lib/audio/html-audio-backend.ts b/src/lib/audio/html-audio-backend.ts
new file mode 100644
index 000000000..ee30cf17a
--- /dev/null
+++ b/src/lib/audio/html-audio-backend.ts
@@ -0,0 +1,172 @@
+import {
+  AudioContext,
+  type IAudioContext,
+  type IGainNode,
+  type IMediaElementAudioSourceNode,
+} from 'standardized-audio-context'
+import { logger } from '@/utils/logger'
+import { ReplayGainParams } from '@/utils/replayGain'
+import { AudioBackend, AudioBackendCallbacks } from './backend'
+
+type IAudioSource = IMediaElementAudioSourceNode<IAudioContext>
+
+export class HTMLAudioBackend implements AudioBackend {
+  private audio: HTMLAudioElement
+  private audioContextRef: IAudioContext | null = null
+  private sourceNodeRef: IAudioSource | null = null
+  private gainNodeRef: IGainNode<IAudioContext> | null = null
+  private useWebAudio: boolean
+  private eventController = new AbortController()
+
+  constructor(callbacks: AudioBackendCallbacks = {}, useWebAudio = false) {
+    this.audio = new Audio()
+    this.useWebAudio = useWebAudio
+    if (useWebAudio) {
+      this.audio.crossOrigin = 'anonymous'
+    }
+
+    const { signal } = this.eventController
+    if (callbacks.onPlay) this.audio.addEventListener('play', callbacks.onPlay, { signal })
+    if (callbacks.onPause)
+      this.audio.addEventListener('pause', callbacks.onPause, { signal })
+    if (callbacks.onLoadedMetadata)
+      this.audio.addEventListener('loadedmetadata', callbacks.onLoadedMetadata, { signal })
+    if (callbacks.onTimeUpdate)
+      this.audio.addEventListener('timeupdate', callbacks.onTimeUpdate, { signal })
+    if (callbacks.onEnded)
+      this.audio.addEventListener('ended', callbacks.onEnded, { signal })
+    if (callbacks.onLoadStart)
+      this.audio.addEventListener('loadstart', callbacks.onLoadStart, { signal })
+    if (callbacks.onError)
+      this.audio.addEventListener('error', callbacks.onError, { signal })
+  }
+
+  load(src: string): void {
+    this.audio.src = src
+  }
+
+  async play(): Promise<void> {
+    if (this.useWebAudio) await this.resumeAudioContext()
+    return this.audio.play()
+  }
+
+  pause(): void {
+    if (this.audio.networkState === this.audio.NETWORK_EMPTY) return
+    this.audio.pause()
+  }
+
+  seek(seconds: number): void {
+    this.audio.currentTime = seconds
+  }
+
+  getCurrentTime(): number {
+    return this.audio.currentTime
+  }
+
+  getDuration(): number {
+    return this.audio.duration
+  }
+
+  setVolume(value: number): void {
+    this.audio.volume = value
+  }
+
+  get loop(): boolean {
+    return this.audio.loop
+  }
+
+  set loop(value: boolean) {
+    this.audio.loop = value
+  }
+
+  get playbackRate(): number {
+    return this.audio.playbackRate
+  }
+
+  set playbackRate(value: number) {
+    this.audio.playbackRate = value
+  }
+
+  get preload(): string {
+    return this.audio.preload
+  }
+
+  set preload(value: string) {
+    this.audio.preload = value
+  }
+
+  setGain(linearGain: number, replayGain?: ReplayGainParams): void {
+    if (!this.useWebAudio) return
+    this.setupAudioContext()
+
+    if (!this.audioContextRef || !this.gainNodeRef) return
+
+    if (!linearGain || Number.isNaN(linearGain)) {
+      logger.error('Invalid gain value', { linearGain })
+      return
+    }
+
+    const currentTime = this.audioContextRef.currentTime
+    logger.info('Replay Gain', { linearGain, ...replayGain })
+    this.gainNodeRef.gain.setValueAtTime(linearGain, currentTime)
+  }
+
+  resetWebAudio(): void {
+    if (this.sourceNodeRef) {
+      this.sourceNodeRef.disconnect()
+      this.sourceNodeRef = null
+    }
+    if (this.gainNodeRef) {
+      this.gainNodeRef.disconnect()
+      this.gainNodeRef = null
+    }
+    if (this.audioContextRef) {
+      this.audioContextRef.close()
+      this.audioContextRef = null
+    }
+  }
+
+  destroy(): void {
+    // Detach all listeners before resetting the element so that cleanup-triggered
+    // load/error events (e.g. React Strict Mode unmount) don't fire callbacks.
+    this.eventController.abort()
+    this.resetWebAudio()
+    this.audio.pause()
+    this.audio.src = ''
+    this.audio.load()
+  }
+
+  private setupAudioContext(): void {
+    if (!this.useWebAudio) return
+
+    if (!this.audioContextRef) {
+      this.audioContextRef = new AudioContext()
+    }
+
+    const ctx = this.audioContextRef
+
+    if (!this.sourceNodeRef) {
+      this.sourceNodeRef = ctx.createMediaElementSource(this.audio)
+    }
+
+    if (!this.gainNodeRef) {
+      this.gainNodeRef = ctx.createGain()
+      this.sourceNodeRef.connect(this.gainNodeRef)
+      this.gainNodeRef.connect(ctx.destination)
+    }
+  }
+
+  private async resumeAudioContext(): Promise<void> {
+    const ctx = this.audioContextRef
+    if (!ctx) return
+
+    logger.info('AudioContext State', { state: ctx.state })
+
+    if (ctx.state === 'suspended') {
+      await ctx.resume()
+    }
+    if (ctx.state === 'closed') {
+      this.setupAudioContext()
+    }
+  }
+}
diff --git a/src/store/player.store.ts b/src/store/player.store.ts
index 4b9862c1f..3cab35115 100644
--- a/src/store/player.store.ts
+++ b/src/store/player.store.ts
@@ -1,4 +1,3 @@
-import { produce } from 'immer'
 import clamp from 'lodash/clamp'
 import merge from 'lodash/merge'
 import omit from 'lodash/omit'
@@ -55,7 +54,6 @@ export const usePlayerStore = createWithEqualityFn<IPlayerContext>()(
             volume: 100,
             currentDuration: 0,
             mediaType: 'song',
-            audioPlayerRef: null,
             mainDrawerState: false,
             queueState: false,
             lyricsState: false,
@@ -584,7 +582,6 @@ export const usePlayerStore = createWithEqualityFn<IPlayerContext>()(
                 state.playerState.hasSyncedTheCurrentTrack = false
                 state.playerState.hasScrobbledTheCurrentTrack = false
                 state.playerState.currentDuration = 0
-                state.playerState.audioPlayerRef = null
                 state.settings.colors.currentSongColor = null
                 state.listenTime.accumulated = 0
                 state.playerState.playbackContext.source = null
@@ -727,13 +724,6 @@ export const usePlayerStore = createWithEqualityFn<IPlayerContext>()(
                 state.playerState.currentPlaybackRate = value
               })
             },
-            setAudioPlayerRef: (audioPlayer) => {
-              set(
-                produce((state: IPlayerContext) => {
-                  state.playerState.audioPlayerRef = audioPlayer
-                }),
-              )
-            },
             removeSongFromQueue: (id) => {
               const {
                 currentList,
@@ -979,7 +969,6 @@ export const usePlayerStore = createWithEqualityFn<IPlayerContext>()(
             'songlist',
             'actions',
             'playerState.isPlaying',
-            'playerState.audioPlayerRef',
             'playerState.mainDrawerState',
             'playerState.queueState',
             'playerState.lyricsState',
@@ -1262,9 +1251,6 @@ export const usePlayerPrevAndNext = () =>
     hasNext: state.playerState.hasNext,
   }))
 
-export const usePlayerRef = () =>
-  usePlayerStore((state) => state.playerState.audioPlayerRef)
-
 export const getVolume = () => usePlayerStore.getState().playerState.volume
 
 export const useMainDrawerState = () =>
diff --git a/src/types/playerContext.ts b/src/types/playerContext.ts
index c7106b7e9..75ebbd5cf 100644
--- a/src/types/playerContext.ts
+++ b/src/types/playerContext.ts
@@ -47,7 +47,6 @@ export interface IPlayerState {
   currentDuration: number
   mediaType: 'song' | 'radio' | 'podcast'
   currentPlaybackRate: number
-  audioPlayerRef: HTMLAudioElement | null
   mainDrawerState: boolean
   queueState: boolean
   lyricsState: boolean
@@ -188,7 +187,6 @@ export interface IPlayerActions {
   handleVolumeWheel: (isScrollingDown: boolean) => void
   setCurrentDuration: (duration: number) => void
   setPlayRadio: (list: Radio[], index: number) => void
-  setAudioPlayerRef: (ref: HTMLAudioElement) => void
   setNextOnQueue: (songlist: ISong[]) => void
   setLastOnQueue: (songlist: ISong[]) => void
   removeSongFromQueue: (id: string) => void

From fe000595e8089e7decbbb4644156bd385240d6a4 Mon Sep 17 00:00:00 2001
From: Brad Taylor <brad.taylor@gmail.com>
Date: Tue, 30 Jun 2026 07:02:53 -0700
Subject: [PATCH 2/3] feat: native macos AVPlayer backend

---
 .gitignore                               |   5 +-
 electron-builder.yml                     |   3 +
 electron/main/core/avPlayerBridge.ts     | 153 ++++++++++++++++
 electron/main/core/avPlayerProxy.ts      | 111 +++++++++++
 electron/main/core/events.ts             |   7 +-
 electron/preload/index.ts                |  19 +-
 electron/preload/types.ts                |  31 ++++
 native/avplayer-helper.swift             | 224 +++++++++++++++++++++++
 package.json                             |   1 +
 src/lib/audio/audio-backend-provider.tsx | 102 +++++++----
 src/lib/audio/avplayer-backend.ts        | 150 +++++++++++++++
 src/lib/audio/backend.ts                 |   3 +
 12 files changed, 775 insertions(+), 34 deletions(-)
 create mode 100644 electron/main/core/avPlayerBridge.ts
 create mode 100644 electron/main/core/avPlayerProxy.ts
 create mode 100644 native/avplayer-helper.swift
 create mode 100644 src/lib/audio/avplayer-backend.ts

diff --git a/.gitignore b/.gitignore
index fccba355e..f35dbce2d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -33,4 +33,7 @@ env-config.js
 
 out
 
-.pnpm-store/*
\ No newline at end of file
+.pnpm-store/*
+
+# Compiled native binary (built from native/avplayer-helper.swift via pnpm build:native:mac)
+native/avplayer-helper
\ No newline at end of file
diff --git a/electron-builder.yml b/electron-builder.yml
index 9bdfbfe5c..6559295ee 100644
--- a/electron-builder.yml
+++ b/electron-builder.yml
@@ -40,6 +40,9 @@ mac:
   notarize: false
   identity: "-"
   icon: ./build/icon.icns
+  extraResources:
+    - from: native/avplayer-helper
+      to: avplayer-helper
   target:
     - target: dmg
       arch:
diff --git a/electron/main/core/avPlayerBridge.ts b/electron/main/core/avPlayerBridge.ts
new file mode 100644
index 000000000..a2a71e5d8
--- /dev/null
+++ b/electron/main/core/avPlayerBridge.ts
@@ -0,0 +1,153 @@
+import { ChildProcess, spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { platform } from '@electron-toolkit/utils'
+import { app, BrowserWindow, ipcMain } from 'electron'
+import {
+  AvPlayerCommandPayload,
+  AvPlayerEventPayload,
+  IpcChannels,
+} from '../../preload/types'
+import {
+  registerProxyStream,
+  startAvPlayerProxy,
+  stopAvPlayerProxy,
+  unregisterProxyStream,
+} from './avPlayerProxy'
+
+let helperProcess: ChildProcess | null = null
+
+function getHelperPath(): string {
+  const binaryName = 'avplayer-helper'
+  if (process.env.NODE_ENV === 'development') {
+    return join(app.getAppPath(), 'native', binaryName)
+  }
+  return join(process.resourcesPath, binaryName)
+}
+
+function sendToHelper(payload: object) {
+  if (!helperProcess?.stdin) {
+    console.warn(
+      '[AVPlayerBridge] sendToHelper: no helper process stdin',
+      payload,
+    )
+    return
+  }
+  helperProcess.stdin.write(JSON.stringify(payload) + '\n')
+}
+
+export async function initAvPlayerBridge(window: BrowserWindow) {
+  if (!platform.isMacOS) {
+    console.log('[AVPlayerBridge] skipping — not macOS')
+    return
+  }
+  if (helperProcess) {
+    console.warn(
+      '[AVPlayerBridge] initAvPlayerBridge called while already initialized — ignoring',
+    )
+    return
+  }
+
+  const helperPath = getHelperPath()
+  console.log(
+    '[AVPlayerBridge] helper path:',
+    helperPath,
+    'exists:',
+    existsSync(helperPath),
+  )
+
+  if (!existsSync(helperPath)) {
+    console.warn(
+      '[AVPlayerBridge] helper binary not found — run pnpm build:native:mac',
+    )
+    return
+  }
+
+  // Start local HTTP proxy — Electron's subprocess can't make direct outgoing
+  // HTTPS requests on macOS, but can connect to localhost. The proxy uses
+  // Electron's net module to fetch the actual stream and serves it locally.
+  const port = await startAvPlayerProxy()
+  console.log('[AVPlayerBridge] proxy started on port', port)
+
+  // Minimal environment — passing the full process.env leaks Electron/Chromium
+  // IPC socket paths and Mach port variables that interfere with AVFoundation's
+  // own XPC and networking channels inside the subprocess.
+  const env: NodeJS.ProcessEnv = {
+    HOME: process.env.HOME,
+    TMPDIR: process.env.TMPDIR,
+    USER: process.env.USER,
+    PATH: process.env.PATH || '/usr/bin:/bin:/usr/sbin:/sbin',
+  }
+
+  helperProcess = spawn(helperPath, [], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env,
+  })
+  console.log('[AVPlayerBridge] helper spawned, pid:', helperProcess.pid)
+
+  let lineBuffer = ''
+  // stdout is non-null: we spawned with stdio: ['pipe', 'pipe', 'pipe']
+  helperProcess.stdout!.setEncoding('utf8')
+  helperProcess.stdout!.on('data', (chunk: string) => {
+    lineBuffer += chunk
+    const lines = lineBuffer.split('\n')
+    lineBuffer = lines.pop() ?? ''
+
+    for (const line of lines) {
+      if (!line.trim()) continue
+      try {
+        const event = JSON.parse(line) as AvPlayerEventPayload
+        if (!window.isDestroyed()) {
+          window.webContents.send(IpcChannels.AvPlayerEvent, event)
+        }
+      } catch {
+        console.warn('[AVPlayerBridge] malformed line from helper:', line)
+      }
+    }
+  })
+
+  helperProcess.stderr!.setEncoding('utf8')
+  helperProcess.stderr!.on('data', (chunk: string) => {
+    console.log('[avplayer-helper]', chunk.trim())
+  })
+
+  helperProcess.on('exit', (code, signal) => {
+    console.log(
+      '[AVPlayerBridge] helper exited — code:',
+      code,
+      'signal:',
+      signal,
+    )
+    helperProcess = null
+  })
+
+  helperProcess.on('error', (err) => {
+    console.error('[AVPlayerBridge] helper spawn error:', err)
+  })
+
+  ipcMain.on(
+    IpcChannels.AvPlayerCommand,
+    (_, payload: AvPlayerCommandPayload) => {
+      if (payload.type === 'load') {
+        // Replace the remote URL with a proxy localhost URL so the helper can
+        // reach the stream (direct HTTPS from the subprocess is blocked by macOS).
+        const proxyUrl = registerProxyStream(payload.id, payload.url)
+        sendToHelper({ ...payload, url: proxyUrl })
+      } else {
+        if (payload.type === 'destroy') unregisterProxyStream(payload.id)
+        sendToHelper(payload)
+      }
+    },
+  )
+
+  console.log('[AVPlayerBridge] ready')
+}
+
+export function destroyAvPlayerBridge() {
+  ipcMain.removeAllListeners(IpcChannels.AvPlayerCommand)
+  if (helperProcess) {
+    helperProcess.kill()
+    helperProcess = null
+  }
+  stopAvPlayerProxy()
+}
diff --git a/electron/main/core/avPlayerProxy.ts b/electron/main/core/avPlayerProxy.ts
new file mode 100644
index 000000000..43e272b41
--- /dev/null
+++ b/electron/main/core/avPlayerProxy.ts
@@ -0,0 +1,111 @@
+import * as http from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { net } from 'electron'
+
+let server: http.Server | null = null
+let proxyPort = 0
+
+// id → original URL
+const streams = new Map<string, string>()
+
+// Hop-by-hop headers must not be forwarded between proxy hops. Forwarding
+// transfer-encoding in particular confuses AVFoundation because Node has
+// already decoded chunked upstream data before we re-send it.
+const HOP_BY_HOP = new Set([
+  'transfer-encoding',
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'upgrade',
+])
+
+function handleRequest(req: http.IncomingMessage, res: http.ServerResponse) {
+  // Strip query string — the ?t= cache-buster is only for AVFoundation's URL cache
+  const id = (req.url?.split('?')[0] ?? '').replace(/^\//, '')
+  const url = streams.get(id)
+
+  if (!url) {
+    res.writeHead(404)
+    res.end()
+    return
+  }
+
+  const headers: Record<string, string> = {}
+  if (req.headers.range) headers.Range = req.headers.range as string
+
+  const upstream = net.request({ url, method: 'GET', headers })
+
+  upstream.on('response', (upRes) => {
+    const forwardHeaders: Record<string, string | string[]> = {}
+    for (const [k, v] of Object.entries(upRes.headers)) {
+      if (v !== undefined && !HOP_BY_HOP.has(k.toLowerCase())) {
+        forwardHeaders[k] = v as string | string[]
+      }
+    }
+    // Tell AVFoundation the connection closes after this response.
+    // Without this, the keep-alive connection stays open and AVFoundation
+    // treats the stream as a live/infinite source, never firing
+    // AVPlayerItemDidPlayToEndTime.
+    forwardHeaders.connection = 'close'
+    res.writeHead(upRes.statusCode ?? 200, forwardHeaders)
+
+    let done = false
+    upRes.on('data', (chunk: Buffer) => res.write(chunk))
+    upRes.on('end', () => {
+      done = true
+      res.end()
+    })
+    upRes.on('error', (err) => {
+      // Ignore errors after the response completes — these are harmless abort
+      // signals from req.on('close') cleaning up an already-finished upstream.
+      if (!done) {
+        console.error('[AVPlayerProxy] upstream error:', err.message)
+        res.destroy()
+      }
+    })
+  })
+
+  upstream.on('error', (err) => {
+    console.error('[AVPlayerProxy] request error:', err.message)
+    if (!res.headersSent) res.writeHead(502)
+    res.end()
+  })
+
+  req.on('close', () => upstream.abort())
+  upstream.end()
+}
+
+export function startAvPlayerProxy(): Promise<number> {
+  if (server) return Promise.resolve(proxyPort)
+
+  return new Promise((resolve, reject) => {
+    server = http.createServer(handleRequest)
+    server.on('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      proxyPort = (server!.address() as AddressInfo).port
+      console.log('[AVPlayerProxy] listening on port', proxyPort)
+      resolve(proxyPort)
+    })
+  })
+}
+
+export function stopAvPlayerProxy() {
+  server?.close()
+  server = null
+  proxyPort = 0
+  streams.clear()
+}
+
+export function registerProxyStream(id: string, url: string): string {
+  streams.set(id, url)
+  // The ?t= cache-buster ensures AVFoundation doesn't reuse a cached response
+  // from a previous song that happened to use the same player id.
+  return `http://127.0.0.1:${proxyPort}/${id}?t=${Date.now()}`
+}
+
+export function unregisterProxyStream(id: string) {
+  streams.delete(id)
+}
diff --git a/electron/main/core/events.ts b/electron/main/core/events.ts
index d245ea493..5d486e600 100644
--- a/electron/main/core/events.ts
+++ b/electron/main/core/events.ts
@@ -7,13 +7,14 @@ import {
 } from '../../preload/types'
 import { isQuitting } from '../index'
 import { tray, updateTray } from '../tray'
-import { updateDockMenu } from './dockMenu'
+import { destroyAvPlayerBridge, initAvPlayerBridge } from './avPlayerBridge'
 import { colorsState } from './colors'
 import {
   clearDiscordRpcActivity,
   RpcPayload,
   setDiscordRpcActivity,
 } from './discordRpc'
+import { updateDockMenu } from './dockMenu'
 import { playerState } from './playerState'
 import { getAppSetting, ISettingPayload, saveAppSettings } from './settings'
 import { setTaskbarButtons } from './taskbar'
@@ -104,6 +105,10 @@ export function setupIpcEvents(window: BrowserWindow | null) {
   if (!window) return
 
   resetIpcEvents()
+  destroyAvPlayerBridge()
+  initAvPlayerBridge(window).catch((err) =>
+    console.error('[AVPlayerBridge] init failed:', err),
+  )
 
   ipcMain.on(IpcChannels.ToggleFullscreen, (_, isFullscreen: boolean) => {
     window.setFullScreen(isFullscreen)
diff --git a/electron/preload/index.ts b/electron/preload/index.ts
index 8743e946d..97f29b745 100644
--- a/electron/preload/index.ts
+++ b/electron/preload/index.ts
@@ -1,6 +1,12 @@
 import { electronAPI } from '@electron-toolkit/preload'
 import { contextBridge, ipcRenderer } from 'electron'
-import { IAonsokuAPI, IpcChannels, PlayerStateListenerActions } from './types'
+import {
+  AvPlayerCommandPayload,
+  AvPlayerEventPayload,
+  IAonsokuAPI,
+  IpcChannels,
+  PlayerStateListenerActions,
+} from './types'
 
 // Custom APIs for renderer
 const api: IAonsokuAPI = {
@@ -82,6 +88,17 @@ const api: IAonsokuAPI = {
   onUpdateDownloaded: (callback) => {
     ipcRenderer.on(IpcChannels.UpdateDownloaded, (_, info) => callback(info))
   },
+  avPlayer: {
+    command: (payload: AvPlayerCommandPayload) => {
+      ipcRenderer.send(IpcChannels.AvPlayerCommand, payload)
+    },
+    onEvent: (callback: (event: AvPlayerEventPayload) => void) => {
+      const listener = (_: Electron.IpcRendererEvent, event: AvPlayerEventPayload) =>
+        callback(event)
+      ipcRenderer.on(IpcChannels.AvPlayerEvent, listener)
+      return () => ipcRenderer.removeListener(IpcChannels.AvPlayerEvent, listener)
+    },
+  },
 }
 
 // Use `contextBridge` APIs to expose Electron APIs to
diff --git a/electron/preload/types.ts b/electron/preload/types.ts
index 54fa6a5d2..3df94afaf 100644
--- a/electron/preload/types.ts
+++ b/electron/preload/types.ts
@@ -8,6 +8,31 @@ import { RpcPayload } from '../main/core/discordRpc'
 import { IDownloadPayload } from '../main/core/downloads'
 import { ISettingPayload } from '../main/core/settings'
 
+export type AvPlayerCommandPayload =
+  | { type: 'load'; id: string; url: string }
+  | { type: 'play'; id: string }
+  | { type: 'pause'; id: string }
+  | { type: 'seek'; id: string; seconds: number }
+  | { type: 'setVolume'; id: string; value: number }
+  | { type: 'setLoop'; id: string; loop: boolean }
+  | { type: 'setRate'; id: string; rate: number }
+  | { type: 'destroy'; id: string }
+
+export type AvPlayerEventPayload = {
+  id: string
+  type:
+    | 'play'
+    | 'pause'
+    | 'timeupdate'
+    | 'loadedmetadata'
+    | 'ended'
+    | 'loadstart'
+    | 'error'
+  time?: number
+  duration?: number
+  message?: string
+}
+
 export enum IpcChannels {
   FullscreenStatus = 'fullscreen-status',
   ToggleFullscreen = 'toggle-fullscreen',
@@ -35,6 +60,8 @@ export enum IpcChannels {
   UpdateError = 'update-error',
   DownloadProgress = 'download-progress',
   UpdateDownloaded = 'update-downloaded',
+  AvPlayerCommand = 'avplayer-command',
+  AvPlayerEvent = 'avplayer-event',
 }
 
 export type OverlayColors = {
@@ -89,4 +116,8 @@ export interface IAonsokuAPI {
   onUpdateError: (callback: (error: string) => void) => void
   onDownloadProgress: (callback: (progress: ProgressInfo) => void) => void
   onUpdateDownloaded: (callback: (info: UpdateDownloadedEvent) => void) => void
+  avPlayer: {
+    command: (payload: AvPlayerCommandPayload) => void
+    onEvent: (callback: (event: AvPlayerEventPayload) => void) => () => void
+  }
 }
diff --git a/native/avplayer-helper.swift b/native/avplayer-helper.swift
new file mode 100644
index 000000000..a7ec11243
--- /dev/null
+++ b/native/avplayer-helper.swift
@@ -0,0 +1,224 @@
+import AVFoundation
+import Foundation
+
+// ─── Per-backend player state ─────────────────────────────────────────────────
+
+// Class (not struct) so closures can mutate fields like endEmitted directly.
+final class PlayerState {
+  var player: AVPlayer
+  var timeObserver: Any?
+  var endObserver: NSObjectProtocol?
+  var statusObservation: NSKeyValueObservation?
+  var timeControlObservation: NSKeyValueObservation?
+  var endEmitted = false
+
+  init(player: AVPlayer) {
+    self.player = player
+  }
+}
+
+var states: [String: PlayerState] = [:]
+
+// ─── stdout event emission ────────────────────────────────────────────────────
+
+func emit(_ dict: [String: Any]) {
+  guard let data = try? JSONSerialization.data(withJSONObject: dict, options: []),
+    let line = String(data: data, encoding: .utf8)
+  else { return }
+  print(line)
+  fflush(stdout)
+}
+
+func log(_ message: String) {
+  fputs("[avplayer-helper] \(message)\n", stderr)
+  fflush(stderr)
+}
+
+// ─── Per-backend cleanup ──────────────────────────────────────────────────────
+
+func teardown(id: String) {
+  guard let state = states[id] else { return }
+  // Deactivate observations before pausing so no play/pause events leak out
+  // during teardown (e.g., when load() replaces a currently-playing item).
+  state.timeControlObservation = nil
+  state.statusObservation = nil
+  if let obs = state.timeObserver {
+    state.player.removeTimeObserver(obs)
+  }
+  if let obs = state.endObserver {
+    NotificationCenter.default.removeObserver(obs)
+  }
+  state.player.pause()
+  states.removeValue(forKey: id)
+}
+
+// ─── Command dispatch ─────────────────────────────────────────────────────────
+
+func handle(_ cmd: [String: Any]) {
+  guard let type = cmd["type"] as? String, let id = cmd["id"] as? String else {
+    log("ignoring command with missing type/id: \(cmd)")
+    return
+  }
+
+  switch type {
+
+  case "load":
+    guard let urlStr = cmd["url"] as? String else {
+      log("load: url key missing or not a string")
+      emit(["type": "error", "id": id, "message": "Missing URL"])
+      return
+    }
+    guard let url = URL(string: urlStr) else {
+      log("load: URL(string:) returned nil for: \(urlStr)")
+      emit(["type": "error", "id": id, "message": "Invalid URL: \(urlStr)"])
+      return
+    }
+
+    log("load: url=\(urlStr)")
+    teardown(id: id)
+
+    let item = AVPlayerItem(url: url)
+    let player = AVPlayer(playerItem: item)
+    let state = PlayerState(player: player)
+
+    emit(["type": "loadstart", "id": id])
+
+    state.statusObservation = item.observe(\.status, options: [.new]) { observedItem, _ in
+      switch observedItem.status {
+      case .readyToPlay:
+        let secs = CMTimeGetSeconds(observedItem.duration)
+        log("readyToPlay: duration=\(secs) id=\(id)")
+        if secs.isFinite && secs > 0 {
+          emit(["type": "loadedmetadata", "id": id, "duration": secs])
+        }
+      case .failed:
+        let msg = observedItem.error?.localizedDescription ?? "Playback failed"
+        log("KVO failed: \(msg)")
+        emit(["type": "error", "id": id, "message": msg])
+      default:
+        break
+      }
+    }
+
+    // Drive play/pause events from actual player state rather than echoing
+    // commands. This correctly handles system-triggered pauses (audio focus
+    // loss, Bluetooth disconnect) and avoids false events from rapid toggling.
+    // .waitingToPlayAtSpecifiedRate means buffering — not a play/pause transition.
+    state.timeControlObservation = player.observe(\.timeControlStatus, options: [.new]) { _, change in
+      switch change.newValue {
+      case .playing:
+        emit(["type": "play", "id": id])
+      case .paused:
+        emit(["type": "pause", "id": id])
+      default:
+        break
+      }
+    }
+
+    // Periodic time updates (every 0.5 s).
+    // Also the fallback end detector: if the HTTP stream doesn't close cleanly,
+    // AVFoundation may never fire AVPlayerItemDidPlayToEndTime. Detect end by
+    // time proximity instead (within 0.5 s of duration while playing).
+    let interval = CMTime(seconds: 0.5, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
+    state.timeObserver = player.addPeriodicTimeObserver(
+      forInterval: interval, queue: .main
+    ) { [weak player, weak state] time in
+      let secs = CMTimeGetSeconds(time)
+      guard secs.isFinite else { return }
+      emit(["type": "timeupdate", "id": id, "time": secs])
+      guard let s = state, !s.endEmitted,
+            let p = player,
+            p.timeControlStatus == .playing,
+            let dur = p.currentItem.map({ CMTimeGetSeconds($0.duration) }),
+            dur.isFinite && dur > 0 && secs >= dur - 0.5 else { return }
+      s.endEmitted = true
+      emit(["type": "ended", "id": id])
+    }
+
+    // Primary end notification — fires when HTTP response closes cleanly.
+    state.endObserver = NotificationCenter.default.addObserver(
+      forName: .AVPlayerItemDidPlayToEndTime, object: item, queue: .main
+    ) { [weak state] _ in
+      guard let s = state, !s.endEmitted else { return }
+      s.endEmitted = true
+      emit(["type": "ended", "id": id])
+    }
+
+    states[id] = state
+
+  case "play":
+    states[id]?.player.play()
+
+  case "pause":
+    states[id]?.player.pause()
+
+  case "seek":
+    guard let seconds = cmd["seconds"] as? Double else { return }
+    let time = CMTime(seconds: seconds, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
+    states[id]?.player.seek(to: time, toleranceBefore: .zero, toleranceAfter: .zero)
+
+  case "setVolume":
+    guard let value = cmd["value"] as? Float else { return }
+    states[id]?.player.volume = max(0, min(1, value))
+
+  case "setRate":
+    guard let rate = cmd["rate"] as? Float else { return }
+    states[id]?.player.rate = rate
+
+  case "destroy":
+    teardown(id: id)
+
+  default:
+    break
+  }
+}
+
+// ─── stdin command reader ─────────────────────────────────────────────────────
+
+var inputBuffer = Data()
+
+// Close all file descriptors inherited from the parent (Electron/Chromium opens
+// many IPC sockets and Mach ports that can interfere with AVFoundation's own
+// XPC/networking channels). Keep only stdin(0), stdout(1), stderr(2).
+do {
+  var closedCount = 0
+  for fd in Int32(3)..<Int32(1024) {
+    if fcntl(fd, F_GETFD) >= 0 {
+      close(fd)
+      closedCount += 1
+    }
+  }
+  if closedCount > 0 {
+    log("closed \(closedCount) inherited fds")
+  }
+}
+
+log("avplayer-helper started")
+
+FileHandle.standardInput.readabilityHandler = { fh in
+  let chunk = fh.availableData
+  guard !chunk.isEmpty else {
+    log("stdin closed, exiting")
+    DispatchQueue.main.async { exit(0) }
+    return
+  }
+
+  // Dispatch to main so AVPlayer is created/used on the main thread, where
+  // dispatchMain() is active and AVFoundation callbacks can be delivered.
+  DispatchQueue.main.async {
+    inputBuffer.append(chunk)
+
+    while let newline = inputBuffer.firstIndex(of: UInt8(ascii: "\n")) {
+      let lineData = inputBuffer[inputBuffer.startIndex..<newline]
+      inputBuffer = inputBuffer[inputBuffer.index(after: newline)...]
+
+      if let json = try? JSONSerialization.jsonObject(with: lineData) as? [String: Any] {
+        handle(json)
+      } else if !lineData.isEmpty {
+        log("failed to parse JSON: \(String(data: lineData, encoding: .utf8) ?? "<non-utf8>")")
+      }
+    }
+  }
+}
+
+dispatchMain()
diff --git a/package.json b/package.json
index 0fa3a3827..acee8c42a 100644
--- a/package.json
+++ b/package.json
@@ -22,6 +22,7 @@
     "electron:start": "electron-vite preview",
     "electron:dev": "electron-vite dev --watch",
     "electron:build": "electron-vite build",
+    "build:native:mac": "swiftc native/avplayer-helper.swift -o native/avplayer-helper -framework Foundation -framework AVFoundation -framework CoreMedia -O",
     "postinstall": "electron-builder install-app-deps",
     "build:unpack": "electron-builder --dir",
     "build:win": "electron-builder --win",
diff --git a/src/lib/audio/audio-backend-provider.tsx b/src/lib/audio/audio-backend-provider.tsx
index 2f4d94a65..78c1f6147 100644
--- a/src/lib/audio/audio-backend-provider.tsx
+++ b/src/lib/audio/audio-backend-provider.tsx
@@ -19,9 +19,12 @@ import {
 } from '@/store/player.store'
 import { LoopState } from '@/types/playerContext'
 import { ensureSupportForAlac } from '@/utils/alac'
+import { isMacOS } from '@/utils/desktop'
 import { logger } from '@/utils/logger'
 import { calculateReplayGain, ReplayGainParams } from '@/utils/replayGain'
 import { AudioBackendContext } from './audio-backend-context'
+import { AVPlayerBackend } from './avplayer-backend'
+import { AudioBackend } from './backend'
 import { HTMLAudioBackend } from './html-audio-backend'
 
 export function AudioBackendProvider({ children }: { children: ReactNode }) {
@@ -55,6 +58,7 @@ export function AudioBackendProvider({ children }: { children: ReactNode }) {
   const radio = radioList[currentSongIndex]
   const podcast = podcastList[currentSongIndex]
   const songId = song?.id
+  const songDuration = song?.duration
 
   const songStreamUrl = useMemo(() => {
     if (!songId) return ''
@@ -64,10 +68,15 @@ export function AudioBackendProvider({ children }: { children: ReactNode }) {
     return getSongStreamUrl(
       songId,
       undefined,
-      ensureSupportForAlac(song.suffix),
+      ensureSupportForAlac(song?.suffix ?? ''),
       cacheBustToken,
     )
-  }, [songId, song, mediaCacheEnabled])
+    // song?.suffix is the only property used; using `song` (full object) as a dep
+    // causes the memo to recompute on every Zustand re-render where the song object
+    // gets a new reference, generating a new Date.now() token and re-triggering the
+    // load effect while the song is still playing.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [songId, song?.suffix, mediaCacheEnabled])
 
   const trackReplayGain = useMemo<ReplayGainParams>(() => {
     const preAmp = replayGainPreAmp
@@ -105,36 +114,53 @@ export function AudioBackendProvider({ children }: { children: ReactNode }) {
     handleRadioError: () => {},
   })
 
-  const songBackend = useRef<HTMLAudioBackend | null>(null)
-  const radioBackend = useRef<HTMLAudioBackend | null>(null)
-  const podcastBackend = useRef<HTMLAudioBackend | null>(null)
+  const songBackend = useRef<AudioBackend | null>(null)
+  const radioBackend = useRef<AudioBackend | null>(null)
+  const podcastBackend = useRef<AudioBackend | null>(null)
 
   if (!songBackend.current) {
-    songBackend.current = new HTMLAudioBackend(
-      {
-        onPlay: () => setPlayingState(true),
-        onPause: () => setPlayingState(false),
-        onLoadedMetadata: () => handlersRef.current.setupDuration(),
-        onTimeUpdate: () => handlersRef.current.setupProgress(),
-        onEnded: () => handlersRef.current.handleSongEnded(),
-        onLoadStart: () => handlersRef.current.setupInitialVolume(),
-        onError: () => handlersRef.current.handleSongError(),
+    const songCallbacks = {
+      onPlay: () => setPlayingState(true),
+      onPause: () => setPlayingState(false),
+      onLoadedMetadata: () => handlersRef.current.setupDuration(),
+      onTimeUpdate: () => handlersRef.current.setupProgress(),
+      onEnded: () => {
+        // LoopState.One: seek back to the start and replay. HTMLAudioBackend
+        // handles this natively via <audio>.loop so onEnded never fires there.
+        const backend = songBackend.current!
+        if (backend.loop) {
+          backend.seek(0)
+          backend
+            .play()
+            .catch((e) =>
+              logger.error('[AudioBackendProvider] loop replay failed', e),
+            )
+        } else {
+          handlersRef.current.handleSongEnded()
+        }
       },
-      !replayGainError,
-    )
+      onLoadStart: () => handlersRef.current.setupInitialVolume(),
+      onError: () => handlersRef.current.handleSongError(),
+    }
+    songBackend.current = isMacOS
+      ? new AVPlayerBackend('song', songCallbacks)
+      : new HTMLAudioBackend(songCallbacks, !replayGainError)
   }
 
   if (!radioBackend.current) {
-    radioBackend.current = new HTMLAudioBackend({
+    const radioCallbacks = {
       onPlay: () => setPlayingState(true),
       onPause: () => setPlayingState(false),
       onLoadStart: () => handlersRef.current.setupInitialVolume(),
       onError: () => handlersRef.current.handleRadioError(),
-    })
+    }
+    radioBackend.current = isMacOS
+      ? new AVPlayerBackend('radio', radioCallbacks)
+      : new HTMLAudioBackend(radioCallbacks)
   }
 
   if (!podcastBackend.current) {
-    podcastBackend.current = new HTMLAudioBackend({
+    const podcastCallbacks = {
       onPlay: () => setPlayingState(true),
       onPause: () => setPlayingState(false),
       onLoadedMetadata: () => handlersRef.current.setupDuration(),
@@ -144,19 +170,33 @@ export function AudioBackendProvider({ children }: { children: ReactNode }) {
         handlersRef.current.handleSongEnded()
       },
       onLoadStart: () => handlersRef.current.setupInitialVolume(),
-    })
-    podcastBackend.current.preload = 'auto'
+    }
+    if (isMacOS) {
+      podcastBackend.current = new AVPlayerBackend('podcast', podcastCallbacks)
+    } else {
+      const htmlBackend = new HTMLAudioBackend(podcastCallbacks)
+      htmlBackend.preload = 'auto'
+      podcastBackend.current = htmlBackend
+    }
   }
 
+  // Keep IPC listeners alive across React Strict Mode's simulated
+  // unmount+remount. Strict Mode runs cleanup then immediately re-runs setup.
+  // detachListener() removes only the IPC listener (not the helper player),
+  // and reconnect() re-registers it on the next setup. The helper player
+  // survives because load() always calls teardown() before creating a new one.
   useEffect(() => {
+    for (const ref of [songBackend, radioBackend, podcastBackend]) {
+      if (ref.current instanceof AVPlayerBackend) ref.current.reconnect()
+    }
     return () => {
-      songBackend.current?.destroy()
-      radioBackend.current?.destroy()
-      podcastBackend.current?.destroy()
+      for (const ref of [songBackend, radioBackend, podcastBackend]) {
+        if (ref.current instanceof AVPlayerBackend) ref.current.detachListener()
+      }
     }
   }, [])
 
-  const getActiveBackend = useCallback((): HTMLAudioBackend => {
+  const getActiveBackend = useCallback((): AudioBackend => {
     if (isRadio) return radioBackend.current!
     if (isPodcast) return podcastBackend.current!
     return songBackend.current!
@@ -169,8 +209,8 @@ export function AudioBackendProvider({ children }: { children: ReactNode }) {
 
     if (!infinityDuration) {
       setCurrentDuration(audioDuration)
-    } else if (isSong && song?.duration) {
-      setCurrentDuration(song.duration)
+    } else if (isSong && songDuration) {
+      setCurrentDuration(songDuration)
     }
 
     if (isPodcast && infinityDuration && podcast) {
@@ -194,7 +234,7 @@ export function AudioBackendProvider({ children }: { children: ReactNode }) {
     getActiveBackend,
     isPodcast,
     isSong,
-    song,
+    songDuration,
     podcast,
     setCurrentDuration,
     getCurrentPodcastProgress,
@@ -301,9 +341,9 @@ export function AudioBackendProvider({ children }: { children: ReactNode }) {
     podcastBackend.current!.playbackRate = currentPlaybackRate
   }, [currentPlaybackRate, isPodcast])
 
-  // Reset Web Audio nodes when replayGain errors
+  // Reset Web Audio nodes when replayGain errors (no-op for non-Web Audio backends)
   useEffect(() => {
-    if (replayGainError) songBackend.current?.resetWebAudio()
+    if (replayGainError) songBackend.current?.resetWebAudio?.()
   }, [replayGainError])
 
   // Apply ReplayGain
@@ -330,7 +370,7 @@ export function AudioBackendProvider({ children }: { children: ReactNode }) {
     if (isSong) handle()
   }, [isPlaying, isSong, songStreamUrl])
 
-  // Play/pause — radio (reloads stream each play for fresh connection)
+  // Play/pause — radio reloads the stream on every play for a fresh connection
   useEffect(() => {
     async function handle() {
       const backend = radioBackend.current!
diff --git a/src/lib/audio/avplayer-backend.ts b/src/lib/audio/avplayer-backend.ts
new file mode 100644
index 000000000..80e51fb53
--- /dev/null
+++ b/src/lib/audio/avplayer-backend.ts
@@ -0,0 +1,150 @@
+import { logger } from '@/utils/logger'
+import { AudioBackend, AudioBackendCallbacks } from './backend'
+
+/**
+ * macOS-only AudioBackend that delegates to a native AVPlayer process via
+ * Electron IPC. Commands are fire-and-forget; events arrive asynchronously
+ * through the avplayer-event channel and are cached locally so that the
+ * synchronous getCurrentTime() / getDuration() methods remain fast.
+ */
+export class AVPlayerBackend implements AudioBackend {
+  private _currentTime = 0
+  private _duration = NaN
+  private _loop = false
+  private _playbackRate = 1.0
+  private _volume = 1.0
+  private removeListener: (() => void) | null = null
+  private readonly callbacks: AudioBackendCallbacks
+
+  constructor(
+    private readonly id: string,
+    callbacks: AudioBackendCallbacks = {},
+  ) {
+    this.callbacks = callbacks
+    logger.info(`[AVPlayerBackend:${id}] created`)
+    this.registerListener()
+  }
+
+  private registerListener(): void {
+    this.removeListener = window.api.avPlayer.onEvent((event) => {
+      if (event.id !== this.id) return
+      switch (event.type) {
+        case 'play':
+          this.callbacks.onPlay?.()
+          break
+        case 'pause':
+          this.callbacks.onPause?.()
+          break
+        case 'timeupdate':
+          this._currentTime = event.time ?? this._currentTime
+          this.callbacks.onTimeUpdate?.()
+          break
+        case 'loadedmetadata':
+          this._duration = event.duration ?? NaN
+          this.callbacks.onLoadedMetadata?.()
+          break
+        case 'ended':
+          this.callbacks.onEnded?.()
+          break
+        case 'loadstart':
+          this._currentTime = 0
+          this._duration = NaN
+          this.callbacks.onLoadStart?.()
+          break
+        case 'error':
+          logger.error(`[AVPlayerBackend:${this.id}] error event`, event)
+          this.callbacks.onError?.()
+          break
+      }
+    })
+  }
+
+  // Remove the IPC listener without destroying the helper player. Used by the
+  // provider's effect cleanup to survive React Strict Mode's simulated unmount.
+  detachListener(): void {
+    this.removeListener?.()
+    this.removeListener = null
+  }
+
+  // Re-register the IPC listener after it was removed by detachListener.
+  reconnect(): void {
+    if (!this.removeListener) {
+      this.registerListener()
+    }
+  }
+
+  load(src: string): void {
+    logger.info(`[AVPlayerBackend:${this.id}] load`, { src })
+    this._currentTime = 0
+    this._duration = NaN
+    window.api.avPlayer.command({ type: 'load', id: this.id, url: src })
+  }
+
+  play(): Promise<void> {
+    logger.info(`[AVPlayerBackend:${this.id}] play`)
+    window.api.avPlayer.command({ type: 'play', id: this.id })
+    return Promise.resolve()
+  }
+
+  pause(): void {
+    window.api.avPlayer.command({ type: 'pause', id: this.id })
+  }
+
+  seek(seconds: number): void {
+    this._currentTime = seconds
+    window.api.avPlayer.command({ type: 'seek', id: this.id, seconds })
+  }
+
+  getCurrentTime(): number {
+    return this._currentTime
+  }
+
+  getDuration(): number {
+    return this._duration
+  }
+
+  setVolume(value: number): void {
+    this._volume = Math.max(0, Math.min(1.0, value))
+    window.api.avPlayer.command({
+      type: 'setVolume',
+      id: this.id,
+      value: this._volume,
+    })
+  }
+
+  // AVPlayer has no separate gain stage; the caller has already combined
+  // volume and ReplayGain into a single linear factor.
+  setGain(linearGain: number): void {
+    this._volume = Math.max(0, Math.min(1.0, linearGain))
+    window.api.avPlayer.command({
+      type: 'setVolume',
+      id: this.id,
+      value: this._volume,
+    })
+  }
+
+  get loop(): boolean {
+    return this._loop
+  }
+
+  // Looping is handled in the provider's onEnded callback (seek to 0 + play).
+  // HTMLAudioBackend uses the native <audio>.loop attribute instead.
+  set loop(value: boolean) {
+    this._loop = value
+  }
+
+  get playbackRate(): number {
+    return this._playbackRate
+  }
+
+  set playbackRate(value: number) {
+    this._playbackRate = value
+    window.api.avPlayer.command({ type: 'setRate', id: this.id, rate: value })
+  }
+
+  destroy(): void {
+    this.removeListener?.()
+    this.removeListener = null
+    window.api.avPlayer.command({ type: 'destroy', id: this.id })
+  }
+}
diff --git a/src/lib/audio/backend.ts b/src/lib/audio/backend.ts
index d231f9591..b115c103a 100644
--- a/src/lib/audio/backend.ts
+++ b/src/lib/audio/backend.ts
@@ -19,5 +19,8 @@ export interface AudioBackend {
   getDuration(): number
   setVolume(value: number): void
   setGain?(linearGain: number, replayGain?: ReplayGainParams): void
+  loop: boolean
+  playbackRate: number
+  resetWebAudio?(): void
   destroy(): void
 }

From 1922e3d94ed0913753c6a3fa50b51a1f91c24245 Mon Sep 17 00:00:00 2001
From: Brad Taylor <brad.taylor@gmail.com>
Date: Tue, 30 Jun 2026 16:54:32 -0700
Subject: [PATCH 3/3] feat: airplay support on macos

---
 electron/preload/types.ts                    |   1 +
 native/avplayer-helper.swift                 | 108 +++++++++++++++++--
 package.json                                 |   2 +-
 src/app/components/player/airplay-button.tsx |  33 ++++++
 src/app/components/player/player.tsx         |   7 ++
 5 files changed, 143 insertions(+), 8 deletions(-)
 create mode 100644 src/app/components/player/airplay-button.tsx

diff --git a/electron/preload/types.ts b/electron/preload/types.ts
index 3df94afaf..b7acb5bc0 100644
--- a/electron/preload/types.ts
+++ b/electron/preload/types.ts
@@ -17,6 +17,7 @@ export type AvPlayerCommandPayload =
   | { type: 'setLoop'; id: string; loop: boolean }
   | { type: 'setRate'; id: string; rate: number }
   | { type: 'destroy'; id: string }
+  | { type: 'showAirPlay'; x: number; y: number; height: number }
 
 export type AvPlayerEventPayload = {
   id: string
diff --git a/native/avplayer-helper.swift b/native/avplayer-helper.swift
index a7ec11243..ed6c12eb5 100644
--- a/native/avplayer-helper.swift
+++ b/native/avplayer-helper.swift
@@ -1,4 +1,6 @@
 import AVFoundation
+import AVKit
+import AppKit
 import Foundation
 
 // ─── Per-backend player state ─────────────────────────────────────────────────
@@ -12,13 +14,61 @@ final class PlayerState {
   var timeControlObservation: NSKeyValueObservation?
   var endEmitted = false
 
-  init(player: AVPlayer) {
-    self.player = player
-  }
+  init(player: AVPlayer) { self.player = player }
 }
 
 var states: [String: PlayerState] = [:]
 
+// ─── AirPlay picker ───────────────────────────────────────────────────────────
+
+var airplayPicker: AVRoutePickerView?
+var airplayPanel: NSPanel?
+var airplayPickerIsOpen = false
+var airplayLastDismissed: Date = .distantPast
+
+func clickPickerButton() {
+  guard let picker = airplayPicker else { return }
+  func click(_ v: NSView) {
+    if let btn = v as? NSButton { btn.performClick(nil); return }
+    v.subviews.forEach { click($0) }
+  }
+  click(picker)
+}
+
+class RoutePickerDelegate: NSObject, AVRoutePickerViewDelegate {
+  func routePickerViewDidEndPresentingRoutes(_ routePickerView: AVRoutePickerView) {
+    airplayPickerIsOpen = false
+    airplayLastDismissed = Date()
+  }
+}
+
+var routePickerDelegate: RoutePickerDelegate?
+
+func setupAirPlayPicker() {
+  let size: CGFloat = 44
+  let picker = AVRoutePickerView(frame: NSRect(x: 0, y: 0, width: size, height: size))
+  let delegate = RoutePickerDelegate()
+  routePickerDelegate = delegate
+  picker.delegate = delegate
+
+  let panel = NSPanel(
+    contentRect: NSRect(x: -size * 2, y: -size * 2, width: size, height: size),
+    styleMask: [.nonactivatingPanel],
+    backing: .buffered,
+    defer: false
+  )
+  panel.isOpaque = false
+  panel.backgroundColor = .clear
+  panel.alphaValue = 0
+  panel.level = .popUpMenu
+  panel.ignoresMouseEvents = true
+  panel.contentView = picker
+  panel.orderFrontRegardless()
+
+  airplayPicker = picker
+  airplayPanel = panel
+}
+
 // ─── stdout event emission ────────────────────────────────────────────────────
 
 func emit(_ dict: [String: Any]) {
@@ -55,8 +105,45 @@ func teardown(id: String) {
 // ─── Command dispatch ─────────────────────────────────────────────────────────
 
 func handle(_ cmd: [String: Any]) {
-  guard let type = cmd["type"] as? String, let id = cmd["id"] as? String else {
-    log("ignoring command with missing type/id: \(cmd)")
+  guard let type = cmd["type"] as? String else {
+    log("ignoring command with missing type: \(cmd)")
+    return
+  }
+
+  // showAirPlay is not tied to a player instance — handle before the id guard.
+  if type == "showAirPlay" {
+    guard let x = cmd["x"] as? Double,
+          let y = cmd["y"] as? Double,
+          let height = cmd["height"] as? Double,
+          let screen = NSScreen.main,
+          let panel = airplayPanel else { return }
+
+    if airplayPickerIsOpen {
+      // Toggle: click again to dismiss the open popover.
+      clickPickerButton()
+      return
+    }
+
+    // The popover dismisses on mouse-down when the user clicks the button while
+    // it's open. The React onClick fires on mouse-up, arriving here shortly after.
+    // Ignore that trailing click so we don't immediately reopen the picker.
+    if Date().timeIntervalSince(airplayLastDismissed) < 0.3 { return }
+
+    let size: CGFloat = 44
+    let panelX = CGFloat(x) - size / 2
+    let panelY = screen.frame.height - CGFloat(y) - CGFloat(height) / 2 - size / 2
+    panel.setFrameOrigin(NSPoint(x: panelX, y: panelY))
+    airplayPickerIsOpen = true
+
+    // Brief delay so the panel finishes repositioning before the click.
+    DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) {
+      clickPickerButton()
+    }
+    return
+  }
+
+  guard let id = cmd["id"] as? String else {
+    log("ignoring command with missing id: \(cmd)")
     return
   }
 
@@ -79,6 +166,7 @@ func handle(_ cmd: [String: Any]) {
 
     let item = AVPlayerItem(url: url)
     let player = AVPlayer(playerItem: item)
+    player.allowsExternalPlayback = true
     let state = PlayerState(player: player)
 
     emit(["type": "loadstart", "id": id])
@@ -177,6 +265,10 @@ func handle(_ cmd: [String: Any]) {
 
 var inputBuffer = Data()
 
+// Initialize NSApplication so AppKit (AVRoutePickerView, NSPanel) works.
+// .accessory = no Dock icon, no menu bar entry.
+NSApplication.shared.setActivationPolicy(.accessory)
+
 // Close all file descriptors inherited from the parent (Electron/Chromium opens
 // many IPC sockets and Mach ports that can interfere with AVFoundation's own
 // XPC/networking channels). Keep only stdin(0), stdout(1), stderr(2).
@@ -195,6 +287,8 @@ do {
 
 log("avplayer-helper started")
 
+setupAirPlayPicker()
+
 FileHandle.standardInput.readabilityHandler = { fh in
   let chunk = fh.availableData
   guard !chunk.isEmpty else {
@@ -204,7 +298,7 @@ FileHandle.standardInput.readabilityHandler = { fh in
   }
 
   // Dispatch to main so AVPlayer is created/used on the main thread, where
-  // dispatchMain() is active and AVFoundation callbacks can be delivered.
+  // NSApplication.run() is active and AVFoundation callbacks can be delivered.
   DispatchQueue.main.async {
     inputBuffer.append(chunk)
 
@@ -221,4 +315,4 @@ FileHandle.standardInput.readabilityHandler = { fh in
   }
 }
 
-dispatchMain()
+NSApplication.shared.run()
diff --git a/package.json b/package.json
index acee8c42a..cd2aa288d 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,7 @@
     "electron:start": "electron-vite preview",
     "electron:dev": "electron-vite dev --watch",
     "electron:build": "electron-vite build",
-    "build:native:mac": "swiftc native/avplayer-helper.swift -o native/avplayer-helper -framework Foundation -framework AVFoundation -framework CoreMedia -O",
+    "build:native:mac": "swiftc native/avplayer-helper.swift -o native/avplayer-helper -framework Foundation -framework AVFoundation -framework AVKit -framework AppKit -framework CoreMedia -O",
     "postinstall": "electron-builder install-app-deps",
     "build:unpack": "electron-builder --dir",
     "build:win": "electron-builder --win",
diff --git a/src/app/components/player/airplay-button.tsx b/src/app/components/player/airplay-button.tsx
new file mode 100644
index 000000000..b233b9fa7
--- /dev/null
+++ b/src/app/components/player/airplay-button.tsx
@@ -0,0 +1,33 @@
+import { AirplayIcon } from 'lucide-react'
+import { Button } from '@/app/components/ui/button'
+import { SimpleTooltip } from '@/app/components/ui/simple-tooltip'
+
+interface AirPlayButtonProps {
+  disabled?: boolean
+}
+
+export function AirPlayButton({ disabled }: AirPlayButtonProps) {
+  function handleClick(event: React.MouseEvent<HTMLButtonElement>) {
+    const rect = event.currentTarget.getBoundingClientRect()
+    window.api.avPlayer.command({
+      type: 'showAirPlay',
+      x: rect.left + rect.width / 2 + window.screenX,
+      y: rect.top + window.screenY,
+      height: rect.height,
+    })
+  }
+
+  return (
+    <SimpleTooltip text="AirPlay">
+      <Button
+        variant="ghost"
+        size="icon"
+        className="rounded-full w-10 h-10 p-2 text-secondary-foreground"
+        onClick={handleClick}
+        disabled={disabled}
+      >
+        <AirplayIcon className="w-4 h-4" />
+      </Button>
+    </SimpleTooltip>
+  )
+}
diff --git a/src/app/components/player/player.tsx b/src/app/components/player/player.tsx
index 2803a8705..373897045 100644
--- a/src/app/components/player/player.tsx
+++ b/src/app/components/player/player.tsx
@@ -8,6 +8,8 @@ import {
   usePlayerSonglist,
 } from '@/store/player.store'
 import { hasPiPSupport } from '@/utils/browser'
+import { isMacOS } from '@/utils/desktop'
+import { AirPlayButton } from './airplay-button'
 import { PlayerClearQueueButton } from './clear-queue-button'
 import { PlayerControls } from './controls'
 import { PlayerExpandButton } from './expand-button'
@@ -32,6 +34,7 @@ const MemoPlayerExpandButton = memo(PlayerExpandButton)
 const MemoPodcastPlaybackRate = memo(PodcastPlaybackRate)
 const MemoLyricsButton = memo(PlayerLyricsButton)
 const MemoMiniPlayerButton = memo(MiniPlayerButton)
+const MemoAirPlayButton = memo(AirPlayButton)
 
 export function Player() {
   const hideFavoritesSection = useAppStore().pages.hideFavoritesSection
@@ -83,6 +86,10 @@ export function Player() {
 
             <MemoPlayerVolume disabled={!song && !radio && !podcast} />
 
+            {isMacOS && (
+              <MemoAirPlayButton disabled={!song && !radio && !podcast} />
+            )}
+
             {isSong && <MemoPlayerExpandButton disabled={!song} />}
             {isSong && hasPiPSupport && <MemoMiniPlayerButton />}
           </div>