@bharper/atv-js 0.2.6 → 0.3.4

package/pyatv/docs/development/apps.md

@@ -0,0 +1,81 @@
+---
+layout: template
+title: Apps
+permalink: /development/apps/
+link_group: development
+---
+# Apps
+
+It is possible to launch and list installed apps via the Apps interface.
+To use this interface, the Companion protocol must be available.
+
+## Using the Apps API
+
+After connecting to a device, you get the apps interface via {% include api i="interface.AppleTV.apps" %}:
+
+```python
+atv = await pyatv.connect(config, ...)
+apps = atv.apps
+```
+
+To retrieve a list of installed apps, use {% include api i="interface.Apps.app_list" %}
+
+```python
+app_list = await apps.app_list()
+
+for app in app_list:
+    print(f"Name: {app.name}, Bundle Identifier: {app.identifier}")
+```
+
+To launch an app, use its bundle identifier when calling {% include api i="interface.Apps.launch_app" %}
+
+ ```python
+await apps.launch_app("com.netflix.Netflix")
+ ```
+
+To launch an app with a URL, pass the URL when calling {% include api i="interface.Apps.launch_app" %}
+
+ ```python
+await apps.launch_app("https://tv.apple.com/show/marvels-spidey-and-his-amazing-friends/umc.cmc.3ambs8tqwzphbn0u8e9g76x7m?profile=kids&action=play")
+ ```
+
+### App deep links
+
+tvOS, allows deep linking into apps. So the {% include api i="interface.Apps.launch_app" %} API is very powerful for
+navigating content on the Apple TV.
+
+Here are some known working examples:
+* https://tv.apple.com/show/severance/umc.cmc.1srk2goyh2q2zdxcx605w8vtx
+* https://www.disneyplus.com/series/the-beatles-get-back/7DcWEeWVqrkE
+* https://play.hbomax.com/page/urn:hbo:page:GXkRjxwjR68PDwwEAABKJ:type:series
+* https://www.netflix.com/title/80234304
+
+The simplest way to find useful deep links is to use the "Share" feature in iOS or macOS versions of the App. Share 
+sheets will often have a "Copy" or "Copy link" feature. For apps that have a web accessible version, links copied from
+the browser usually work too (this is how iOS handles linking into apps from web links).
+
+Sometimes a link copied this way will not work, but can be made to work with a slight modification, e.g. removing a 
+country code from the URL.
+
+If this approach fails, you can inspect the app to discover insights about supported URLs. The recommended way to 
+support [app links](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content)
+is by defining
+[associated domains](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content).
+
+To discover domains associated with an app, list the app entitlements, then search for `associated-domains` within 
+the output. You can do this using the `codesign` tool on macOS.
+```bash
+$ codesign -d --entitlements - "/path/to/Interesting.app/"
+```
+
+Once potential domains are identified you can check the content of the file hosted at  
+`https://<domain>/.well-known/apple-app-site-association`. This is a file that is required to be hosted to support 
+associated domains, and contains patterns matching URLs that the app claims to support. Check out some examples from
+[Disney+](https://www.disneyplus.com/.well-known/apple-app-site-association) and
+[Netflix](https://www.netflix.com/.well-known/apple-app-site-association).
+
+Some apps also define a
+[custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app), which
+is an alternative API for supporting app links. These can be inspected by looking at
+`/path/to/Interesting.app/Info.plist` or
+`/path/to/Interesting.app/Contents/Info.plist` and searching for CFBundleURLSchemes.

package/pyatv/docs/development/audio.md

@@ -0,0 +1,42 @@
+---
+layout: template
+title: Audio
+permalink: /development/audio/
+link_group: development
+---
+# Audio
+
+Protocols supporting volume controls can be controlled via the audio interface.
+
+## Using the Audio API
+
+After connecting to a device, you get the apps interface via {% include api i="interface.AppleTV.audio" %}:
+
+```python
+atv = await pyatv.connect(config, ...)
+audio = atv.audio
+```
+
+To get current volume level, use {% include api i="interface.Audio.volume" %}:
+
+```python
+print("Volume:", audio.volume)
+```
+
+To change current volume, use {% include api i="interface.Audio.set_volume" %}:
+
+```python
+await audio.set_volume(20.0)
+```
+
+The volume level is normalized in the interval 0.0-100.0, where 0.0 means
+the audio is muted.
+
+You can also step volume up or down using step level provided from the device (if available):
+
+```python
+await audio.volume_up()
+await audio.volume_down()
+```
+
+The audio API supports push updates via a listener, as described [here](../listeners#audio-updates).

package/pyatv/docs/development/control.md

@@ -0,0 +1,56 @@
+---
+layout: template
+title: Control
+permalink: /development/control/
+link_group: development
+---
+# Control
+
+Controlling a device is done with the remote control interface,
+{% include api i="interface.RemoteControl" %}. It allows you navigate the menus and
+change playback (play, pause, etc.).
+
+## Using the Remote Control API
+
+After connecting to a device, you get the remote control via {% include api i="interface.AppleTV.remote_control" %}:
+
+```python
+atv = await pyatv.connect(config, ...)
+rc = atv.remote_control
+```
+
+You can then control via the available functions:
+
+```python
+await rc.up()
+await rc.select()
+await rc.volume_up()
+await rc.set_position(100)
+```
+
+All available actions can be found in {% include api i="interface.RemoteControl" %}.
+
+## Input Actions
+
+Currently three types of input actions are supported:
+
+* Single tap ("click")
+* Double tap ("double click")
+* Hold
+
+These actions are supported by the following buttons:
+
+* Arrow keys (up, down, left, right)
+* Select
+* Menu
+* Home
+
+By default, {% include api i="const.InputAction.SingleTap" %} are used. Pass another `action`
+to use another input action:
+
+```python
+await rc.menu(action=InputAction.Hold)
+await rc.home(action=InputAction.DoubleTap)
+```
+
+All input actions are specified in {% include api i="const.InputAction" %}.

package/pyatv/docs/development/development.md

@@ -0,0 +1,15 @@
+---
+layout: template
+title: Development
+permalink: /development/
+link_group: development
+---
+# :construction_worker: Development
+
+These sections cover the basics on how you develop with pyatv.
+So if you are a developer and want to create some software that
+controls an Apple TV, you are in the right place.
+
+If you instead want develop pyatv itself, there are details for
+that over at the GitHub wiki. Click
+[here](https://github.com/postlund/pyatv/wiki) to go there.

package/pyatv/docs/development/device_info.md

@@ -0,0 +1,36 @@
+---
+layout: template
+title: Device Information
+permalink: /development/device_info/
+link_group: development
+---
+# Device Information
+
+pyatv can extract various information about a device, e.g. which
+operating system (and version) it runs or its hardware model (3, 4K, etc.).
+This information is exposed via the interface {% include api i="interface.DeviceInfo" %}.
+
+## Using the Device Information API
+
+After connecting to a device, you get device info via {% include api i="interface.AppleTV.device_info" %}:
+
+```python
+atv = await pyatv.connect(config, ...)
+devinfo = atv.device_info
+```
+
+You can then access the actual information via properties:
+
+```python
+print(devinfo.operating_system)
+print(devinfo.version)
+print(devinfo.mac)
+```
+
+ Just printing `devinfo` will produce a summary of the device information
+ (MAC-address is not included here):
+ 
+ ```python
+ >>> print(devinfo)
+ 4K tvOS 13.3.1 build 17K795
+ ```

package/pyatv/docs/development/examples.md

@@ -0,0 +1,44 @@
+---
+layout: template
+title: Examples
+permalink: /development/examples/
+link_group: development
+
+files:
+  - name: auto_connect.py
+    description: Demonstrates the simple `auto_connect` helper.
+  - name: connect_with_credentials.py
+    description: Restores credentials for a device before connecting.
+  - name: manual_connect.py
+    description: Manual creation of a configuration used to connect to a device.
+  - name: pairing.py
+    description: Generic example demonstrating the pairing API.
+  - name: play_url.py
+    description: Play a video from URL using AirPlay.
+  - name: scan_and_connect.py
+    description: Scans for devices, picks the first one and connects to it.
+  - name: storage.py
+    description: Connect to a device using storage API.
+  - name: stream.py
+    description: Stream audio file to an AirPlay/RAOP receiver.
+  - name: tutorial.py
+    description: Complete source code of [tutorial](../../documentation/tutorial).
+---
+# Examples
+
+There are a few example bundled with pyatv in the `examples` subdirectory:
+
+| Filename | Description |
+| -------- | ----------- |
+{% for file in page.files -%}
+| [{{ file['name'] | replace: "__", "\_\_" }}]({{ "https://github.com/postlund/pyatv/blob/master/examples/" | append:file['name'] }}) | {{ file['description'] }} |
+{% endfor- %}
+
+These scripts that are bundled with pyatv can be used for inspiration as well:
+
+* [atvremote](https://github.com/postlund/pyatv/blob/master/pyatv/scripts/atvremote.py)
+* [atvscript](https://github.com/postlund/pyatv/blob/master/pyatv/scripts/atvscript.py)
+
+More examples can be added on request, please write an
+[issue](https://github.com/postlund/pyatv/issues/new?assignees=&labels=question&template=question-or-idea.md&title=)
+if you want something more specific.

package/pyatv/docs/development/features.md

@@ -0,0 +1,70 @@
+---
+layout: template
+title: Features
+permalink: /development/features/
+link_group: development
+---
+# Features
+
+It is possible to obtain information about available features of a device, e.g. if it supports playback actions or power management, using {% include api i="interface.Features" %}. Supported features are listed in {% include api i="const.FeatureName" %}.
+
+## Feature State
+
+A feature can at any given time be considered to be in one of the following states:
+
+| State | Meaning |
+| ----- | ------- |
+| Unknown | The feature is supported by the device but it is not possible to determine if it is available or not, i.e. if it can be used *now*. All devices for instance supports `Pause`, but it is only possible to pause if something is playing.
+| Unsupported | The feature is not supported by the device at all, e.g. Siri is unsupported on Apple TV 3 *or* none of the configured protocols support this feature.
+| Unavailable | The feature is supported but currently not possible to use, e.g. skip to next track is only possible if a song is playing.
+| Available | The feature is supported and available now, e.g. `Pause` is possible because something is playing.
+
+Because of technical reasons, the state of some features are not possible to determine, so pyatv will make an educated guess. If something seems strange, please write an [issue](https://github.com/postlund/pyatv/issues/new?assignees=&labels=bug&template=bug_report.md&title=) about it. Make sure you include full debug logs, otherwise it will be hard to troubleshoot.
+
+## Using the Features API
+
+After connecting to a device, you get the interface via {% include api i="interface.AppleTV.features" %}:
+
+```python
+atv = await pyatv.connect(config, ...)
+ft = atv.features
+```
+
+To obtain current state of a feature, e.g. {% include api i="const.FeatureName.Play" %}, use {% include api i="interface.Features.get_feature" %}:
+
+```python
+from pyatv.const import FeatureName, FeatureState
+
+info = ft.get_feature(FeatureName.Play)
+if info.state == FeatureState.Available:
+    await atv.remote_control.play()
+else:
+    print("Play is not possible right now")
+```
+
+The state of all features can be obtained via {% include api i="interface.Features.all_features" %}. By default, this method will exclude unsupported features. Pass `include_unsupported=True` when calling to include state of all features:
+
+```python
+all_features = ft.all_features(include_unsupported=unsupported)
+for name, feature in all_features.items():
+    print(f"{name} = {feature.state}")
+```
+
+There's a helper method, {% include api i="interface.Features.in_state" %}, that checks if one or
+more features are in one or several states:
+
+```python
+# Check if Play is available
+if ft.in_state(FeatureState.Available, FeatureName.Play):
+    pass
+
+# Check if Play is either available or unsupported
+if ft.in_state([FeatureState.Available, FeatureState.Unsupported],
+               FeatureName.Play):
+    pass
+
+# Check if Play *and* Pause are supported
+if not ft.in_state(FeatureName.Unsupported, FeatureName.Play, FeatureName.Pause):
+    pass
+
+```

package/pyatv/docs/development/keyboard.md

@@ -0,0 +1,51 @@
+---
+layout: template
+title: Keyboard
+permalink: /development/keyboard/
+link_group: development
+---
+# Keyboard
+
+It is possible to interact with the Apple TV virtual keyboard via the Keyboard interface.
+To use this interface, the Companion protocol must be available.
+
+## Using the Keyboard API
+
+After connecting to a device, you get the keyboard interface via {% include api i="interface.AppleTV.keyboard" %}:
+
+```python
+atv = await pyatv.connect(config, ...)
+keyboard = atv.keyboard
+```
+
+To check whether the virtual keyboard is focused and active, use {% include api i="interface.Keyboard.text_focus_state" %}:
+
+```python
+print("Keyboard focus state:", keyboard.text_focus_state)
+```
+
+To fetch the current virtual keyboard text content, use {% include api i="interface.Keyboard.text_get" %}:
+
+```python
+print("Keyboard text:", await keyboard.text_get())
+```
+
+To set (replace) the virtual keyboard text, use {% include api i="interface.Keyboard.text_set" %}:
+
+```python
+await keyboard.text_set("text to set")
+```
+
+To append to the virtual keyboard text, use {% include api i="interface.Keyboard.text_append" %}:
+
+```python
+await keyboard.text_append("text to append")
+```
+
+Finally, to clear the virtual keyboard text, use {% include api i="interface.Keyboard.text_clear" %}:
+
+```python
+await keyboard.text_clear()
+```
+
+The keyboard API supports push updates via a listener, as described [here](../listeners#keyboard-updates).

package/pyatv/docs/development/listeners.md

@@ -0,0 +1,144 @@
+---
+layout: template
+title: Listeners
+permalink: /development/listeners/
+link_group: development
+---
+ Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# Listeners
+
+In some cases it's not appropriate to continuously poll the device for information.
+What is currently playing should be updated instantly for instance. This is supported
+via callbacks using a `listener`.
+
+## Push Updates
+
+The push update API is based on a regular callback interface. When playstatus
+information is available, a method called ``playstatus_update`` is called.
+Similarly, ``playstatus_error`` is called if an error occur. See the
+following example:
+
+```python
+class MyPushListener(interface.PushListener):
+
+    def playstatus_update(self, updater, playstatus):
+        # Currently playing in playstatus
+
+    def playstatus_error(self, updater, exception):
+        # Error in exception
+
+
+listener = MyPushListener()
+atv.push_updater.listener = listener
+atv.push_updater.start()
+```
+
+Assuming the connection to the device is still active, push updates will
+continue to be delivered after an error has happened. The parameter
+`initial_delay` to `start` specifies the delay that should be used before
+"trying to deliver updates again", but it might also be ignored if it is
+deemed not necessary. The reason for its existence is purly to provide a
+way to not hammer the device in case of errors.
+
+## Device Updates
+
+It is possible to get callbacks whenever a device loses its connection. Two methods
+are used: one for expected loss, e.g. manually disconnecting and one for unexpected
+loss, e.g. a crash or network problem. The API is defined by the
+{% include api i="interface.DeviceListener" %} interface and works similarly to how push updates works.
+
+Here is a simple example:
+
+```python
+class MyDeviceListener(interface.DeviceListener):
+
+    def connection_lost(self, exception):
+        print("Lost connection:", str(exception))
+
+    def connection_closed(self):
+        print("Connection closed!")
+
+
+listener = MyDeviceListener()
+atv.listener = listener
+```
+
+A small note here about this API. For `MRP` this works fine as that protocol
+is connection oriented. It's another case for `DMAP`, since that protocol is
+request based. For now, this interface is implemented by the push updates
+API (to be clear: for `DMAP`). So when the push updates API fails to establish
+a connection, the callbacks in this interface will be called.
+
+## Power State Updates
+
+It is possible to get callbacks whenever a device power state is changed, 
+e.g. the device turned on or turned off. The API is defined by the
+ {% include api i="interface.PowerListener" %} interface and works similarly to how push updates works.
+
+Here is a simple example:
+
+```python
+class MyPowerListener(interface.PowerListener):
+
+    def powerstate_update(self, old_state, new_state):
+        print('Power state changed from {0:s} to {1:s}'.format(old_state, new_state))
+
+
+listener = MyPowerListener()
+atv.power.listener = listener
+```
+
+A small note here about this API. Power state updates are working for `MRP` devices
+only.
+
+## Audio Updates
+
+It is possible to get callbacks whenever the volume level of a device is changed, or the AirPlay output
+devices are altered.
+The API is defined by the
+{% include api i="interface.AudioListener" %} interface and works similarly to how push updates works.
+
+Here is a simple example:
+
+```python
+class MyAudioListener(interface.AudioListener):
+
+    def volume_update(self, old_level, new_level):
+        print('Volume level changed from {0:f} to {1:f}'.format(old_level, new_level))
+
+    def outputdevices_update(self, old_devices, new_devices):
+        print('Output devices changed from {0:s} to {1:s}'.format(old_devices, new_devices))
+
+
+listener = MyAudioListener()
+atv.audio.listener = listener
+```
+
+Live volume level and output device updates are only sent over the `MRP` protocol.
+If an Apple TV is connected to speakers in a way that doesn't support volume levels,
+it will not send these updates.
+
+## Keyboard Updates
+
+It is possible to get callbacks whenever the virtual keyboard focus state of a device is changed.
+The API is defined by the
+{% include api i="interface.KeyboardListener" %} interface and works similarly to how push updates works.
+
+Here is a simple example:
+
+```python
+class MyKeyboardListener(interface.KeyboardListener):
+
+    def focusstate_update(self, old_state, new_state):
+        print('Focus state changed from {0:s} to {1:s}'.format(old_state, new_state))
+
+
+listener = MyKeyboardListener()
+atv.keyboard.listener = listener
+```
+
+Keyboard focus state updates are only sent over the `Companion` protocol.

package/pyatv/docs/development/logging.md

@@ -0,0 +1,55 @@
+---
+layout: template
+title: Logging
+permalink: /development/logging/
+link_group: development
+---
+# Logging
+
+In case you need to troubleshoot something, you can enable additional log points in pyatv.
+This page describes how you do that.
+
+# Log points
+
+To enable full logging, use this:
+
+```python
+logging.basicConfig(
+    level=logging.DEBUG,
+    datefmt="%Y-%m-%d %H:%M:%S",
+    format="%(asctime)s %(levelname)s [%(name)s]: %(message)s",
+)
+```
+
+This output format is preferred as it is compatible with [atvlog](../../documentation/atvlog) and
+contains the most useful information.
+
+In case you need to troubleshoot MDNS/Zeroconf traffic, use this:
+
+```python
+logging.getLogger(
+    "pyatv.support.mdns"
+).level = logging.TRAFFIC  # pylint: disable=no-member
+```
+
+*NOTE: This section is WIP for now as most interesting log points are internal. In the future,
+a `log` module will be added to simplify enabling log points.*
+
+# Bundled scripts
+
+You can enable additional debugging information by specifying either `--verbose` or `--debug.`.
+
+# Output line cropping
+
+By default pyatv will limit some log points in length, mainly due to an excessive amount of
+data might be logged otherwise. This mainly applies to binary data (raw protocol data) and
+protobuf messages. These limits can be overridden by setting the following environment variables:
+
+```shell
+$ export PYATV_BINARY_MAX_LINE=1000
+$ export PYATV_PROTOBUF_MAX_LINE=1000
+$ atvremote --debug ... playing
+```
+
+In general, you shouldn't have to change these, but under some cicrumstances the complete
+logs might be deseriable.