Skip to content

Jellyfin and Emby Integration

Jump to bottom
khak1s edited this page Apr 29, 2026 · 2 revisions

Jellyfin & Emby Integration Guide

The Jellyfin and Emby integration brings media server analytics directly into Arr Dashboard, providing real-time stream monitoring, watch history, library statistics, and library cleanup — at full parity with the Plex integration, without requiring a Tautulli-equivalent layer.

Overview

With a Jellyfin or Emby instance connected, you get:

  • Now Playing — Real-time view of active streams with transcode/direct play status and bandwidth
  • Continue Watching / On Deck — Resume where you left off
  • Recently Added — Latest media added to your libraries
  • Watch History — Detailed viewing history captured every 5 minutes from active sessions
  • Statistics tab (v2.17.0+) — A dedicated Jellyfin tab in the Statistics page renders 14 cards at full parity with the Plex tab: 6 leaderboards (Top + Most Popular × movies/shows/music), transcode/bandwidth/codec/device breakdowns, user analytics, watch history, quality score, and bandwidth forecast. See Statistics for the full surface.
  • Library Enrichment — Watch status overlaid on library items throughout the dashboard
  • Library Cleanup — Watch-aware cleanup rules using Jellyfin/Emby data

Jellyfin and Emby expose session data directly through their own APIs — no separate analytics service (like Plex's Tautulli) is needed. The Jellyfin Statistics tab works out of the box once an instance is configured; leaderboards populate as new sessions are captured.

Jellyfin and Emby Share the Same Backend

Because Emby and Jellyfin descend from the same codebase, Arr Dashboard treats them as a single unified integration:

  • The same backend client handles both services
  • The same connection test, cache layer, and dashboard widgets work transparently for each
  • Adding both Jellyfin and Emby side-by-side is fully supported; multi-instance aggregates combine data from both

You choose the service type (Jellyfin or Emby) when adding a new instance — everything else is handled for you.

Prerequisites

Before setting up the integration:

  1. A running Jellyfin or Emby server
  2. An API key from your Jellyfin/Emby instance (admin access required for some features)
  3. Network connectivity between Arr Dashboard and the media server

Configuration

Adding a Jellyfin Instance

  1. Log in to Arr Dashboard
  2. Go to Settings → Services
  3. Click Add Instance
  4. Select Jellyfin as the service type
  5. Enter:
    • Name - A friendly label (e.g., "Main Jellyfin")
    • Base URL - Your Jellyfin server URL (e.g., http://192.168.1.100:8096)
    • API Key - Your Jellyfin API key
  6. Click Test Connection to verify
  7. Click Save

Finding your Jellyfin API key:

  1. Log in to Jellyfin as an admin
  2. Navigate to Dashboard → API Keys
  3. Click the + button to create a new API key
  4. Copy the generated key

Adding an Emby Instance

  1. Go to Settings → Services
  2. Click Add Instance
  3. Select Emby as the service type
  4. Enter:
    • Name - A friendly label (e.g., "Main Emby")
    • Base URL - Your Emby server URL (e.g., http://192.168.1.100:8096)
    • API Key - Your Emby API key
  5. Click Test Connection to verify
  6. Click Save

Finding your Emby API key:

  1. Log in to Emby as an admin
  2. Navigate to Settings → General (or Advanced → API Keys on some versions)
  3. Create a new API key
  4. Copy the generated key

Tip: Jellyfin and Emby both default to port 8096. If you changed the port, use the value from your media server settings.

Features

Now Playing Widget

The Now Playing widget on the Dashboard shows all active Jellyfin/Emby streams in real time.

Information Description
User Who is watching
Title What they are watching (movie, episode)
Progress Playback progress bar
Stream Type Direct Play, Direct Stream, or Transcode
Quality Resolution and bitrate
Bandwidth Current bandwidth usage
Device Device name and client application

Session snapshots refresh on a short interval so active streams stay current across multiple clients.

Continue Watching / On Deck

Shows in-progress items and next-up episodes for each user. Data is pulled directly from the Jellyfin/Emby on-deck APIs.

  • Partially-watched movies and in-progress series
  • Episode-level progress for TV series
  • Per-user on-deck lists when multiple users are active

Recently Added

Displays the latest media added to your libraries:

  • Movies, TV shows, and episodes recently added
  • Organized by library section
  • Includes poster artwork and metadata

Watch History

Full watch history is available for every connected user without requiring a separate analytics service:

  • Per-item play history with timestamps
  • Watch count per item
  • Platform and device information per play
  • Last watched date

This history is used throughout the dashboard for library enrichment and cleanup rule evaluation.

Analytics

The analytics suite mirrors the Plex integration and surfaces deep insight into media server usage.

User Analytics

  • Per-user watch statistics
  • Most active users
  • Watch time trends

Device Analytics

  • Breakdown of devices and clients used for playback
  • Device usage frequency

Transcode Analytics

  • Direct Play vs. Direct Stream vs. Transcode ratios
  • Transcode decision reasons
  • Hardware acceleration usage

Codec Analytics

  • Video and audio codec distribution across your library
  • Codec usage in active streams

Quality Score

  • Library quality scoring based on resolution, codec, and bitrate
  • Identify low-quality items that may benefit from upgrades

Bandwidth Forecast

  • Historical bandwidth usage patterns
  • Forecasted bandwidth needs based on usage trends

Episode Completion

  • Per-series episode completion tracking
  • Per-user series progress

Library Enrichment

When a Jellyfin or Emby instance is connected, watch status information is overlaid on library items throughout the dashboard:

  • Library page - Items show watched/unwatched badges
  • Watch count - How many times an item has been played
  • Last watched date - When the item was most recently viewed
  • Watched by - Which users have watched the item

This enrichment data is also available to the Library Cleanup feature for making watch-aware decisions.

Library Cleanup Rules

Jellyfin/Emby integration unlocks the following watch-aware cleanup rule evaluators:

Evaluator Description
Last Watched Items not watched for longer than a threshold
Watch Count Items below or above a play count threshold
On Deck Skip or prioritize items currently on deck
User Rating Filter by user rating
Watched By Match items watched by specific users
Added At Filter by when the item was added to the library
Episode Completion Match series where episode completion meets a threshold

See Library Cleanup for how to combine these with other cleanup rules.

Cache Management

Arr Dashboard caches Jellyfin/Emby library metadata and session data to avoid excessive API calls.

Cache Types

Cache Source Purpose
JellyfinCache Jellyfin/Emby Library metadata (titles, ratings, file info)
JellyfinEpisodeCache Jellyfin/Emby Episode-level data for series

Cache Refresh

  • Caches refresh automatically on a schedule
  • Cache Health status is tracked via CacheRefreshStatus
  • You can trigger a manual cache refresh from the dashboard
  • Stale caches trigger a CACHE_REFRESH_STALE notification event (if notifications are configured)

Manual Refresh

  1. Navigate to the Jellyfin/Emby analytics or library section
  2. Click the Refresh button to force a cache update
  3. Wait for the refresh to complete (large libraries may take a moment)

Best Practices

One API Key Per Server

Rather than reusing a personal API key, create a dedicated API key in Jellyfin/Emby for Arr Dashboard. This makes it easy to revoke access without affecting your personal clients.

Use LAN Addresses

If Jellyfin/Emby and Arr Dashboard run on the same machine or LAN, use the internal address (e.g., http://192.168.1.100:8096) rather than any remote access URL. LAN access is faster and avoids depending on external DNS or reverse proxies.

Large Library Initial Sync

The first cache refresh on a large library (10,000+ items) can take several minutes. Let it complete before navigating between analytics tabs so every chart has data to render.

Combining with Plex

Running both Plex and Jellyfin/Emby side-by-side is fully supported. Multi-instance analytics combine data across media servers, and the dashboard's incognito mode anonymizes server names and user identifiers in screenshots.

Troubleshooting

"Cannot connect to Jellyfin/Emby"

Causes:

  • Incorrect Base URL or API key
  • Server is not running or unreachable from Arr Dashboard's network
  • API key was revoked or regenerated

Solutions:

  1. Verify the URL is reachable from the Arr Dashboard host
  2. Confirm the API key is still valid by listing it in the Jellyfin/Emby admin UI
  3. Test the connection via Settings → Services → Test Connection
  4. Check firewall rules allow traffic on port 8096 (or your custom port)

"Now Playing shows no streams"

Causes:

  • No one is currently watching
  • Session snapshot not yet captured
  • Server connection is stale

Solutions:

  1. Start a playback on Jellyfin/Emby to verify
  2. Wait for the next session refresh cycle
  3. Test the server connection in Settings → Services

"Analytics charts are empty"

Causes:

  • No watch history yet (new or lightly-used server)
  • Cache not yet populated
  • API key lacks permission to read analytics data

Solutions:

  1. Allow time for watch history to accumulate on your server
  2. Trigger a manual cache refresh
  3. Verify the API key is from an admin account (required for some analytics endpoints)

"Artwork is not loading"

Causes:

  • Image proxy cannot reach the media server
  • Reverse proxy stripping required headers
  • Mixed HTTP/HTTPS content blocking in the browser

Solutions:

  1. Ensure the Base URL uses the same protocol as Arr Dashboard (HTTP or HTTPS)
  2. Confirm the API key has admin access (image proxy requires it)
  3. Review reverse proxy rules to ensure Authorization and X-Emby-Token headers are passed through

"Watched items appearing as unwatched"

Causes:

  • Cache has not refreshed since the watch event
  • Account used for the API key does not see other users' watch status
  • Multi-user library with restricted user permissions

Solutions:

  1. Trigger a manual cache refresh
  2. Use an admin-level API key so watch status is visible across users
  3. Verify user permissions in Jellyfin/Emby allow the API user to see shared libraries

API Reference

Server Info

GET /api/jellyfin/info/:instanceId

Now Playing

GET /api/jellyfin/now-playing/:instanceId

On Deck

GET /api/jellyfin/on-deck/:instanceId

Recently Added

GET /api/jellyfin/recently-added/:instanceId

Watch History

GET /api/jellyfin/history/:instanceId

Watch Enrichment

GET /api/jellyfin/watch-enrichment/:instanceId

Cache Management

# Cache health status
GET /api/jellyfin/cache/health

# Trigger cache refresh
POST /api/jellyfin/cache/refresh/:instanceId

Analytics Endpoints

# User analytics
GET /api/jellyfin/analytics/users/:instanceId

# Device analytics
GET /api/jellyfin/analytics/devices/:instanceId

# Transcode analytics
GET /api/jellyfin/analytics/transcode/:instanceId

# Codec analytics
GET /api/jellyfin/analytics/codec/:instanceId

# Bandwidth analytics
GET /api/jellyfin/analytics/bandwidth/:instanceId

# Quality score
GET /api/jellyfin/analytics/quality-score/:instanceId

# Bandwidth forecast
GET /api/jellyfin/analytics/forecast/:instanceId

# Episode completion
GET /api/jellyfin/analytics/episode-completion/:instanceId

Note: All Jellyfin routes also serve Emby instances — the backend automatically routes requests based on the service type of the instance ID.

Clone this wiki locally