Skip to content
BranchesTags

Repository files navigation

Streamarr Preview

Streamarr harvests stream URLs from popular Turkish streaming sites, exposes them through a resolver API, integrates with Jellyfin via STRM libraries and a native plugin, and provides a mobile media player app for direct streaming.

Highlights

  • Modular Architecture – Playwright scrapers, resolver API, metadata enrichment, and plugin separated cleanly
  • Dizibox & HDFilm Support – Automation for the two most-requested Turkish streaming sources
  • On-Demand Resolution – Stream URLs are refreshed only when a user presses play
  • Jellyfin Plugin – Adds a configuration UI and /play/ integration
  • Mobile Media Player – Native Expo app with built-in video player for direct streaming
  • Manager Backend – FastAPI + Redis Queue for job management and library synchronization
  • CLI Utilities – Collect links, build catalogs, generate STRM files, update plugin manifest
  • Docker Support – Run the resolver API in a container with a single command

Repository Layout

Path Purpose
backend/resolver/ Playwright scrapers & Flask resolver API
backend/manager_api/ FastAPI backend with Redis Queue for job management
backend/manager_worker/ RQ worker for background job processing
apps/expo/ React Native mobile app with media player functionality
scripts/ CLI utilities (collect_links, catalog_builder, strm_generator, update_manifest)
plugins/Streamarr/ Jellyfin plugin source (config page, metadata providers, build output)
data/ Harvested link lists and generated catalog
output/strm/ Autogenerated STRM files ready to import into Jellyfin
docs/archive/ Legacy POC notes and exploratory scripts

Requirements

  • Python 3.11+
  • Node.js 20 LTS (for Expo app)
  • Playwright (pip install -r requirements.txt and playwright install firefox)
  • .NET SDK 8.0 (for Jellyfin plugin builds)
  • Optional TMDB API key (TMDB_KEY) for metadata enrichment

Mobile Media Player App (Expo)

The Streamarr mobile app provides a native media player experience for streaming content directly from Turkish streaming sites.

Features

  • Library Management – Browse and search through your media catalog
  • Built-in Video Player – Stream content directly without external players
  • STRM Generation – Create .strm files for Jellyfin integration
  • Real-time Job Monitoring – Track bootstrap and STRM generation progress
  • Cross-platform – Works on iOS, Android, and Web

Quick Start

  1. Install dependencies

    cd apps/expo
npm install

  2. Start the development server

    npx expo start

  3. Configure backend connection

    • Enter your Manager API URL (default: http://127.0.0.1:8000)
    • Complete initial setup with resolver configuration

  4. Start streaming

    • Browse your library
    • Tap on any media item to view details
    • Use "Test et" to stream directly in the app
    • Generate STRM files for Jellyfin integration

Development

The Expo app uses:

  • React Native with Expo SDK 54
  • React Query for API state management
  • Expo AV for media playback (planned)
  • TypeScript for type safety

Docker Deployment

The resolver API ships with a ready-to-use Docker configuration.

# Build and start the resolver API
docker compose up -d

# The API is now available at http://127.0.0.1:5055

By default the container mounts ./data inside /app/data, so any catalog updates on the host are immediately visible. Environment variables you can override:

  • TMDB_KEY – optional TMDB API key for catalog enrichment
  • PROXY_BASE_URL – optional upstream proxy for stream URLs
  • CATALOG_PATH – location of catalog.json inside the container (defaults to /app/data/catalog.json)

To stop the container:

docker compose down

Manager Backend (FastAPI + Redis Queue)

The new manager backend provides a FastAPI surface, RQ-powered background jobs, and a small CLI.

Quick start (single command)

Use the helper script to bring up Redis, the API, and the worker together:

python scripts/run_manager_stack.py

By default the script:

  • Spins up the redis service defined in docker-compose.yml (skip with --no-start-redis).
  • Launches uvicorn with auto-reload on http://127.0.0.1:8000.
  • Starts the RQ worker connected to the same Redis instance.

Override behaviour with flags such as --host, --port, or --redis-url. The script forwards all logs to your terminal and shuts everything down when you press Ctrl+C.

Manual setup

If you prefer to manage each process yourself, follow these steps instead:

  1. Create & activate a virtual environment (optional but recommended)

    python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

  2. Install backend dependencies

    pip install -r requirements.txt

  3. Start Redis – required for the job queue. You can reuse docker-compose:

    docker compose up -d redis

    Redis defaults to redis://localhost:6379/0. Override with STREAMARR_MANAGER_REDIS_URL if needed.

  4. Launch the Manager API (served on http://127.0.0.1:8000 by default):

    cd backend
make dev
# or
uvicorn backend.manager_api.app:create_app --factory --reload

    The API auto-creates data/manager.db with default configuration the first time it runs. Adjust settings via environment variables prefixed with STREAMARR_MANAGER_ (e.g. STREAMARR_MANAGER_DATABASE_URL).

  5. Run the background worker in another terminal so queued jobs execute:

    cd backend
make worker
# or
python -m backend.manager_worker

  6. (Optional) Use the CLI – interact with the API for smoke tests:

    python -m backend.manager_cli health check
python -m backend.manager_cli setup --resolver-url http://localhost:5055

    Provide --api-url http://127.0.0.1:8000 if the API is hosted on a different address.

With the manager backend running, the Expo app and CLI will talk to http://127.0.0.1:8000 by default. The API documentation lives at http://127.0.0.1:8000/docs for interactive exploration.

Resolver + STRM Workflow (Manual)

  1. Install dependencies 
    pip install -r requirements.txt
playwright install firefox

2. **Harvest URLs**
   ```bash
   python scripts/collect_links.py --site hdfilm
   python scripts/collect_links.py --site dizibox --max-shows 100

   # reuse cached HDFilm sitemap responses (skips ones fetched in the last 12h)
   python scripts/collect_links.py --site hdfilm --sitemap-delay 0.5 --sitemap-ttl 43200

Outputs are written to data/hdfilm_links.json and data/dizibox_links.json. When sitemap caching is enabled, cache metadata is stored at data/hdfilm_sitemap_cache.json by default.

  1. Build Catalog

    # quick pass without TMDB enrichment
python scripts/catalog_builder.py --skip-tmdb --chunk-size 5000

# or enrich with TMDB metadata
python scripts/catalog_builder.py --tmdb-key "<TMDB_KEY>" --chunk-size 5000

# store results directly in SQLite (no JSON output)
python scripts/catalog_builder.py --skip-tmdb --skip-json --sqlite-db data/catalog.sqlite

# pull page <title> tags for better names (slow; hits each URL once)
python scripts/catalog_builder.py --fetch-html-titles --title-fetch-limit 500

    Outputs chunked files such as data/catalog.movies.001.json and data/catalog.episodes.001.json, keeping each JSON small enough for editors. Leave out --chunk-size to emit single catalog.movies.json / catalog.episodes.json files.

    Useful flags:

    • --skip-tmdb -> skip metadata lookups even if a TMDB key is configured.
    • --chunk-size <N> -> split the catalog into files with at most N entries for easier inspection.
    • --sqlite-db <path> -> write the catalog into a SQLite database (tables are recreated on each run).
    • --skip-json -> suppress JSON output (useful when only SQLite export is desired).
    • --fetch-html-titles -> fetch the source page <title> to improve initial names (adds HTTP requests; combine with --title-fetch-limit to sample).
    • --title-fetch-limit <N> -> stop fetching HTML titles after N requests (omit for all entries).

  2. Generate STRM Files

    python scripts/strm_generator.py --resolver-base http://192.168.0.15:5055
   Creates STRM files under output/strm/. Point Jellyfin at this folder as a virtual library.

5. **Run Resolver API (non-docker)**
   ```bash
   cd backend/resolver
   python api.py

Exposes:

  • POST /resolve – resolve an episode/movie URL
  • GET /stream/ – redirect/JSON with stream details
  • GET /catalog – returns the static catalog
  • GET /play/ – convenience route for catalog IDs

Jellyfin Plugin

Build & Package

dotnet build plugins/Streamarr/StreamarrPlugin.csproj -c Release

Artifacts appear in plugins/Streamarr/bin/Release/net8.0/ (StreamarrPlugin.dll, StreamarrPlugin.zip).

Update Manifest

Use the helper script to refresh version, checksum, and download URL before publishing:

python scripts/update_manifest.py \
    --manifest docs/manifest.json \
    --zip plugins/Streamarr/bin/Release/net8.0/StreamarrPlugin.zip \
    --version 0.1.1 \
    --target-abi 10.9.0.0 \
    --source-url https://github.com/<user>/streamarr/releases/download/v0.1.1/StreamarrPlugin.zip \
    --guid 68c71f7d-a14e-4f21-9e10-7c02f51ae7b0 \
    --name Streamarr \
    --category General \
    --owner <user>

Publish

  1. Upload StreamarrPlugin.zip and the updated manifest.json (e.g., GitHub Release or Pages)
  2. In Jellyfin: Dashboard -> Plugins -> Repositories -> Add the manifest URL
  3. Install "Streamarr" from the catalog
  4. Configure the resolver base URL/API key in the plugin settings page

Command Summary

python scripts/collect_links.py --site hdfilm
python scripts/collect_links.py --site dizibox --max-shows 50
python scripts/catalog_builder.py --chunk-size 5000 --skip-tmdb
python scripts/catalog_builder.py --skip-json --sqlite-db data/catalog.sqlite --skip-tmdb
python scripts/strm_generator.py
python backend/resolver/api.py
python scripts/update_manifest.py ...
dotnet build plugins/Streamarr/StreamarrPlugin.csproj -c Release

Troubleshooting

  • Playwright errors – Ensure playwright install firefox ran and system dependencies are present
  • TMDB enrichment skipped – Set TMDB_KEY or pass --tmdb-key to catalog_builder.py
  • Checksum mismatch in Jellyfin – Re-run scripts/update_manifest.py after re-packaging a ZIP
  • Plugin settings invisible – Rebuild the plugin after updating configPage.html (assets are embedded)
  • Docker resolver not starting – Run docker compose logs resolver for details
  • Expo app connection issues – Ensure Manager API is running on http://127.0.0.1:8000
  • Media playback not working – Check that expo-av is installed and properly configured

Credits & Notes

  • Scraper automation inspired by early Playwright POCs
  • Thanks to community projects bridging Debrid services with Jellyfin
  • Intended for personal/educational use only

Happy streaming!

About

HLS Stream Resolver

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages