itsytv-core

Swift package implementing the Apple TV Companion Link and AirPlay 2 protocols. Powers itsytv for macOS and itsytv for iOS.

If you want to control an Apple TV from Swift – discover it over Bonjour, pair with a PIN, send remote button presses, type into text fields, read now-playing state, or launch apps – this is a native implementation of the same MediaRemote (MRP) and Companion protocols the Siri Remote uses, with no Python or cloud dependency. It is the Swift counterpart to what pyatv does for Python.

What it does

• Device discovery – finds Apple TVs on the local network via Bonjour
• Pairing – SRP-based pair-setup (PIN entry) and pair-verify with Keychain-backed credential storage
• Remote control – HID button commands (d-pad, select, menu, home, play/pause, volume)
• Text input – live keyboard input to Apple TV text fields
• Now playing – artwork, title, artist, progress, and playback state via MRP protobuf messages
• App launching – launch installed apps and fetch their icons from the App Store
• AirPlay 2 tunnel – HAP-encrypted AirPlay control channel with MRP transport

Architecture

Sources/ItsytvCore/
├── Discovery/            # Bonjour device discovery
├── Protocol/
│   ├── AppleTVManager    # Orchestrator: discovery -> pairing -> session -> commands
│   ├── CompanionConnection / CompanionFrame  # TCP framing
│   ├── CompanionCommands # HID buttons, session start, app launching
│   ├── TextInputSession  # Live text input
│   ├── OPACK             # Apple's OPACK binary serialization
│   ├── BinaryPlist       # Binary plist with NSKeyedArchiver UIDs
│   └── TLV8              # TLV8 encoding for HomeKit-style pairing
├── Crypto/
│   ├── PairSetup         # SRP pair-setup flow (M1-M6)
│   ├── PairVerify        # Pair-verify flow (M1-M4)
│   ├── CompanionCrypto   # ChaCha20-Poly1305 session encryption
│   ├── CryptoHelpers     # Nonce padding, HKDF-SHA512
│   └── KeychainStorage   # Secure credential persistence
├── AirPlay/
│   ├── AirPlayControlChannel  # HTTP/RTSP with pair-verify and HAP encryption
│   ├── AirPlayPairVerify      # Pair-verify over AirPlay HTTP
│   ├── AirPlayMRPTunnel       # MRP transport over AirPlay 2
│   ├── DataStreamChannel      # MRP protobuf framing
│   ├── HAPChannel / HAPSession # HAP-encrypted TCP
├── MRP/
│   ├── MRPManager        # Now-playing state and media commands
│   └── Proto/Generated/  # Protobuf Swift code
├── Models/               # AppleTVDevice, NowPlayingState, HAPCredentials, MediaCommand
└── Utilities/            # AppIconFetcher, AppOrderStorage

Usage

Add the package as a dependency:

.package(path: "../itsytv-core")

import ItsytvCore

let manager = AppleTVManager()
// manager handles discovery, pairing, and connection automatically

Requirements

• Swift 5.10+
• macOS 14.0+ or iOS 17.0+

Testing

swift test

Used by

• Itsytv for macOS – open source menu bar remote (brew install --cask itsytv)
• Itsytv for iOS and iPadOS – touch-screen Apple TV remote on the App Store

License

MIT License (c) 2026 Nick Ustinov – see LICENSE for details.

Acknowledgements

Protocol implementation informed by pyatv, the comprehensive Python library for Apple TV control.