Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/skills/playbridge-apple/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ description: Work on PlayBridge's native Apple phone and Apple TV applications.

## Phone playback and website bridge

- Read `docs/ios-phone-playback.md` for the mpv-only phone policy, TLS trust and verification. Standard MPVKit handles all local streams, audio and files; do not restore format-dependent AVPlayer selection or a silent fallback. Preserve original URL/MIME for diagnostics even when routing produces an opaque proxy URL.
- Read `docs/ios-phone-playback.md` for the phone engine policy, TLS trust and verification. Standard MPVKit is the default for all local streams, audio and files; AVPlayer (`AVPlayerPhonePlayback`) is only a per-session user choice (Player settings or the failure screen's **Try with AVPlayer**). Do not add format-dependent AVPlayer selection, a silent fallback or a saved default. AVPlayer streams with headers or plain HTTP go through the loopback proxy. Preserve original URL/MIME for diagnostics even when routing produces an opaque proxy URL.
- Preserve the selected route, headers and resume position across preparation/retry. mpv feeds the progress, final-close and lazy-queue contract for every local format. Keep mpv calls/destruction serialized, retain the rendering surface during teardown and fence stale callbacks by decoder generation.
- Local Via phone registrations use loopback, including rewritten HLS children; receiver casts retain LAN advertisement. Preserve route selection, scoped private-origin grants and registration lifetime; never silently fall back to Direct.
- Drawable-size changes rebuild only mpv’s video output, preserving decoder, position and user pause. Metal bounds/property checks alone do not prove visible resizing; keep portrait, both landscapes, return-to-portrait and paused-rotation pixel assertions.
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ If `AGENTS.local.md` exists at the repository root, read and follow it for optio
| Android phone | `mobile/android/` | Kotlin, Compose, GeckoView; Gradle modules `:app` and `:shared` |
| Android TV | `tv/android/` | Kotlin, TV UI, ExoPlayer/MPV; Gradle modules `:player:app`, `:geckoview-plugin:app`, and `:shared` |
| Shared Kotlin | `shared/` | Kotlin Multiplatform module currently targeting Android only; protocol and playback/domain logic included by both Android builds |
| Apple phone | `mobile/apple/` | SwiftUI/Xcode sender, MPVKit-only local playback; optional Cast Core external transports |
| Apple phone | `mobile/apple/` | SwiftUI/Xcode sender, MPVKit local playback (AVPlayer as a per-session choice); optional Cast Core external transports |
| Apple TV | `tv/apple/` | Swift/Xcode project |
| Desktop | `desktop/` | Flutter receiver and sender for macOS, Windows, and Linux |
| Stream proxy (Rust) | `stream-proxy-rust/` | High-performance Rust streaming proxy with MediaFlow AES-256 encryption. The old standalone Dart proxy has been removed. |
Expand Down
57 changes: 51 additions & 6 deletions docs/ios-phone-playback.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,56 @@
# iOS local playback

The phone uses standard MPVKit 1.0.0 for all local video/audio playback: website
sessions, browser-detected streams, imported files and completed downloads.
MP4, MKV, HLS, DASH, audio and opaque URLs all use the same decoder; there is no
AVPlayer fallback or **Try with mpv** action. A missing mpv engine fails explicitly.
Retries preserve the selected route, headers and current position. Original URL
and MIME information remain available for diagnostics, not engine selection.
The phone uses standard MPVKit 1.0.0 for local video/audio playback by default:
website sessions, browser-detected streams, imported files and completed downloads.
MP4, MKV, HLS, DASH, audio and opaque URLs all start on mpv. Apple's AVPlayer is a
second engine the user can switch to (see [Player engine](#player-engine)); PlayBridge
never picks it by format and never falls back to it on its own. A missing engine fails
explicitly. Retries preserve the selected route, headers, engine and current position.
Original URL and MIME information remain available for diagnostics.

## Player engine

**Player settings → Player engine** switches the open player between **mpv** and
**AVPlayer**. When playback fails, the failure screen also offers **Try with AVPlayer**
(or **Try with mpv** on AVPlayer). Switching prepares the selected route again, as
**Try again** does, and reopens the video at the current position; a playing video
keeps playing and a paused one stays paused.

The choice lasts for the open player: a website queue's next episode and a watch-party
replacement keep it, and the next video opened starts on mpv again. It is not saved
as a preference, because AVPlayer suits particular streams (for example an HLS video
that mpv opens as live and can't seek, or a stream mpv shows without a picture) and
would be the weaker choice for most others.

With AVPlayer:

- Streams that need request headers (cookies, referer, user agent) and plain-HTTP
streams play through the phone's loopback proxy (`StreamRouteService.localPlayback`),
which sends the headers on every request, including HLS segments. AVPlayer itself
gets only a `127.0.0.1` address. Streams already routed **Via phone** or website
media are already on loopback. If the proxy isn't available, playback fails with a
message suggesting mpv.
- The stream's own audio and subtitle tracks come from AVFoundation's media
selection, with their languages, so the remembered audio/subtitle languages apply
as with mpv. Embedded subtitles use the phone's subtitle style where AVFoundation
allows it (size, generic font family, background, edge; custom fonts don't apply).
- Subtitles ticked in the cast sheet (SRT/WebVTT files) and website subtitles are
drawn over the video with the same caption view, style and timing offset as on
mpv. The timing offset applies only to these overlay captions, not to subtitles
inside the stream.
- Fit/Fill, speed, seeking, the queue, website progress and watch-party controls work
as on mpv. AVPlayer pauses in the background and on audio interruptions, keeping the
user's pause choice, and does not offer AirPlay or Picture in Picture from the
phone player.
- Not supported: MKV files (refused at once, with a message suggesting mpv), styled
ASS/SSA subtitle files (left out of the subtitle list), bitmap subtitles, DASH,
and codecs Apple doesn't decode. These fail with a message suggesting mpv.
- AVFoundation is part of iOS; it adds no third-party code or licence notice.

Debug-build `[PhonePlayback]` lines for AVPlayer show the host and file extension,
header names, whether loopback was used, track counts and languages, and error domains
and codes. AVPlayer's error-log comments and URIs are never printed; they are only
classified into the fixed TLS/HTTP/network categories used in diagnostics.

MPVKit is pinned with Swift Package Manager in the phone project. The Apple TV
pins the same version in its own project. Both link the standard product,
Expand Down
Loading
Loading