---
layout: template
title: AirPlay
permalink: /development/airplay/
link_group: development
---
# AirPlay

Currently there is some AirPlay functionality supported in `pyatv`, but it is
very limited. Only two features are supported:

- Device authentication ("pairing")
- Playing media via URL

In the external interface, AirPlay support is implemented via the {% include api i="interface.Stream" %}
API.

Additional features will be added as needed.

## Device Authentication

In tvOS 10.2, Apple started to enforce a feature called "device authentication".
This requires every device that streams content via AirPlay to enter a PIN code
the first time before playback is started. Once done, the user will never have
to do this again. The actual feature has been available for a while but as
opt-in, so it would have to be explicitly enabled. Now it is enabled by default
and cannot be disabled. Devices not running tvOS (e.g. Apple TV 2nd and 3rd
generation) are not affected, even though device authentication can be enabled
on theses devices as well.

The device authentication process is based on the *Secure Remote Password*
protocol (SRP), with slight modifications. All the reverse engineering required
for this process was made by funtax (GitHub username) and has merly been ported
to python for usage in this library. Please see references at bottom of page
for reference implementation.

## Device Authentication ("Pairing")

When performing device authentication, a device identifier and a private key is
required. Once authenticated, they can be used to authenticate without using a
PIN code. So they must be saved and re-used whenever something is to be played.

In this library, the device identifier and private key is called
*AirPlay credentials* and are concatenated into a string, using : as separator.
An example might look like this:

    D9B75D737BE2F0F1:6A26D8EB6F4AE2408757D5CA5FF9C37E96BEBB22C632426C4A02AD4FA895A85B
           ^                       ^
      Identifier              Private key

The device authentication is performed via the pairing API, just like with
any other protocol. New random credentials are generated by default, as long
as no existing credentials are provided. So there is nothing special here.

## Playing media

Playing a URL is as simple as passing the URL to {% include api i="interface.Stream.play_url" %}:

```python
url = 'http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4'
await atv.stream.play_url(url)
```

If the device requires device authentication, credentials must be present for
the AirPlay service. Otherwise an error message will be shown on the screen.

## References

[AirPlayAuth](https://github.com/funtax/AirPlayAuth)

[Unofficial AirPlay Protocol Specification](https://nto.github.io/AirPlay.html)
