nstream 1.43.0__tar.gz

nstream-1.43.0/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "nstream",
+  "description": "Headless streaming control for nstream — search a movie or TV series and play it locally (mpv) or cast it to a Chromecast, non-interactively, with machine-readable JSON output.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Gianluca Mazza"
+  },
+  "homepage": "https://github.com/gianlucamazza/nstream",
+  "repository": "https://github.com/gianlucamazza/nstream"
+}

nstream-1.43.0/.github/workflows/check.yml

@@ -0,0 +1,24 @@
+name: Verify
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+concurrency:
+  group: verify-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - run: bash scripts/check.sh

nstream-1.43.0/.github/workflows/pypi.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+on:
+  push:
+    tags:
+      - "v*"
+permissions:
+  contents: read
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+jobs:
+  pypi:
+    if: github.repository == 'gianlucamazza/nstream'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nstream
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

nstream-1.43.0/.gitignore

@@ -0,0 +1,18 @@
+# Never commit the real config: it contains the Real-Debrid API token
+config.json
+*.local.json
+
+# Python / build
+__pycache__/
+*.pyc
+.venv/
+dist/
+.ruff_cache/
+
+# Arch packaging build artifacts
+packaging/pkg/
+packaging/src/
+packaging/nstream/
+packaging/*.pkg.tar.zst
+packaging/*.tar.gz
+packaging/*.sig

nstream-1.43.0/AGENTS.md

@@ -0,0 +1,97 @@
+# AGENTS.md
+
+Guidance for agents working in this repository.
+
+## Project
+
+nstream is a native, terminal-first Stremio alternative: no Electron, no embedded browser,
+no Node server. Pure Python 3.13+ stdlib (zero runtime dependencies) orchestrating external
+CLIs (`fzf`, `mpv`, `ffprobe`, `catt`, `chafa`, optional TorrServer / castbridge) over Stremio
+addon HTTP APIs. Entry point is `nstream.cli:_entry` (`src/nstream/cli.py`).
+
+Pipeline: search/browse (Cinemeta + catalogs) → pick title/episode (fzf or `--json`) → optional
+subtitles (OpenSubtitles v3 + alignment) → fetch streams (Torrentio and/or `cfg.addons`) →
+hardware- or cast-aware rank/filter → play (mpv) or cast (castbridge/catt/remux/mirror) →
+track progress (resume / continue-watching).
+
+## Commands
+
+Tooling is `uv`-based (no venv activation needed).
+
+| Task | Command |
+| ---- | ------- |
+| Run tests | `uv run python -m pytest` |
+| Single test | `uv run python -m pytest tests/test_labels.py::test_display_title_movie` |
+| Lint | `uvx ruff check . && uvx ruff format --check .` |
+| Type check | `uvx ty check` |
+| Dev run | `uv run nstream "the matrix"` |
+| Install (dev) | `./install.sh` (uses `uv tool install`) |
+
+Use `python -m pytest` (not bare `uv run pytest`): if a system-wide `nstream` is installed,
+bare `pytest` resolves to the system interpreter and imports the **installed** package instead
+of `src/`. `python -m` runs the project venv with the editable `src/` checkout.
+
+Ruff: line-length 100, rules `E,F,I,UP,B,SIM`. Pytest: `testpaths=["tests"]`, `-q`.
+Each `src/nstream/<mod>.py` has a matching `tests/test_<mod>.py` (or package coverage).
+
+## Documentation map (do not re-duplicate)
+
+| Topic | Source of truth |
+| ----- | --------------- |
+| Module map / domains | [`docs/architecture.md`](docs/architecture.md) |
+| Stream ranking / cast vet | [`docs/selection.md`](docs/selection.md) |
+| Headless `--json` contract | [`docs/headless.md`](docs/headless.md) |
+| Config keys | [`docs/user/config.md`](docs/user/config.md) |
+| Decisions (why) | [`docs/adr/`](docs/adr/README.md) |
+| Hub / audience routing | [`docs/README.md`](docs/README.md) |
+| Agent playbook (intent→cmd) | [`skills/nstream/SKILL.md`](skills/nstream/SKILL.md) |
+| Contributor process | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
+
+Update architecture when adding/moving modules — **not** the README module list (there is none).
+
+### Import-graph discipline (non-negotiable)
+
+- Top: `util` / `ui` / `languages` / `types` / `sources` / `net` / `log` (see architecture)
+- `cli` orchestrates at the bottom
+- Everything below `cli` **never** imports `cli` (including `headless`, `cast_flow`,
+  `stream_select`, `cast_vet`, `player`, `caster`, …)
+- Cast policy lives in `cast_vet`; cast decision tree in `cast_flow`; backends in
+  `caster` / `remux` / `mirror`; TUI cast lifecycle in `cast_control`. Selection facade:
+  `stream_select.prepare_stream`. Availability probes/denylist: `availability`. Domain
+  TypedDicts: `types` (not `config`). Headless play body: `headless_play`; argparse:
+  `cli_args`. State package: `state/` (history, cast_session, dead, breaker)
+
+### Hard constraints when editing
+
+- **Debrid provider-agnostic:** never special-case RealDebrid; tokens/markers/redaction are generic
+- **Never log stream URLs or debrid tokens in clear** — use `what=` labels; `log.RedactFormatter`
+- **Cast audio language** is decided at selection (`cast_vet.vet_cast_audio`), not on the DMR
+- **Dead sources (ADR 0025):** only `gone` probes are persisted; incomplete reads are not proof
+- **P2P privacy gate (ADR 0032):** at every swarm join, not one call site
+- **Disk I/O best-effort** try/except — never block playback
+- fzf sentinels are module-level `object()` values (`_PLAY`, `_ALL`, …) so `None` means ESC
+- Comments/docs in English; concise, no over-engineering
+- **`ui.Caps`** = terminal caps; **`quality.HwCaps`** = GPU/vainfo — different types
+- New architectural trade-off → ADR ([template](docs/adr/0000-template.md)); cite symbols not lines
+
+### Stream sources (ADR 0024)
+
+Torrentio (`torrentio_enabled`) + `cfg.addons` manifests. `api.streams` stamps `addon`, fuses
+debrid url with torrent infoHash by filename, collapses duplicates (cached > url > infoHash).
+
+### Secrets & paths
+
+- Config: `$XDG_CONFIG_HOME/nstream/config.json` (chmod 600; template `config.example.json`)
+- History: `$XDG_STATE_HOME/nstream/history.json`
+- Library: `$XDG_STATE_HOME/nstream/library.json` (recent + watchlist metadata only)
+- Dead sources: `$XDG_STATE_HOME/nstream/dead-sources.json` (`--forget-dead`)
+- Addon breakers: `$XDG_STATE_HOME/nstream/addon-breakers.json` (`--forget-breakers`, ADR 0027)
+- Caches: `$XDG_CACHE_HOME/nstream/` (`manifests.json`, `hwcaps.json`, `devices.json`, `meta/`, `posters/`, `torrents/`)
+- Log: `$XDG_STATE_HOME/nstream/nstream.log` (rotating); `--debug` / `NSTREAM_DEBUG=1` → stderr DEBUG
+- Runtime deps: `mpv`, `fzf` (required); `ffmpeg`/`ffprobe`, `catt`, TorrServer, `vainfo`, `chafa`, `foot`, castbridge/mirror (optional)
+
+## Packaging hygiene
+
+`packaging/` tracked files: `PKGBUILD`, `build-local.sh`, `nstream.install`, `.SRCINFO` only.
+Build artifacts (`pkg/`, `src/`, `*.pkg.tar.zst`, `*.sig`) are gitignored; `build-local.sh`
+cleans them. Do not commit wheels or makepkg trees.

nstream-1.43.0/CHANGELOG.md

@@ -0,0 +1,251 @@
+# Changelog
+
+All notable changes to nstream are documented here. Version source:
+`src/nstream/__init__.py` (and `packaging/PKGBUILD` `pkgver`).
+
+Format loosely follows [Keep a Changelog](https://keepachangelog.com/).
+
+## Unreleased
+
+## [1.43.0] — 2026-10-02
+
+### Added
+
+- `SECURITY.md`: report debrid-token leaks and LAN/remux-server issues via GitHub
+  private advisories.
+- GitHub Actions Trusted Publisher workflow publishes to PyPI on `v*` tags (OIDC, no
+  API token in secrets).
+
+### Changed
+
+- Field notes and tests use RFC 5737 TEST-NET-1 (`192.0.2.10`) and a dummy Cast
+  application id (`CA5T0001`) in place of a home LAN address and a personal receiver id.
+- Arch `PKGBUILD` source is the GitHub tag tarball over HTTPS (directory
+  `nstream-$pkgver`). `sha256sums` stays `SKIP` until the public `v1.43.0` tarball exists.
+
+## [1.42.0] — 2026-10-02
+
+### Added
+
+- **ADR 0044 Accepted:** live `started` is an observed player state
+  (PLAYING/PAUSED/BUFFERING). Dual-layer Dolby Vision and a first HLS segment the DMR
+  cannot decode skip live; the complete-file remux is the fallback.
+
+### Fixed
+
+- Live fire-and-return no longer reports `ok: true` on a mere LOAD ack, so a DMR that
+  fetches the playlist and then ERRORs falls back to the complete-file remux.
+- Dual-layer Dolby Vision (enhancement layer) and a first HLS segment without decodable
+  audio skip the live path. Profile 8 single-layer stays live. Field 2026-10-02:
+  *After Hours* live head refused → `delivery: file` → PLAYING.
+
+## [1.41.0] — 2026-10-02
+
+### Added
+
+- **ADR 0042 Accepted:** a live cast that wants subtitles uses the release's own full text
+  track (never a `forced` one) as an HLS WebVTT rendition, activated by castbridge ≥ 0.4.1
+  (`textLanguage`). The complete-file path extracts the same track in its pass.
+  `subtitles_match: "embedded"`.
+- `--sub-shift ±S` (and TUI cast menu ±0.5 s) moves a live cast's subtitles.
+- After-start subtitle alignment on live casts: the producer measures speech activity, and
+  after 10 min the cues are aligned with the same gates as the complete-file path.
+  `--status` reports `subtitles_offset`.
+- Live seeks anywhere (producer restart at the target), the TV clock in film time
+  (`EXT-X-GAP` filler), bandwidth-aware ranking and a `live_slow` warning.
+- Binge: the next episode's live producer is prepared near the end of the current one
+  and adopted at the change.
+- Interactive (TUI) live casts share the live state: seeks, sub-shift and film-time status.
+
+### Changed
+
+- **ADR 0043 Accepted:** a downloaded subtitle on a live cast is a rendition too (the
+  producer's second input), so `--sub-shift` and the after-start alignment only rewrite
+  the cues the TV fetches next: the media is never reloaded.
+- With castbridge ≥ 0.4.2 a live seek's LOAD rides the running receiver session (no app
+  relaunch, no INTERRUPTED playback).
+
+### Fixed
+
+- `--sub-shift` on a live cast no longer leaves the TV IDLE or stuck in BUFFERING (it
+  re-LOADed the media).
+- A live seek that restarts the producer no longer sends the TV IDLE (ERROR) before the new
+  playlist loads: the old generation is kept until the receiver moves on.
+- `tests/test_e2e.py` no longer spawns the real castbridge (216 orphaned daemons found).
+- `--follow` events report film time and the probed duration on live casts.
+
+## [1.40.0] — 2026-10-01
+
+### Added
+
+- **ADR 0039 Accepted:** a cast whose audio needs conversion (Dolby/DTS, or an `.mkv`
+  rewrap) streams a live HLS-TS playlist and starts in seconds instead of after the
+  whole-file remux. Stereo AAC; disk bounded to a ~40-min window; the complete file is the
+  fallback. `cast_live` config key; JSON `delivery` (`live`/`file`/`direct`/`mirror`/`local`).
+- Live seeks: far jumps re-LOAD the playlist at the target (the receiver clamps them);
+  a resume starts the producer at the resume point (27 s instead of 223 s for 50 min).
+
+### Changed
+
+- **ADR 0041 Accepted:** with the live tier, a soft `audio_langs` preference starts the
+  preferred dub instead of yielding to another one (ADR 0035 stays the fallback when live
+  cannot run; its notice now names `--audio-lang <lang>`).
+
+### Fixed
+
+- A live cast's progress reaches history (the playlist reports no duration).
+- A live LOAD always uses the Default Media Receiver: the custom receiver refuses HLS.
+- A recast of the title the TV is playing (another dub, a retry) resumes where the TV is
+  at LOAD time, not where it was when the command began.
+- `urlproxy` resumes dropped upstream reads and never prints tracebacks (#5).
+- Releases with burned-in CJK subtitles are demoted (CJK-script name on any addon, HC/CHS
+  tags) and never picked for an instant direct cast (#6).
+- A search whose catalog (Cinemeta) never answered is a `network` error to retry, not
+  `no_result` (#4).
+
+## [1.39.0] — 2026-10-01
+
+### Fixed
+
+- **ADR 0036 Accepted:** remux feasibility (disk, size budget) is decided before the
+  prepare, never after a multi-GB download; an infeasible conversion fails as
+  `remux_infeasible` instead of a mute direct cast. Search, cast ranking and disc-sized
+  releases fixed from the 2026-10-01 incident.
+- **ADR 0038 Accepted:** a dead source is keyed by what failed, never by a shared
+  display name.
+- Debrid tokens no longer appear in child-process argv: ffmpeg/ffprobe read through a
+  loopback proxy (`urlproxy`), mpv through a private playlist file.
+- Subtitles: local audio alignment works (it had failed every time since July: mono
+  16 kHz analysis, runtime-based timeout). One cue model (`srt`): CP1252/UTF-16 decoding,
+  valid WebVTT (3-digit ms, ASS/`<font>` tags removed, `<`/`&` escaped), cues before 0
+  dropped instead of piled at 00:00. A failed download tries the next candidate.
+  Downloads are size-capped (gzip bombs) and cached by URL. catt receives the cleaned
+  WebVTT. `subs_delivered` follows the receiver's confirmed active tracks; the caption
+  track carries a BCP-47 language and a display name.
+- Reselects (dub, MP4 twin, castable video, in-cast switch, forced `--audio-lang`) rank
+  with the searched title like the initial pick. Accented titles ("Léon") no longer
+  demote their own releases.
+- Lifecycle: no signal to a reused pid; detached servers and ffmpeg are reclaimed; the
+  remux prepare lock is published only once held; the previous cast session is kept
+  until a new cast really starts; headless Ctrl-C on a direct cast aborts instead of
+  re-casting through catt.
+- `--doctor` detects castbridge; series resume follows the next episode with autoplay
+  off; headless resolves the TV before any stream work; a zero receiver volume is
+  re-read before warning; short language codes ("Chi", "Por") count only in capitals;
+  untagged MP4/WebM releases are considered for an instant direct cast; never-started
+  addon tasks no longer trip breakers; poster downloads are capped; the P2P privacy
+  notice shows once per process.
+
+### Changed
+
+- **ADR 0037 Accepted:** interactivity is an explicit mode; menus and confirmations are
+  injected by the frontend, and the domain never opens fzf. One failure table
+  (`failures.describe`) for the TUI and `--json`; domain notices reach `--json` as
+  `notices` with stable codes (`remux_infeasible`, `subs_unverified`, `volume_zero`, …).
+- Performance: cold search 25.6 s → 0.1–1.6 s (bounded half-open probes, search quorum,
+  stale-while-revalidate manifests); bounded ffprobe; subtitles are fetched while the
+  Tier-2 remux runs.
+- Configurable custom receiver app id (ADR 0013).
+- The bench-only sparse alignment moved to `_subalign_remote` (not shipped); debrid
+  provider keys live in the `providers` leaf; the bottom import tier is test-enforced.
+
+### Proposed
+
+- ADR 0039 (Tier-2 as live HLS-TS; receiver gate 3 passed: 62 min, 0 stalls) and
+  ADR 0040 (subtitles off the cast start path).
+
+## [1.38.0] — 2026-09-25
+
+### Added
+
+- Shared local playback service, explicit media-start evidence, and actionable player
+  errors. Movies no longer activate the next-episode overlay or quit half a second
+  before EOF.
+- `--doctor` / `--json --doctor`: read-only local diagnostics. Optional binaries are
+  reported apart from required ones.
+- Reproducible verification: `scripts/check.sh` (Ruff, ty, pytest, wheel contents,
+  disposable install) on Python 3.13 and 3.14, architecture contracts, subprocess
+  playback acceptance, benchmarks, and an mpv smoke that does not touch the desktop
+  or the TV.
+- **ADR 0034 Accepted:** bounded addon gathering, deadline-aware retries, bounded JSON
+  decoding, validated stream fields, collector-owned breaker updates, serialized
+  best-effort state writes, atomic runtime snapshots, and a private recovery copy
+  before a malformed JSON file is replaced. Existing state files stay compatible.
+
+### Changed
+
+- **ADR 0035 Accepted:** a soft `audio_langs` preference no longer forces a full-file
+  remux when a verified direct cast (MP4/WebM, decodable first track) exists at the
+  same quality. Headless starts that direct cast, keeps primary-language safety
+  subtitles, and explains the choice in `notice`. A TUI asks once. `--audio-lang`
+  still waits for the preferred dub. Remux progress is printed even when stderr is
+  not a terminal.
+- Playback no longer changes the host firewall. Capability URLs are redacted in logs
+  and machine-readable output.
+- The development-only subtitle benchmark is excluded from the wheel with `exclude`,
+  not `force-exclude`.
+
+## [1.37.1] — 2026-08-10
+
+### Fixed
+
+- **ADR 0033 Accepted:** a title with nothing playable no longer returns to the menu in
+  silence. `stream_select.prepare_stream` reserves `None` for the user backing out (ESC) and
+  raises `NoPlayableStream(reason)` on exhaustion; the reason reaches the fzf header (TUI) and
+  the `no_playable_stream` message (headless). Typical case: every source is a pure torrent and
+  the P2P privacy gate (ADR 0032) is closed, or the debrid left no direct link.
+
+### Added
+
+- `--explain`: `SORGENTI: n/m con link diretto · k torrent` line, plus `counts.direct_links`,
+  `counts.torrents` and `unresolvable_reason` in the JSON output — the same diagnosis before
+  attempting playback.
+- `engine.p2p_block_reason`: the privacy gate's predicate without its side effects, so
+  explainers can state the refusal without triggering it.
+
+## [1.37.0] — 2026-08-09
+
+### Added
+
+- **ADR 0027 Accepted:** per-addon circuit breaker (`state/breaker.py`) on gather paths;
+  Open sources skipped without network; `--forget-breakers`; listed in `--explain`.
+- TUI cast session menu: pause / resume / relative seek / refresh / volume / stop; cast row
+  also on Film/Serie sections (`cast_control`).
+- Settings: cast/P2P/subs knobs, hybrid `playback_backend: auto`, `default_quality`,
+  diagnostics for required bins (`mpv`, `fzf`) and optional cast/P2P deps.
+- Config load tightens world-readable `config.json` to 0600 (debrid token hygiene).
+- Multi-addon gather progress on TTY (completion order, not submit order).
+
+### Fixed
+
+- Alt-C reuses full cast decision tree (`run_cast`); quality miss surfaces available res;
+  `default_quality` on headless + TUI paths.
+- Headless-only flags without `--json` are usage errors (no silent TUI no-op).
+
+### Documentation
+
+- Full documentation restructure: audience hub (`docs/README.md`), user guides
+  (`docs/user/`), official headless contract (`docs/headless.md`), config reference tables,
+  cast/TUI/troubleshooting pages, CONTRIBUTING, roadmap/non-goals, CHANGELOG.
+- Aligned `config.example.json` with `Config` defaults (`playback_backend: local`, all keys
+  including `cast_mirror_over_remux_gb` / `sub_align*`).
+- ADR 0026/0027 normalized to English MADR template; 0027 status **Accepted**.
+- Config/example drift test (`tests/test_config_docs.py`).
+
+## [1.36.1] — 2026-08-08
+
+- P2P privacy gate enforced on every swarm-join path (ADR 0032).
+
+## [1.36.0] and earlier — summary of major features
+
+Historical releases were not logged in this file. Major capabilities present by 1.36.x:
+
+- Terminal-first Stremio-like client (Cinemeta, fzf, mpv), zero runtime Python deps.
+- Multi-source streams (Torrentio + user manifests; ADR 0024).
+- Playback backends: local TorrServer P2P, debrid, auto hybrid, native TorBox/Premiumize.
+- Hardware-aware ranking, cast-aware ranking, dead-source denylist, duration vetting.
+- Cast stack: castbridge + catt fallback, Tier-2 remux, realtime mirror, discovery cache.
+- Headless `--json` API for agents/scripts; series binge overlay; resume / continue-watching.
+- Native subtitle alignment (ADR 0020); structured stream metadata precedence (ADR 0026).
+
+See [docs/adr/](docs/adr/README.md) for the decision timeline.

nstream-1.43.0/CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+Guidance for agents working in this repository.
+
+## Project
+
+nstream is a native, terminal-first Stremio alternative: no Electron, no embedded browser,
+no Node server. Pure Python 3.13+ stdlib (zero runtime dependencies) orchestrating external
+CLIs (`fzf`, `mpv`, `ffprobe`, `catt`, `chafa`, optional TorrServer / castbridge) over Stremio
+addon HTTP APIs. Entry point is `nstream.cli:_entry` (`src/nstream/cli.py`).
+
+Pipeline: search/browse (Cinemeta + catalogs) → pick title/episode (fzf or `--json`) → optional
+subtitles (OpenSubtitles v3 + alignment) → fetch streams (Torrentio and/or `cfg.addons`) →
+hardware- or cast-aware rank/filter → play (mpv) or cast (castbridge/catt/remux/mirror) →
+track progress (resume / continue-watching).
+
+## Commands
+
+Tooling is `uv`-based (no venv activation needed).
+
+| Task | Command |
+| ---- | ------- |
+| Run tests | `uv run python -m pytest` |
+| Single test | `uv run python -m pytest tests/test_labels.py::test_display_title_movie` |
+| Lint | `uvx ruff check . && uvx ruff format --check .` |
+| Type check | `uvx ty check` |
+| Dev run | `uv run nstream "the matrix"` |
+| Install (dev) | `./install.sh` (uses `uv tool install`) |
+
+Use `python -m pytest` (not bare `uv run pytest`): if a system-wide `nstream` is installed,
+bare `pytest` resolves to the system interpreter and imports the **installed** package instead
+of `src/`. `python -m` runs the project venv with the editable `src/` checkout.
+
+Ruff: line-length 100, rules `E,F,I,UP,B,SIM`. Pytest: `testpaths=["tests"]`, `-q`.
+Each `src/nstream/<mod>.py` has a matching `tests/test_<mod>.py` (or package coverage).
+
+## Documentation map (do not re-duplicate)
+
+| Topic | Source of truth |
+| ----- | --------------- |
+| Module map / domains | [`docs/architecture.md`](docs/architecture.md) |
+| Stream ranking / cast vet | [`docs/selection.md`](docs/selection.md) |
+| Headless `--json` contract | [`docs/headless.md`](docs/headless.md) |
+| Config keys | [`docs/user/config.md`](docs/user/config.md) |
+| Decisions (why) | [`docs/adr/`](docs/adr/README.md) |
+| Hub / audience routing | [`docs/README.md`](docs/README.md) |
+| Agent playbook (intent→cmd) | [`skills/nstream/SKILL.md`](skills/nstream/SKILL.md) |
+| Contributor process | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
+
+Update architecture when adding/moving modules — **not** the README module list (there is none).
+
+### Import-graph discipline (non-negotiable)
+
+- Top: `util` / `ui` / `languages` / `types` / `sources` / `net` / `log` (see architecture)
+- `cli` orchestrates at the bottom
+- Everything below `cli` **never** imports `cli` (including `headless`, `cast_flow`,
+  `stream_select`, `cast_vet`, `player`, `caster`, …)
+- Cast policy lives in `cast_vet`; cast decision tree in `cast_flow`; backends in
+  `caster` / `remux` / `mirror`; TUI cast lifecycle in `cast_control`. Selection facade:
+  `stream_select.prepare_stream`. Availability probes/denylist: `availability`. Domain
+  TypedDicts: `types` (not `config`). Headless play body: `headless_play`; argparse:
+  `cli_args`. State package: `state/` (history, cast_session, dead, breaker)
+
+### Hard constraints when editing
+
+- **Debrid provider-agnostic:** never special-case RealDebrid; tokens/markers/redaction are generic
+- **Never log stream URLs or debrid tokens in clear** — use `what=` labels; `log.RedactFormatter`
+- **Cast audio language** is decided at selection (`cast_vet.vet_cast_audio`), not on the DMR
+- **Dead sources (ADR 0025):** only `gone` probes are persisted; incomplete reads are not proof
+- **P2P privacy gate (ADR 0032):** at every swarm join, not one call site
+- **Disk I/O best-effort** try/except — never block playback
+- fzf sentinels are module-level `object()` values (`_PLAY`, `_ALL`, …) so `None` means ESC
+- Comments/docs in English; concise, no over-engineering
+- **`ui.Caps`** = terminal caps; **`quality.HwCaps`** = GPU/vainfo — different types
+- New architectural trade-off → ADR ([template](docs/adr/0000-template.md)); cite symbols not lines
+
+### Stream sources (ADR 0024)
+
+Torrentio (`torrentio_enabled`) + `cfg.addons` manifests. `api.streams` stamps `addon`, fuses
+debrid url with torrent infoHash by filename, collapses duplicates (cached > url > infoHash).
+
+### Secrets & paths
+
+- Config: `$XDG_CONFIG_HOME/nstream/config.json` (chmod 600; template `config.example.json`)
+- History: `$XDG_STATE_HOME/nstream/history.json`
+- Library: `$XDG_STATE_HOME/nstream/library.json` (recent + watchlist metadata only)
+- Dead sources: `$XDG_STATE_HOME/nstream/dead-sources.json` (`--forget-dead`)
+- Addon breakers: `$XDG_STATE_HOME/nstream/addon-breakers.json` (`--forget-breakers`, ADR 0027)
+- Caches: `$XDG_CACHE_HOME/nstream/` (`manifests.json`, `hwcaps.json`, `devices.json`, `meta/`, `posters/`, `torrents/`)
+- Log: `$XDG_STATE_HOME/nstream/nstream.log` (rotating); `--debug` / `NSTREAM_DEBUG=1` → stderr DEBUG
+- Runtime deps: `mpv`, `fzf` (required); `ffmpeg`/`ffprobe`, `catt`, TorrServer, `vainfo`, `chafa`, `foot`, castbridge/mirror (optional)
+
+## Packaging hygiene
+
+`packaging/` tracked files: `PKGBUILD`, `build-local.sh`, `nstream.install`, `.SRCINFO` only.
+Build artifacts (`pkg/`, `src/`, `*.pkg.tar.zst`, `*.sig`) are gitignored; `build-local.sh`
+cleans them. Do not commit wheels or makepkg trees.

nstream-1.43.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to nstream
+
+## Setup
+
+```sh
+./install.sh                          # uv tool install + optional config bootstrap
+uv run python -m pytest               # tests (always python -m — see below)
+uvx ruff check . && uvx ruff format --check .
+uvx ty check
+uv run nstream "the matrix"           # run from source
+```
+
+Tooling is **uv**-based. Runtime stays **stdlib-only**; `ruff` / `ty` / `pytest` are
+dev-group tools.
+
+### Why `python -m pytest`
+
+If a system-wide `nstream` is installed, bare `pytest` can resolve to the system interpreter
+and import the **installed** package instead of `src/`. `uv run python -m pytest` uses the
+project venv with the editable checkout.
+
+## Project rules
+
+Read [CLAUDE.md](CLAUDE.md) for agent-oriented hard constraints. Summary for humans:
+
+- **Import graph:** `cli` at the bottom — nothing imports `cli`. Leaves: `util`, `ui`,
+  `languages`, `types`, `sources`, `net`, `log` (and related pure helpers). See
+  [docs/architecture.md](docs/architecture.md).
+- **Debrid provider-agnostic:** no RealDebrid special-cases; tokens/markers/redaction are
+  generic.
+- **Never log stream URLs or debrid tokens** — use `what=` labels; `log.RedactFormatter`.
+- **Disk I/O best-effort** — never block playback on state writes.
+- **Dead sources (ADR 0025):** only `gone` probes are persisted.
+- **Cast audio language** decided in `cast_vet.vet_cast_audio`, not on the DMR.
+- Comments and technical docs: **English**. TUI strings may stay Italian.
+- Concise code; no over-engineering.
+
+## Adding or moving a module
+
+1. Place it where the **policy** lives (not the first caller).
+2. Preserve import discipline.
+3. Add `tests/test_<mod>.py` (or package tests under `tests/`).
+4. Update **[docs/architecture.md](docs/architecture.md)** only (not README module tables).
+5. Architectural trade-off → new ADR (below).
+
+## Tests
+
+The complete gate is `bash scripts/check.sh` (also run in CI on Python 3.13/3.14).
+See [verification and recovery](docs/verification.md) for package, benchmark, and real
+mpv checks and the separate audiovisual receiver acceptance procedure.
+
+| Kind | Location | Notes |
+| ---- | -------- | ----- |
+| Unit | `tests/test_*.py` | Prefer unit before integration |
+| Fixtures | `tests/data/`, `tests/conftest.py` | Offline stream/meta samples |
+| Config/doc drift | `tests/test_config_docs.py` | `Config` ↔ `config.example.json` |
+
+Mock network at `net` / `api` boundaries; do not hit live debrid in unit tests. Cast and
+TorrServer paths should use fakes or skip when binaries are absent.
+
+Ruff: line-length 100, rules `E,F,I,UP,B,SIM`. Pytest: `testpaths=["tests"]`, quiet by default.
+
+## Architecture Decision Records
+
+Format: MADR-light — see [docs/adr/0000-template.md](docs/adr/0000-template.md).
+
+1. Copy the template → next number `NNNN-short-title.md`.
+2. Status starts as **Proposed**; mark **Accepted** when landed in code.
+3. **Append-only:** do not rewrite an Accepted ADR’s decision. Supersede with a new ADR and
+   set the old one to `Superseded by NNNN`.
+4. Add a row to [docs/adr/README.md](docs/adr/README.md).
+5. Cite **symbols** (`stream_select.prepare_stream`), not fragile line numbers.
+6. No personal vault wikilinks (`[[…]]`) — they do not resolve in the public repo.
+7. Empirical data may live in `docs/adr/NNNN-phase*/` (see ADR 0020).
+
+When to write an ADR: a constraint future code must respect, a rejected alternative that
+would otherwise be re-proposed, or a cross-module policy (cast finish predicate, privacy
+gate, denylist rules, …).
+
+## Packaging
+
+Tracked under `packaging/`: `PKGBUILD`, `build-local.sh`, `nstream.install`, `.SRCINFO` only.
+Do not commit build trees, wheels, or `*.pkg.tar.zst`. Keep `pkgver` in sync with
+`src/nstream/__init__.py`. See [docs/roadmap.md](docs/roadmap.md) release process.
+
+## Maintainer scripts
+
+| Script | Role |
+| ------ | ---- |
+| `scripts/refresh-stream-addons.py` | Rebuild RD-backed stream addon URLs in the local config from `torrentio_base` (never prints the token). Not part of the runtime package. |
+
+## Documentation map
+
+[docs/README.md](docs/README.md) — audience routing and single sources of truth. Do not
+duplicate module maps or full ranking tables in the root README.

nstream-1.43.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gianluca Mazza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.