werstreamtes-to-ryot

Convert a werstreamt.es CSV export into a Ryot-compatible JSON by scraping IMDb links from each item page and resolving metadata via TMDB. Supports optional "seen" mode to mark movies or all episodes of shows as watched and multithreaded processing for speed. Logs go to stderr; only the final JSON goes to stdout.

Features

• Extracts IMDb IDs from werstreamt.es item pages
• Resolves items through TMDB's Find API (by IMDb ID) using a Bearer token
• Emits Ryot-compatible JSON under metadata
• Modes:
  • Default (watchlist): add items without watch history
  • Seen (--seen): mark entire movies or all show episodes as watched
• Multithreading with --threads
• Clean outputs: JSON to stdout, logs/warnings/errors to stderr

Requirements

• Python 3.12+
• A TMDB API key (Docs)
• A Ryot API key (Settings > Integrations)
• uv (for fast, isolated Python project management)

Install

Get dependencies with

uv sync

Environment

Set environment variables:

• TMDB_API_KEY: TMDB v3 Bearer token
• RYOT_API_URL: Ryot GraphQL endpoint
• RYOT_API_TOKEN: Ryot API token (used to get the IDs of the "Watchlist" and "Completed" collections)

Examples:

• macOS/Linux:

  export TMDB_API_KEY="your_tmdb_v4_bearer_token"
  export RYOT_API_URL="https://your-ryot.example.com/backend/graphql"
  export RYOT_API_TOKEN="your_ryot_api_key"

• Windows (Command Prompt):

  set TMDB_API_KEY=your_tmdb_v4_bearer_token
  set RYOT_API_URL=https://your-ryot.example.com/backend/graphql
  set RYOT_API_TOKEN=your_ryot_api_key

• Windows (PowerShell):

  $env:TMDB_API_KEY="your_tmdb_v4_bearer_token"
  $env:RYOT_API_URL="https://your-ryot.example.com/backend/graphql"
  $env:RYOT_API_TOKEN="your_ryot_api_key"

Optional:

• TMDB_API_URL defaults to https://api.themoviedb.org/3

Input CSV

Expected werstreamt.es CSV headers:

Type,WSE-ID,Title,OriginalTitle,Year,Link

Only Title and Link are required by the script.

Usage

Basic (watchlist mode, default):

uv run python main.py 'Watchlist.csv' > ryot_watchlist.json

Mark all items as seen:

uv run python main.py --seen 'Bereits gesehen.csv' > ryot_seen.json

Enable multithreading (e.g., 4 threads):

uv run python main.py --threads 4 'Watchlist.csv' > ryot.json

Combine options:

uv run python main.py --seen --threads 4 'Bereits gesehen.csv' > ryot_seen.json

Notes:

• Progress, warnings, and errors are printed to stderr.
• Only the final JSON is printed to stdout; redirect stdout to save to a file.

Notes on Concurrency

• --threads 1 (default) processes sequentially.
• --threads N uses a thread pool and processes rows concurrently.
• If encountering API rate limits, reduce --threads.