@bharper/atv-js 0.2.6 → 0.3.4

package/pyatv/docs/documentation/workspace.code-workspace

@@ -0,0 +1,7 @@
+{
+	"folders": [
+		{
+			"path": "../.."
+		}
+	]
+}

package/pyatv/docs/index.md

@@ -0,0 +1,109 @@
+---
+layout: template
+title: pyatv
+---
+# :tv: Main Page
+
+This is an asyncio python library for interacting with Apple TV and AirPlay devices. It mainly
+targets Apple TVs (all generations), but also support audio streaming via AirPlay to receivers like the HomePod,
+AirPort Express and third-party speakers. It can act as remote control to the Music app/iTunes in macOS.
+
+![Tests](https://github.com/postlund/pyatv/workflows/Tests/badge.svg)
+[![codecov](https://codecov.io/gh/postlund/pyatv/branch/master/graph/badge.svg)](https://codecov.io/gh/postlund/pyatv)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![PyPi Package](https://badge.fury.io/py/pyatv.svg)](https://badge.fury.io/py/pyatv)
+[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/postlund/pyatv.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/postlund/pyatv/context:python)
+[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/postlund/pyatv)
+[![Downloads](https://static.pepy.tech/badge/pyatv)](https://pepy.tech/project/pyatv)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/pyatv.svg)](https://pypi.python.org/pypi/pyatv/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# :satisfied: Features
+
+Here is a short summary of supported features:
+
+* Automatic device discovery with Zeroconf
+* Device information, e.g. hardware model and operating system version
+* Currently playing metadata, artwork and push updates
+* Remote, navigation and volume control commands
+* Basic support for streaming video and audio with AirPlay
+* Listing installed apps, launching apps and currently playing app
+* Power management, e.g. turn on or off
+* Supports Apple TV (all of them), AirPort Express, HomePod, macOS music app and most AirPlay v1 receivers
+* Persistent storage of credentials and settings, e.g. to file or custom built storage
+
+A complete list of supported features and limitations is available
+[here](documentation/supported_features).
+
+There are also few utility scripts bundled with pyatv that makes it easy to try the library
+out. Check out [atvremote](documentation/atvremote), [atvproxy](documentation/atvproxy),
+[atvscript](documentation/atvscript) and [atvlog](documentation/atvlog).
+
+# :eyes: Where to start?
+
+To get going, install with `pip`:
+
+<div class="center_box" style="margin-bottom: 2em">
+  <p style="margin: 0px">:tada: <a href="https://pypi.org/project/pyatv">pip install pyatv :tada:</a></p>
+</div>
+
+Head over to [Getting started](documentation/getting-started) to see what you can do! There's
+also a [Tutorial](documentation/tutorial) if you want to get going faster!
+
+As pyatv is a library, it is mainly aimed for developers creating applications that can interact
+with Apple TVs. However, pyatv ships with a few powerful command lines tools you can use to
+try the library without writing any code.
+
+If you need help or have questions, check out the [Support](support) page instead.
+
+In case you are upgrading from an earlier version of pyatv, make sure to check out the migration
+guide [here](support/migration) that will help you port your existing code.
+
+# :cloud: In other the news...
+
+As pyatv depends solely on private and reverse engineered protocols, things sometimes break because
+Apple changes something. Or because of other reasons. This section covers the major things that you
+need to be aware of.
+
+* As of tvOS 15, the Media Remote Protocol (MRP) is tunneled over AirPlay 2. Support for this was
+  introduced in version 0.9.0 of pyatv, so be sure to use a later version than that.
+* Support for {% include api i="interface.Stream.play_url" %} on tvOS was restored in version 0.13.3.
+* It is possible to control the Music app running on a Mac, but macOS 11.4 seems to not work.
+* If you have problems with {% include pypi package="miniaudio" %} on ARM (e.g. Rasperry Pi), try
+  re-installing {% include pypi package="miniaudio" %} and building it from source. See [here](support/faq#when-using-pyatv-on-a-raspberry-pi-eg-running-atvremote-i-get-illegal-instruction-how-do-i-fix-that)
+  for details.
+* Other general issues can be found in the [FAQ](support/faq).
+
+# :trophy: Who uses pyatv?
+
+Here are a few projects known to use pyatv:
+
+* [Home Assistant](https://home-assistant.io) - The Apple TV integration is powered by pyatv
+* [node-pyatv](https://github.com/sebbo2002/node-pyatv) - Node.Js binding built using pyatv
+* [pyatv-mqtt-bridge](https://github.com/sebbo2002/pyatv-mqtt-bridge) - MQTT Bridge allows you to remote control your Apple TV using the MQTT protocol (built using node-pyatv)
+* [homebridge-appletv-enhanced](https://github.com/maxileith/homebridge-appletv-enhanced#homebridge-appletv-enhanced) - Homebridge plugin that is providing functionality that should be native to HomeKit
+* [Indigo Domotics Plugin](https://github.com/kw123/appleTV) - Plugin to Indigo Domotics
+* [iSponsorBlockTV](https://github.com/dmunozv04/iSponsorBlockTV) - Skip sponsor segments in YouTube videos playing on an Apple TV
+* [homebridge-homepod-radio](https://github.com/petro-kushchak/homebridge-homepod-radio) - Homebridge accessory for streaming radio to Homepod mini
+* [node-red-contrib-apple-tv-x](https://github.com/twocolors/node-red-contrib-apple-tv-x) - Apple TV control from inside Node-RED
+* [c4-pyatv-remote](https://github.com/13mralex/c4-pyatv-remote) - Control4 remote control integration
+* [atv-desktop-remote](https://github.com/bsharper/atv-desktop-remote) - Desktop remote control for Apple TV
+
+If you are maintaining a project using pyatv, feel free to add it to the list (open a PR
+or [issue](https://github.com/postlund/pyatv/issues/new?assignees=&labels=question,documentation&template=question-or-idea.md&title=Add+my+pyatv+project+to+list&assignees=postlund)).
+You don't need to provide a URL if you don't want, just a short description of the use case
+is fine too!
+
+# :office: License
+
+This library is licensed under the
+[MIT license](https://github.com/postlund/pyatv/blob/master/LICENSE.md).
+
+# :person_with_blond_hair: 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](support/acknowledgements)!

package/pyatv/docs/internals/design.md

@@ -0,0 +1,354 @@
+---
+layout: template
+title: Design
+permalink: /internals/design
+link_group: internals
+---
+# :construction: Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# Design
+
+This page gives a brief introduction to the architecture and design of pyatv.
+
+*NB: This page is far from complete and under development. Please let me know if you
+want any part of pyatv explained further, so I can add it here.*
+
+# General Topics
+
+This section contains a few topics covering general design concepts, not going into any
+protocol specific details.
+
+## Configuration
+
+A *configuration* is a general description of a device and is represented by an instance of
+{% include api i="conf.AppleTV" %}. The easiest and best way of obtaining a configuration is
+{% include api i="pyatv.scan" %}, as a list of configurations are returned. Both when pairing
+and connecting, a configuration is needed.
+
+The configuration instance stores general information about the device, like IP address,
+name and various other properties used by the device info interface. It also stores a list
+of services associated with the device, i.e. the protocols it supports. A simple overview:
+
+<code class="diagram">
+classDiagram
+    class AppleTV
+    AppleTV : str address
+    AppleTV : int port
+    AppleTV : ...
+    class AirPlayService
+    AirPlayService : str identifier
+    AirPlayService : int port
+    AirPlayService : ...
+    class CompanionService
+    CompanionService : int port
+    CompanionService : ...
+    class DmapService
+    DmapService : str identifier
+    DmapService : int port
+    DmapService : ...
+    class MrpService
+    MrpService : str identifier
+    MrpService : int port
+    MrpService : ...
+    class RaopService
+    RaopService : str identifier
+    RaopService : int port
+    RaopService : ...
+    AppleTV --* AirPlayService
+    AppleTV --* CompanionService
+    AppleTV --* DmapService
+    AppleTV --* MrpService
+    AppleTV --* RaopService
+</code>
+
+## Scanning
+
+Scanning can be performed in one of two ways: unicast or multicast. The different methods are
+implemented as separate scanners in {% include code file="support/scan.py" %}:
+
+<code class="diagram">
+graph TD
+    A[User] -->|hosts=X| B(pyatv.scan)
+    B -->|X=None| C[MulticastMdnsScanner]
+    B -->|X=10.0.0.2,10.0.0.3| D[UnicastMdnsScanner]
+</code>
+
+**UnicastMdnsScanner:** Sends zeroconf requests directly to one or more hosts as specified via the *hosts* argument.
+
+**MulticastMdnsScanner:** Uses multicast and sends requests to all hosts on the network.
+
+Each request contains a list of all the services that pyatv are interested in, i.e. services
+used by the implemented protocols. Each protocol must implement a `scan` method returning
+which Zeroconf services it needs as well as handlers that are called when a service is found.
+An example from Companion looks like this:
+
+```python
+def companion_service_handler(
+    mdns_service: mdns.Service, response: mdns.Response
+) -> ScanHandlerReturn:
+    """Parse and return a new Companion service."""
+    service = conf.CompanionService(
+        mdns_service.port,
+        properties=mdns_service.properties,
+    )
+    return mdns_service.name, service
+
+
+def scan() -> Mapping[str, ScanHandler]:
+    """Return handlers used for scanning."""
+    return {"_companion-link._tcp.local": companion_service_handler}
+```
+
+Whenever a service with type `_companion-link._tcp.local` is found, the function/handler
+`companion_service_handler` is called. Device name and a {% include api i="interface.BaseService" %}
+representing the service is returned and added to the final device configuration.
+
+Both unicast (which is a pyatv specific term) and multicast scanning uses a homegrown
+implementation of Zeroconf instead of relying on a third party. One exception however
+is when publishing new services on the network. In that case
+[python-zeroconf](https://github.com/jstasiak/python-zeroconf) is used. Prior to version
+0.7.0 of pyatv, python-zerconf would also be used for scanning but some limitations in
+the library drove a new implementation. Namely these:
+
+* No other library seems to support sending requests to a specific host, but only allow
+  multicast. Unicast was added as an alternative method of scanning for people experiencing
+  problems with multicast. It's a very special case but works quite well.
+* Not possible to request more than one service at the time in a request. One device in
+  pyatv generally depend on service data from more than one service (e.g. MRP and AirPlay).
+  Using python-zeroconf, pyatv needed to subscribe to each service independently and await
+  all responses. It's not really possible to know when to stop waiting as one cannot know
+  how many services to wait for. The implementation in pyatv supports requesting all the
+  relevant services at the same time, yielding one response with all service data.
+  It means less traffic, more accurate scanning and less waiting.
+* Response messages contains a special entry (`_device-info._tcp.local`) which isn't a pure
+  service, so it's not possible to subscribe to. It contains the device model, used under
+  some circumstances to derive hardware model. Other libraries does not allow access
+  to this entry, basically ignoring it, so device info would be lost.
+
+The Zeroconf implementation is in {% include code file="support/mdns.py" %} and some helper
+routines for DNS in {% include code file="support/dns.py" %}.
+
+## Connecting
+
+When connecting to a device, an instance of {% include api i="interface.AppleTV" %} is created.
+This section describes the basics of how that is done.
+
+### Set up of a protocol instance
+
+When connecting to a device, each service is used to set up a new protocol. This will
+create instances of all interface implementations, register them with it's corresponding
+relayer (see next section) and connect (if needed by the protocol). Each protocol must
+implement a `setup` method and add that to the list in
+{% include code file="__init__.py" %} for this to work.
+
+A simple example of a setup method looks like this:
+
+```python
+def setup(
+    loop: asyncio.AbstractEventLoop,
+    config: conf.AppleTV,
+    interfaces: Dict[Any, Relayer],
+    device_listener: StateProducer,
+    session_manager: ClientSessionManager,
+) -> Generator[SetupData, None, None]:
+    # Service information for current protocol
+    service = config.get_service(Protocol.XXX)
+
+    # Create any protocol specific things here
+    protocol = DummyProtocol()
+
+    # Register interfaces with corresponding relayers
+    interfaces = {
+        RemoteControl: DummyRemoteControl(protocol)
+    }
+
+    # Called for all protocols _after_ setup has been called for all protocols
+    async def _connect() -> bool:
+        await protocol.start()
+        return True  # Connect succeeded
+
+    # Called when closing the device connection
+    def _close() -> Set[asyncio.Task]:
+        protocol.stop()
+        return set()  # Tasks thas has not yet finished
+
+    # Yield connect handler, close handler and a set with _all_ features supported
+    # by the protocol.
+    yield SetupData(Protocol.XXX, _connect, _close, interfaces, set([FeatureName.Play]))
+```
+
+The `_connect` and `close` methods will be called by the facade object when connecting
+or disconnecting. For the feature interface to work properly, each protocol must yield
+which features they support. This is used internally in the features implementation in
+the facade to know if a protocol implements a certain feature or not.
+
+A protocol can yield as many protocol implementations as they want, even protocols of
+a different kind. This is to support the use case where one protocol is tunneled over
+another protocol, for instance how MRP is carried over a stream in AirPlay 2.
+
+### Relaying
+
+The general idea of the {% include code file="support/relayer.py" %} module is to allow
+protocols to only implement parts of an interface as well as allowing multiple protocols
+to implement the same interfaces, but still provide meaningful output to the user. This
+is accomplished in two ways:
+
+* There's a built-in priority amongst protocols. If several protocols implement the same
+  functionality, the implementation of the protocol with highest priority is picked. The
+  general priority is MRP, DMAP, Companion, AirPlay and RAOP.
+* The relayer verifies if a protocol has actually provided an implementation of a
+  particular member before relaying, ignoring it otherwise.
+
+One relayer is responsible for one interface only. This means that several realyers must
+be used to support all the interfaces in pyatv. The facade implementation described below
+keeps track of all those relayers.
+
+A typical example of a relayer instance might look like this:
+
+<code class="diagram">
+classDiagram
+    class Relayer
+    Relayer : relay(target, priority)
+    class MrpPower
+    MrpPower : PowerState power_state
+    MrpPower : turn_on(await_new_state)
+    MrpPower : turn_off(await_new_state)
+    class CompanionPower
+    CompanionPower : turn_on(await_new_state)
+    CompanionPower : turn_off(await_new_state)
+    Relayer --> MrpPower
+    Relayer --> CompanionPower
+</code>
+
+Here, only `MrpPower` implements {% include api i="interface.Power.power_state" %},
+making the relayer always return the value from the MRP implementation. The remaining
+methods are implemented by both instances, leaving the choice to priority. A relayer
+always has a pre-defined priority list from when it was created (general priority list
+mentioned above), but it's also possible to override the internal priority list when
+calling the `relay` method. This makes it possible to deal with special cases, where
+one protocol with lower priority provides a better implementation than one with
+higher priority. The power interface is one such example, where the Companion
+implementation is better than MRP (even though MRP has higher general priority than
+Companion).
+
+### Facade
+The "facade" implements {% include api i="interface.AppleTV" %} as well as all
+interfaces belonging to it. One relayer is allocated per interface and protocols
+register instances of interfaces they implement during the setup phase (when
+connecting). An example with some of the interfaces looks like this:
+
+<code class="diagram">
+graph TD
+    AppleTV -->|interface.AppleTV| FacadeAppleTV
+    FacadeAppleTV -->|interface.Power|PowerRelayer[Relayer]
+    FacadeAppleTV -->|interface.Audio|AudioRelayer[Relayer]
+    FacadeAppleTV -->|interface.Apps|AppsRelayer[Relayer]
+    FacadeAppleTV -->|interface.Remotecontrol|RCRelayer[Relayer]
+    PowerRelayer --> CompanionPower
+    PowerRelayer --> MrpPower
+    AudioRelayer --> RaopAudio
+    AppsRelayer --> CompanionApps
+    RCRelayer --> DmapRemoteControl
+    RCRelayer --> MrpRemoteControl
+    RCRelayer --> RaopRemoteControl
+</code>
+
+From a user point of view, all interaction occurs with the facade object which
+relays calls to the most appropriate protocol instance. A typical interface
+implementation looks like this:
+
+```python
+class FacadeApps(Relayer, interface.Apps):
+
+    def __init__(self):
+        super().__init__(interface.Apps, DEFAULT_PRIORITIES)
+
+    async def app_list(self) -> List[interface.App]:
+        return await self.relay("app_list")()
+
+    async def launch_app(self, bundle_id: str) -> None:
+        await self.relay("launch_app")(bundle_id)
+```
+
+Calls are relayed and potentially returning a value. As described in the relayer
+section above, the priority rule is generally used to determine which instance is called.
+But the facade can side-step this rule and implement it's own logic when deemed necessary.
+One example is the power implementation (short version):
+
+```python
+class FacadePower(Relayer, interface.Power, interface.PowerListener):
+    OVERRIDE_PRIORITIES = [
+        Protocol.Companion,
+        Protocol.MRP,
+        Protocol.DMAP,
+        Protocol.AirPlay,
+        Protocol.RAOP,
+    ]
+
+    ...
+
+    async def turn_on(self, await_new_state: bool = False) -> None:
+        await self.relay("turn_on", priority=self.OVERRIDE_PRIORITIES)(
+            await_new_state=await_new_state
+        )
+
+```
+
+Here, the priority list is overridden for {% include api i="interface.Power.turn_on" %}
+(and {% include api i="interface.Power.turn_off" %}). Another example is the audio
+interface:
+
+```python
+class FacadeAudio(Relayer, interface.Audio):
+    def __init__(self):
+        super().__init__(interface.Audio, DEFAULT_PRIORITIES)
+
+    @property
+    def volume(self) -> float:
+        volume = self.relay("volume")
+        if 0.0 <= volume <= 100.0:
+            return volume
+        raise exceptions.ProtocolError(f"volume {volume} is out of range")
+
+    async def set_volume(self, level: float) -> None:
+        if 0.0 <= level <= 100.0:
+            await self.relay("set_volume")(level)
+        else:
+            raise exceptions.ProtocolError(f"volume {level} is out of range")
+```
+
+In this case, the facade will guard that an invalid audio level is passed over to the
+protocol implementation (i.e. must not be checked there) as well as the value
+returned from the protocol.
+
+
+### General sequence of connecting
+Here's a very rough diagram of what happens during a connect call:
+
+<code class="diagram">
+sequenceDiagram
+    autonumber
+    participant User
+    participant pyatv
+    participant Protocol
+    participant Facade
+    User ->> pyatv: connect(config)
+    loop For each service in config
+        pyatv ->> Protocol: setup
+        Protocol ->> pyatv: protocol, connect, close, interfaces, feature list
+        pyatv ->> Facade: register interfaces
+    end
+    pyatv ->> Facade: connect
+    loop For each protocol
+        Facade ->> Protocol: connect
+    end
+    pyatv ->> User: facade instance
+    note over User: Use returned instance
+    User ->> Facade: close
+    loop For each protocol
+        Facade ->> Protocol: close
+    end
+</code>

package/pyatv/docs/internals/documentation.md

@@ -0,0 +1,84 @@
+---
+layout: template
+title: Documentation
+permalink: /internals/documentation
+link_group: internals
+---
+# :books: Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# Documentation
+
+This section describes how to work with the pyatv documentation, i.e. the site you are currently
+reading.
+
+# Building the Documentation
+
+To preview changes you make before pushing them to GitHub, run this script (only tested on Linux):
+
+```shell
+./scripts/build_doc.sh
+```
+
+This will spawn Jekyll in preview mode and serve the documentation at [http://localhost:4000](http://localhost:4000). Changes are picked up and re-generated automatically. Note that Docker is required to run this script.
+
+If you make changes to `_config.yml`, you need to restart the script for them to take effect. If you make changes to indirect dependencies, e.g. `page_links:` in `_config.yml`, it will not be enough to restart the script. You will either have to make a dummy modification to your file (for instance use the `touch <file>` command) or remove `_site` prior to starting the script. This is because the information under `page_links:` might be used by your page but Jekyll doesn't know that, so it won't re-generate that page and serve the cached version instead.
+
+# Updating Documentation
+
+All documentation is written in markdown. One resource is [this one](https://guides.github.com/features/mastering-markdown/). The index page is `docs/index.md` and other pages are located in sub-directories, e.g. `docs/development`. You can just go ahead and make simple changes like spelling errors and clarifications directly and push a PR. If you want to add new pages, continue reading.
+
+## Navigation
+
+At the top of the site there are a few buttons, e.g. `Development` and `Support`. These buttons are generated by `top_pages:` in `_config.yml`. To add a new button, just extend this list. There are already too many buttons, so please try placing your changes on a new subpage instead.
+
+Subpage navigation links are shown below the buttons but above the actual content. Each section, e.g. `Development` can have its own subpages and are defined under `page_links:`. A basic example:
+
+```yml
+top_pages:
+  - link: /support/
+    title: Support
+
+page_links:
+  support:
+    - link: /support/
+      title: Start
+    - link: /support/migration/
+      title: Migration
+```
+
+The key used under `top_pages:` should be the same key that is used under `page_links:`, i.e. `support` in this case (due to link being `/support/`).
+
+When creating the actual page, you need to make sure that `permalink` and `link_group` is correctly set, otherwise the navigation won't work. Here is an example based on the configuration above:
+
+```markdown
+---
+layout: template
+title: Migration
+permalink: /support/migration/
+link_group: support
+---
+# Migration
+
+...
+```
+
+Since `permalink` is used to say how the page is accessed, location of the source file doesn't really matter. But try to keep the structure that is already in place as it makes it easier to find pages.
+
+## Interfaces
+
+In general each interface should have its own page under `Development`. So when adding a new interface (or extending an existing one), make sure you add a new subpage for that interface. Start by adding it to `page_links:` in `_config.yml` and then create a new file for it under `docs/development`. You can look at for instance `device_info.md` for inspiration.
+
+## API Reference
+
+Unfortunately there are no API reference libraries for Jekyll (at least not that works with GitHub Pages). So it cannot be automatically generated by jekyll. As a workaround, the API reference is manually updated and checked into the repository. The API reference is located under `docs/api` and can be updated by calling:
+
+```shell
+$ ./scripts/api.py generate
+```
+
+Calling with `verify` instead will check if it is already up-to-date. This check is done by `chickn` and it will fail the build in case something has changed. So if you forget to update the API, you will be notified of this (your PR will not be possible to merge).
+
+The API reference is generated using [pdoc3](https://pdoc3.github.io/pdoc/). To make it work with the rest of the site, the default HTML template has been modified to add some frontmatter (for `permalinks` and those parts) as well as not adding default HTML tags, like `<html>`. The pdoc specific parts can be found [here](https://github.com/postlund/pyatv/tree/master/docs/pdoc_templates). Some of the CSS and Javascript parts that are required are available [here](https://github.com/postlund/pyatv/tree/master/docs/assets).

package/pyatv/docs/internals/interfaces.md

@@ -0,0 +1,95 @@
+---
+layout: template
+title: Interfaces
+permalink: /internals/interfaces
+link_group: internals
+---
+# :information_desk_person: Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# Interfaces
+
+This page covers topics regarding the public interface provided to developers using pyatv.
+
+# External Interfaces
+
+The external interface is documented in the [developer documentation](https://pyatv.dev/development/api_reference/) (no need do duplicate it here). Everything else should be considered private.
+
+In general these interfaces shall not be altered in such a way that it breaks conformity with released versions of pyatv. It is however OK to change an interface on `master` that has not yet been released as part of the development cycle.
+
+If a breaking change must be made:
+
+* Create issue describing the breaking change, add the `breaking change` label
+* Update the [Migration](https://pyatv.dev/support/migration/) page
+* Make sure this change is clearly marked in `CHANGES.md` (responsibility of @postlund)
+
+When adding a new interface or updating an existing one, consider the following:
+
+* Make necessary changes in {% include code file="interface.py" %}
+* Is your addition a [feature](#features)?
+* Reflect your changes in the protocols (e.g. {% include code file="dmap/__init__.py" %} and {% include code file="mrp/__init__.py" %})
+* Update [documentation](documentation#interfaces)
+* Generate API reference (`./scripts/api.py generate`)
+
+## Adding a new Interface
+
+Add a new interface by defining it in {% include code file="interface.py" %}. In general you need to add one interface (class) and also add a property to `interface.AppleTV` used to access the interface. General considerations mentioned above must also be taken into account. You can look at [this](https://github.com/postlund/pyatv/pull/498/commits/bba5a4f03b4dc087f5d8ef44d48c06c3a2360759) commit for some inspiration. The [PR](https://github.com/postlund/pyatv/pull/498) is also a good resource for how the feature was implemented and documented.
+
+## Changing Existing Interface
+
+Changing an already existing interface is generally simpler than adding a new one. Follow the same guidelines as above and there should be no problems.
+
+## Features
+
+When adding something with varying availability or something that is device/OS dependent, it should be considered a "feature" and conform to {% include api i="interface.Features" %}. In practice this means that a user should be able to ask if a certain feature is supported by the device or its availability.
+
+This is done by adding the `@feature` decorator to your method or property (*only* in {% include code file="interface.py" %}):
+
+```python
+    @abstractmethod
+    @feature(6, "Pause", "Pause playing media.")
+    def pause(self) -> None:
+        """Press key play."""
+        raise exceptions.NotSupportedError()
+```
+
+The decorator takes three arguments:
+
+* An index that is unique for the feature
+* Feature name - creates a constant in `const.FeatureName.<name>`
+* Description of the feature - shown in API reference
+
+All features need a unique index and it doesn't really matter what it is, but common practice is to use the "next free". pyatv will fail to load if there is a collision. More about this below.
+
+When a new feature has been added, the {% include api i="const.FeatureName" %} enum must be updated. You do this simply by running:
+
+```shell
+$ python ./scripts/features.py
+# This enum is generated by scripts/features.py
+class FeatureName(Enum):
+    """All supported features."""
+
+    Up = 0
+    """Up button on remote."""
+
+    Down = 1
+    """Down button on remote."""
+
+    Left = 2
+    """Left button on remote."""
+...
+
+Next free index: 35
+```
+
+Then just copy-paste the generated code. As seen at the bottom of the input, the next free index is printed. So you can just run this script before adding a new feature to get a new index.
+
+Next step is to make sure {% include api i="interface.Features.get_feature" %} returns the correct state for your feature. Refer to each protocol implementation and make sure to add tests.
+
+## Adding to facade
+
+All new interfaces must all be added to {% include code file="support/facade.py" %}. It should in most cases be
+fairly straight-forward: just use one of the other implementations as an example. You can read
+more about the facade pattern under [design](design#facade).