Tvos media playback workflow

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.

Customization

Use references/customization-flow.md.

scripts/customization_config.py preserves the shared customization-file contract. This first version has no runtime-enforced knobs.

References

Workflow References

• references/system-player-and-remote-commands.md
• references/playback-validation-and-handoffs.md
• references/customization-flow.md

Support References

• Recommend avfoundation-media-pipeline-workflow for general media-pipeline shape and coremedia-timing-samplebuffer-workflow for typed timing behavior.
• Recommend explore-apple-swift-docs for current framework availability and release-note evidence.

Script Inventory

• scripts/customization_config.py