AwesomeREA.org

Case study

pyatv: a reverse-engineered client for Apple TV and AirPlay protocols

Asyncio Python library and command-line tools that act as an independent client for Apple TV and AirPlay devices by reimplementing the DMAP/DACP, Media Remote Protocol, Companion Link, AirPlay and RAOP protocols, which its protocol documentation describes as reverse engineered. That page records the recovered binary formats, Zeroconf properties, the OPACK encoding, pair-setup and pair-verify exchanges and Companion commands, with some request headers taken from Wireshark captures of the iPhone Remote app, and the bundled atvproxy relays MRP, Companion and AirPlay sessions to print decrypted messages for further analysis. On this basis pyatv provides remote control, metadata with push updates, app and account switching, audio-output management and AirPlay streaming to Apple TVs, HomePods and third-party receivers.

Requirements & limits

  • Release at review: 0.18.0, published to GitHub and PyPI on 2026-06-19 as a tvOS-compatibility release; the reviewed master commit is the release commit, while the v0.18.0 tag points to a parallel commit that differs only in CHANGES.md and pyatv/const.py. The protocol page limits itself to what has been reverse engineered: its Companion Link section is called mostly speculation and guesses, the OPACK description is incomplete and unverified, and the MRP implementation section is still marked TBD. The acknowledgements say MRP support builds on Jean Regisser's mediaremotetv-protocol findings.
  • No Apple software, firmware or keys are bundled. pyatv connects to the user's own Apple TV, HomePod, AirPort Express or other AirPlay receiver on the local network; most protocols require pairing with a PIN shown on the device, and credentials and settings are kept in pyatv's storage. On tvOS 15 and later AirPlay must be set up because MRP moved into an AirPlay 2 stream, and RAOP supports only legacy pairing.
  • Requires Python 3.9+ and installs from PyPI or the project's container images; the installation guide lists build-essential, libssl-dev, libffi-dev and Python headers for building dependencies on Debian-style systems, and RAOP audio streaming relies on miniaudio. CI runs on Ubuntu, macOS and Windows with Python 3.9 to 3.14.
  • Tests are mostly unit tests, plus functional tests for DMAP, MRP, Companion, RAOP, mDNS and scanning that run against a fake device which, according to the testing guide, implements limited functionality and is only meant to be compatible with pyatv. They do not establish conformance with Apple's implementations, and atvproxy is described as an incubating script that depends on internal APIs. This review ran neither tests nor devices.
  • MIT (LICENSE.md). Apple's protocols, devices and software keep their own rights; pyatv is an independent implementation, not recovered Apple source. The reviewed sources establish no REA or AI use.

About this entry

Type
Case study
Category
Independent reconstruction cases
Relationship
Independent reconstruction project
Targets
Protocol

Sources reviewed

The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.

Report an outdated entry Suggest a translation fix

Primary sources

  1. docs/documentation/protocols.md GitHub · postlund/pyatv · Revision b277a4c
  2. README.md GitHub · postlund/pyatv · Revision b277a4c
  3. docs/documentation/protocols.md#L13-L18 GitHub · postlund/pyatv · Revision b277a4c
  4. docs/documentation/protocols.md#L363-L375 GitHub · postlund/pyatv · Revision b277a4c
  5. docs/documentation/atvproxy.md GitHub · postlund/pyatv · Revision b277a4c
  6. docs/documentation/supported_features.md GitHub · postlund/pyatv · Revision b277a4c
  7. docs/documentation/documentation.md GitHub · postlund/pyatv · Revision b277a4c
  8. docs/internals/testing.md GitHub · postlund/pyatv · Revision b277a4c
  9. docs/support/acknowledgements.md GitHub · postlund/pyatv · Revision b277a4c
  10. .github/workflows/tests.yml GitHub · postlund/pyatv · Revision b277a4c
  11. pyproject.toml GitHub · postlund/pyatv · Revision b277a4c
  12. CHANGES.md GitHub · postlund/pyatv · Revision b277a4c
  13. LICENSE.md GitHub · postlund/pyatv · Revision b277a4c
  14. https://github.com/postlund/pyatv/releases/tag/v0.18.0
  15. https://pypi.org/project/pyatv/0.18.0/

More in Protocols

All 31 entries in ProtocolsProtocols case studies (11)