Main Page

This is an asyncio python library for interacting with Apple TV and AirPlay devices. It mainly targets Apple TVs (all generations), but also support audio streaming via AirPlay to receivers like the HomePod, AirPort Express and third-party speakers. It can act as remote control to the Music app/iTunes in macOS.

Features

Here is a short summary of supported features:

• Automatic device discovery with Zeroconf
• Device information, e.g. hardware model and operating system version
• Currently playing metadata, artwork and push updates
• Remote, navigation and volume control commands
• Basic support for streaming video and audio with AirPlay
• Listing installed apps, launching apps and currently playing app
• Power management, e.g. turn on or off
• Supports Apple TV (all of them), AirPort Express, HomePod, macOS music app and most AirPlay v1 receivers

A complete list of supported features and limitations is available here.

There are also few utility scripts bundled with pyatv that makes it easy to try the library out. Check out atvremote, atvproxy, atvscript and atvlog.

Where to start?

To get going, install with pip:

pip install pyatv

Head over to Getting started to see what you can do! There’s also a Tutorial if you want to get going faster!

As pyatv is a library, it is mainly aimed for developers creating applications that can interact with Apple TVs. However, pyatv ships with a few powerful command lines tools you can use to try the library without writing any code.

If you need help or have questions, check out the Support page instead.

In case you are upgrading from an earlier version of pyatv, make sure to check out the migration guide here that will help you port your existing code.

In other the news…

As pyatv depends solely on private and reverse engineered protocols, things sometimes break because Apple changes something. Or because of other reasons. This section covers the major things that you need to be aware of.

• Apple removed the “regular” MRP protocol in tvOS 15 and started tunneling it over AirPlay instead. Version 0.9.0 of pyatv is the first version supporting tvOS 15. As long as credentials are provided for AirPlay, everything should be seamless, i.e. nothing more needs to be done. Credentials obtained from earlier versions will not work however, pairing must be re-performed with 0.9.0 (or later).
• Playing anything with interface.Stream.play_url tends to break devices running tvOS, e.g. metadata stops working. Rebooting is the only recovery. Everything points at a bug in tvOS.
• It is possible to control the Music app running on a Mac, but macOS 11.4 seems to not work. Make sure to upgrade.
• There are some issues with miniaudio when running on ARM (e.g. Rasperry pi) which can be fixed by re-installing miniaudio and building it from source. See here for details.
• miniaudio fails to compile on Apple Silicon [#1162]
• Other general issues can be found in the FAQ.

Who uses pyatv?

Here are a few projects known to use pyatv:

• Home Assistant - The Apple TV integration is powered by pyatv
• node-pyatv - Node.Js binding built using pyatv
• pyatv-mqtt-bridge - MQTT Bridge allows you to remote control your Apple TV using the MQTT protocol (built using node-pyatv)
• homebridge-appletv - Configuration of pyatv and homebridge-cmd4 for reading the Apple TV status in Homebridge
• Indigo Domotics Plugin - Plugin to Indigo Domotics
• iSponsorBlockTV - Skip sponsor segments in YouTube videos playing on an Apple TV
• homebridge-homepod-radio - Homebridge accessory for streaming radio to Homepod mini
• node-red-contrib-apple-tv-x - Apple TV control from inside Node-RED

If you are maintaining a project using pyatv, feel free to add it to the list (open a PR or issue). You don’t need to provide a URL if you don’t want, just a short description of the use case is fine too!

License

This library is licensed under the MIT license.

Who is making this?

I, Pierre Ståhl, is the lead developer and maintainer of this library. It is a hobby project that I put a few hours in every now and then to maintain. If you find it useful, please consider to sponsor me!

Of course, this is an open source project which means I couldn’t do it all by myself. I have created dedicated page for acknowledgements!