From f2ce865cb8d44aa17f52c16682a2eb5c8c45ab2b Mon Sep 17 00:00:00 2001 From: Natalie Date: Tue, 9 Jun 2026 20:57:51 -0700 Subject: [PATCH] =?UTF-8?q?docs(@applications/tv-anarchy):=20=F0=9F=93=9D?= =?UTF-8?q?=20update=20app=20description=20and=20architecture=20details?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Lilith Autocommit --- README.md | 43 +++++++++++++++++++++++++++++-------------- docs/README.md | 15 ++++++++------- docs/data-model.md | 30 ++++++++++++++++++++++++------ docs/operations.md | 8 +++++--- 4 files changed, 66 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index b9fbb41..1f798a3 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,16 @@ # TVAnarchy -Native macOS app (SwiftUI) for the home media stack on **plum**. Unifies what was -previously CLI/MCP-only: pick a **playback target** (plum's VLC or the HDMI TV on -**black**) and drive transport; later phases add a cached library browser, a -download searcher/manager, and a local (MLX) filename→metadata pipeline. +Native macOS app (SwiftUI) for the home media stack on **plum**, plus an iOS +companion. Unifies what was previously CLI/MCP-only: pick a **playback device** +(plum's VLC/QuickTime or the HDMI TV on **black**) and drive transport, browse a +cached library, search and manage downloads, enrich metadata, and manage the +device registry — all from one app. -**Hybrid architecture:** the control plane is native Swift (SSH shell-outs to the -deployed `black-tv` script; HTTP to VLC's Lua interface — zero new runtime deps); -the data-heavy plane reuses existing projects (`plum-control-mcp`, `media-recommender`) -as helper subprocesses. See the build plan for phases. +**Hybrid architecture:** the control plane is native Swift (HTTP to VLC's Lua +interface; mpv JSON-IPC over SSH to black — zero new runtime deps); the +data-heavy plane reuses the vendored helper projects (`mcp/`, `recommender/`, +`search/`) as subprocesses. See [docs/](docs/README.md) for the full picture and +[docs/roadmap.md](docs/roadmap.md) for built-vs-designed status. ## Build @@ -23,13 +25,26 @@ xcodebuild -scheme TVAnarchy -destination 'platform=macOS' build ## Layout -- `Sources/TVAnarchyCore/` — framework: models, `PlayerTarget` protocol + impls, target selector. -- `Sources/TVAnarchy/` — SwiftUI app (App, RootView, feature views). -- `Tests/TVAnarchyCoreTests/` — unit tests for the core (status decoders, mappings). +- `Sources/TVAnarchyCore/` — framework: models, `PlayerTarget` protocol + impls, + library/metadata/torrents/VPN subsystems, device registry. +- `Sources/TVAnarchy/` — SwiftUI macOS app (App, RootView, feature views: + Home/Player/Library/Search/Downloads/Metadata/Adult/Devices/Logs/Settings). +- `Sources/TVAnarchyiOS/` — iOS companion (VLCKit player, library, downloads, + remote control over an HTTP bridge). +- `Tests/TVAnarchyCoreTests/`, `Tests/TVAnarchyiOSUITests/` — unit + UI tests. +- `governor/`, `mcp/`, `recommender/`, `search/` — helper subsystems (own READMEs). +- `fleet/` — designed-only mesh layer; `tools/` — release/update/stamping scripts; + `docs/` — cross-cutting documentation. -## Targets +## Playback devices - **Plum VLC** — HTTP to `http://127.0.0.1:8080/requests/…` (password from `~/.config/portable-net-tv/config.json` or `$VLC_HTTP_PASSWORD`). -- **Black TV** — `ssh lilith@10.9.0.4 /usr/local/bin/black-tv ` (the overlay IP; - the LAN address flaps). All playback intelligence lives in `black-tv` on black. +- **Black (mpv)** — mpv JSON-IPC over SSH, endpoints LAN `10.0.0.11` → + WG overlay `10.9.0.4` fallback (the LAN address flaps). Launch/library/stats + are delegated to per-device command templates wrapping `/usr/local/bin/black-tv` + (the legacy `blacktv` kind auto-migrates to this). +- **QuickTime** — local, zero-install, AppleScript-driven. + +Devices live in `~/.config/tv-anarchy/devices.json` and are editable in the +Devices tab. diff --git a/docs/README.md b/docs/README.md index 9d3358b..6c2621a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,11 +1,11 @@ # TV Anarchy — Documentation -TV Anarchy is a native macOS (SwiftUI) front end for a home media stack centered -on **plum** (the laptop) and **black** (the media server). It unifies what was -previously CLI/MCP-only: pick a playback target, browse a cached library, search -and manage torrents, and enrich metadata — all from one app. A larger, -forward-looking layer (the self-healing torrent **fleet/mesh**) is designed but -not yet built. +TV Anarchy is a native macOS (SwiftUI) front end — plus an iOS companion app — +for a home media stack centered on **plum** (the laptop) and **black** (the +media server). It unifies what was previously CLI/MCP-only: pick a playback +device, browse a cached library, search and manage torrents, enrich metadata, +and manage the device registry — all from one app. A larger, forward-looking +layer (the self-healing torrent **fleet/mesh**) is designed but not yet built. This directory is the project's living documentation. Component-level READMEs stay next to their code; these documents are the cross-cutting reference. @@ -22,9 +22,10 @@ next to their code; these documents are the cross-cutting reference. ## Component docs (next to the code) -- [`../README.md`](../README.md) — the Swift app: targets, layout, build +- [`../README.md`](../README.md) — the Swift apps (macOS + iOS): targets, layout, build - [`../governor/README.md`](../governor/README.md) — `portable-net-tv`: watch tracking + prefetch buffer - [`../mcp/README.md`](../mcp/README.md) — `plum-control-mcp`: VLC / black-tv / transmission / display tools +- [`../search/README.md`](../search/README.md) — vendored torrent-search MCP fork (TPB/Nyaa/1337x) - [`../fleet/README.md`](../fleet/README.md) — fleet/mesh placeholder (not yet implemented) - [`../recommender/`](../recommender/) — Python enrichment + recommendations (`recommend_local.py`, `media_rec/`) diff --git a/docs/data-model.md b/docs/data-model.md index 9d0d90d..3397d18 100644 --- a/docs/data-model.md +++ b/docs/data-model.md @@ -7,26 +7,37 @@ and write these), and the **planned fleet/mesh data model** (designed, unbuilt). ## In use today -### `hosts.json` — playback target config +### `devices.json` — device registry + playback target config -Path: `~/.config/tv-anarchy/hosts.json` (auto-migrated forward from the pre-rename -`~/.config/plumtv/hosts.json`). Source: `Sources/TVAnarchyCore/HostConfig.swift`. -Written pretty-printed + sorted-keys; seeded on first run with Plum VLC + Black -(mpv) if absent. +Path: `~/.config/tv-anarchy/devices.json` (auto-migrated forward from +`~/.config/tv-anarchy/hosts.json`, and before that `~/.config/plumtv/hosts.json`). +Source: `Sources/TVAnarchyCore/DeviceConfig.swift`. Written pretty-printed + +sorted-keys; seeded on first run with Plum VLC + Black (mpv) if absent. The +decoder accepts the legacy top-level `hosts` key alongside `devices`. + +Each device carries a `type` — `cellphone | laptop | storage | seed | broadcast`, +mapping to the planned fleet classes `consumer | roamer | server | seedbox | +broadcast` — and an overridable `services` preset (`stream`, `offlineCache`, +`ttlSeed`, `custody`, `publicSwarmFace`, `f2fRelay`, `meshAnchor`). Legacy +entries without a `type` get one inferred from the player backend. ```jsonc { - "hosts": [ + "devices": [ { "id": "plum-vlc", "name": "Plum VLC", "kind": "vlc", // vlc | mpv-ipc | quicktime | blacktv(legacy) + "type": "laptop", // cellphone | laptop | storage | seed | broadcast + "services": { "stream": true, "offlineCache": true, "ttlSeed": true }, "vlc": { "host": "127.0.0.1", "port": 8080 } }, { "id": "black", "name": "Black TV", "kind": "mpv-ipc", + "type": "storage", + "services": { "stream": true, "custody": true }, "mpv": { "endpoints": ["lilith@10.0.0.11", "lilith@10.9.0.4"], // LAN first, WG overlay fallback "socket": "/tmp/mpv.sock", // default @@ -88,6 +99,7 @@ filename (everything before the `SxxEyy` marker). | Artifact | Path | Writer | |---|---|---| +| App settings | `~/.local/state/tv-anarchy/settings.json` | `SettingsStore` (adult gating, hover previews, media-key forwarding, offline-cache sizing; tolerant decode) | | Library snapshot | `~/.local/state/tv-anarchy/library.json` | `LibraryStore` | | Metadata sidecar | `~/.local/state/tv-anarchy/meta/.json` | `MetaWriter` (mirrored best-effort to `.meta` on black) | | Artwork cache | frame-grab JPEGs (keyed by path) | `ArtworkService` | @@ -146,6 +158,12 @@ Duty = custody_floor | public_swarm_face | f2f_relay | broadcast Example fleet: black = server, apricot = secondary always-on, plum = roamer (TTL seeder), phone = consumer (pure sink, never any duty). +> **Partially landed:** the app's `devices.json` (above) already carries the +> class mapping (`DeviceType.fleetClass`) and a `services` preset that mirrors +> the duty vocabulary. What does **not** exist is the manager that *assigns* +> duties from capacity/reachability — services today are user-set presets, not +> computed duties. + ### Duty-assignment rules (deterministic, run on registry change) | Duty | Eligibility | Rule | diff --git a/docs/operations.md b/docs/operations.md index eaaa245..c519b4b 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -75,7 +75,8 @@ localhost+overlay networking). | File | Purpose | |---|---| -| `~/.config/tv-anarchy/hosts.json` | Playback targets (migrates from `~/.config/plumtv/hosts.json`) | +| `~/.config/tv-anarchy/devices.json` | Device registry + playback targets (migrates from `hosts.json`, then `~/.config/plumtv/hosts.json`) | +| `~/.local/state/tv-anarchy/settings.json` | App settings (adult gating, previews, media keys, offline cache) | | `~/.config/portable-net-tv/config.json` | Governor config **and** the VLC HTTP password source | | `~/.local/state/plum-control-mcp/watched.jsonl` | Shared watch log | | `~/.local/state/tv-anarchy/library.json` | Cached library snapshot | @@ -93,8 +94,9 @@ localhost+overlay networking). (`10.9.0.4`) because the LAN address flaps. - **QuickTime** — local, zero-install; no setup. -Hosts are editable in-app (Hosts tab: add/edit/delete, make-active, reload, reset, -reveal `hosts.json`). +Devices are editable in-app (Devices tab: add/edit/delete, make-active, set +type/services, reload, reset, reveal `devices.json`). The list shows a +per-device system-load badge (low/med/high). ## governor (`portable-net-tv`)