pyatv is an asyncio Python client library, distributed on PyPI under the MIT licence, that lets developers and home-automation builders control Apple TV, HomePod, AirPort Express, and other AirPlay and RAOP receivers from their own code and scripts.

What it is

pyatv is a client library for Apple TV and AirPlay devices, written in Python and built around asyncio. It targets Apple TVs across all generations, including tvOS 15 and later, and it also handles audio streaming over AirPlay to receivers such as the HomePod, AirPort Express, and third-party speakers. It can additionally act as a remote control for the Music app and iTunes running on macOS. The library lives in the Python ecosystem, installs from PyPI, exposes its API at pyatv.dev, and ships a companion command-line tool called atvremote for day-to-day use.

The concrete problem it solves is access. Without it, controlling an Apple TV means using a physical remote and an on-screen interface, and there is no supported way for a program to read what is playing, launch an app, switch accounts, or change audio output destinations. pyatv replaces that manual, screen-bound control with a scriptable interface, pairing over the Media Remote Protocol (Protocol.MRP) and exposing playback state, metadata, and app control as ordinary calls. That makes Apple TV devices addressable from automation, dashboards, and other software rather than only from the sofa.

Key capabilities

• Send remote control commands and read playback state, for example atvremote -s 10.0.10.254 playing and atvremote -s 10.0.10.254 pause.
• Retrieve metadata with push updates, so currently playing media and state changes arrive without polling.
• Discover and pair devices through atvremote wizard, which scans the local network, lists found devices with name, model, and address, and reports pairing success per protocol.
• Address devices by network name as well as by address, for example atvremote -n FakeATV play.
• Stream files over AirPlay, and add, remove, or set audio output devices such as HomePods.
• List and launch installed apps, list and switch user accounts, and accept keyboard input.
• Persist credentials and settings, and run in a container image published as ghcr.io/postlund/pyatv:0.14.0.

Who uses it and how

• Home-automation developers who want Apple TV playback and state folded into their own automations, with the home-automation topic marking that audience.
• Python developers building interactive control surfaces, since the library is asyncio-based and installs as the pyatv package.
• Teams running headless on a home server: the container image covers x86_64, aarch64, and armv7, and docker run -it --rm --network=host ghcr.io/postlund/pyatv:0.14.0 atvremote scan needs no Python environment.
• Contributors who want a prepared environment rather than local setup, using the Gitpod button in the README.
• Script and CLI users who set a device up once with the wizard, then drive it with short atvremote calls.

Getting started

Install with pip install pyatv, then run atvremote wizard to scan the network and pair with a device by entering the PIN shown on screen. A container is available as an alternative: docker run -it --rm --network=host ghcr.io/postlund/pyatv:0.14.0 atvremote scan, where the master tag points to the latest commit on master and latest to the latest release.

How it compares

This registry entry does not list comparable or paid products that pyatv replaces, and the README names no similar tools. It therefore stands alone in this registry, and any comparison would have to come from outside the provided facts.

When to use it — and when not to

Choose pyatv when the goal is programmatic control of Apple TV and AirPlay hardware from Python or from a container, and when operating a device that must be paired once with a PIN entered on screen is acceptable. Anyone who wants a finished graphical application, or who cannot run Python or a Docker container on the network the devices live on, should look elsewhere. The project carries a substantial open issue count of 258, so some behaviours and device combinations are still unsettled, and the credentials and settings it stores persistently are a thing to manage rather than ignore.

$ pip install pyatv
$ atvremote wizard
Looking for devices...
Found the following devices:
    Name                      Model                    Address
--  ------------------------  -----------------------  -----------
 1  Receiver+                 airupnp                  10.0.10.200
 2  Receiver                  RX-V773                  10.0.10.82
 3  Pierre's AirPort Express  AirPort Express (gen 2)  10.0.10.168
 4  FakeATV                   Unknown                  10.0.10.254
 5  Vardagsrum                Apple TV 4K              10.0.10.81
 6  Apple TV                  Apple TV 3               10.0.10.83
Enter index of device to set up (q to quit): 4
Starting to set up FakeATV
Starting to pair Protocol.MRP
Enter PIN on screen: 1111
Successfully paired Protocol.MRP, moving on...
Pairing finished, trying to connect and get some metadata...
Currently playing:
  Media type: Music
Device state: Playing
       Title: Never Gonna Give You Up
      Artist: Rick Astley
    Position: 1/213s (0.0%)
      Repeat: Off
     Shuffle: Off
Device is now set up!

$ atvremote -s 10.0.10.254 playing
  Media type: Music
Device state: Playing
       Title: Never Gonna Give You Up
      Artist: Rick Astley
    Position: 1/213s (0.0%)
      Repeat: Off
     Shuffle: Off
$ atvremote -s 10.0.10.254 pause
$ atvremote -n FakeATV play

docker run -it --rm --network=host ghcr.io/postlund/pyatv:0.14.0 atvremote scan