@bharper/atv-js 0.2.6 → 0.3.4

package/pyatv/docs/development/storage.md

@@ -0,0 +1,259 @@
+---
+layout: template
+title: Storage and Settings
+permalink: /development/storage/
+link_group: development
+---
+ Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# Storage and Settings
+
+The storage API provides a way to store and read settings persistently, e.g. in a local file or remotely
+on a cloud service. Settings include things such as:
+
+* Various metadata, e.g. remote name, MAC address
+* Credentials and passwords for services
+* Protocol specific settings, e.g. port numbers
+
+As storage is still a new API, only a handful settings are supported at the time of writing. More settings
+will be added over time. To request a new setting, please open a new issue.
+
+## Available Storage Modules
+
+The following storage modules are shipped with pyatv:
+
+| **Module** | **Description** | **API** |
+| MemoryStorage | Stores settings within an instance in memory and are discarded when the object is no longer referenced. | {% include api i="storage/memory_storage.MemoryStorage" %}
+| FileStorage | Stores settings in a file in JSON format. | {% include api i="storage/file_storage.FileStorage" %}
+| AbstractStorage | Base class to ease development of custom storage modules, see [here](#custom-storage-module). | {% include api i="storage.AbstractStorage" %}
+
+All main methods in `pyatv` ({% include api i="pyatv.connect" %}, {% include api i="pyatv.scan" %} and
+{% include api i="pyatv.pair" %}) accept `storage` as an argument. Typically a storage instance is created once
+and are then passed on to all mentioned methods. If no storage module is provided, a
+{% include api i="storage/memory_storage.MemoryStorage" %} instance is created internally and used for storage.
+
+## Storage Guidelines
+
+When using the storage API, there are a few guidelines to consider:
+
+* All settings are device specific
+* If a setting is not set, a default value is used (see {% include api i="settings" %} for values)
+* Settings are generally not changed after {% include api i="pyatv.connect" %} has been called
+
+The gist is more or less that settings are independent on device level (you can set different MAC addresses
+per device for instance) and they apply instantly. It is however not certain that it will be used until the
+next {% include api i="pyatv.connect" %} call, since many settings are only used when connecting.
+
+Internally, `pyatv` will automatically populate the provided storage with new devices when scanning and also
+insert credentials when pairing. Once a protocol has been successfully paired, no further credential
+management is necessary as the credentials will be available via the storage.
+
+Settings are managed via an instance of {% include api i="settings.Settings" %}, typically available via
+{% include api i="interface.AppleTV.settings" %}. It is also possible to retrieve settings directly from
+storage using {% include api i="interface.Storage.get_settings" %}.
+
+*Note: All changes made to a storage are stored in memory only until
+{% include api i="interface.Storage.save" %} is called. Make sure to call this method after all
+relevant updates, otherwise they will be lost!*
+
+## Settings Priority
+
+Storage is treated as a "first-class citizen" in pyatv. This means that internally, whenever pyatv
+needs settings for a configuration, it will load whatever is in storage and overwrite what is currently
+set in the configuration. If a setting is not present in storage, the corresponding setting in the
+configuration will however remain unchanged.
+
+The practical way of thinking about this is that settings and configurations are modified independently,
+i.e. you can change a setting in storage to one value and corresponding setting in the configuration to
+another value, thus creating an inconsistency. However, when you call a pyatv method, e.g.
+{% include api i="pyatv.connect" %}, settings will be loaded from storage and overwrite whatever is
+set in the configuration. Here is a simple example illustrating this:
+
+```python
+storage = FileStorage("pyatv.conf", loop)
+
+conf = await pyatv.scan(loop, identifier="xxx")[0]    # Scan without storage
+conf.get_service(Protocol.AirPlay).password ="pyatv"  # Change something in configuration
+
+settings = await storage.get_settings(conf)           # "conf" does not exist in this storage => new settings
+                                                      # password for AirPlay will be copied
+
+conf.get_service(Protocol.AirPlay).password ="pass"   # Change to something else
+settings = await storage.get_settings(conf)           # "conf" exists => return existing settings with
+                                                      # AirPlay password set to "pyatv"
+
+# connect will read settings from storage and apply to configuration (e.g. "pyatv" as AirPlay password)
+atv = await pyatv.connect(conf, loop, storage=storage)
+```
+
+If you make changes to a configuration and want to save them, use
+{% include api i="interface.Storage.update_settings" %} explicitly to force an update to storage:
+
+```python
+storage = FileStorage("pyatv.conf", loop)
+conf = await pyatv.scan(loop, identifier="xxx", storage=storage)[0]  # Scan and insert into storage
+
+conf.get_service(Protocol.AirPlay).credentials ="new_creds"  # Change something in configuration
+await storage.update_settings(conf)
+
+# "new_creds" have been saved to storage, so connect till use that password
+atv = await pyatv.connect(conf, loop, storage=storage)
+```
+
+The recommended way to alter settings is update settings directly in storage, i.e. by changing
+the instance returned by {% include api i="interface.Storage.get_settings" %} and not
+changing the configuration.
+
+## Using the Storage API
+
+Create a new storage of choice:
+
+```python
+from pyatv.storage.file_storage import FileStorage
+
+loop = asyncio.get_event_loop()
+storage = FileStorage("pyatv.json", loop)
+await storage.load()
+```
+
+Note that the storage must be loaded using {% include api i="interface.Storage.load" %} in order to fetch
+settings from the underlying storage, e.g. reading from file. Not calling this method results in undefined
+behavior.
+
+Scanning with storage:
+
+```python
+confs = await pyatv.scan(loop, storage=storage)
+```
+
+The storage will automatically be populated with all discovered devices.
+
+To pair with a storage:
+
+```python
+pairing = await pair(atvs[0], Protocol.AirPlay, loop, storage=storage)
+```
+
+When a successful pairing has been made, the resulting credentials are automatically inserted into
+the storage for further references.
+
+To connect with storage:
+
+```python
+atv = await pyatv.connect(confs[0], loop, storage=storage)
+```
+
+An instance of {% include api i="settings.Settings" %} containing loaded settings is available
+via {% include api i="interface.AppleTV.settings" %}.
+
+Changes made to settings in the storage are only stored in memory and must be saved using
+{% include api i="interface.Storage.save" %} to make them persistent:
+
+```python
+await storage.save()
+```
+
+Storages are supposed to keep track of changes and only save changes if something has actually
+changed.
+
+### Default File Storage
+
+When using tools bundled with pyatv, e.g. `atvremote` or `atvscript`,
+{% include api i="storage/file_storage.FileStorage" %} is used with the file `$HOME/.pyatv.conf`.
+You can tap into this storage with your own applications, thus sharing credentials with pyatv.
+There is a convenience method called
+{% include api i="storage/file_storage.FileStorage.default_storage" %} that is recommended to use
+as it is platform agnostic:
+
+```python
+loop = asyncio.get_event_loop()
+storage = FileStorage.default_storage(loop)
+await storage.load()
+```
+## Changing Settings
+
+As stated in [Storage Guidelines](#storage-guidelines), some settings are only used when connecting
+while others can be used at any given time (e.g. port numbers). It is recommended to update settings
+prior to connecting, but it is allowed to change setting even after connecting but the changes
+might not apply until the next time you connect.
+
+To get settings for a device, use {% include api i="interface.Storage.get_settings" %}:
+
+```python
+conf = ... # Scan for device
+
+settings = await storage.get_settings(conf)
+```
+
+To change setting, simply set new values according to your needs:
+
+```python
+settings.name = "My App"  # Named used when pairing
+settings.mac = "aa:bb:cc:dd:ee:ff"  # MAC address pyatv presents itself when needed
+
+settings.raop.password = "never_gonna_give_you_up"
+```
+
+Remember to save changes to storage to ensure they are stored persistently
+({% include api i="interface.Storage.save" %}).
+
+To find available settings, look at {% include api i="settings.Settings" %} in the API
+reference as each field are described there (including default values when applicable).
+
+## Custom Storage Module
+
+To implement your own storage module, it is recommended to inherit from
+{% include api i="storage.AbstractStorage" %} and implement the missing methods. Internally `pyatv` uses
+[pydantic](https://docs.pydantic.dev/) for the storage model, simplifying things like serialization when
+storing and loading settings. The {% include api i="storage.AbstractStorage.storage_model" %} property
+is used to get the current representation but also to update it when loading a model from an external
+source.
+
+Simply put:
+
+* `save` shall serialize {% include api i="storage.AbstractStorage.storage_model" %} in some way, e.g.
+  into JSON or YAML and save that somewhere
+* `load` shall take the saved data, de-serialize it and set
+  {% include api i="storage.AbstractStorage.storage_model" %} with the de-serialized data
+
+A simple pseudo example looks like this:
+
+```python
+import json
+from pyatv.storage import AbstractStorage
+
+class CloudStorage(AbstractStorage):
+
+    def __init__(self, cloud_api):
+        super().__init__()
+        self.cloud_api = cloud_api
+
+    async def save(self) -> None:
+        if self.changed:
+            json_data = self.storage_model.model_dump_json(exclude_defaults=True)
+            await self.cloud_api.save("myfile.json", json_data)
+            self.mark_as_saved()
+
+    async def load(self) -> None:
+        json_data = await self.cloud_api.load("myfile.json")
+        self.storage_model = StorageModel(**json.loads(json_data))
+        self.mark_as_saved()
+
+```
+
+Nothing else is really needed to implement a new storage module (implementing `__str__` for debugging
+purposes is also recommended). Do note how {% include api i="storage.AbstractStorage.changed" %} and
+{% include api i="storage.AbstractStorage.mark_as_saved" %} are used to only save the storage model
+in case it was changed. This removes unnecessary writes to disk since the same content would be
+re-written every time {% include api i="interface.Storage.save" %} is called otherwise.
+
+More complex implementations may inherit from
+{% include api i="interface.Storage" %} directly, but additional care must be taken to implement the
+interface correctly.
+
+*Note: Ensure to pass `exclude_defaults=True` when dumping the model, otherwise you will also save
+default values. This pollutes the output a lot, but also causes problems if default values are changed
+in pyatv as the settings written to storage will be used instead, i.e. old default values.*

package/pyatv/docs/development/stream.md

@@ -0,0 +1,241 @@
+---
+layout: template
+title: Stream
+permalink: /development/stream/
+link_group: development
+---
+ Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# Stream
+
+It is possible to stream audio and video to a device via the stream interface using
+AirPlay. The AirPlay suite consists of two protocols:
+
+* AirTunes/RAOP - Used for real time streaming of audio
+* "AirPlay - Everything else (video, images and screen mirroring)
+
+Currently there is some AirPlay functionality supported in pyatv, but it is
+very limited. These features are currently supported:
+
+- Device authentication ("pairing")
+- Playing media via URL
+- Streaming of local files
+
+Early support for streaming audio files via RAOP is also supported
+(even for non-Apple TV devices). MP3, wav, FLAC and ogg files are
+supported. Devices that require a password are only supported for the AirTunes/RAOP protocol, not the AirPlay protocol. 
+
+In the external interface, AirPlay (including RAOP) support is implemented via
+the {% include api i="interface.Stream" %} interface.
+
+## Using the streaming API
+
+Devices supporting the AirPlay protocol (e.g. Apple TV) can play files by simply providing
+a URL. It will then be streamed directly from the device. Audio can be streamed to other
+devices (like AirPlay speakers) that does not support this.
+
+### Play from URL
+
+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.
+
+To play a local file, just pass a local file to {% include api i="interface.Stream.play_url" %}
+instead:
+
+```python
+url = "/home/user/BigBuckBunny.mp4"
+await atv.stream.play_url(url)
+```
+
+When doing this, pyatv will internally start web server on a random port, serving this
+file only and start streaming from there. When streaming is done, the web server is shut
+down.
+
+The Apple TV will not provide any feedback if anything is not working. If you have
+problems, start by testing the example file above (`BigBuckBunny.mp4`) as that is
+known to work. Also make sure that you don't stream from an HTTPS server with a bad
+or self-signed certificate: that will not work.
+
+### Stream a file
+
+To stream a file, use {% include api i="interface.Stream.stream_file" %}:
+
+```python
+stream = ...
+await stream.stream_file("sample.mp3")
+```
+
+Files in MP3, WAV, FLAC and OGG format are supported and will be automatically converted
+to a format the receiving device supports. Metadata is also extracted from files
+of these types and sent to the receiver.
+
+It is also possible to stream directly from a buffer. In this example, a file is
+read into a buffer and streamed:
+
+```python
+import io
+
+with io.open("myfile.mp3", "rb") as source_file:
+    await stream.stream_file(source_file)
+```
+
+Streaming directly from `stdin` also works, e.g. when piping output from another
+process:
+
+```python
+await stream.stream_file(sys.stdin.buffer)
+```
+
+As `stdin` is a text stream, the underlying binary buffer must be retrieved and used.
+
+It is also possible to use an asyncio
+[StreamReader](https://docs.python.org/3/library/asyncio-stream.html#streamreader) as
+input. Here is an example piping output from ffmpeg:
+
+```python
+import asyncio.subprocess as asp
+
+process = await asp.create_subprocess_exec(
+    "ffmpeg", "-i", "file.mp3", "-f", "mp3", "-",
+    stdin=None, stdout=asp.PIPE, stderr=None,
+)
+
+await self.atv.stream.stream_file(process.stdout)
+```
+
+When streaming from a buffer, it's important to know that some audio formats are
+not suitable for that. MP3 works fine, WAV and OGG does not. The reason is that
+seeking is done in the stream and `stdin` does for instance not support that. If
+the buffer supports seeking, then all formats will work fine, otherwise stick with
+MP3. For the same reason, metadata will not work if seeking is not supported as
+that is extracted prior to playing the file, so seeking is needed to return to
+the beginning of file again before playback.
+
+Note 1: Since  pyatv v0.13.0, buffer improvements have been made to support some
+seeking, even in non-seekable streams. This is however not fool-proof and not all
+audio formats (or files/streams) work, but compatibility is much better from that
+version and onwards.
+
+Note 2: that there's (roughly) a two second delay until audio starts to play. This
+is part of the buffering mechanism and not much pyatv can do anything about.
+
+#### Custom Metadata
+
+By default, pyatv will try to extract metadata from whatever content you are playing.
+Some file formats or streams either does not support nor provide any metadata,
+in which case you can manually provide the metadata that pyatv will report to the
+receiver by passing an instance of {% include api i="interface.MediaMetadata" %}
+when starting to stream:
+
+```python
+from pyatv.interface import MediaMetadata
+
+metadata = MediaMetadata(artist="pyatv", title="Look at me, I'm streaming")
+await stream.stream_file("myfile.mp3", metadata=metadata)
+```
+
+All fields in {% include api i="interface.MediaMetadata" %} can be overridden (including
+artwork) except for {% include api i="interface.MediaMetadata.duration" %}, which is
+ignored. Please note that artwork must be in JPEG format.
+
+Custom metadata will override any metadata provided by the streamed content. You
+can however tell pyatv to only override metadata fields that are missing by setting
+`override_missing_metadata` to `True`:
+
+```python
+from pyatv.interface import MediaMetadata
+
+metadata = MediaMetadata(artist="pyatv")
+await stream.stream_file("myfile.mp3", metadata=metadata, override_missing_metadata=True)
+```
+
+This will use all the metadata from `myfile.mp3`, but use _pyatv_ as artist but **only**
+if that field is not present in the file.
+
+#### Stream from HTTP(S)
+
+There is experimental support for streaming directly from HTTP or HTTPS. A URL can
+be passed instead of a file path:
+
+```python
+await stream.stream_file("https://foo.bar/test.mp3")
+```
+
+#### File Compatibility
+
+It is possible to verify if a file is supported programmatically using
+{% include api i="helpers.is_streamable" %}:
+
+```python
+from pyatv.helpers import is_streamable
+
+if await is_streamable("myfile.mp3"):
+    await atv.stream_file("myfile.mp3")
+else:
+    print("File is not supported")
+```
+
+There are a few caveats worth knowing:
+
+* No exception is ever raised, even when file is not found or lack of permissions
+* Only valid for {% include api i="interface.Stream.stream_file" %} (*not*
+  {% include api i="interface.Stream.play_url" %})
+* Only a basic check is made, the file might be broken and not still not playable
+
+## Password
+
+If you stream audio using the RAOP protocol and the device requires a password, you can set the password like this: 
+
+```python
+raop_service = atv_conf.get_service(Protocol.RAOP)
+raop_service.password = "test"
+atv = await connect(atv_conf, ...)
+await atv.stream.stream_file("sample.mp3")
+```
+
+## 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 these 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 merely been ported
+to python for usage in this library. Please see references at bottom of page
+for reference implementation.
+
+### Device Pairing in pyatv
+
+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 reused 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:
+
+```raw
+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.

package/pyatv/docs/development/testing.md

@@ -0,0 +1,9 @@
+---
+layout: template
+title: Services
+permalink: /development/testing/
+link_group: development
+---
+# Testing
+
+This page has not yet been migrated to GitHub Pages. Come back later...

package/pyatv/docs/documentation/atvlog.md

@@ -0,0 +1,64 @@
+---
+layout: template
+title: atvlog
+permalink: /documentation/atvlog/
+link_group: documentation
+---
+# Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# atvlog
+
+The `atvlog` script simplifies log inspection by generating an HTML file with basic
+live filtering capabilities.
+
+*Note: This is an incubating script and may change behavior with short notice.*
+
+# Features
+
+Log output from the following tools are supported as input:
+
+* atvremote and atvscript
+* Home Assistant log
+
+A special `markdown` mode is supported, which extracts a log from the following
+format:
+
+~~~
+text here is ignored
+```log
+log data here
+```
+also ignored
+~~~
+
+Filtering can be performed on the following attributes:
+
+* Include entries based on regexp
+* Exclude entries based on regexp (performed prior to include regexp)
+* Log levels
+* Date can be stripped for more compact log
+
+# Serving output via web server
+
+It is possible to serve the generated log output via a built in web server using flag `-w`:
+
+```shell
+$ atvlog -w pyatv.log
+Press ENTER to quit
+```
+
+Then visit `http://<ip>:8008` to see the log. The port number can be changed
+with `-p xxxx`.
+
+# Examples
+
+```shell
+$ atvlog pyatv.log  # Print output to stdout
+$ atvlog --output pyatv.html pyatv.log
+$ cat pyatv.log | atvlog -  # Read from stdin
+$ cat markdown.log | atvlog --format=markdown -
+```
+