Known limitations

#Audio

• Reducing an initial positive audio delay drops the head of the audio (3.5.4). When a session starts with a positive audioDelaySeconds and the delay is later reduced, the served audio init opens the track with an empty edit of the old delay; audio that would now land before it cannot be placed, so roughly the old delay's length is dropped from the start of the audio. Only the head is affected; the rest of the film follows the new delay. Pinned by RuntimeAudioDelayTests.
• A runtime audio-delay change on the remux path re-buffers. It takes effect at a producer re-anchor (.pendingReanchor), AVPlayer first plays what it had already buffered at the old offset, and a sequential session cannot change the offset at all (.unsupported).
• Bridged audio is a channel bed. Atmos objects in TrueHD and DTS:X do not survive the bridge (FFmpeg's E-AC-3 encoder writes no JOC). With the AAC target — any FFmpeg build without an eac3 encoder, stock MPVKit included — bridged tracks are AAC up to 5.1 with no bitstream passthrough to an AV receiver, and side/back surround positions are merged.
• Switching to a lazy rendition costs a re-anchor — a non-DEFAULT bridged track or a dialogue-boost level is produced only once AVPlayer fetches it, and sequential sessions leave those renditions out of the master entirely.
• Dialogue boost needs a centre channel. Stereo sources would need FFmpeg's dialoguenhance filter, which current builds do not ship.

#Seeking and indexing

• When a container's index does not load within the 3 s budget and the source is not read through the coordinated HTTP reader (a local file, a mounted share, FFmpeg's own HTTP), the first play is sequential — no seekable plan — and only the next play benefits from the harvested map.
• A background late index load only ever helps a successor session, never the running one, and needs coordinatedHTTP, a strong ETag (or a host identity) and a cache directory.
• The keyframe cache is off for any remote source that cannot prove its version — no strong ETag, FFmpeg's own HTTP, a host input on a non-file URL — unless the host supplies a SourceCacheIdentity. A rotated query token is a miss.
• The sliding-window playlist for sequential sessions is not yet confirmed on a device (its moving start under AVPlayer and AirPlay).

#Subtitles, captions and HDR

• CEA-708 is not decoded; a stream that carries only 708 captions gets no caption rendition.
• CLOSED-CAPTIONS=NONE cannot be stated in the media-playlist shape (the muxed fallback, or an HDR source on a display not vouched HDR-ready), so AVPlayer may still surface in-band captions there.
• Bitmap subtitles are OCR'd into renditions only when the source has no text track; OCR is lossy (typography is lost). ASS colours, fonts, karaoke and drawing commands are not preserved.
• HDR10+ is detection only, opt-in, and reports seen / notSeenWithinBudget / unknown — it changes no playlist or display signalling. Matroska BlockAdditional HDR10+ is not scanned.
• The hermetic test suite cannot carry real Dolby Vision RPUs or Atmos objects. The Profile 7 → 8.1 conversion is checked by the opt-in real-media harness (PRISMCORE_MEDIA), not by committed fixtures.

#Inputs and transport

• The coordinated HTTP reader is for finite files on servers that answer Range requests with 206. It is not for live streams, nested HLS playlists or range-less servers; a cross-origin redirect drops custom headers; CDN performance has not been benchmarked.
• Keyframe maps supplied as SourceOpenHints are validated and carried, but not consumed by the planner, and an indexLocation hint is not acted on. Hints take effect only over the coordinated reader.
• PrismCoreEngine.open and SoftwarePlaybackPipeline.load(url:) take no custom input:; use a PrismCoreSession or SourceProbe for host-supplied bytes.

#Sessions and networking

• A session is single use; makeSession(changing:) is not seamless — the successor starts from zero and the host seeks it — and a session mints at most one successor. Startup checkpoints are not replayed onto fallback sessions.
• stop() waits 2 s for a wedged producer, then detaches it and returns.
• The AirPlay LAN mode is cleartext HTTP and IPv4 only; anyone on the network who can observe the traffic sees the token and the media.
• HLS segments must be served over a socket: AVPlayer rejects segments delivered through an AVAssetResourceLoader (-12881), which is why a loopback server exists at all. In the macOS sandbox that needs the network.server entitlement.

#Proven by construction, not yet by a device

Several headline claims are implemented and unit-tested but can only be confirmed with real media on real hardware: that Atmos objects reach an AV receiver over HDMI, Dolby Vision engagement on a panel, the tvOS display handshake, and on the software path that frames reach a display and audio switches are inaudible. Frame-accurate seeking on the software path remains open.

#Non-goals

Deliberate omissions: no UI (no view, controls or HUD), no published playback state (your AVPlayer is the source of truth for time, rate and status), no subtitle rendering, no playlist or queue management (make a new session for the next title), no analytics (nothing leaves the device), and no re-encoding of video, ever.