mvw-cli 0.1.0__tar.gz

mvw_cli-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local tooling
+.recall/

mvw_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Boettinger
+
+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.

mvw_cli-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: mvw-cli
+Version: 0.1.0
+Summary: Search and download German public-broadcasting media from MediathekViewWeb, with Plex-friendly season downloads.
+Author-email: Max Boettinger <perplexity@bttngr.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ard,cli,download,german,mediathek,mediathekviewweb,plex,television,zdf
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Natural Language :: German
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# mvw
+
+A command-line tool for searching and downloading content from
+[MediathekViewWeb](https://mediathekviewweb.de/) (MVW), the index of German
+public-broadcasting media libraries (ARD, ZDF, WDR, and more). Built for
+automation: the headline feature is reliable, Plex-friendly **season**
+downloads.
+
+## Install
+
+Requires Python ≥ 3.13. The distribution is published as **`mvw-cli`** (the
+PyPI name `mvw` was already taken); the installed command is `mvw`.
+
+Install as a standalone tool with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv tool install mvw-cli      # adds the `mvw` command to your PATH
+```
+
+Or run it once without installing:
+
+```bash
+uvx --from mvw-cli mvw search "#Tatort"
+```
+
+With pip:
+
+```bash
+pip install mvw-cli
+```
+
+> **Note:** HLS (`.m3u8`) downloads require [ffmpeg](https://ffmpeg.org/download.html)
+> on your `PATH`. It is an external (non-Python) dependency and is not installed
+> automatically.
+
+### From source
+
+```bash
+uv sync                      # create the dev environment
+uv run mvw --help            # run from the working tree
+```
+
+## Query grammar
+
+The query string follows the MediathekViewWeb syntax:
+
+| Prefix | Field searched | Example |
+|--------|---------------|---------|
+| `!` | channel | `!ARD` |
+| `#` | topic | `#Tatort` |
+| `+` | title | `+Schokolade` |
+| `*` | description | `*Berlin` |
+| (none) | topic and title | `feuer flamme` |
+| `>N` | duration > N minutes | `>80` |
+| `<N` | duration < N minutes | `<10` |
+
+Combination rules:
+
+- **Space between different selectors** → AND: `!WDR #Tatort` means channel=WDR
+  AND topic=Tatort.
+- **Same selector repeated** → OR: `!ARD !ZDF` means ARD or ZDF.
+- **Comma within a selector's value** → AND of words: `#Olympia,Tokio` matches
+  topic containing both "Olympia" and "Tokio".
+- **No negation operator.** Exclusion is done client-side with `--exclude`.
+
+> Note: the API is case-insensitive and flexible with umlauts
+> (`ö` ≈ `oe` ≈ `OE`).
+
+## Commands
+
+### `mvw search`
+
+Search MVW and display a Rich results table.
+
+```
+mvw search QUERY
+           [--channel C] [--topic T] [--title T] [--description D]
+           [--min-duration MIN] [--max-duration MAX]
+           [--sort timestamp|duration|channel] [--order asc|desc]
+           [--future] [--limit N] [--offset N] [--json]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--channel` | — | Filter by channel (structured flag, not query syntax) |
+| `--topic` | — | Filter by topic |
+| `--title` | — | Filter by title |
+| `--description` | — | Filter by description |
+| `--min-duration` | — | Minimum duration in minutes |
+| `--max-duration` | — | Maximum duration in minutes |
+| `--sort` | `timestamp` | Sort field |
+| `--order` | `desc` | Sort order (`asc` or `desc`) |
+| `--future` | off | Include not-yet-aired entries |
+| `--limit` | 15 | Number of results to fetch |
+| `--offset` | 0 | Pagination offset |
+| `--json` | off | Emit raw JSON to stdout (scripting-friendly) |
+
+Example:
+
+```bash
+mvw search "#Tatort !ARD >80"
+```
+
+### `mvw download`
+
+Search and download matching entries. Run `--dry-run` first to preview the
+exact file tree before downloading anything.
+
+```
+mvw download QUERY
+             [--channel C] [--topic T] [--title T]
+             [--min-duration MIN] [--max-duration MAX]
+             [--season] [--dry-run]
+             [--resolution low|medium|high|best]
+             [--output DIR] [-o DIR] [--template STR]
+             [--exclude TERM ...] [--dedup] [--latest-season]
+             [--season-number N] [--subtitles] [--limit N]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--channel` | — | Filter by channel |
+| `--topic` | — | Filter by topic |
+| `--title` | — | Filter by title |
+| `--min-duration` | — | Minimum duration in minutes |
+| `--max-duration` | — | Maximum duration in minutes |
+| `--season` | off | Group into Plex season folders using `S##E##` numbering |
+| `--dry-run` | off | Preview the file tree and source URLs; download nothing |
+| `--resolution` | `best` | Resolution preference: `low`, `medium`, `high`, or `best` |
+| `--output`, `-o` | config default | Output directory |
+| `--template` | Plex default | Custom filename template (see below) |
+| `--exclude` | — | Regex to exclude entries from title/topic/description (repeatable) |
+| `--dedup` | off | Remove near-duplicate entries, keeping the highest-quality copy |
+| `--latest-season` | off | Keep only entries from the highest detected season |
+| `--season-number` | — | Override detected season number |
+| `--subtitles` | off | Also fetch subtitle files alongside each video |
+| `--limit` | 200 | Maximum number of entries to resolve |
+
+#### Filename template
+
+The default template produces Plex/Jellyfin-compatible paths:
+
+```
+{series} ({year})/Season {s:02d}/{series} ({year}) - s{s:02d}e{e:02d} - {ep_title} [{res}].{ext}
+```
+
+Override with `--template`. Available tokens:
+
+| Token | Value |
+|-------|-------|
+| `{series}` | Topic (show name) |
+| `{year}` | Broadcast year |
+| `{s}` | Season number (supports `:02d` formatting) |
+| `{e}` | Episode number (supports `:02d` formatting) |
+| `{ep_title}` | Cleaned episode title |
+| `{res}` | Resolution label (see note below) |
+| `{channel}` | Broadcaster |
+| `{date}` | Broadcast date (`YYYY-MM-DD`) |
+| `{ext}` | File extension |
+
+**`{res}` label note:** MVW exposes only three tiers (`low` / `medium` / `high`),
+not measured pixel heights. The `{res}` token maps these to conventional labels —
+`high → "1080p"`, `medium → "720p"`, `low → "480p"` — because Plex parses these
+and they reflect typical public-broadcast encodes. These are labels, not
+guarantees of exact resolution.
+
+#### ffmpeg requirement for HLS
+
+Some entries serve `.m3u8` HLS playlists instead of direct `.mp4` files. Those
+are downloaded via `ffmpeg -i <url> -c copy <dest>`. If ffmpeg is not on your
+PATH and an HLS entry is encountered, `mvw` exits with code 4 and prints an
+install hint. Install from <https://ffmpeg.org/download.html>.
+
+#### Flagship example: Feuer und Flamme
+
+```bash
+# Preview the newest season, no audio description, deduped
+mvw download "#Feuer und Flamme" --season --latest-season --dedup \
+    --exclude Audiodeskription --exclude "Gebärdensprache" \
+    --output ~/Media/TV --dry-run
+
+# Then download for real in best resolution
+mvw download "#Feuer und Flamme" --season --latest-season --dedup \
+    --exclude Audiodeskription --output ~/Media/TV
+```
+
+### `mvw info`
+
+Show a Rich detail panel for the first match of a query.
+
+```
+mvw info QUERY
+```
+
+Displays: topic, title, description, channel, aired datetime, duration, size,
+available resolutions with URLs, subtitle URL, website URL, and detected
+season/episode.
+
+### `mvw config`
+
+Manage persistent configuration stored in `config.toml`
+(location: `platformdirs.user_config_dir("mvw")`).
+
+```
+mvw config show              # Print the effective config (key = value)
+mvw config set KEY VALUE     # Write a key to config.toml
+mvw config path              # Print the path to config.toml
+```
+
+Available keys: `download_dir`, `template`, `resolution`, `user_agent`,
+`page_size`, `request_timeout`.
+
+CLI flags always override config file values, which override built-in defaults.
+
+## Exit codes
+
+| Code | Condition |
+|------|-----------|
+| 0 | Success or no results |
+| 2 | API error (non-null `err`), HTTP error, or network/timeout after retries |
+| 4 | HLS entry encountered but ffmpeg is not installed |
+| 5 | Partial/interrupted download failure |
+
+## Running tests
+
+```bash
+# Unit and mocked tests (default)
+uv run pytest -q
+
+# Include the live API test (requires network access)
+uv run pytest -m live tests/test_live.py -v
+```

mvw_cli-0.1.0/README.md

@@ -0,0 +1,232 @@
+# mvw
+
+A command-line tool for searching and downloading content from
+[MediathekViewWeb](https://mediathekviewweb.de/) (MVW), the index of German
+public-broadcasting media libraries (ARD, ZDF, WDR, and more). Built for
+automation: the headline feature is reliable, Plex-friendly **season**
+downloads.
+
+## Install
+
+Requires Python ≥ 3.13. The distribution is published as **`mvw-cli`** (the
+PyPI name `mvw` was already taken); the installed command is `mvw`.
+
+Install as a standalone tool with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv tool install mvw-cli      # adds the `mvw` command to your PATH
+```
+
+Or run it once without installing:
+
+```bash
+uvx --from mvw-cli mvw search "#Tatort"
+```
+
+With pip:
+
+```bash
+pip install mvw-cli
+```
+
+> **Note:** HLS (`.m3u8`) downloads require [ffmpeg](https://ffmpeg.org/download.html)
+> on your `PATH`. It is an external (non-Python) dependency and is not installed
+> automatically.
+
+### From source
+
+```bash
+uv sync                      # create the dev environment
+uv run mvw --help            # run from the working tree
+```
+
+## Query grammar
+
+The query string follows the MediathekViewWeb syntax:
+
+| Prefix | Field searched | Example |
+|--------|---------------|---------|
+| `!` | channel | `!ARD` |
+| `#` | topic | `#Tatort` |
+| `+` | title | `+Schokolade` |
+| `*` | description | `*Berlin` |
+| (none) | topic and title | `feuer flamme` |
+| `>N` | duration > N minutes | `>80` |
+| `<N` | duration < N minutes | `<10` |
+
+Combination rules:
+
+- **Space between different selectors** → AND: `!WDR #Tatort` means channel=WDR
+  AND topic=Tatort.
+- **Same selector repeated** → OR: `!ARD !ZDF` means ARD or ZDF.
+- **Comma within a selector's value** → AND of words: `#Olympia,Tokio` matches
+  topic containing both "Olympia" and "Tokio".
+- **No negation operator.** Exclusion is done client-side with `--exclude`.
+
+> Note: the API is case-insensitive and flexible with umlauts
+> (`ö` ≈ `oe` ≈ `OE`).
+
+## Commands
+
+### `mvw search`
+
+Search MVW and display a Rich results table.
+
+```
+mvw search QUERY
+           [--channel C] [--topic T] [--title T] [--description D]
+           [--min-duration MIN] [--max-duration MAX]
+           [--sort timestamp|duration|channel] [--order asc|desc]
+           [--future] [--limit N] [--offset N] [--json]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--channel` | — | Filter by channel (structured flag, not query syntax) |
+| `--topic` | — | Filter by topic |
+| `--title` | — | Filter by title |
+| `--description` | — | Filter by description |
+| `--min-duration` | — | Minimum duration in minutes |
+| `--max-duration` | — | Maximum duration in minutes |
+| `--sort` | `timestamp` | Sort field |
+| `--order` | `desc` | Sort order (`asc` or `desc`) |
+| `--future` | off | Include not-yet-aired entries |
+| `--limit` | 15 | Number of results to fetch |
+| `--offset` | 0 | Pagination offset |
+| `--json` | off | Emit raw JSON to stdout (scripting-friendly) |
+
+Example:
+
+```bash
+mvw search "#Tatort !ARD >80"
+```
+
+### `mvw download`
+
+Search and download matching entries. Run `--dry-run` first to preview the
+exact file tree before downloading anything.
+
+```
+mvw download QUERY
+             [--channel C] [--topic T] [--title T]
+             [--min-duration MIN] [--max-duration MAX]
+             [--season] [--dry-run]
+             [--resolution low|medium|high|best]
+             [--output DIR] [-o DIR] [--template STR]
+             [--exclude TERM ...] [--dedup] [--latest-season]
+             [--season-number N] [--subtitles] [--limit N]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--channel` | — | Filter by channel |
+| `--topic` | — | Filter by topic |
+| `--title` | — | Filter by title |
+| `--min-duration` | — | Minimum duration in minutes |
+| `--max-duration` | — | Maximum duration in minutes |
+| `--season` | off | Group into Plex season folders using `S##E##` numbering |
+| `--dry-run` | off | Preview the file tree and source URLs; download nothing |
+| `--resolution` | `best` | Resolution preference: `low`, `medium`, `high`, or `best` |
+| `--output`, `-o` | config default | Output directory |
+| `--template` | Plex default | Custom filename template (see below) |
+| `--exclude` | — | Regex to exclude entries from title/topic/description (repeatable) |
+| `--dedup` | off | Remove near-duplicate entries, keeping the highest-quality copy |
+| `--latest-season` | off | Keep only entries from the highest detected season |
+| `--season-number` | — | Override detected season number |
+| `--subtitles` | off | Also fetch subtitle files alongside each video |
+| `--limit` | 200 | Maximum number of entries to resolve |
+
+#### Filename template
+
+The default template produces Plex/Jellyfin-compatible paths:
+
+```
+{series} ({year})/Season {s:02d}/{series} ({year}) - s{s:02d}e{e:02d} - {ep_title} [{res}].{ext}
+```
+
+Override with `--template`. Available tokens:
+
+| Token | Value |
+|-------|-------|
+| `{series}` | Topic (show name) |
+| `{year}` | Broadcast year |
+| `{s}` | Season number (supports `:02d` formatting) |
+| `{e}` | Episode number (supports `:02d` formatting) |
+| `{ep_title}` | Cleaned episode title |
+| `{res}` | Resolution label (see note below) |
+| `{channel}` | Broadcaster |
+| `{date}` | Broadcast date (`YYYY-MM-DD`) |
+| `{ext}` | File extension |
+
+**`{res}` label note:** MVW exposes only three tiers (`low` / `medium` / `high`),
+not measured pixel heights. The `{res}` token maps these to conventional labels —
+`high → "1080p"`, `medium → "720p"`, `low → "480p"` — because Plex parses these
+and they reflect typical public-broadcast encodes. These are labels, not
+guarantees of exact resolution.
+
+#### ffmpeg requirement for HLS
+
+Some entries serve `.m3u8` HLS playlists instead of direct `.mp4` files. Those
+are downloaded via `ffmpeg -i <url> -c copy <dest>`. If ffmpeg is not on your
+PATH and an HLS entry is encountered, `mvw` exits with code 4 and prints an
+install hint. Install from <https://ffmpeg.org/download.html>.
+
+#### Flagship example: Feuer und Flamme
+
+```bash
+# Preview the newest season, no audio description, deduped
+mvw download "#Feuer und Flamme" --season --latest-season --dedup \
+    --exclude Audiodeskription --exclude "Gebärdensprache" \
+    --output ~/Media/TV --dry-run
+
+# Then download for real in best resolution
+mvw download "#Feuer und Flamme" --season --latest-season --dedup \
+    --exclude Audiodeskription --output ~/Media/TV
+```
+
+### `mvw info`
+
+Show a Rich detail panel for the first match of a query.
+
+```
+mvw info QUERY
+```
+
+Displays: topic, title, description, channel, aired datetime, duration, size,
+available resolutions with URLs, subtitle URL, website URL, and detected
+season/episode.
+
+### `mvw config`
+
+Manage persistent configuration stored in `config.toml`
+(location: `platformdirs.user_config_dir("mvw")`).
+
+```
+mvw config show              # Print the effective config (key = value)
+mvw config set KEY VALUE     # Write a key to config.toml
+mvw config path              # Print the path to config.toml
+```
+
+Available keys: `download_dir`, `template`, `resolution`, `user_agent`,
+`page_size`, `request_timeout`.
+
+CLI flags always override config file values, which override built-in defaults.
+
+## Exit codes
+
+| Code | Condition |
+|------|-----------|
+| 0 | Success or no results |
+| 2 | API error (non-null `err`), HTTP error, or network/timeout after retries |
+| 4 | HLS entry encountered but ffmpeg is not installed |
+| 5 | Partial/interrupted download failure |
+
+## Running tests
+
+```bash
+# Unit and mocked tests (default)
+uv run pytest -q
+
+# Include the live API test (requires network access)
+uv run pytest -m live tests/test_live.py -v
+```

mvw_cli-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "mvw-cli"
+description = "Search and download German public-broadcasting media from MediathekViewWeb, with Plex-friendly season downloads."
+readme = "README.md"
+requires-python = ">=3.13"
+dynamic = ["version"]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Max Boettinger", email = "perplexity@bttngr.de" }]
+keywords = [
+    "mediathek",
+    "mediathekviewweb",
+    "ard",
+    "zdf",
+    "german",
+    "television",
+    "download",
+    "cli",
+    "plex",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Natural Language :: German",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "httpx>=0.27",
+    "platformdirs>=4.2",
+]
+
+[project.scripts]
+mvw = "mvw.cli:app"
+
+# Fill these in once the project has a public home, then uncomment.
+# [project.urls]
+# Homepage = "https://github.com/<you>/mvw-cli"
+# Repository = "https://github.com/<you>/mvw-cli"
+# Issues = "https://github.com/<you>/mvw-cli/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.2",
+    "respx>=0.21",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/mvw/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mvw"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/mvw",
+    "tests",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.pytest.ini_options]
+markers = ["live: hits the real MediathekViewWeb API (opt-in)"]
+addopts = "-m 'not live'"

mvw_cli-0.1.0/src/mvw/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mvw_cli-0.1.0/src/mvw/api.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+
+import httpx
+
+from mvw.models import MediathekResult, QueryInfo, QueryResult
+
+
+class MediathekError(Exception):
+    """Raised on API errors, HTTP failures, or transport errors."""
+
+
+class MediathekClient:
+    def __init__(
+        self,
+        user_agent: str = "mvw/0.1.0",
+        timeout: float = 30.0,
+        retries: int = 2,
+        base_url: str = "https://mediathekviewweb.de/api/query",
+    ) -> None:
+        self.user_agent = user_agent
+        self.timeout = timeout
+        self.retries = retries
+        self.base_url = base_url
+
+    def query(self, payload: dict) -> QueryResult:
+        headers = {"Content-Type": "text/plain", "User-Agent": self.user_agent}
+        body = json.dumps(payload)
+        transport_err: Exception | None = None
+        for _ in range(self.retries + 1):
+            try:
+                resp = httpx.post(
+                    self.base_url, content=body, headers=headers, timeout=self.timeout
+                )
+            except httpx.TransportError as exc:
+                transport_err = exc
+                continue
+            if resp.status_code != 200:
+                raise MediathekError(f"HTTP {resp.status_code}: {resp.text[:200]}")
+            data = resp.json()
+            err = data.get("err")
+            if err:
+                raise MediathekError("; ".join(str(e) for e in err))
+            result = data.get("result") or {}
+            results = [MediathekResult.from_api(r) for r in result.get("results", [])]
+            info = QueryInfo.from_api(result.get("queryInfo", {}))
+            return QueryResult(results=results, query_info=info)
+        raise MediathekError(f"network error: {transport_err}")
+
+    def iter_all(
+        self, payload: dict, page_size: int = 50, cap: int | None = None
+    ) -> Iterator[MediathekResult]:
+        offset = int(payload.get("offset", 0))
+        yielded = 0
+        while True:
+            page = dict(payload, offset=offset, size=page_size)
+            result = self.query(page)
+            if not result.results:
+                return
+            for row in result.results:
+                yield row
+                yielded += 1
+                if cap is not None and yielded >= cap:
+                    return
+            offset += len(result.results)
+            if offset >= result.query_info.total_results:
+                return