# 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.

- Type: Case study
- Targets: Protocol
- Category: Independent reconstruction cases
- Relationship: Independent reconstruction project
- Sources reviewed: 2026-10-19
- Added to the catalog: 2026-11-01
- Original resource: <https://github.com/postlund/pyatv>
- Primary source: <https://github.com/postlund/pyatv/blob/b277a4c8222ecdcbaab8a24e3e713ca44765adb4/docs/documentation/protocols.md>
- Catalog page: <https://awesomerea.org/resources/pyatv-apple-tv-airplay-protocols-case/>
- Record JSON: <https://awesomerea.org/resources/pyatv-apple-tv-airplay-protocols-case/record.json>
- Chinese version: [简体中文](https://awesomerea.org/zh/resources/pyatv-apple-tv-airplay-protocols-case/index.md)

## 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. atvproxy is described as an incubating script that depends on internal APIs.
- MIT (LICENSE.md). Apple's protocols, devices and software keep their own rights; pyatv is an independent implementation.

## Primary sources

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

## More in Protocols

- [BudsPro-Headtracking: streaming Galaxy Buds Pro head tracking over Samsung’s serial protocol](https://awesomerea.org/resources/budspro-headtracking-case/index.md) · Case study
- [Even G2 protocol: reverse-engineering Even Realities G2 smart-glasses BLE traffic](https://awesomerea.org/resources/even-g2-ble-protocol-case/index.md) · Case study
- [fuji-cam-wifi-tool: reconstructing Fujifilm X-series Wi-Fi remote control](https://awesomerea.org/resources/fuji-cam-wifi-tool-protocol-case/index.md) · Case study
- [Gymnasticon: bridging proprietary exercise-bike data to standard cycling sensors](https://awesomerea.org/resources/gymnasticon-exercise-bike-bridge-case/index.md) · Case study
- [garmin-ble: a Python client for Garmin's GFDI watch protocol](https://awesomerea.org/resources/garmin-ble-gfdi-protocol-case/index.md) · Case study
- [bosectl: reconstructing Bose’s BMAP headphone protocol](https://awesomerea.org/resources/bosectl-bose-bmap-protocol-case/index.md) · Case study

## About this entry

The description was reviewed against primary sources.
Original editorial content: MIT. Linked projects, papers and assets retain their own rights and licenses.