unidl 2.0.0__tar.gz

unidl-2.0.0/MANIFEST.in

@@ -0,0 +1,16 @@
+# Public source archives include the user-facing documentation and install
+# requirement lists, but never local runtime state or private media devices.
+include README.md pyproject.toml requirements.txt requirements-dev.txt
+recursive-include docs *.md *.yaml
+recursive-exclude cdm *
+recursive-exclude helpers *
+recursive-exclude db *
+recursive-exclude cookies *
+recursive-exclude tokens *
+recursive-exclude downloads *
+recursive-exclude download_commands *
+recursive-exclude exports *
+recursive-exclude logs *
+recursive-exclude cache *
+global-exclude *.wvd *.prd *.mld *.sqlite *.sqlite3 *.db-shm *.db-wal *.db-journal
+global-exclude *.pem

unidl-2.0.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: unidl
+Version: 2.0.0
+Summary: Integrated TUI for browsing streaming services and downloading selected media.
+Author: unidl contributors
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: textual>=0.80
+Requires-Dist: pywidevine>=1.8
+Requires-Dist: pyplayready>=0.8.5
+Requires-Dist: wasmtime>=20
+Requires-Dist: requests[socks]>=2.31
+Requires-Dist: qrcode[pil]>=7.4
+Requires-Dist: textual-image[textual]>=0.13.2; python_version >= "3.12"
+Requires-Dist: httpx[http2]>=0.27
+Requires-Dist: cryptography>=42
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: geonamescache>=2.0
+Requires-Dist: pycryptodome>=3.20
+Requires-Dist: python-bidi>=0.6
+Requires-Dist: arabic-reshaper>=3.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: setuptools>=68; extra == "dev"
+Requires-Dist: wheel>=0.43; extra == "dev"
+
+# UniDL
+
+UniDL is a terminal-first media browser and native downloader. It connects
+streaming services to one consistent workflow: find a title or channel, sign in
+when needed, inspect the available media, choose the tracks you want, resolve
+DRM keys through the service contract, and download or record the result.
+
+The project is designed around three clear layers:
+
+- **Services** handle login, catalogues, search, manifests, service settings and
+  service-owned licence requests.
+- **Core/TUI** handles navigation, settings, credentials, CDM/vault selection,
+  track selection, progress, logs and the interactive workflow.
+- **Native downloader** parses manifests, downloads segments, decrypts media,
+  writes subtitles and chapters, and muxes the final output in-process.
+
+## Features
+
+### Interactive TUI
+
+- Keyboard and mouse navigation with predictable Back, Cancel and Quit behavior.
+- Service home screens with URL, search, live, library and login entry points.
+- Search results that continue through seasons and episodes without leaving the
+  service flow.
+- JustWatch title and availability search with configurable regions and provider
+  mapping.
+- Responsive log and progress panels, selectable text, copy actions, light and
+  dark themes, and localized interface strings.
+- Explicit development reload for service packages without silently watching
+  files in the background.
+
+### VOD
+
+- DASH/MPD, HLS, ISM/Smooth Streaming, JSON manifests and direct media URLs.
+- Multiple video, audio and subtitle tracks with independent output selection.
+- Resolution, codec, dynamic-range, language, channel-layout and subtitle
+  controls, including HDR/Dolby Vision and audio codec labels where available.
+- Multi-manifest playback plans for services that expose separate ladders.
+- Optional chapter retrieval and chapter embedding into the final container.
+- Safe output naming with title, season/episode, resolution, audio and codec
+  tags based on the tracks the user actually downloads.
+- Resumable segment downloads, cache-aware retries, post-processing and muxing.
+
+### Live recording
+
+- Live HLS, DASH/fMP4 and other refreshable playlists.
+- Track selection before recording, replay/DVR window inspection, recording
+  from the live edge or a chosen offset, and finite or unlimited duration.
+- `00:00:00` means no duration limit; Stop, Back or Esc ends an active recording.
+- Real-time merge and pipe-mux modes where the source and container support them.
+- Rotating live keys with service-provided init data and an interactive fallback
+  for a genuinely new KID.
+- Progress, replay-window information, segment counts, estimated size and
+  cancellation state in the TUI.
+
+### DRM, vaults and credentials
+
+- Local Widevine, PlayReady and MonaLisa device contracts with strict system
+  matching.
+- Optional remote CDM endpoints for systems that support remote challenge and
+  licence parsing.
+- Local SQLite key vaults and compatible remote key vaults, with multi-vault
+  read/write policies, service scoping and manual KID:key entry.
+- Service-local licence transport: the shared DRM layer creates challenges and
+  parses responses, while each service owns its endpoint, headers and request
+  format.
+- Independent credential slots, cookie profiles, token stores and refresh
+  lifecycles per service and login method.
+
+### Audio and metadata
+
+- Audio-only services and audio tracks use a dedicated presentation and naming
+  path.
+- MP3 export with ID3v2 metadata, cover art, artist/album/title fields and
+  chapter-aware post-processing.
+- Clear audio formats remain available when the source already matches the
+  requested container; other sources are converted through FFmpeg.
+
+### Helpers, proxy and storage
+
+- Declared service helpers resolved from configuration, `PATH`, project helper
+  folders or package resources; no arbitrary filesystem scan.
+- HTTP/HTTPS and SOCKS proxy support plus provider-specific VPN integrations
+  when configured by the user.
+- Project-relative paths for tokens, cookies, CDMs, vaults, caches, commands,
+  subtitles and finished media.
+- JSON command/export artifacts for automation and reproducible downloads.
+
+## Install
+
+The minimum supported runtime is **Python 3.11** on Windows, macOS or Linux.
+Use a 64-bit Python build and install FFmpeg (including `ffprobe`) for the full
+download, conversion and muxing workflow. The Python dependency list is kept in
+[`requirements.txt`](requirements.txt); development checks are in
+[`requirements-dev.txt`](requirements-dev.txt).
+
+From a published PyPI release:
+
+```console
+python3 -m venv .venv
+source .venv/bin/activate             # Windows: .venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip install unidl
+```
+
+The project is also installable directly from a source checkout:
+
+```console
+python3 -m venv .venv
+source .venv/bin/activate             # Windows: .venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip install .
+```
+
+For development and tests:
+
+```console
+python -m pip install -e '.[dev]'
+```
+
+The project also works with `uv`:
+
+```console
+uv sync --extra dev
+```
+
+`pip install unidl` is the shortest installation after a release has been
+published to PyPI. Until then, use the source-checkout command above.
+
+Place local CDM files under the configured `paths.cdm` tree and keep their
+private material outside version control. Helpers, cookies, tokens and vault
+databases are runtime data and should be stored in the configured project
+directories.
+
+See [Requirements and installation](docs/requirements.md) for external tools,
+platform notes and a complete preflight checklist.
+
+## Use UniDL
+
+Launch the installed TUI:
+
+```console
+unidl
+```
+
+`python -m unidl` is equivalent. A packaged install uses `unidl.yaml` from the
+current directory when it exists; otherwise it starts with the safe built-in
+path defaults. Pass an explicit configuration whenever the file lives elsewhere:
+
+```console
+unidl --config ./unidl.yaml
+```
+
+Useful read-only diagnostics:
+
+```console
+unidl --config ./unidl.yaml --help
+unidl --config ./unidl.yaml services
+unidl --config ./unidl.yaml cdm --check
+unidl --config ./unidl.yaml keys <kid> --service <service-id>
+```
+
+The native downloader can also consume an exported JSON manifest or a direct
+source URL:
+
+```console
+unidl list <manifest-or-json>
+unidl download <manifest-or-url> --save-name "Example.Title"
+```
+
+In the TUI, choose a service, search or open a URL, select the title and tracks,
+then choose whether to download now or save a command/export. A service's own
+settings control provider API/profile choices; the shared track settings control
+the final output tracks only. See [docs/settings.md](docs/settings.md).
+
+For live channels, choose the tracks first, then choose recording, replay/DVR
+behavior and duration. Leave the duration at `00:00:00` for an unlimited
+recording and use Stop/Back/Esc to finish it.
+
+## Configuration and data
+
+`unidl.yaml` is the static configuration surface. Relative paths are resolved
+from the directory containing that file, so a checkout can be moved safely.
+Interactive preferences are stored in `settings.json` under `paths.home`.
+Credentials, cookies, tokens, CDMs, vaults, logs, command files and exports are
+never required to be committed. Use a private override file for secrets:
+
+```console
+python -m unidl --config ./unidl.private.yaml
+```
+
+The application uses the explicitly selected configuration or the project-root
+configuration when launched from a source checkout.
+
+## Project layout
+
+```text
+src/unidl/core/        contracts, DRM, vaults, storage and flow engine
+src/unidl/tui/         Textual interface and screens
+src/unidl/downloader/  native parsers, transfer, decrypt and mux pipeline
+src/unidl/services/    one package per service
+helpers/               declared helper assets and modules
+cdm/                   local device files, kept private
+docs/                  architecture, service and downloader documentation
+tests/                 offline contract and integration tests
+```
+
+## Documentation
+
+Start with [docs/README.md](docs/README.md). The most useful paths are:
+
+- [Architecture](docs/architecture.md) — boundaries and data flow.
+- [Requirements and installation](docs/requirements.md) — supported runtimes,
+  package installation and external tools.
+- [Publishing](docs/publishing.md) — PyPI releases, token handling and GitHub
+  account switching.
+- [Writing a service](docs/writing-a-service.md) — add a service and integrate
+  native Core capabilities.
+- [Native downloader](docs/downloader-integration.md) — supported inputs,
+  delivery contracts and progress.
+- [Configuration](docs/configuration.md) and [Settings](docs/settings.md) —
+  static configuration versus interactive preferences.
+- [DRM](docs/drm.md) and [Key vault](docs/key-vault.md) — local/remote key
+  resolution and service-owned licensing.
+- [Live channels](docs/live.md), [Audio](docs/audio.md) and
+  [Chapters](docs/chapters.md) — specialized playback paths.
+- [Testing](docs/testing.md), [Troubleshooting](docs/troubleshooting.md) and
+  [Security](docs/SECURITY.md) — verification and safe operation.
+
+## Development checks
+
+```console
+python -m pytest -q
+python -m ruff check src tests
+python -m compileall -q src
+```
+
+When changing a service, run its offline checks and a real playback check with
+authorized account, region and device data. Never include credentials, cookies,
+tokens, CDM private material, vault keys or signed URLs in commits or bug
+reports.
+
+Copyright © 2026 Chris20

unidl-2.0.0/README.md

@@ -0,0 +1,243 @@
+# UniDL
+
+UniDL is a terminal-first media browser and native downloader. It connects
+streaming services to one consistent workflow: find a title or channel, sign in
+when needed, inspect the available media, choose the tracks you want, resolve
+DRM keys through the service contract, and download or record the result.
+
+The project is designed around three clear layers:
+
+- **Services** handle login, catalogues, search, manifests, service settings and
+  service-owned licence requests.
+- **Core/TUI** handles navigation, settings, credentials, CDM/vault selection,
+  track selection, progress, logs and the interactive workflow.
+- **Native downloader** parses manifests, downloads segments, decrypts media,
+  writes subtitles and chapters, and muxes the final output in-process.
+
+## Features
+
+### Interactive TUI
+
+- Keyboard and mouse navigation with predictable Back, Cancel and Quit behavior.
+- Service home screens with URL, search, live, library and login entry points.
+- Search results that continue through seasons and episodes without leaving the
+  service flow.
+- JustWatch title and availability search with configurable regions and provider
+  mapping.
+- Responsive log and progress panels, selectable text, copy actions, light and
+  dark themes, and localized interface strings.
+- Explicit development reload for service packages without silently watching
+  files in the background.
+
+### VOD
+
+- DASH/MPD, HLS, ISM/Smooth Streaming, JSON manifests and direct media URLs.
+- Multiple video, audio and subtitle tracks with independent output selection.
+- Resolution, codec, dynamic-range, language, channel-layout and subtitle
+  controls, including HDR/Dolby Vision and audio codec labels where available.
+- Multi-manifest playback plans for services that expose separate ladders.
+- Optional chapter retrieval and chapter embedding into the final container.
+- Safe output naming with title, season/episode, resolution, audio and codec
+  tags based on the tracks the user actually downloads.
+- Resumable segment downloads, cache-aware retries, post-processing and muxing.
+
+### Live recording
+
+- Live HLS, DASH/fMP4 and other refreshable playlists.
+- Track selection before recording, replay/DVR window inspection, recording
+  from the live edge or a chosen offset, and finite or unlimited duration.
+- `00:00:00` means no duration limit; Stop, Back or Esc ends an active recording.
+- Real-time merge and pipe-mux modes where the source and container support them.
+- Rotating live keys with service-provided init data and an interactive fallback
+  for a genuinely new KID.
+- Progress, replay-window information, segment counts, estimated size and
+  cancellation state in the TUI.
+
+### DRM, vaults and credentials
+
+- Local Widevine, PlayReady and MonaLisa device contracts with strict system
+  matching.
+- Optional remote CDM endpoints for systems that support remote challenge and
+  licence parsing.
+- Local SQLite key vaults and compatible remote key vaults, with multi-vault
+  read/write policies, service scoping and manual KID:key entry.
+- Service-local licence transport: the shared DRM layer creates challenges and
+  parses responses, while each service owns its endpoint, headers and request
+  format.
+- Independent credential slots, cookie profiles, token stores and refresh
+  lifecycles per service and login method.
+
+### Audio and metadata
+
+- Audio-only services and audio tracks use a dedicated presentation and naming
+  path.
+- MP3 export with ID3v2 metadata, cover art, artist/album/title fields and
+  chapter-aware post-processing.
+- Clear audio formats remain available when the source already matches the
+  requested container; other sources are converted through FFmpeg.
+
+### Helpers, proxy and storage
+
+- Declared service helpers resolved from configuration, `PATH`, project helper
+  folders or package resources; no arbitrary filesystem scan.
+- HTTP/HTTPS and SOCKS proxy support plus provider-specific VPN integrations
+  when configured by the user.
+- Project-relative paths for tokens, cookies, CDMs, vaults, caches, commands,
+  subtitles and finished media.
+- JSON command/export artifacts for automation and reproducible downloads.
+
+## Install
+
+The minimum supported runtime is **Python 3.11** on Windows, macOS or Linux.
+Use a 64-bit Python build and install FFmpeg (including `ffprobe`) for the full
+download, conversion and muxing workflow. The Python dependency list is kept in
+[`requirements.txt`](requirements.txt); development checks are in
+[`requirements-dev.txt`](requirements-dev.txt).
+
+From a published PyPI release:
+
+```console
+python3 -m venv .venv
+source .venv/bin/activate             # Windows: .venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip install unidl
+```
+
+The project is also installable directly from a source checkout:
+
+```console
+python3 -m venv .venv
+source .venv/bin/activate             # Windows: .venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip install .
+```
+
+For development and tests:
+
+```console
+python -m pip install -e '.[dev]'
+```
+
+The project also works with `uv`:
+
+```console
+uv sync --extra dev
+```
+
+`pip install unidl` is the shortest installation after a release has been
+published to PyPI. Until then, use the source-checkout command above.
+
+Place local CDM files under the configured `paths.cdm` tree and keep their
+private material outside version control. Helpers, cookies, tokens and vault
+databases are runtime data and should be stored in the configured project
+directories.
+
+See [Requirements and installation](docs/requirements.md) for external tools,
+platform notes and a complete preflight checklist.
+
+## Use UniDL
+
+Launch the installed TUI:
+
+```console
+unidl
+```
+
+`python -m unidl` is equivalent. A packaged install uses `unidl.yaml` from the
+current directory when it exists; otherwise it starts with the safe built-in
+path defaults. Pass an explicit configuration whenever the file lives elsewhere:
+
+```console
+unidl --config ./unidl.yaml
+```
+
+Useful read-only diagnostics:
+
+```console
+unidl --config ./unidl.yaml --help
+unidl --config ./unidl.yaml services
+unidl --config ./unidl.yaml cdm --check
+unidl --config ./unidl.yaml keys <kid> --service <service-id>
+```
+
+The native downloader can also consume an exported JSON manifest or a direct
+source URL:
+
+```console
+unidl list <manifest-or-json>
+unidl download <manifest-or-url> --save-name "Example.Title"
+```
+
+In the TUI, choose a service, search or open a URL, select the title and tracks,
+then choose whether to download now or save a command/export. A service's own
+settings control provider API/profile choices; the shared track settings control
+the final output tracks only. See [docs/settings.md](docs/settings.md).
+
+For live channels, choose the tracks first, then choose recording, replay/DVR
+behavior and duration. Leave the duration at `00:00:00` for an unlimited
+recording and use Stop/Back/Esc to finish it.
+
+## Configuration and data
+
+`unidl.yaml` is the static configuration surface. Relative paths are resolved
+from the directory containing that file, so a checkout can be moved safely.
+Interactive preferences are stored in `settings.json` under `paths.home`.
+Credentials, cookies, tokens, CDMs, vaults, logs, command files and exports are
+never required to be committed. Use a private override file for secrets:
+
+```console
+python -m unidl --config ./unidl.private.yaml
+```
+
+The application uses the explicitly selected configuration or the project-root
+configuration when launched from a source checkout.
+
+## Project layout
+
+```text
+src/unidl/core/        contracts, DRM, vaults, storage and flow engine
+src/unidl/tui/         Textual interface and screens
+src/unidl/downloader/  native parsers, transfer, decrypt and mux pipeline
+src/unidl/services/    one package per service
+helpers/               declared helper assets and modules
+cdm/                   local device files, kept private
+docs/                  architecture, service and downloader documentation
+tests/                 offline contract and integration tests
+```
+
+## Documentation
+
+Start with [docs/README.md](docs/README.md). The most useful paths are:
+
+- [Architecture](docs/architecture.md) — boundaries and data flow.
+- [Requirements and installation](docs/requirements.md) — supported runtimes,
+  package installation and external tools.
+- [Publishing](docs/publishing.md) — PyPI releases, token handling and GitHub
+  account switching.
+- [Writing a service](docs/writing-a-service.md) — add a service and integrate
+  native Core capabilities.
+- [Native downloader](docs/downloader-integration.md) — supported inputs,
+  delivery contracts and progress.
+- [Configuration](docs/configuration.md) and [Settings](docs/settings.md) —
+  static configuration versus interactive preferences.
+- [DRM](docs/drm.md) and [Key vault](docs/key-vault.md) — local/remote key
+  resolution and service-owned licensing.
+- [Live channels](docs/live.md), [Audio](docs/audio.md) and
+  [Chapters](docs/chapters.md) — specialized playback paths.
+- [Testing](docs/testing.md), [Troubleshooting](docs/troubleshooting.md) and
+  [Security](docs/SECURITY.md) — verification and safe operation.
+
+## Development checks
+
+```console
+python -m pytest -q
+python -m ruff check src tests
+python -m compileall -q src
+```
+
+When changing a service, run its offline checks and a real playback check with
+authorized account, region and device data. Never include credentials, cookies,
+tokens, CDM private material, vault keys or signed URLs in commits or bug
+reports.
+
+Copyright © 2026 Chris20

unidl-2.0.0/docs/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing to unidl
+
+UniDL services are the account, catalogue and key-acquisition layer; the native
+delivery core is part of the same application. Keep that boundary intact:
+services may log in, discover playback and acquire keys; the native core owns
+manifest parsing, track selection, download, decrypt, subtitles and muxing.
+
+## Before changing code
+
+1. Create a virtual environment and install UniDL plus the development extras
+   as described in [docs/testing.md](testing.md).
+2. Read [docs/architecture.md](architecture.md) and, for service work,
+   [docs/writing-a-service.md](writing-a-service.md).
+3. Keep credentials, cookies, tokens, device files, content keys, command
+   exports and debug logs out of version control. The visible project-local
+   runtime layout is supported, but its paths must remain ignored.
+
+## Project rules
+
+- Service code never imports Textual, calls `print()` or calls `input()`. It
+  yields Flow asks and returns a `Playback`.
+- Put HTTP clients and response parsing in the service's `api.py`; keep the flow
+  in `__init__.py`.
+- Add each provider as one native package under `src/unidl/services/` and
+  register it in `src/unidl/services/__init__.py`; follow
+  [writing-a-service.md](writing-a-service.md).
+- Do not duplicate manifest parsing, selection or download logic from the native delivery core.
+- Do not hardcode credentials, local absolute paths or helper locations.
+- Declare settings, credentials, helpers and `DRM_SYSTEMS`; do not make the UI
+  infer them from service internals.
+- Shared Track output selection controls only what the native delivery core downloads and muxes.
+  Never reuse its quality/codec/range/audio/subtitle settings as licence-track
+  policy; configurable licence tracks/profiles/PSSH seeds require a separate
+  setting in that service's own section. The app-wide post-selection licence
+  compatibility mode is implemented by Core and is not permission for service
+  code to read those shared settings.
+- Read and write session state only through `ctx.tokens`, which is rooted at this
+  service's own folder under `paths.tokens`. Name the file, never the directory:
+  path separators, absolute paths and `..` are rejected by `TokenStore`.
+- If a service's file is renamed, move it rather than copy it: leaving the old
+  name behind leaves a session that signing out does not remove and the next read
+  adopts again.
+- Keep narrative documentation free of fixed service totals. The porting record
+  may quote a measured snapshot; nothing else should.
+
+## Documentation with code changes
+
+Update the matching reference in the same change:
+
+- a config key: `docs/configuration.md` and `unidl.example.yaml`
+- a global or track setting: `docs/settings.md`
+- a Flow ask or service hook: `docs/writing-a-service.md` and the reference
+  service comments
+- a screen, binding or snapshot target: `docs/interface.md` and
+  `docs/ui-design.md`
+- DRM or vault behaviour: `docs/drm.md` or `docs/key-vault.md`
+- a new verification command or fixture: `docs/testing.md`
+
+Link new user-facing documents from `README.md` and use relative Markdown links
+inside the repository.
+
+## Verification
+
+Run `ruff` and `compileall`, then the smallest relevant offline checks. Run live
+checks only when you have the required account, region, device and authority;
+state exactly which commands ran and which were not run. Never paste live
+credentials, full content keys, CDM secrets or unredacted debug logs into a bug
+report or review.
+
+For a service port, exercise every declared entry point against the real
+service. Importing successfully is not proof that login, catalogue parsing,
+licensing or the current third-party schema works.
+
+## Reloading service code during development
+
+unidl does not watch source files. To adopt an edit without quitting, turn on
+global **Debug mode**, return to the bare Home screen, highlight one service (or
+filter to exactly one), and press `ctrl+r`. The action compiles the selected
+service's loaded source first, reloads its multi-file package in dependency
+order, and also reloads native service packages that share those modules. Core,
+TUI and unrelated service modules are outside the reload graph.
+
+The registry receives new classes, so only the **next** service session uses the
+new code. No active service instance, download, licence exchange, heartbeat or
+playback-session cleanup is patched. Reload is deliberately unavailable while a
+service or overlay is on the screen.
+
+This is a development convenience, not a transactional production hot patch.
+A syntax error is rejected before any module is touched and the old registry is
+restored after an import error, but Python cannot fully undo module globals that
+an already-started import changed. Restart unidl after a failed reload, or after
+adding/removing/renaming modules or symbols whose old names may remain in a
+module namespace. Changing a service id also requires a restart.
+
+## Change description
+
+Explain:
+
+- what user-visible behaviour changed;
+- which contract or bug motivated it;
+- the checks run and their environment (offline, loopback or live);
+- any account, region, helper, CDM or external-service limitation;
+- any migration or configuration step users must take.
+
+Use the software only with accounts and content you are authorised to access.

unidl-2.0.0/docs/README.md

@@ -0,0 +1,53 @@
+# UniDL documentation
+
+This directory documents the public UniDL contracts and the workflow for using
+and extending the project.
+
+## Start here
+
+- [Architecture](architecture.md) — Core, TUI, services and native delivery.
+- [Writing a service](writing-a-service.md) — package layout, registration,
+  Flow asks, playback, DRM, credentials and testing.
+- [Configuration](configuration.md) — YAML, paths, devices and runtime state.
+- [Settings](settings.md) — global, service and output-track preferences.
+- [Requirements and installation](requirements.md) — supported Python versions,
+  external tools, package installs and runtime data.
+- [Publishing](publishing.md) — PyPI tokens, trusted publishing and GitHub
+  account switching.
+- [Native downloader](downloader-integration.md) — manifest inputs and delivery
+  integration.
+- [Testing](testing.md) — offline checks, live checks and regression practice.
+
+## Playback and delivery
+
+- [DRM systems](drm.md) — local/remote CDMs, PlayReady PSSH handling and key
+  acquisition boundaries.
+- [Key vault](key-vault.md) — local and remote vaults, policies and manual keys.
+- [Live channels](live.md) — recording, DVR/replay, duration and rotation.
+- [Audio-only services](audio.md) — audio presentation, metadata and export.
+- [Chapters](chapters.md) — chapter retrieval and embedding.
+- [Downloader audio formats](downloader/mp3-audio-format.md) and
+  [JSON manifests](downloader/json-manifest-format.md).
+- [Live pipe mux](downloader/live-pipe-mux.md), [ISM](downloader/ism-smooth-streaming.md)
+  and [Audio Vivid](downloader/audio-vivid.md) for specialized delivery paths.
+
+## Interface and integration
+
+- [Interface](interface.md) and [UI design](ui-design.md) — navigation,
+  selection, logs, themes and accessibility.
+- [Internationalization](i18n.md) — adding interface locales.
+- [External helpers](external-helpers.md) — declaring and resolving helpers.
+- [Partner authorization](partner-authorization.md) — service-to-service login
+  handoffs.
+- [Playback lifecycle](playback-lifecycle.md) — session, heartbeat and cleanup
+  rules.
+- [Availability](availability.md) — JustWatch search and regional offers.
+- [Troubleshooting](troubleshooting.md) — common configuration and playback
+  issues.
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before
+opening a change. Keep credentials and device/private material outside commits,
+and update the matching documentation whenever a Core or service contract
+changes.