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
• Persistent storage of credentials and settings, e.g. to file or custom built storage

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.

• As of tvOS 15, the Media Remote Protocol (MRP) is tunneled over AirPlay 2. Support for this was introduced in version 0.9.0 of pyatv, so be sure to use a later version than that.
• Support for interface.Stream.play_url on tvOS was restored in version 0.13.3.
• It is possible to control the Music app running on a Mac, but macOS 11.4 seems to not work.
• If you have problems with miniaudio on ARM (e.g. Rasperry Pi), try re-installing miniaudio and building it from source. See here for details.
• 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-enhanced - Homebridge plugin that is providing functionality that should be native to HomeKit
• 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
• c4-pyatv-remote - Control4 remote control integration

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!