yle-areena-dvr 0.1.0__tar.gz

yle_areena_dvr-0.1.0/.env.template

@@ -0,0 +1,10 @@
+# Yle Data API credentials (optional; by default read from areena.yle.fi at runtime)
+YLE_APP_ID=
+YLE_APP_KEY=
+
+# TMDb API Key for ratings and multi-language searching
+# Get a free key from https://www.themoviedb.org/documentation/api
+TMDB_API_KEY=your_tmdb_key_here
+
+# Download base directory
+DOWNLOAD_BASE_DIR=~/Downloads/YleAreena

yle_areena_dvr-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --python ${{ matrix.python-version }}
+      - run: uv run yle-dvr naming
+      - run: uv build

yle_areena_dvr-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+# Publishes to PyPI when a version tag (e.g. v0.1.0) is pushed, using PyPI trusted publishing (OIDC).
+# One-time setup on pypi.org: add a publisher for owner junousia, repo yle-areena-dvr,
+# workflow release.yml, environment pypi.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Tag must match pyproject version
+        run: test "v$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)" = "$GITHUB_REF_NAME"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

yle_areena_dvr-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Secrets
+.env
+*.key
+*.pem
+
+# Python
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+
+# Local runtime data
+*.db
+*.sqlite
+*.sqlite3
+.tmdb-cache.json
+
+# OS / editor
+.DS_Store
+.vscode/
+.idea/
+node_modules/
+dist/
+state.json

yle_areena_dvr-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

yle_areena_dvr-0.1.0/LICENSE

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

yle_areena_dvr-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: yle-areena-dvr
+Version: 0.1.0
+Summary: A tool for Yle Areena to download movies and series of interest.
+Project-URL: Homepage, https://github.com/junousia/yle-areena-dvr
+Project-URL: Issues, https://github.com/junousia/yle-areena-dvr/issues
+Author: Jukka Nousiainen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skill,areena,dvr,tmdb,yle,yt-dlp
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.12
+Requires-Dist: aiosqlite
+Requires-Dist: greenlet
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Requires-Dist: pydantic-cli
+Requires-Dist: pydantic-settings
+Requires-Dist: pyyaml
+Requires-Dist: sqlmodel
+Requires-Dist: yt-dlp
+Description-Content-Type: text/markdown
+
+# Yle Areena DVR
+
+A Python tool for searching, scraping, and downloading movies and series from Yle Areena with integrated TMDb ratings and flexible naming templates.
+
+## Features
+- **Yle Areena Search**: Find movies by query or category.
+- **Scrape Curated Lists**: Extract movies directly from Areena's curated lists (e.g., "Katsotuimmat leffat").
+- **TMDb Ratings**: Automatically fetch and filter by TMDb ratings (The Movie Database). Excellent multi-language support.
+- **yt-dlp Integration**: High-quality downloads with subtitle support.
+- **Flexible Organization**: Customize your folder structure and file naming via `config.yaml`.
+- **Modern Python**: Built with Python 3.12+, Pydantic 2, and managed entirely with `uv`.
+
+## Installation
+
+This project is built using `uv`, an extremely fast Python package and project manager.
+
+```bash
+# Clone the repository
+git clone https://github.com/junousia/yle-areena-dvr.git
+cd yle-areena-dvr
+
+# Sync the environment
+uv sync
+
+# Or install it globally as a tool
+uv tool install .
+```
+
+## Setup
+
+1. Copy `.env.template` to `.env`:
+   ```bash
+   cp .env.template .env
+   ```
+2. Fill in your `TMDB_API_KEY` (free from themoviedb.org). `YLE_APP_ID` and `YLE_APP_KEY` are **optional**: by default the tool reads the keys that Areena's own web frontend embeds in its pages at runtime; set them only to override that.
+3. Customize `assets/config.yaml` to change where your movies are saved.
+
+## Usage
+
+If you installed it via `uv tool install .`, you can run `yle-dvr` directly. Otherwise, use `uv run yle-dvr` inside the project directory.
+
+### Search for Programs
+```bash
+uv run yle-dvr search --query "Metsolat" --limit 5 --min-rating 7.0
+
+# Search for expiring programs
+uv run yle-dvr search --only-expiring
+
+# Search for recently added programs
+uv run yle-dvr search --only-new
+
+# You can also get machine-readable output for AI agents:
+uv run yle-dvr search --query "Action" --json
+```
+
+### Scrape Curated Lists (Movies or Series)
+```bash
+# Scrape movies
+uv run yle-dvr scrape --url "https://areena.yle.fi/tv/ohjelmat/57-1BbXLDz6v" --min-rating 7.5
+
+# Scrape series
+uv run yle-dvr scrape --url "https://areena.yle.fi/tv/ohjelmat/57-p8JeXvBA0"
+```
+
+### Download a Program (Movie or Series)
+```bash
+uv run yle-dvr download --id "1-2345678"
+```
+
+### Look Up Full Details for Suitability (Overview, Genres, Cast)
+```bash
+# From a program already in the local DB
+uv run yle-dvr details --id "1-2345678" --json
+
+# Directly by title, no DB entry required
+uv run yle-dvr details --title "Fight Club" --year 1999 --json
+```
+
+## Configuration
+See `assets/config.yaml` for customization options including folder templates and subtitle preferences.
+
+## Disclaimer
+
+This is an unofficial tool and is not affiliated with Yle. Downloading is intended for personal use of content that Yle makes available to you; respect Yle's terms of service and applicable copyright law. You are responsible for how you use it.
+
+## Use as an agent skill
+
+`SKILL.md` makes this repo usable as a skill in [Hermes Agent](https://hermes-agent.nousresearch.com) and OpenClaw.
+Clone it into the agent's skills directory (for Hermes e.g. `~/.hermes/skills/<category>/yle-areena-dvr`,
+for OpenClaw `<workspace>/skills/yle-areena-dvr`), run `uv sync` there, and copy `.env.template` to `.env`.
+Python 3.12-3.14 is required (3.13 is tested).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

yle_areena_dvr-0.1.0/README.md

@@ -0,0 +1,95 @@
+# Yle Areena DVR
+
+A Python tool for searching, scraping, and downloading movies and series from Yle Areena with integrated TMDb ratings and flexible naming templates.
+
+## Features
+- **Yle Areena Search**: Find movies by query or category.
+- **Scrape Curated Lists**: Extract movies directly from Areena's curated lists (e.g., "Katsotuimmat leffat").
+- **TMDb Ratings**: Automatically fetch and filter by TMDb ratings (The Movie Database). Excellent multi-language support.
+- **yt-dlp Integration**: High-quality downloads with subtitle support.
+- **Flexible Organization**: Customize your folder structure and file naming via `config.yaml`.
+- **Modern Python**: Built with Python 3.12+, Pydantic 2, and managed entirely with `uv`.
+
+## Installation
+
+This project is built using `uv`, an extremely fast Python package and project manager.
+
+```bash
+# Clone the repository
+git clone https://github.com/junousia/yle-areena-dvr.git
+cd yle-areena-dvr
+
+# Sync the environment
+uv sync
+
+# Or install it globally as a tool
+uv tool install .
+```
+
+## Setup
+
+1. Copy `.env.template` to `.env`:
+   ```bash
+   cp .env.template .env
+   ```
+2. Fill in your `TMDB_API_KEY` (free from themoviedb.org). `YLE_APP_ID` and `YLE_APP_KEY` are **optional**: by default the tool reads the keys that Areena's own web frontend embeds in its pages at runtime; set them only to override that.
+3. Customize `assets/config.yaml` to change where your movies are saved.
+
+## Usage
+
+If you installed it via `uv tool install .`, you can run `yle-dvr` directly. Otherwise, use `uv run yle-dvr` inside the project directory.
+
+### Search for Programs
+```bash
+uv run yle-dvr search --query "Metsolat" --limit 5 --min-rating 7.0
+
+# Search for expiring programs
+uv run yle-dvr search --only-expiring
+
+# Search for recently added programs
+uv run yle-dvr search --only-new
+
+# You can also get machine-readable output for AI agents:
+uv run yle-dvr search --query "Action" --json
+```
+
+### Scrape Curated Lists (Movies or Series)
+```bash
+# Scrape movies
+uv run yle-dvr scrape --url "https://areena.yle.fi/tv/ohjelmat/57-1BbXLDz6v" --min-rating 7.5
+
+# Scrape series
+uv run yle-dvr scrape --url "https://areena.yle.fi/tv/ohjelmat/57-p8JeXvBA0"
+```
+
+### Download a Program (Movie or Series)
+```bash
+uv run yle-dvr download --id "1-2345678"
+```
+
+### Look Up Full Details for Suitability (Overview, Genres, Cast)
+```bash
+# From a program already in the local DB
+uv run yle-dvr details --id "1-2345678" --json
+
+# Directly by title, no DB entry required
+uv run yle-dvr details --title "Fight Club" --year 1999 --json
+```
+
+## Configuration
+See `assets/config.yaml` for customization options including folder templates and subtitle preferences.
+
+## Disclaimer
+
+This is an unofficial tool and is not affiliated with Yle. Downloading is intended for personal use of content that Yle makes available to you; respect Yle's terms of service and applicable copyright law. You are responsible for how you use it.
+
+## Use as an agent skill
+
+`SKILL.md` makes this repo usable as a skill in [Hermes Agent](https://hermes-agent.nousresearch.com) and OpenClaw.
+Clone it into the agent's skills directory (for Hermes e.g. `~/.hermes/skills/<category>/yle-areena-dvr`,
+for OpenClaw `<workspace>/skills/yle-areena-dvr`), run `uv sync` there, and copy `.env.template` to `.env`.
+Python 3.12-3.14 is required (3.13 is tested).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

yle_areena_dvr-0.1.0/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: yle-areena-dvr
+description: Search, scrape, enrich (TMDb), and download Yle Areena movies/series with Plex-friendly naming and local DB workflows.
+---
+
+# Yle Areena DVR Skill
+
+Use `uv run yle-dvr ...`.
+
+## Core commands
+
+- `search` → query local DB
+- `scrape` → scrape Areena list page into DB (+ TMDb enrich)
+- `details` → fetch full TMDb detail (overview, genres, cast, runtime) for one title, to judge suitability
+- `download` → download by Areena ID
+- `naming` → list naming presets
+- `backfill-years` → fill missing DB years from TMDb
+
+## Judging suitability with `details`
+
+`search`/`scrape` only carry a title, TMDb rating, and year — not enough to judge whether a movie
+is actually a good fit. Before recommending or auto-downloading something, look it up:
+
+```bash
+# By Areena ID already in the local DB
+uv run yle-dvr details --id "1-70111573" --json
+
+# By title directly (no DB entry needed)
+uv run yle-dvr details --title "Fight Club" --year 1999 --json
+
+# Series (default type is "program", i.e. movie)
+uv run yle-dvr details --title "Breaking Bad" --type series --json
+```
+
+Returns `overview` (plot summary), `genres`, `cast`, `directors`, `runtime_minutes`, `tagline`,
+`vote_average`/`vote_count`, and `keywords` — enough to actually reason about whether a title
+matches what the user wants, instead of guessing from the title alone.
+
+If TMDb is unreachable (network blip), the response is `{"ok": false, "error": "TMDb unreachable, try again: ..."}` —
+distinct from `{"ok": false, "error": "No TMDb match for '<title>'"}`, which means it genuinely isn't
+on TMDb. Retry on the former; don't treat it as "not found".
+
+## Key improvements
+
+- TMDb year support in DB + download path
+- Backfill command for existing records in DB
+- Naming preset support and custom output templates in CLI
+- JSON output on all key commands
+
+## Examples
+
+```bash
+# Scrape list and enrich with TMDb
+uv run yle-dvr scrape --url "https://areena.yle.fi/tv/ohjelmat/57-1BbXLDz6v"
+
+# Search DB
+uv run yle-dvr search --query "Three Billboards" --json
+
+# Show naming presets
+uv run yle-dvr naming
+
+# Download with preset naming
+uv run yle-dvr download --id "1-70111573" --naming-preset "plex-movie"
+
+# Download with explicit output template
+uv run yle-dvr download --id "1-70111573" --output-template "{title} ({year}) [YLE].%(ext)s"
+
+# Dry run (resolve naming/path without downloading)
+uv run yle-dvr download --id "1-70111573" --naming-preset "plex-movie" --dry-run
+
+# Backfill missing years from TMDb for existing DB rows
+uv run yle-dvr backfill-years --limit 500
+```
+
+## Naming format
+
+Configured in `assets/config.yaml` under `naming`:
+
+- `movie_filename`
+- `series_filename`
+- `presets` (e.g. `plex-movie`, `plex-series`)
+
+Download precedence:
+
+1. `--output-template`
+2. `--naming-preset`
+3. Default `movie_filename` / `series_filename`
+
+## TMDb requirement
+
+Set `TMDB_API_KEY` in `.env` to enable TMDb year/rating enrichment and backfill.
+
+Without TMDb key, backfill is skipped and year enrichment is limited.

yle_areena_dvr-0.1.0/assets/config.yaml

@@ -0,0 +1,26 @@
+# Yle Areena DVR Configuration
+
+# File Naming and Directory Structure Templates
+# Available tokens: {title}, {year}, {id}, {genres}, {rating}
+naming:
+  movie_folder: "movies"
+  movie_filename: "{title} ({year}).%(ext)s"
+  series_folder: "series/{title}"
+  series_filename: "{title} - S{season_number}E{episode_number} - {episode_title}.%(ext)s"
+  presets:
+    plex-movie: "{title} ({year}).%(ext)s"
+    plex-series: "{title} - S{season_number}E{episode_number} - {episode_title}.%(ext)s"
+    title-only: "{title}.%(ext)s"
+
+# Download Settings
+download:
+  base_directory: "./downloads"
+  format: "bv*+ba/b"
+  merge_output_format: "mkv"
+  subtitles:
+    enabled: true
+    languages: ["fi", "sv", "en"]
+
+# Rating Filtering (Min rating to auto-download)
+filters:
+  min_imdb_rating: 7.0

yle_areena_dvr-0.1.0/assets/example_asset.txt

@@ -0,0 +1 @@
+Placeholder for assets.

yle_areena_dvr-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "yle-areena-dvr"
+version = "0.1.0"
+description = "A tool for Yle Areena to download movies and series of interest."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jukka Nousiainen" }]
+keywords = ["yle", "areena", "dvr", "yt-dlp", "tmdb", "agent-skill"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.12,<3.15"
+dependencies = [
+    "yt-dlp",
+    "httpx",
+    "aiosqlite",
+    "sqlmodel",
+    "pydantic",
+    "pydantic-settings",
+    "pydantic-cli",
+    "pyyaml",
+    "greenlet",
+]
+
+[project.urls]
+Homepage = "https://github.com/junousia/yle-areena-dvr"
+Issues = "https://github.com/junousia/yle-areena-dvr/issues"
+
+[project.scripts]
+yle-dvr = "yle_areena_dvr.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel.force-include]
+"assets/config.yaml" = "yle_areena_dvr/default_config.yaml"

yle_areena_dvr-0.1.0/references/example_reference.md

@@ -0,0 +1,17 @@
+# Reference Documentation for Yle Areena Dvr
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Best practices

yle_areena_dvr-0.1.0/scripts/example_script.cjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+/**
+ * Example helper script for yle-areena-dvr
+ *
+ * This is a placeholder script that can be executed directly.
+ * Replace with actual implementation or delete if not needed.
+ *
+ * Example real scripts from other skills:
+ * - pdf/scripts/fill_fillable_fields.cjs - Fills PDF form fields
+ * - pdf/scripts/convert_pdf_to_images.cjs - Converts PDF pages to images
+ *
+ * Agentic Ergonomics:
+ * - Suppress tracebacks.
+ * - Return clean success/failure strings.
+ * - Truncate long outputs.
+ */
+
+async function main() {
+  try {
+    // TODO: Add actual script logic here.
+    // This could be data processing, file conversion, API calls, etc.
+
+    // Example output formatting for an LLM agent
+    process.stdout.write("Success: Processed the task.\n");
+  } catch (err) {
+    // Trap the error and output a clean message instead of a noisy stack trace
+    process.stderr.write(`Failure: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+main();