Jellyfin × TorBox × PotPlayer
Windows 10/11 · PowerShell 7+ · MIT

Direct-stream 4K from TorBox into PotPlayer.

Jellyfin library + TorBox cloud + PotPlayer playback, on Windows, with no transcoding. Cloud torrents mount as local drives, Jellyfin keeps metadata, resume and Next-Up, and PotPlayer direct-streams full-season 4K through a local proxy. A loopback-only panel owns start/stop, health and Play-in-PotPlayer.

Get it on GitHub Read the docs
Jellyfin 10.xTorBoxPotPlayer x64rclone VFSPython 3.11Loopback-only by default
A 4K title streaming from TorBox through the local proxy into PotPlayer Animated diagram: the TorBox cloud hands a fresh CDN link to the local proxy on port 8888, the proxy serves a never-expiring local URL to PotPlayer, which plays a 4K title with no transcoding. A sync tracker posts progress to Jellyfin every 5 seconds and marks the episode Played at 80 percent. TorBox cloud 4K REMUX · CDN fresh CDN link per request torbox-proxy 127.0.0.1:8888 302 → fresh CDN stable URL HTTP Range PotPlayer x64 · direct stream 4K no transcoding Demo title · S01E04 resume ✓ Played · 80% Jellyfin :8096 library · resume · Next-Up sync-tracker: progress tick every 5 s marks Played at 80% so Next-Up advances
Never-expiring local URLsThe proxy mints a fresh CDN link per request, so stale links do not break playback.
Resume tick every 5 sThe sync tracker posts progress to Jellyfin while PotPlayer plays.
Played at 80%Next-Up keeps working on every Jellyfin client.
5 sprogress ticks back to Jellyfin
80%marks an episode Played
6loopback ports (services + rclone RC)
9suites in the regression test harness
Features

Everything between the cloud and the couch.

Six moving parts, one chain. Each one is a script or service in the repo, so you can read exactly what runs.

TorBox proxy

Stable local URLs that never expire. It refreshes short-lived CDN links per request and caches mylist to stay fast.

server/torbox-proxy.py · :8888

One-click play

Jellyfin Play hands a potplayer:// link to Windows. The launcher picks the right file, refreshes stale cache and opens the full season at your resume point.

potplayer-launcher.ps1 · bridge :18099

Resume sync

Posts progress every 5 s and marks Played at 80%, so Next-Up keeps working on every client.

potplayer-sync-tracker.ps1

Watch console

A live tail of launcher and playback ticks, episode hints and 80% Played events.

show-playback-log.ps1

Control panel

Loopback-only Start / Stop / Restart, status, metrics and Play buttons. No console juggling.

control-panel/control_panel.py · :18080

Supervisor

Ordered start (mounts, proxy, bridge, Jellyfin, panel) plus a watchdog, mutex and PID files.

supervisor.ps1 · -Mode Run / Start / Stop / Status
Optional: Google Drive .strm sync FULLCACHE=1 full-file prefetch Full-season .dpl with /seek= resume Nagios-style check_*.ps1 probes (-AsJson) rclone MCP bridge Prometheus /metrics on the proxy
Press play

One click, end to end.

This is the repo's own walkthrough of a single episode, from the panel to the progress bar and back to Jellyfin.

# the whole loop, in your browser
http://127.0.0.1:18080   # Start all
http://127.0.0.1:8096    # Jellyfin: Play-in-PotPlayer

  1. Start everything

    Open the panel and click Start all. Mounts come first, then proxy :8888, bridge :18099, Jellyfin :8096 and the panel itself.

  2. Pick a show in Jellyfin

    Metadata, posters and Next-Up come from TMDB plus the .strm scan.

  3. Press Play-in-PotPlayer

    A potplayer:// link is built and handed to Windows.

  4. Launcher resolves

    It maps the Jellyfin item to a .strm on T:\, refreshes a stale VFS through rclone RC :5572 if needed, and picks the TorBox CDN or the :8888 proxy fallback.

  5. PotPlayer opens the season

    A full-season UTF-16 .dpl loads with your episode queued and /seek= set to your Jellyfin resume position.

  6. Watch the bar fill

    Direct HTTP from :8888/torbox/... 302s to a fresh CDN URL, so 4K REMUX direct-streams with a full-cache seek bar.

  7. Resume stays in sync

    Progress is POSTed every 5 s and the episode is marked Played at 80%. Pause in Jellyfin Web, resume in PotPlayer, and Next-Up advances.

How it works

One required chain, supervised end to end.

Every play follows the same path. The proxy hides expiring CDN links behind stable loopback URLs; the sync tracker closes the loop back to Jellyfin.

Architecture: TorBox, rclone VFS, Jellyfin, bridge, launcher, proxy and PotPlayerSeven numbered stages: TorBox cloud, rclone VFS mount on T:, Jellyfin on 8096, PotPlayer bridge on 18099, the launcher, the TorBox proxy on 8888, and PotPlayer x64. The proxy asks TorBox for a fresh CDN link, and the sync tracker posts progress from PotPlayer back to Jellyfin every five seconds. A supervisor watchdog and the control panel on 18080 sit underneath.proxy asks TorBox for a fresh CDN linkexpiring tokens stay hidden behind stable loopback URLssync-tracker: progress every 5 s, Played at 80%POST /Sessions/Playing/Progress, so Next-Up advances1TorBox cloudtorrent / UsenetCDN links2rclone VFST:\ mountRC :55723Jellyfin:8096 · TMDBresume · Next-Up4PotPlayer Bridge:18099health gate5LauncherGUID resolvestale-VFS refresh6Proxy:8888302 → fresh CDN7PotPlayer x64full-season .dpl/seek= resumesupervisor.ps1 watchdog15 s checks · mutex · PID files · aborts on first failed gatestart order: mounts → proxy → bridge → Jellyfin → panelStop reverses the orderControl panel :18080Start all · health · metrics · Play Architecture: TorBox, rclone VFS, Jellyfin, bridge, launcher, proxy and PotPlayerSeven numbered stages: TorBox cloud, rclone VFS mount on T:, Jellyfin on 8096, PotPlayer bridge on 18099, the launcher, the TorBox proxy on 8888, and PotPlayer x64. The proxy asks TorBox for a fresh CDN link, and the sync tracker posts progress from PotPlayer back to Jellyfin every five seconds. A supervisor watchdog and the control panel on 18080 sit underneath.proxy asks TorBox: fresh CDN linksync-tracker: tick every 5 s · Played at 80%1TorBox cloudtorrent / Usenet cloud · CDN links2rclone VFST:\ mount · RC :55723Jellyfin:8096 · TMDB · resume · Next-Up4PotPlayer Bridge:18099 · health gate5LauncherGUID resolve · stale-VFS refresh6Proxy:8888 · 302 → fresh CDN7PotPlayer x64full-season .dpl · /seek= resumesupervisor.ps1 watchdog (15 s)mounts → proxy → bridge → Jellyfin → panelControl panel :18080 · Stop reverses the order

Proxy leg

Hides expiring CDN tokens behind stable loopback URLs. Only the short resolver result is cached; expiry becomes a redirect.

Bridge leg

Exposes /health and /status and refuses to start unless the proxy is healthy. The supervisor and panel enforce the same gate.

Panel leg

Merges live process scans with proxy /metrics, and runs bulk Start / Restart in mount-first order with health waits. Stop reverses it.

Full service map, session model and boot order: ARCHITECTURE.md. Day-2 operations: RUNBOOK.md.

Control panel & watch console

Green means go.

Service cards show a process match plus a real health probe, so a green badge maps to something that is actually running.

Illustrative mockups built from the repo docs, with demo values. The repo has no screenshots committed yet; its capture checklist lives in assets/screenshots/PLACEHOLDER.md. Panel cards and endpoints are documented in docs/panel.md.

Quick start

Installed in about 30 seconds.

For a fresh PC with the prerequisites already installed: PotPlayer x64, rclone + WinFsp, Python 3.11, Jellyfin 10.x files and a TorBox account. Pick one path.

git clone https://github.com/MHJoy99/jellyfin-torbox-potplayer-stack.git
cd jellyfin-torbox-potplayer-stack
pwsh -File install.ps1 -WhatIf
pwsh -File install.ps1

install.ps1 prompts for TORBOX_API_KEY (masked), validates it with a live API call, initializes the F:\Jellyfin directory layout, registers the potplayer:// protocol handler and the MediaStackSupervisor scheduled task, starts the stack and runs port health probes (:8888, :18099, :18080, :8096). Switches (-WhatIf, -Uninstall, -SkipTasks, -Portable, -TorboxApiKey, -KeyScope) are in docs/install.md.

pwsh -File setup-wizard.ps1

Step-by-step: masked key entry, library root folders, Jellyfin connection test, PotPlayer auto-detection, rclone configuration, port availability and playback mode, with a dry-run preview before anything is applied. Supports -Resume and -NonInteractive.

# Run component installers in dependency order:
pwsh -File install-all.ps1

# Perform one-time ordered service startup (mounts -> proxy -> bridge -> Jellyfin -> panel):
pwsh -File supervisor.ps1 -Mode Start

Full dependency order and verification steps live in docs/install.md and docs/quickstart.md.

Then open the panel

http://127.0.0.1:18080

Click Start all, wait for green, open Jellyfin at http://127.0.0.1:8096, press Play-in-PotPlayer. The full-season playlist opens at your resume point.

Secrets stay in the environment

# Persistent (survives reboot, read live by supervisor):
[Environment]::SetEnvironmentVariable("TORBOX_API_KEY", "<your-key>", "User")
$env:TORBOX_API_KEY = [Environment]::GetEnvironmentVariable("TORBOX_API_KEY", "User")

# Verify without leaking the key:
pwsh -File check_status.ps1 -AsJson; $LASTEXITCODE  # expect 0
Invoke-RestMethod http://127.0.0.1:8888/health
Configuration & ports

All secrets from the environment.

No tokens in files, no .env committed. Every service binds loopback only by default.

Environment variables

VariableRequiredDefault / use
TORBOX_API_KEYYesEmpty: the proxy refuses to start. Re-read live from the Machine/User registry by the supervisor.
JELLYFIN_URLNohttp://localhost:8096
JELLYFIN_USER / JELLYFIN_PASSWORDFor health checksUsed by check_status.ps1 and check_user_views.ps1; never logged.
JELLYFIN_API_KEYNoAutomation: gdrive-library-sync.ps1 for POST /Library/Refresh.
FULLCACHENo0. Set 1 to prefetch the full file for a solid seek bar.
RCLONE_EXE / RCLONE_CONFIGNoFor the rclone MCP bridge; the real config file is untracked.

Ports

PortService
8888TorBox proxy: /health, /torbox/... 302 to fresh CDN, /mylist, /metrics
18099PotPlayer bridge: /health, /status; health gate before every launch
18080Control panel: status, metrics, playback buttons
8096Jellyfin HTTP: web UI, /System/Info/Public, /Videos/{id}/stream
5572rclone RC, TorBox mount (vfs/refresh, core/stats)
5573rclone RC, Google Drive mount
Performance notes

Pre-tuned for high-bitrate 4K.

Defaults aimed at residential gigabit connections, taken from the repo's mount script and proxy.

rclone VFS mount

--vfs-cache-mode full with a 25G cache cap, 12h max age and 30G min free space. Chunks start at 32M (fast first byte) and double to 256M with 128M read-ahead. Directory cache 15m. Keep the cache on an NVMe SSD.

mount-torbox.ps1

Local proxy

Fresh CDN links by 302 with a token-bucket rate limiter, a shared mylist cache (10 minutes, singleflight coalescing) and HTTP/1.0 progressive streaming to avoid client hangs.

server/torbox-proxy.py

Seek bar & prefetch

PotPlayer gets progressive HTTP straight from the proxy for instant seeking. Set $env:FULLCACHE = "1" before launch to cache the full file for ultra-high-bitrate REMUX.

~20 GB disk headroom suggested
Who it's for

Five people this stack was built for.

From the repo's USECASES.md. Each plays only files they own or have the right to play.

The 4K remux fan

Direct-play large files, instant seeking, no stutter on high bitrates and no forced transcoding.

The anime watcher

Correct episode order, fast Next-Up and reliable subtitles, preserved on direct play.

The family server

Simple start and stop, green means go, and per-user resume and watched state.

The debrid migrant

Familiar instant links with your own catalog and history, and a proxy that keeps links fresh.

The tinkerer

Observable services: Prometheus metrics, JSON health output, an allowlisted automation bridge, assert-based smoke tests.

Windows-first by design

Windows 10/11 x64, Jellyfin 10.x, PotPlayer x64, rclone VFS. Linux, macOS, Docker, Plex and Emby are out of scope.

Comparison

An honest map.

From the repo's COMPARISON.md. Every option is good at something; this stack is tuned for direct-play control on a Windows home server with cloud-backed libraries.

CapabilityThis stackPlexEmbyPlain JellyfinInfuse
License and costMIT, free, self-hostedFreemium with paid tierFreemium with paid PremiereFree and open sourcePaid app with free tier
Source availabilityFully openProprietary serverProprietary with some open clientsFully openProprietary
Setup effortManual, guided by installer and runbookGuided, easiest for beginnersGuided, easyManual, moderateVery easy on Apple devices
4K remux direct-playTuned for it via external player and local proxyYes, depends on client and server settingsYes, depends on client and server settingsYes, depends on clientExcellent on Apple hardware
External player choiceYes, first-class queue and resumeLimited, client dependentLimited, client dependentBrowser and app clients, DLNANatively its own player
Cloud and debrid style librariesBuilt-in mount plus sync workflowVia add-ons and manual mountsVia plugins and manual mountsVia manual mounts and pluginsVia cloud integrations
Local proxy with metricsIncluded with cache and Prometheus endpointNot includedNot includedNot includedNot included
Web control panelIncluded local panel for status and playbackHosted dashboard plus appsHosted dashboard plus appsBuilt-in dashboardNative app UI
Best fitTinkerers who want control and logsHouseholds wanting polished appsHouseholds wanting live TV and appsSelf-hosters wanting open basicsApple-first viewers wanting polish

No option wins everywhere. If another tool fits you better, that is a good outcome too (the repo's words).

Roadmap

What's landed, what's planned.

VERSION is 1.0.0 with no newer tag cut. Work since then sits under [Unreleased] in the changelog. Items marked Planned are roadmap only; v1.1, v1.2 and v2.0 are planning milestones, not releases.

Landed (unreleased)
  • One-click installer install.ps1
  • Setup wizard with resume and headless modes
  • 12-file docs site under docs/
  • Windows CI and secret scanning
  • 9-suite regression harness
  • Rescued curation tools
  • Idempotent TorBox mount guard
  • Release automation toolkit
Planned · v1.1
  • Playback timeline export (CSV)
  • One-command health bundle
  • Launcher resume accuracy pass
  • Quickstart polish with annotated screenshots
Planned · v1.2
  • Multi-user play-state isolation
  • Proxy cache-hit tiles in the panel
  • Scheduled backup and DB vacuum
  • Cross-platform launcher research
  • Stdlib subtitle normalizer and metrics exporter
Planned · later
  • One-click GUI installer with preflight checks
  • Offline-first metadata cache
  • Read-only mobile companion view
  • Community translation workflow
  • Stdlib Jellyfin API SDK

The README's older wish list also mentions Grafana dashboards and a Docker / Caddy / Cloudflared edge profile for remote access. Both are roadmap, not current.

Use responsibly. This project is neutral tooling that connects services you already use. Play only media you own or have the right to access, and respect the terms of service of TorBox, Jellyfin, TMDB and any other service you connect.

The panel and proxy bind to loopback and have no login by design. Do not expose them to your network without adding authentication and TLS. Keep your TorBox key in environment variables, never in files, issues or commits.

FAQ

Questions, answered from the repo.

What does this stack do that plain Jellyfin cannot do on Windows?

It mounts TorBox and Google Drive as local drives with rclone, serves fresh CDN URLs through a local proxy on port 8888, and launches PotPlayer with a full-season playlist at your exact resume point. Jellyfin keeps the library, metadata and watched state, while PotPlayer handles 4K direct-stream playback without transcoding or browser codec limits.

Where do I store my TorBox API key so it never leaks to GitHub?

Store it only as a Windows environment variable named TORBOX_API_KEY at User or Machine scope, then restart the proxy and supervisor so child processes inherit it. Never paste the key into scripts, configs, issues or commits. The proxy refuses to start when the variable is empty, and rotation means updating the environment plus registry and restarting the services.

Why does PotPlayer start instantly while Jellyfin Web sometimes buffers on the same file?

Jellyfin Web often remuxes or transcodes high-bitrate 4K REMUX files because of browser codec and subtitle limits, which costs CPU and adds buffering. PotPlayer direct-streams the original file over HTTP from the local TorBox proxy, so it seeks instantly with a full-cache bar and uses negligible server CPU while preserving the original video, audio and subtitle tracks.

How do resume and watched status stay in sync between PotPlayer and Jellyfin?

A lightweight tracker posts the playback position to the Jellyfin Sessions Playing Progress endpoint every five seconds while PotPlayer runs. When you pass eighty percent, it marks the episode Played, so Next-Up advances and other clients resume correctly. You can verify it live in the watch console, show-playback-log.ps1.

What should I do when the T drive looks stale or libraries are empty after a reboot?

Start the mounts before Jellyfin, because a scan that races a downed VFS indexes stub files and empty views. Verify the drive paths exist, refresh the rclone RC cache on ports 5572 and 5573, confirm proxy health on port 8888, then trigger a Jellyfin library refresh. The included check scripts return Nagios-style exit codes and JSON for fast automated checks.

What do I need installed, and which systems are supported?

Windows 10 or 11 x64 with PowerShell 7+, Jellyfin Server 10.x, PotPlayer x64 with the potplayer protocol registered, rclone with WinFsp and TorBox and Google Drive remotes, a TorBox API key, and Python 3.11 for the proxy, bridge and panel. Linux, macOS, Docker, Plex, Emby and remote hosting are not in scope. Google Drive sync is optional and TorBox is the primary cloud.

Is it safe to expose the panel or proxy to my local network?

No. Both bind to localhost with no login by design, so anyone on the network could control playback or services. Do not expose them without adding authentication and TLS. A Caddy or Cloudflared edge profile for secure remote access is on the roadmap, not part of the current release.

How do I install, update or remove it?

Clone the repository and run pwsh -File install.ps1, using -WhatIf first to preview every planned action. The guided alternative is setup-wizard.ps1. To update, stop the stack, pull the latest branch, re-run the installer and re-run the health checks. To remove it, run install.ps1 with -Uninstall. The full lifecycle is in docs/install.md.

Is it free, and what can I use it for?

Yes. It is MIT licensed and free to use, modify and distribute, with no warranty. You need your own Jellyfin install, PotPlayer, rclone and a TorBox account. Use it responsibly: play only media you own or have the right to access, and respect the terms of service of TorBox, Jellyfin and any other service you connect. It is not affiliated with those projects.

More by MHJoy99

Other open-source tools.

CCUsageXClaude Code usage dashboard ZipStream-HubStream video from remote ZIPs mirror-leech-telegram-bot-fuseTelegram mirror/leech bot joyvoiceWindows voice typing with Gemini

See everything on the MHJoy99 GitHub profile.

Skip the transcode. Just press Play.

Free, MIT licensed and open source. Star the repo, open an issue, or send a small focused PR.

Get it on GitHub Open an issue