/tvos-media-playback-workflow

name: tvos-media-playback-workflow
description: "Guide tvOS media playback: AVKit-first player choice, custom escalation, remote commands, Now Playing, and validation. Use for AVPlayerViewController, MPRemoteCommandCenter, playback focus, or media-control boundaries."

tvOS Media Playback Workflow

Purpose

Guide the tvOS media-control contract. This skill starts with AVKit's system player, makes custom-player escalation evidence-based, and keeps remote command routing, player state, and Now Playing information under one explicit owner. It does not replace general AVFoundation pipelines, Core Media timing, audio session policy, or Xcode execution workflows.

When To Use

• Use this skill for `AVPlayerViewController`, system-player adoption, AVKit

playback UI, custom info tabs, overlays, content proposals, HLS interstitials, Picture in Picture, and playback-focused tvOS design.

• Use this skill for `MPRemoteCommandCenter`, remote transport commands,

`MPNowPlayingInfoCenter`, custom player controls, command enablement, and Apple TV media-state ownership.

• Use this skill when a product believes it needs a custom player; first decide

whether AVKit's system player satisfies the actual requirement.

• Use this skill for remote/controller command validation, post-playback focus

restoration, and device-only playback capability gates.

• Recommend `tvos-app-experience-workflow` for browsing UI, focus layout,

remote-first app navigation, Large Text, TVMLKit migration, or general tvOS platform constraints.

• Recommend `avfoundation-media-pipeline-workflow` for general asset loading,

capture, readers, writers, export, transcode, and playback-pipeline repair.

Single-Path Workflow

1. Classify the playback request:

• system player adoption
• AVKit extension or supporting content
• custom-player justification
• remote command or Now Playing state
• HLS/interstitial/continuity feature
• runtime validation or repair

2. Apply the Apple docs gate:

• read current AVKit, AVFoundation, MediaPlayer, and release-note evidence
• state the documented behavior relied on before recommending a control path
• version-qualify beta APIs and device-specific behavior

3. Prefer the system player:

• choose `AVPlayerViewController` when its controls and supported extension

points satisfy the requirement

• name the concrete unavailable product behavior before choosing custom UI
• keep the custom path responsible for every relevant remote command and

media-state transition 4. Establish one media-control owner:

• player lifecycle and current item
• command enablement and `MPRemoteCommandCenter` handlers
• `MPNowPlayingInfoCenter` state
• interruption/end-of-item behavior and focus restoration

5. Return one recommendation with:

• player choice and documented rationale
• command/state ownership
• feature and device gates
• remote validation matrix and handoff

Inputs

• `request`: optional free-text playback task.
• `playback_goal`: optional `system-player`, `custom-player`, `remote-command`,

`now-playing`, `hls`, `interstitial`, `overlay`, `proposal`, `continuity`, or `validation`.

• `player_context`: optional current player, UI customization, media type, and

command requirement.

• `target_context`: optional Apple TV model, tvOS/Xcode version, controller,

and physical-device availability.

• Defaults:
• docs-first guidance always applies
• prefer `AVPlayerViewController` over a custom player
• one explicit owner manages player state, commands, and Now Playing state

Outputs

• `status`
• `success`: a playback ownership recommendation is ready
• `handoff`: another workflow owns the actual next step
• `blocked`: the required device, entitlement, stream, or framework evidence

is missing

• `path_type`
• `primary`: AVKit system-player or documented extension path
• `fallback`: custom-player or device-only feature path
• `output`
• resolved player path
• documented Apple behavior relied on
• command and state ownership
• capability/beta gate
• validation matrix and handoff

Guards and Stop Conditions

• Do not start with custom playback controls when `AVPlayerViewController`

satisfies the product requirement.

• Do not treat a custom player as cosmetic: it must support applicable remote

commands, media-control state, interruption/end behavior, and focus return.

• Do not scatter `MPRemoteCommandCenter` handlers, player state, or

`MPNowPlayingInfoCenter` updates across unrelated views.

• Do not claim HLS, interstitial, Picture in Picture, Continuity Camera,

controller, remote, or system-media-control behavior is verified without relevant runtime evidence.

• Do not run general media type, timing, capture, reader/writer, export, or

audio-session work through this skill when an existing specialist owns it.

• Stop with `blocked` when the requested behavior depends on unavailable stream,

account, hardware, signed entitlement, or physical-device evidence.

Fallbacks and Handoffs

• Recommend `tvos-app-experience-workflow` for app navigation, focus layout,

Large Text, remote-first browsing UI, and TVMLKit migration.

• Recommend `avfoundation-media-pipeline-workflow` for assets, capture, player

pipeline, reader/writer, export, or transcode ownership.

• Recommend `coremedia-timing-samplebuffer-workflow` for timestamps, timebases,

format descriptions, and sample-buffer synchronization.

• Recommend `avfaudio-session-workflow` for audio intent, routes,

interruptions, microphone permission, and audio-session behavior.

• Recommend `xcode-build-run-workflow` for project/device deployment and

`xcode-testing-workflow` for repeatable playback/runtime verification.

• Recommend `explore-apple-swift-docs` when current AVKit or tvOS docs lookup

is the real task.

References

Workflow References

• `references/system-player-and-remote-commands.md`
• `references/playback-val