Table of Contents
- Supported Features
- Some things worth knowing…
- Feature List
- Core Features
- Protocols per Device
- Protocols Details
Supported Features
pyatv supports multiple protocols, each of them providing a certain set of features.
This page aims to summarize the provided feature set, what each protocol supports as
well as limitations.
In general, as a developer you should use interface.Features to verify if a particular feature is available or not and refrain from making other assumptions. See this page as informational.
This page is still work-in-progress and a bit inconsistent. State will improve over time.
Some things worth knowing…
Things change. Constantly. Here are a few things worth knowing about the protocols:
- The DMAP protocol (suite) stems from iTunes and was used on all Apple TVs until tvOS 13, i.e. all versions of Apple TV 3 and earlier as well as Apple TV 4 (and later) until tvOS 13 was released. It means it’s not widely used anymore, other than with older devices. It can be used to control the Music app in macOS [#1172].
- The MRP protocol was introduced in tvOS when the Apple TV 4 was introduced. In tvOS 15, it was demoted from a separate protocol (it used to have it’s own Remote app as well as Zeroconf service,
_mediaremotetv._tcp.local) and moved to a special stream type in AirPlay 2 instead. Devices running tvOS 15 (beta or later) require AirPlay to be set up to function properly. - tvOS 10.2 enforced “device authentication” for AirPlay to function. This is referred to as “legacy pairing” and is only used to verify a connection, it does not enforce any encryption. It also works for RAOP. AirPlay 2 however require “HAP” (HomeKit) authentication, which enforce encryption. Only legacy pairing is supported for RAOP in pyatv at the moment (as encryption has not been implemented for HAP based authentication).
Feature List
This is the general feature list provided by the external interface.
| Feature | Links |
|---|---|
| Automatic discovery of devices (zeroconf/Bonjour) | Concept, Doc, pyatv.scan |
| Device Metadata (e.g. operating system and version) | Concept, Doc, interface.DeviceInfo |
| Push updates | Concept, Doc, interface.PushUpdater |
| Remote control pairing | Concept, Doc, interface.PairingHandler |
| List supported features | Concept, Doc, interface.Features |
| AirPlay play URL (including local files) | Doc, interface.Stream |
| AirPlay stream files and from HTTP(s) | Doc, interface.Stream |
| Playback controls (play, pause, next, stop, etc.) | Doc, interface.RemoteControl |
| Navigation controls (select, menu, top_menu, arrow keys) | Doc, interface.RemoteControl |
| Different input actions (tap, double tap, hold) | Doc, interface.RemoteControl |
| Fetch artwork | Doc, interface.Metadata.artwork |
| Currently playing (e.g. title, artist, album, total time, etc.) | Doc, interface.Metadata |
| App used for playback | Doc, interface.App |
| Media type and play state | Doc, interface.Metadata |
| Change media position | Doc, interface.Metadata.set_position |
| Shuffle and repeat | Doc, interface.Metadata.set_shuffle, interface.Metadata.set_repeat |
| Volume Controls | Doc, interface.RemoteControl |
| Power management | Doc, interface.Power |
| Deep Sleep Detection | Concept, Doc, pyatv.scan |
| Launch application | Doc, interface.Apps |
| List installed apps | Doc, interface.Apps |
| Storage | Doc, interface.Storage |
Core Features
Some features are provided generally by pyatv and not bound to any particular protocol. These core features include:
- Automatic service discovery with zeroconf (Scanning)
- Device information via information from service discovery (Device Information)
- Set up of protocols based on provided configuration
- Callbacks when connection is lost (Device Updates)
- Storage API for storing settings and credentials somewhere, e.g. file or a cloud service (Storage and Settings)
Protocols per Device
Here is a summary of what protocols various devices support:
| Protocol | Devices |
|---|---|
| AirPlay (video) | Apple TV (any) |
| Companion | Apple TV 4(K), HomePod (mini) |
| DMAP | Apple TV 2/3 |
| MRP | Apple TV 4(K), tvOS <=14 |
| RAOP | Apple TV, AirPort Express gen 2, HomePod (mini), 3rd party speakers |
pyatv might still not support a particular combination of protocol or hardware, please
refer to protocol details below.
Protocols Details
This section provides details on what each protocols support and current limitations.
AirPlay
This protocol concerns the “video” parts of the AirPlay protocol suite, e.g. video streaming, screen mirroring and image sharing.
Supported Features
- Legacy pairing for older devices (e.g. Apple TV 3)
- HAP based for AirPlay 2 features (only used for remote control)
- Playing files with interface.Stream.play_url
- Tunneling of MRP over AirPlay 2 to support tvOS 15 and the HomePod
Limitations and notes
- Very limited support for this protocol so far. More features will be added in the future.
- Does not implement support for interface.DeviceListener and will
not trigger
connection_lostorconnection_closedwhen used stand-alone.
Companion
This protocol is a low-overhead protocol supporting remote control features, HID (touch control), app and power related functions.
Supported Features
- Pairing is supported as long as target device can show a PIN code, e.g. Apple TV but not HomePod or a Mac
- All features in the app interface (interface.Apps)
- Turn on/off device (interface.Power.turn_on, interface.Power.turn_off)
- Remote control (see interface.RemoteControl for supported buttons)
- Touch gestures and click
Limitations and notes
- Early stage of development - not many features supported
DMAP
This protocol is the same protocol (suite) used by iTunes in the past and mainly deals with metadata and playback. It is used by legacy devices, like Apple TV 3 and also to control the Music app in macOS.
Supported Features
- Pairing
- Device Metadata
- Push Updates
- Features interface
- Remote control (see interface.RemoteControl for supported buttons)
- Artwork
- Playing metadata
- Device and playback state
- Shuffle and repeat
- Volume control
Limitations and notes
- The features interface will make educated gueeses on what is supported as no proper support for this exists in the protocol
- No support for different tap actions in conjunction with button (e.g. double tap or hold) as it’s not supported by the protocol
- It is possible to discover and control a Music app running on macOS (except for 11.4, likely a bug).
MRP
This protocol was introduced in tvOS and superseds DMAP. It has the same features as well as new ones, like notion of apps and game pad controls.
Supported Features
- Pairing
- Device Metadata
- Push Updates
- Features interface
- Remote control including different input actions (see interface.RemoteControl for supported buttons)
- Artwork
- Playing metadata
- Device and playback state
- Shuffle and repeat
- Volume controls
- Current playing app
- Power management
Limitations and notes
- Power management is not very robust (relies on navigating and pressing buttons). The Companion protocol provides better support and it is recommended to set up both concurrently for best experience.
RAOP
This protocols corresponds to the audio streaming part of AirPlay (previously known as AirTunes).
Supported Features
- Stream files with interface.Stream.stream_file
- Basic support to stream from http(s) via interface.Stream.stream_file
- Metadata is read from file and sent to receiver (artist, album and title)
- Supports WAV, MP3, FLAG and OGG as file format (also for metadata)
- Metadata (device state, media type, title, artist, album, position, total_time)
- Push Updates
- Volume controls (volume level, set_volume, volume_up, volume_down)
- One stream can be played at the time (second call raises exceptions.InvalidStateError)
- If the device requires pairing, e.g. Apple TV 4 or later, pairing must be performed and credentials provided. AirPlay credentials obtained prior to version 0.8.2 are compatible, later versions require re-pairing specifically with RAOP.
Limitations and notes
- Metadata and push updates only reflect what pyatv is currently playing as there seems to not be possible to get current play state from an AirPlay receiver (see next bullet for exceptions).
- It is possible to obtain metadata in some cases by combining protocols, e.g. by pairing RAOP in conjunction with AirPlay or MRP for instance. On the HomePod, the AirPlay protocol will provide metadata by tunneling the MRP protocol.
- Devices requiring password are only supported when using the RAOP protocol
- Remote control commands does not work (except for volume_up and volume_down), e.g. play or pause [#1068]
- Does not implement support for interface.DeviceListener and will
not trigger
connection_lostorconnection_closedwhen used stand-alone.
Verified Devices
Audio streaming has been verified to work with these devices:
- Apple TV 3 (v8.4.4)
- Apple TV 4K gen 1 (v14.5)
- airplay2-receiver (224b9660c31ed8624f46fdae9fcb5f44e5ec6c12)
- HomePod Mini (v14.5)
- AirPort Express (v7.8.1)
- Yamaha RX-V773 (v1.98)
The following 3rd party software receivers have also been verified to work:
- shairport-sync (v4.2)
If you have verified another device or receiver, please update the list by pressing Edit this page below and opening a pull request.