Main Page

This is a python 3.6 (or later) library for controlling and querying information from an Apple TV. It is built upon asyncio and supports most of the commands that the regular Apple Remote app does and more!

Support for tvOS is still in early stages, but feel free to give it a spin:

pip install pyatv

This library is licensed under the MIT license.

Where to start?

As pyatv is a library, it is mainly aimed for developers creating applications that can interact with Apple TVs. However, pyatv ships with a powerful command line application that is useful for normal users as well.

So, head over to Getting started to get going!

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

In case you have developed for pyatv 0.3.x before, there’s a short migration guide here that will help you port your code to 0.4.x or later.

Features

Here is the feature list by protocol (DMAP = devices not running tvOS, MRP = Apple TV 4 and later):

Feature DMAP MRP Links
Automatic discovery of devices (zeroconf/Bonjour) Yes Yes Doc, pyatv.scan
Device Metadata (e.g. operating system and version) Yes* Yes* Doc, interface.DeviceInfo
Push updates Yes Yes Doc, interface.PushUpdater
Remote control pairing Yes Yes Doc, interface.PairingHandler
List supported features Yes** Yes Doc, interface.Features
AirPlay stream URL (including tvOS 10.2+) Yes Yes Doc, interface.Stream
Playback controls (play, pause, next, stop, etc.) Yes Yes Doc, interface.RemoteControl
Navigation controls (select, menu, top_menu, arrow keys) Yes Yes Doc, interface.RemoteControl
Fetch artwork Yes Yes Doc, interface.Metadata.artwork
Currently playing (e.g. title, artist, album, total time, etc.) Yes Yes Doc, interface.Metadata
App used for playback No Yes Doc, interface.App
Media type and play state Yes Yes Doc, interface.Metadata
Change media position Yes Yes Doc, interface.Metadata.set_position
Shuffle and repeat Yes Yes Doc, interface.Metadata.set_shuffle, interface.Metadata.set_repeat
Power management No Yes Doc, interface.Power

* Some restrictions apply, see section “Device Metadata” here page.

** Limited support due to restrictions in protocol.

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

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! :heart:

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!