@bharper/atv-js 0.2.6 → 0.3.4

package/pyatv/docs/documentation/atvscript.md

@@ -0,0 +1,275 @@
+---
+layout: template
+title: atvscript
+permalink: /documentation/atvscript/
+link_group: documentation
+---
+# Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+
+# atvscript
+
+This script has been created specifically for scripting purposes or for integration
+with existing software without having to write any additional code. It supports a
+subset of what `atvremote` supports and always produce output in a format that is
+easy to parse, e.g. JSON. It is simple to add support for additional formats if needed.
+
+Extending and improving this script will mostly be left to the community. If you want
+a new feature, feel free to send a PR!
+
+# General Output Format
+
+Output is always in the form of a dictionary (be it JSON, YAML or something else) with
+the following keys pre-defined keys:
+
+| Key | Meaning |
+| --- | ------- |
+| result | `success` if command was successful, else `failure`.
+| datetime | Date and time (ISO8601) when event occurred (was printed), e.g. 2020-04-06T18:51:04.758569+02:00.
+| error | An error occurred and this is a well defined string representing the error. Values: `device_not_found`, `unsupported_command`.
+| exception | If an unexpected exception occurred, this key contains the exception message.
+| stacktrace | If a stacktrace is available with the exception, it is included as a string here.
+
+`error` and `exception` will only be present if `result` is set to `failure`. Any
+additional keys not mentioned here are part of the command response.
+
+
+# Specifying Device and Credentials
+
+Currently `atvscript` supports device discovery using regular scanning and unicast
+scanning, with identifier as filter. The arguments are identical to [atvremote](/documentation/atvremote):
+
+```shell
+$ atvscript --id 12345 xyz
+$ atvscript -s 10.0.0.2 xyz
+```
+
+Credentials are specified via `--dmap-credentials`, `--mrp-credentials` and
+`--airplay-credentials`. Protocol can also be specified with `--protocol`.
+
+When using unicast scanning, i.e. specifying IP address via `-s`, it is not needed to
+specify `--id` as the script will pick the first available device it finds. This can
+only be the requested device.
+
+# Command Reference
+
+This section documents the supported commands. JSON output has been prettified for some
+commands to make them easier to read. One command response is *always* printed per line.
+
+## Scanning
+
+It is possible to scan for devices with the `scan` command:
+
+```shell
+$ atvscript scan
+{
+  "result": "success",
+  "datetime": "2020-04-06T18:51:04.758569+02:00",
+  "devices": [
+    {
+      "name": "Vardagsrum",
+      "address": "10.0.10.81",
+      "identifier": "xxx",
+      "all_identifiers": [
+        "xxx",
+        "xxx",
+        "xxx"
+      ],
+      "device_info": {
+        "mac": "AA:BB:CC:DD:EE:FF",
+        "model": "Gen4K",
+        "model_str": "Apple TV 4K",
+        "operating_system": "TvOS",
+        "version": "15.5.1"
+      },
+      "services": [
+        {
+          "protocol": "mrp",
+          "port": 49152
+        },
+        {
+          "protocol": "airplay",
+          "port": 7000
+        }
+      ]
+    },
+    {
+      "name": "Apple TV",
+      "address": "10.0.10.123",
+      "identifier": "xxx",
+      "all_identifiers": [
+        "xxx",
+        "xxx",
+        "xxx"
+      ],
+      "device_info": {
+        "mac": "AA:BB:CC:DD:EE:FF",
+        "model": "Gen3",
+        "model_str": "Apple TV 3",
+        "operating_system": "Legacy",
+        "version": "8.6.1"
+      }
+      "services": [
+        {
+          "protocol": "airplay",
+          "port": 7000
+        },
+        {
+          "protocol": "dmap",
+          "port": 3689
+        }
+      ]
+    },
+    {
+      "name": "Proxy",
+      "address": "10.0.10.254",
+      "identifier": "xxx",
+      "all_identifiers": [
+        "xxx",
+        "xxx",
+        "xxx"
+      ],
+      "device_info": {
+        "mac": null,
+        "model": "Unknown",
+        "model_str": "Unknown",
+        "operating_system": "Unknown",
+        "version": null
+      },
+      "services": [
+        {
+          "protocol": "mrp",
+          "port": 47531
+        }
+      ]
+    }
+  ]
+}
+```
+
+Scanning also respects the `--scan-hosts` (`-s`) flag, which is useful sometimes if scanning
+is flaky:
+
+```shell
+$ atvscript -s 10.0.10.81 scan
+{
+  "result": "success",
+  "datetime": "2020-04-06T18:51:04.758569+02:00",
+  "devices": [
+    {
+      "name": "Vardagsrum",
+      "address": "10.0.10.81",
+      "identifier": "xxx",
+      "all_identifiers": [
+        "xxx",
+        "xxx",
+        "xxx"
+      ],
+      "device_info": {
+        "mac": "AA:BB:CC:DD:EE:FF",
+        "model": "Gen4K",
+        "model_str": "Apple TV 4K",
+        "operating_system": "TvOS",
+        "version": "15.5.1"
+      },
+      "services": [
+        {
+          "protocol": "mrp",
+          "port": 49152
+        },
+        {
+          "protocol": "airplay",
+          "port": 7000
+        }
+      ]
+    }
+  ]
+}
+```
+
+## What is Playing
+
+To get what is playing:
+
+```shell
+$ atvscript -s 10.0.10.81 playing
+{
+  "result": "success",
+  "datetime": "2020-04-06T18:51:04.758569+02:00",
+  "hash": "azyFEzFpSNOSGq9ZvcaX4A∆DcpumkUoRty+R098MQeIKA",
+  "media_type": "music",
+  "device_state": "paused",
+  "title": "Ordinary World (Live)",
+  "artist": "Duran Duran",
+  "album": "From Mediterranea With Love - EP",
+  "genre": "Rock",
+  "total_time": 395,
+  "position": 1,
+  "shuffle": "off",
+  "repeat": "off",
+  "app": "Musik",
+  "app_id": "com.apple.TVMusic"
+}
+```
+
+Some of the fields, like `media_type` and `device_state` uses the names from their corresponding enum, but in lower case. Check out {% include api i="const.DeviceState" %} for instance to find valid values for `device_state`.
+
+## Remote Control
+
+All buttons in {% include api i="interface.RemoteControl" %} are supported by `atvscript`
+except for the ones beginning with `set_`:
+
+```shell
+$ atvscript -s 10.0.10.81 menu
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "command": "menu"}
+```
+
+## Push, Power, Audio and Keyboard Updates
+
+Push, power, audio and keyboard updates are printed to the terminal as they happen:
+
+```shell
+$ atvscript -s 10.0.10.81 push_updates
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "power_state": "off"}
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "output_devices": [{"name": "Living room", "identifier": "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"}]}
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "focus_state": "unfocused"}
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "hash": "azyFEzFpSNOSGq9ZvcaX4A\u2206DcpumkUoRty+R098MQeIKA", "media_type": "music", "device_state": "paused", "title": "Ordinary World (Live)", "artist": "Duran Duran", "album": "From Mediterranea With Love - EP", "genre": "Rock", "total_time": 395, "position": 1, "shuffle": "off", "repeat": "off", "app": "Musik", "app_id": "com.apple.TVMusic"}
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "power_state": "on"}
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "volume": 20.0}
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "volume": 15.0}
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "focus_state": "focused"}
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "focus_state": "unfocused"}
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "power_state": "off"}
+
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "push_updates": "finished"}
+```
+
+Current power state is always printed as the first update.
+
+When pressing ENTER, the script will exit (as seen on the last line).
+
+## Connection Status
+
+Listening to push updates is a long-lived process and the connection might be closed at some point, e.g.
+due to device reboot or network issues. If this happens, `connection` will be set to `closed`:
+
+```
+$ atvscript --id 6D797FD3-3538-427E-A47B-A32FC6CF3A69 push_updates
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "power_state": "on"}
+...
+{"result": "failure", "datetime": "2020-04-06T18:51:04.758569+02:00", "connection": "closed"}
+```
+
+In case of abnormal disconnection, `connection` will be set to `lost` and an exception will be
+included:
+
+```
+{"result": "success", "datetime": "2020-04-06T18:51:04.758569+02:00", "power_state": "on"}
+...
+{"result": "failure", "datetime": "2020-04-06T18:51:04.758569+02:00", "exception": "something bad happened", "connection": "closed"}
+```
+
+The script will also exit (without requiring user interaction) with a non-zero exit code.

package/pyatv/docs/documentation/concepts.md

@@ -0,0 +1,168 @@
+---
+layout: template
+title: Concepts
+permalink: /documentation/concepts/
+link_group: documentation
+---
+# Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# Concepts
+
+There are a couple of important concepts in pyatv that is good to understand. This page will cover
+the most important ones, giving them relations to how they are used in code.
+
+# Devices and configuration
+
+A physical device, e.g. an Apple TV 4K, is represented by a *configuration*. From a code
+perspective, you find all the important pieces in {% include api i="conf.AppleTV" %}. It stores all
+the necessary information about the device it represents, e.g. name, IP-address, supported protocols,
+etc. You can read more about this in the following sections.
+
+The simplest way to create a configuration is to to scan for devices, as {% include api i="pyatv.scan" %} returns a list of {% include api i="conf.AppleTV" %} objects with almost all information already filled in. You can then just pick the configuration you want and either connect to or pair with the device. Scanning and pairing is explained below.
+
+It is also possible to manually create a configuration, although this is not the recommended way. One reason
+for this is that some information is not static, e.g. port numbers and Zeroconf properties (which pyatv
+heavily relies on). When using {% include api i="pyatv.scan" %}, the correct port will be automatically identified and filled in for you.
+## Services and protocols
+
+Each configuration keeps track of all the different protocols a device supports. The term *service* is also used in this context and it is exactly the same thing (this will likely be consolidated into a single term in the future, but for now they are used interchangeably).
+
+Currently pyatv supports five protocols:
+
+| Protocol | Purpose | Devices |
+| -------- | ------- | ------- |
+| Digital Media Access Protocol (DMAP) | Control device and get metadata | Apple TV <= 3 and tvOS <= 12  |
+| Media Remote Protocol (MRP) | Control device and get metadata | tvOS (any version), e.g. Apple TV 4 and later |
+| AirPlay | Stream video to a device | All devices |
+| RAOP | Stream audio to a device | All devices |
+| Companion | Currently used for app management | Apple TV 4+, HomePod in the future |
+
+Only one protocol is needed to connect, but multiple can be used. The most appropriate protocol
+will be used depending on feature (see [Protocol relaying](#protocol-relaying) for details). The
+Companion protocol is however an exception as there's no unique identifier easily available for
+that protocol.
+
+There are methods in {% include api i="conf.AppleTV" %} to add and retrieve services. When using {% include api i="pyatv.scan" %}, all discovered protocols will be added automatically and all relevant information (e.g. which port is used) is stored as well. When manually creating a configuration, you have to provide this information yourself (e.g. via  {% include api i="conf.DmapService" %} for `DMAP`, and so on).
+
+## Device Information
+
+It is possible to extract some general information about a device,
+for instance which operating system it runs or its MAC address.
+There's generally no "good" way of obtaining this information, but pyatv
+will pull bits and pieces from the metadata received during scanning to
+make a good guess. It can also extract additional information after
+connecting to the device, since some protocols provide information once
+a connection has been made. The amount of device information available
+can because of that differ when scanning or connecting.
+
+## Identifiers
+
+An important concept for pyatv is to be able to *uniquely* identify a device. You should be able to say: "I want to find and connect to *this* specific device" and pyatv should be able to do that for you. This of course means that you cannot use common identifiers, like IP-address or device name, as they can change at any time. And how many devices named "Living Room" aren't there in the world?
+
+Instead, pyatv extracts *unique identifiers* from the different services it finds when scanning. You can then specify that you want to scan for a device with one of these identifiers and be sure that you find the device you expect. What is a unique identifier then? It can be anything, as long as it is unique of course. In case of `MRP`, it actually exposes a property called `UniqueIdentifer`. Looking at `AirPlay`, you can get the device MAC-address via a property called `deviceid`. In practice this means that a device has *multiple* identifiers and you can use *any* of them when scanning. There is a convenience property,  {% include api i="conf.AppleTV.identifier" %}, used to get an identifier. It just picks one from all of the available.
+
+If you perform a scan with `atvremote`, you can see all the available identifiers:
+
+```raw
+$ atvremote scan
+========================================
+       Name: Living Room
+   Model/SW: 4K tvOS 13.3.1 build 17K795
+    Address: 10.0.0.10
+        MAC: AA:BB:CC:DD:EE:FF
+Identifiers:
+ - 01234567-89AB-CDEF-0123-4567890ABCDE
+ - 00:11:22:33:44:55
+Services:
+ - Protocol: MRP, Port: 49152, Credentials: None
+ - Protocol: AirPlay, Port: 7000, Credentials: None
+```
+
+Why is this concept so important then? Well, it *is* important that you connect to the device you expect. Especially for `MRP`, where the port might change at any time and you need to be able to find your way back (reconnect) when that happens. It also makes pyatv more reliable in environments using DHCP, which is the case in most peoples homes.
+
+## Credentials
+
+All protocols has some sort of "authentication" process and require *credentials* when connecting. You obtain said credentials via pairing, which is explained below. The credentials are then stored together with the protocol in a configuration.
+
+The usual flow is:
+
+* Perform scan
+* Pick device of interest
+* Connect
+
+As of pyatv.0.14.0, persistent storage is built in. So credentials are saved and loaded automatically from
+file (or somewhere else). See next section.
+
+# Storage and Settings
+
+To simplify handling of things like credentials, passwords and various settings, pyatv will automatically
+put these into a storage module that allows for persistent storage. It is possible to implement custom
+storage modules that for instance store settings in a cloud service, but pyatv also ships with a file
+based storage module that will save settings in a file. This storage module is used by scripts shipped
+with pyatv, e.g. [atvremote](../atvremote) and [atvscript](../atvscript).
+
+# Scanning
+
+To find devices, you perform a *scan* with the {% include api i="pyatv.scan" %} function. It uses [Zeroconf](https://en.wikipedia.org/wiki/Zero-configuration_networking) to discover devices, just like the Remote app/Control Center widget in iOS. You get a list of all available devices with information pre-filled and you can pretty much connect immediately (you might have to add credentials first though).
+
+Scanning is not 100% reliable, that comes with the territory. Sometimes a device is not found, or even a service might not be found. It will happen and that is just life. Scan again and hope for the best. Usually it works just fine, so it shouldn't be that much of an issue (but bear it in mind when writing your software).
+
+As a workaround for scanning issues, pyatv comes with support for *unicast scanning*. It allows
+you to specify a list of devices to scan for. When doing so, pyatv will not rely on multicast
+but rather send a request to the devices directly. This is much more reliable but of course comes
+with the downside of not having devices auto discovered. You can simply try this out with `atvremote`,
+please see [atvremote](../atvremote/).
+
+Please note that unicast scanning does not work across different network as the Apple TV will ignore
+packets from a different subnet. This is according to the multicast DNS specification (see chapter 5.5
+in RFC 6762 [here](https://tools.ietf.org/html/rfc6762#section-5.5) in case you are interested) and is
+not something that can be fixed in pyatv.
+
+## Deep Sleep Detection
+
+When a device is in deep sleep mode, another node on the network called a
+*sleep proxy* will announce its prescence. It will also wake up the device
+using Wake-On-LAN in case a particular service is requested. When scanning,
+pyatv can detect if the response originates from a sleep proxy and
+deduce that a device is sleeping. This is indicated via the flag
+{% include api i="conf.AppleTV.deep_sleep" %}.
+
+*Please do note that this is an experimental feature.*
+
+# Pairing
+
+Pairing is the process of obtaining credentials. You provide a configuration to the  {% include api i="pyatv.pair" %} method together with the protocol you want to pair. Usually you have to input a PIN code and then the credentials are returned via the `credentials` property in the service. This means that you can scan for a device, pass the configuration you got from {% include api i="pyatv.scan" %} to  {% include api i="pyatv.pair" %} and finish off by passing the same configuration to {% include api i="pyatv.connect" %}. As simple as that.
+
+# Connecting
+
+The final step is to connect to a device. It is done via {% include api i="pyatv.connect" %}, which sets up the connection and validates the credentials (e.g. setup encryption). You will get an error if it doesn't work. Connection attempts will be made to all protocols you have provided
+configuration for (if necessary).
+
+Prior to pyatv 0.8.0, a `protocol` parameter was used to pick protocol used as "main"
+protocol (for primary interaction). This is no longer needed as the most appropriate protocol
+is used automatically beacuase of [Protocol Relaying](#protocol-relaying). The flag is deprecated and unused.
+
+# Metadata and push updates
+
+The object you get when connecting follows the interface specified in the `interface` module. You can get *metadata*, e.g. what is currently playing via the `metadata` property. You don't have to poll the device for that information, you can use the {% include api i="interface.PushUpdater" %} interface to receive updates instantly as they happen via a callback interface.
+
+# Features
+
+Depending on hardware model and software, various features might be supported or not. Siri is for
+instance only supported by devices running tvOS. Certain actions might not be possible to perform
+due to the device state, e.g. pressing "pause" is not possible unless something is playing. In pyatv,
+it's possible to obtain information about the availability of features using {% include api i="interface.Features" %}.
+
+# Protocol Relaying
+
+The concept of *protocol relaying* is an internal mechanism of pyatv, it is however
+worth knowing the basics of it. pyatv provides a uniform API towards the
+developer, removing the need to worry about underlying protocols (other than
+credentials): it is automatically handled "under the hood". The relaying mechanism
+allows multiple protocols to be active and will automatically "relay" interface
+calls to the most suitable protocol. If two protocols implement the same
+feature, the best of the two will be used. One protocol might also implement parts
+of an interface, leaving the reminder to another protocol.

package/pyatv/docs/documentation/documentation.md

@@ -0,0 +1,130 @@
+---
+layout: template
+title: Documentation
+permalink: /documentation/
+link_group: documentation
+---
+# :green_book: Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# Documentation
+
+This section covers general parts of pyatv, like how to install it, concepts and terminology to
+understand how it works. More or less everything that is not *how* you develop with it.
+
+Before diving into code, make sure you read and understand the [Concepts](concepts/)
+first.
+
+# Installing pyatv
+
+You can install/run pyatv either in a container using pre-built images or a virtual environment.
+
+## Container (Docker)
+
+Starting with release 0.9.0, container images for x86_64, aarch64 and armv7 are automatically built and
+available from GitHub. Images are published per version (e.g. v0.9.0, v0.9.1, etc.) and the latest
+commit on `master` (just labeled with `latest`). See the [images](https://github.com/postlund/pyatv/pkgs/container/pyatv)
+page for all available images.
+
+To test atvremote, you can run:
+
+```shell
+$ docker run -it --rm --network=host ghcr.io/postlund/pyatv:master atvremote scan
+```
+
+It is also possible to run simple scripts and applications like this:
+
+```shell
+$ docker run --rm --network=host -v $PWD:/app ghcr.io/postlund/pyatv:v0.9.0 python /app/scan.py
+```
+
+Note that network must be used in `host` mode, otherwise pyatv will not be able to find your
+devices when scanning.
+
+## System dependencies
+
+You might need some additional packages to compile the dependencies. On a debian based system
+(e.g. Debian itself or Ubuntu), you can just run:
+
+```shell
+sudo apt-get install build-essential libssl-dev libffi-dev python-dev
+```
+
+This is not needed when running in a container.
+
+## Virtual Environment
+
+It is recommended to install pyatv in a virtual environment rather than
+system-wide. To create a new virtual environment:
+
+    python3 -m venv pyatv_venv
+    source pyatv_venv/bin/activate
+
+This creates a virtual environment in a directory called `pyatv_venv`. The
+second command activates the virtual environment and must be done every
+time a new shell is started.
+
+Now you can continue by installing the version of pyatv you want.
+
+### Latest Stable Version
+
+Install pyatv using `pip3`:
+
+```shell
+pip3 install {{ site.pyatv_version }}
+```
+
+### Development Version
+
+To try out the latest development version (a.k.a. `master` on GitHub), you can install with:
+
+```shell
+pip3 install --upgrade git+https://github.com/postlund/pyatv.git
+```
+
+### Specific Branch or a Pull Request
+
+To install from a branch, you can install like this:
+
+```shell
+pip3 install --upgrade git+https://github.com/postlund/pyatv.git@refs/heads/<branch>
+```
+
+Replace `<branch>` with the name of the branch.
+
+It is also possible to install directly from a pull request:
+
+```shell
+pip3 install git+https://github.com/postlund/pyatv.git@refs/pull/<id>/head
+```
+
+Replace `<id>` with the pull request number.
+
+# Testing with GitPod
+
+You can try out pyatv and play around with the code using GitPod. Everything is
+already set up and ready to go, just login with one of the supported account,
+e.g. GitHub, and you are ready within a minute. No need to install anything on
+your own computer and works across operating systems and web browsers. Really cool!
+
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/postlund/pyatv)
+
+*Note: This runs in the cloud, so you will not be able to find your own devices. It's mainly for development or basic testing.*
+
+# Dependencies
+
+At least python 3.7 is required to run pyatv. A few additional libraries
+are needed as well. An updated list is available
+[here](https://github.com/postlund/pyatv/blob/master/base_versions.txt).
+
+You also need to have OpenSSL compiled with support for ed25519 in order
+to connect to MRP devices. More details is
+[here](../support/faq/#i-get-an-error-about-ed25519-is-not-supported-how-can-i-fix-that).
+
+# Milestones
+
+Current milestones are available on GitHub:
+
+[Milestones](https://github.com/postlund/pyatv/milestones)