Skip to content
numbrs docs

Jellyfin

The Jellyfin integration pulls play history, library stats, and active session data from your Jellyfin server and syncs it to your numbrs dashboard. Since your Jellyfin server is on your local network, a collector script runs on your machine and pushes the data to Supabase.

Estimated setup time: 10 minutes

What it tracks

Section titled “What it tracks”
  • Play history — what was played, when, by which user, and how long
  • Library stats — item counts by media type (movies, shows, music, etc.)
  • User activity — sessions, last-seen info, and active stream count

Prerequisites

Section titled “Prerequisites”
  • A running Jellyfin server (any version)
  • A Jellyfin API key (see below)
  • Python 3
  • Your numbrs credentials — see Integrations Overview for where to find them

Get a Jellyfin API key

Section titled “Get a Jellyfin API key”
  1. Log into your Jellyfin admin dashboard
  2. Go to Dashboard → Advanced → API Keys
  3. Click + to create a new key
  4. Name it numbrs and save
  5. Copy the API key

Run the collector

Section titled “Run the collector”

The collector script is available in the numbrs app under Integrations — navigate there and find the Jellyfin section to download it. You can also find it in the repo at collectors/jellyfin.sh.

Run it manually first to verify everything works:

Terminal window
NUMBRS_SUPABASE_URL="https://YOUR_PROJECT.supabase.co" \
NUMBRS_SUPABASE_SERVICE_KEY="your-service-role-key" \
NUMBRS_OWNER_ID="your-user-id" \
JELLYFIN_URL="http://192.168.1.x:8096" \
JELLYFIN_API_KEY="your-jellyfin-api-key" \
bash ~/numbrs-jellyfin-collector.sh

You should see output confirming how many records were synced.

Set up cron

Section titled “Set up cron”

Run the collector every 15 minutes — play history doesn’t need 5-minute granularity:

*/15 * * * * NUMBRS_SUPABASE_URL=https://YOUR_PROJECT.supabase.co NUMBRS_SUPABASE_SERVICE_KEY=your-key NUMBRS_OWNER_ID=your-id JELLYFIN_URL=http://192.168.1.x:8096 JELLYFIN_API_KEY=your-jellyfin-key bash /Users/YOUR_USERNAME/numbrs-jellyfin-collector.sh >> /tmp/numbrs-jellyfin.log 2>&1

Troubleshooting

Section titled “Troubleshooting”

“Connection refused” when running the script

Check that JELLYFIN_URL is correct and that your Jellyfin server is reachable at that address and port. Try curl http://192.168.1.x:8096/System/Info/Public — if that works, the URL is right.

No data appearing

Verify the API key is correct. Check /tmp/numbrs-jellyfin.log for errors after the cron runs.

Script can’t find the collector

Download the script from the Integrations page in the numbrs app, or copy it from collectors/jellyfin.sh in the GitHub repo.

Next steps

Section titled “Next steps”