Skip to content

feat(ios): add AVPlayer as a switchable phone player engine - #563

Merged
playbridgeapp merged 1 commit into
mainfrom
feat/ios-avplayer-engine
Nov 18, 2026
Merged

playbridgeapp merged 1 commit into
mainfrom
feat/ios-avplayer-engine

Conversation

@playbridgeapp

Copy link
Copy Markdown
Owner

Adds AVPlayer as a second, switchable engine for the iPhone's own player ("play on this phone"). mpv stays the default. This reverses the earlier mpv-only rule for the phone, for streams mpv handles badly (for example an HLS video that mpv opens as live and can't seek).

What changes

  • Switching: a "Player engine" choice (mpv / AVPlayer) in player settings, and "Try with AVPlayer" (or "Try with mpv") on the failure screen in the full-screen player and the Media Library preview. PlaybackSession.switchEngine(to:) re-prepares the route like Retry and reopens at the current position, keeping play/pause.
  • Per session only: the choice survives Retry, the next episode of a website queue and watch-party replacements; the next video opened starts on mpv. It isn't saved, so later streams never move to AVPlayer silently.
  • Headers: AVPlayer can't attach headers to every HLS request, so streams with headers or plain http:// play through the phone's loopback proxy (StreamRouteService.localPlayback); the registration lives as long as the video. Without the proxy it fails with a message suggesting mpv.
  • Tracks and subtitles: audio and subtitle tracks from AVFoundation's media selection, with automatic selection off so the existing preferred-language rules decide. Embedded subtitles use the subtitle style's avTextStyleRules(). Ticked subtitle files (SRT/WebVTT) and website subtitles use the existing caption overlay, including the timing offset.
  • Failures: AVPlayer errors map to the existing categories (certificate, TLS, DNS, timeout, connection, HTTP status). Diagnostics say which engine failed. MKV is refused at once; DASH, picture-based subtitles and unsupported codecs fail with a message suggesting mpv.
  • Other: Fit/Fill via video gravity; pauses in the background and on audio interruptions; no AirPlay or Picture in Picture from the phone player.
  • Docs and guidance: docs/ios-phone-playback.md gets a "Player engine" section; AGENTS.md and the playbridge-apple skill now describe mpv as the default with AVPlayer as a per-session choice (still no automatic selection, silent fallback or saved default).

What AVPlayer can't do compared with mpv

MKV, ASS/SSA subtitle files, picture-based subtitles, DASH and codecs Apple doesn't decode. Custom subtitle fonts and the timing offset don't apply to subtitles inside the stream.

Privacy

Debug logs show only the host and file extension, header names, and error domain and code, never URLs, header values or AVPlayer's error-log text.

Testing

  • run-phone-engine-checks.sh adds tests for switching, retry and episode changes keeping the engine, pause kept, MKV refusal, diagnostics, loopback rules, error mapping, messages and overlay captions with delay.
  • Phone player features, website playback, subtitle languages, playback error, watch together, cast playback, cast history and page-cast coordinator checks pass; simulator and iPhone builds succeed.
  • On an iPhone 12 Pro Max: an HLS video that mpv opens as live plays on AVPlayer with its real length and a working seek bar.

Not verified

  • The two CoreMedia codes used to recognise HTTP 404 and 403 (-12938, -12660); the HTTP status from AVPlayer's error log is also used.
  • Switching engines during a watch party pauses this phone briefly without telling the party, and resets remembered track choices until the tracks are listed again.
  • run-mpv-phone-probe.sh (needs a booted simulator and ffmpeg) wasn't run; its file list was updated.

🤖 Generated with Claude Code

mpv stays the default for "play on this phone". Player settings gain a
"Player engine" choice, and the failure screen offers "Try with AVPlayer"
(or "Try with mpv"). Switching reopens the stream at the same position for
that player session only; nothing is saved as a default. Streams with
headers or plain HTTP go through the loopback proxy, preferred languages
use AVFoundation's media selection, and ticked and website subtitles use
the existing caption overlay. MKV and other formats AVPlayer can't play
fail with a message suggesting mpv.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@playbridgeapp
playbridgeapp merged commit 0bf10f2 into main Nov 18, 2026
9 checks passed
@playbridgeapp
playbridgeapp deleted the feat/ios-avplayer-engine branch November 18, 2026 09:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant