Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

Library for controlling an Apple TV

Project Description

This is a python library for controlling and querying information from an Apple TV. It is async (python 3.4 syntax) and supports most of the commands that the regular Apple Remote app does as well as some additional iTunes commands, like changing the media position.

As this library is still at an early development stage, functionality is still missing, bugs exist and API may change. Look at this as a “technical preview”. API is not considered final until version 1.0 is released.

NOTE: As pairing is not yet implemented, you must enable home sharing on your Apple TV for this library to work! Once pairing is implemented, this restriction will be lifted.

The MIT license is used for this library.


  • Automatic discovery of devices (zeroconf/Bonjour)
  • Most buttons (play, pause, next, previous, select, menu, topmenu)
  • Fetch artwork in PNG format
  • Currently playing (e.g. title, artist, album, total time, etc.)
  • Change media position


  • python>=3.4.2
  • zeroconf==0.17.6
  • aiohttp==1.2.0

Getting started


Use pip:

$ pip install pyatv

Using the API

Here is a simple example using auto discovery and printing what is playing:

import asyncio
from pyatv import helpers

def print_what_is_playing(atv):
    playing = yield from atv.metadata.playing()
    print('Currently playing:')


Additional and more advanced examples can be found in examples.

Using the CLI application

It is possible to use the reference CLI application as well:

# Automatically discover device (zeroconf)
$ atvremote -a play
$ atvremote -a next

# Scanning for devices on network
$ atvremote
Found Apple TVs:
 - Apple TV at (hsgid: 00000000-1234-5678-9012- 345678901234)

# Manually specify device
$ atvremote --address --hsgid 00000000-1234-5678-9012- 345678901234 playing
album: None
artist: None
media_type: 1
play_state: 1
position: 0
title: None
total_time: 0

# List all commands supported by a device
$ atvremote -a commands
Remote control commands:
 - set_position - Seeks in the current playing media
 - pause - Press key play
 - menu - Press key menu
 - topmenu - Go to top menu (long press menu)
 - down - Press key down
 - previous - Press key previous
 - up - Press key up
 - right - Press key right
 - play - Press key play
 - select - Press key select
 - next - Press key next
 - left - Press key left

Metadata commands:
 - playing - Returns what is currently playing
 - artwork - Returns artwork for what is currently playing (or None)

Playing commands commands:
 - title - Title of the current media, e.g. movie or song name
 - play_state - Current play state, e.g. playing or paused
 - artist - Artist of the currently playing song
 - media_type - What type of media is currently playing, e.g. video, music
 - total_time - Total play time in seconds
 - album - Album of the currently playing song
 - position - Current position in the playing media (seconds)

Type atvremote –help to list all supported commands.

Missing features and improvements

There are still a lot to do. Here is a summary of currently known missing functionality and other improvements. GitHub issues will be created for easier tracking.

Other tasks

  • Help command to get full help text for a command
  • Verify support with Apple TV 4
  • Automatic builds with travis
  • Write simple smoke test for atvremote
  • Improved documentation
    • More examples
    • Better pydoc documentation for classes and methods
    • Manual in docs/
    • Add to
  • Investigate support for additional operations (shuffle, repeat, etc.)


Fork this project, clone it and run to setup a virtual environment and install everything needed for development:

git clone
cd pyatv
source bin/activate

You can run the tests with python test. Also, make sure that pylint, flake8 and pydoc passes before committing. This is done automatically if you run just run tox.

When using atvremote, pass –developer to enable some developer friendly commands. You may also pass –debug to get better logging.

Release History

Release History

This version
History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
pyatv-0.0.1-py3-none-any.whl (18.5 kB) Copy SHA256 Checksum SHA256 py3 Wheel Feb 1, 2017
pyatv-0.0.1.tar.gz (301.9 kB) Copy SHA256 Checksum SHA256 Source Feb 1, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting