Metadata-Version: 2.4
Name: pyatv-http
Version: 0.1.1
Summary: HTTP interface for controlling Apple TVs via pyatv
Project-URL: Homepage, https://github.com/hugoh/pyatv-http
Project-URL: Repository, https://github.com/hugoh/pyatv-http
Project-URL: Issues, https://github.com/hugoh/pyatv-http/issues
Author: Hugo Haas
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Home Automation
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.121.0
Requires-Dist: pyatv>=0.16.0
Requires-Dist: uvicorn>=0.38.0
Description-Content-Type: text/markdown

# pyatv-http

An HTTP interface for controlling Apple TVs, built on top of
[pyatv](https://github.com/postlund/pyatv).

## Features

- `POST /<name>/turnOn` and `POST /<name>/turnOff` — checks the Apple TV's current
  power state and only sends a command if it differs from the desired state.
- `GET /<name>/powerState` — reads the current power state without changing it.
- `GET /devices` — lists the devices available in the config file.
- `GET /health` — unauthenticated liveness check, for load balancers/uptime
  monitors.
- Every other request requires a bearer token, configured as a list of
  accepted tokens in the config file.
- Config-driven: one TOML file lists the port to listen on, accepted API
  tokens, and the paired devices.
- Pairing stays out-of-band, via pyatv's own `atvremote` CLI; a `pyatv-http gen-config`
  helper turns a paired device's stored credentials into a config snippet.

## Setup

### 1. Find your Apple TV

```sh
uvx --from pyatv atvremote scan
```

This lists every Apple TV on the network along with its identifiers, IP
address, and which protocols it supports (AirPlay, Companion, etc).

### 2. Pair with `atvremote`

Power control uses the **Companion** protocol, and pyatv-http talks to the
device over **AirPlay** for the initial handshake, so pair both:

```sh
uvx --from pyatv atvremote --id <device-identifier> pair --protocol airplay
uvx --from pyatv atvremote --id <device-identifier> pair --protocol companion
```

Follow the on-screen PIN prompt for each. Credentials are stored in pyatv's
storage file (default `~/.pyatv.conf`).

### 3. Generate a config entry

```sh
uv run pyatv-http gen-config \
  --identifier <device-identifier> \
  --address <device-ip-or-hostname> \
  --key living_room
```

`<device-identifier>` and `<device-ip-or-hostname>` come from the `scan`
output in step 1; `--key` is whatever short name you want to use in URLs
(`--name` sets the human-readable display name too, defaulting to `--key`).

This prints a `[devices.living_room]` TOML block built from the stored
pairing. Paste it into your config file (see below). If the identifier
doesn't match any paired device, the command lists the identifiers it does
have on file.

### 4. Write the config file

```toml
port = 8080

[auth]
tokens = ["a-long-random-token"]

[devices.living_room]
name = "Living Room"
identifier = "AA:BB:CC:DD:EE:FF"
address = "10.0.0.5"

[devices.living_room.protocols.airplay]
identifier = "AA:BB:CC:DD:EE:FF"
credentials = "..."

[devices.living_room.protocols.companion]
identifier = "11:22:33:44:55:66"
credentials = "..."
```

- `port` — port the HTTP server listens on. Optional, defaults to `8080`.
- `[auth].tokens` — required, non-empty list of bearer tokens accepted on every
  request (see [API](#api) below). Generate one with e.g.
  `python3 -c "import secrets; print(secrets.token_urlsafe(32))"`.
- The `[devices.<key>]` table key (`living_room` above) is the URL path
  segment used in requests, e.g. `POST /living_room/turnOn`.
- `identifier` — the device's main pyatv identifier (from `atvremote scan`).
- `address` — the Apple TV's IP address or hostname; used to connect
  directly instead of relying on mDNS discovery at request time.
- `[devices.<key>.protocols.<protocol>]` — one block per paired protocol,
  exactly as generated by `gen-config`. Supported protocol names: `airplay`,
  `companion`, `dmap`, `mrp`, `raop`.

### 5. Run the server

```sh
uv run pyatv-http serve --config config.toml
```

`--config` is optional; if omitted, it defaults to
`$XDG_CONFIG_HOME/pyatv-http/config.toml`, falling back to
`~/.config/pyatv-http/config.toml` when `$XDG_CONFIG_HOME` isn't set.

By default the server binds `0.0.0.0`; pass `--host` to bind a specific
interface.

## API

Every request must include one of the configured tokens as a bearer token:

```sh
TOKEN=a-long-random-token

curl -X POST http://localhost:8080/living_room/turnOn \
  -H "Authorization: Bearer $TOKEN"

curl -X POST http://localhost:8080/living_room/turnOff \
  -H "Authorization: Bearer $TOKEN"

curl http://localhost:8080/living_room/powerState \
  -H "Authorization: Bearer $TOKEN"

curl http://localhost:8080/devices \
  -H "Authorization: Bearer $TOKEN"

curl http://localhost:8080/health
```

`turnOn`/`turnOff`/`powerState` return a JSON body:
`{"device": "living_room", "power_state": "on"}`.

`GET /devices` returns the devices available in the config file:

```json
[{"device": "living_room", "name": "Living Room"}]
```

`GET /health` (no token required) returns `{"status": "ok"}`.

| Status | Meaning                                                           |
| ------ | ------------------------------------------------------------------ |
| 200    | Command sent (or no-op, if the device was already in that state)   |
| 401    | Missing or invalid bearer token                                    |
| 404    | No device configured under that name                               |
| 504    | Device could not be found/reached on the network                   |
| 502    | pyatv raised an error while connecting or sending the command      |

### Interactive API docs

FastAPI auto-generates interactive documentation for the running server:

- `GET /docs` — Swagger UI (use the "Authorize" button to set your bearer
  token, then try requests directly from the browser).
- `GET /redoc` — ReDoc view of the same schema.
- `GET /openapi.json` — the raw OpenAPI schema.

These three routes are not themselves behind the bearer-token check.

## Notes

- Each request opens a fresh connection to the Apple TV, checks its current
  power state, and only sends `turnOn`/`turnOff` if it differs from the
  desired state — there's no persistent connection or background polling.
- Pairing is entirely out-of-band via `atvremote`; this project never
  performs the pairing handshake itself.

## Development

```sh
uv sync
uv run pytest
hk check --all
```
