# Jellyfin — Free Software Media System

> Jellyfin is a free, open-source media server for streaming movies, TV shows, music, and live TV. Self-hosted Plex/Emby alternative with no premium or tracking.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
docker run -d --name jellyfin 
  -p 8096:8096 
  -v jellyfin-config:/config 
  -v jellyfin-cache:/cache 
  -v /path/to/media:/media 
  jellyfin/jellyfin:latest
```

Open `http://localhost:8096` — complete the setup wizard, point to your media folders, and start streaming.

## Intro

**Jellyfin** is a free, open-source media system for managing and streaming your personal media collection. It serves as a completely free alternative to Plex and Emby, with no premium tiers, no tracking, no central authentication, and no restrictions — just a powerful media server you fully control.

With 50.2K+ GitHub stars and GPL-2.0 license, Jellyfin has grown into the leading truly-free media server solution, supported by an active community of developers and users.

## What Jellyfin Does

Jellyfin provides a complete home media experience:

- **Movies & TV Shows**: Stream your movie and TV library with metadata, artwork, subtitles, and trailers
- **Music**: Music streaming with artist bios, album art, lyrics, and playlist management
- **Live TV & DVR**: IPTV and HDHomeRun integration with EPG guide and recording
- **Books & Comics**: eBook and comic reader with EPUB and CBZ/CBR support
- **Photos**: Photo gallery with timeline view
- **Hardware Transcoding**: Intel QSV, NVIDIA NVENC, AMD AMF, and VA-API for efficient video transcoding
- **Multi-user**: Separate profiles with parental controls and content restrictions
- **Remote Access**: Stream anywhere via reverse proxy or VPN

## Architecture

```
┌─────────────────┐     ┌──────────────┐     ┌──────────────┐
│ Clients         │────▶│  Jellyfin    │────▶│  Media Files │
│ Web / Apps /    │     │  Server      │     │  (Movies,    │
│ Smart TV        │     │  (C#/.NET)   │     │  Music, etc) │
└─────────────────┘     └──────┬───────┘     └──────────────┘
                               │
                        ┌──────┴───────┐
                        │  SQLite DB   │
                        │  (Metadata)  │
                        └──────────────┘
```

## Self-Hosting

### Docker Compose

```yaml
services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    ports:
      - "8096:8096"
    volumes:
      - jellyfin-config:/config
      - jellyfin-cache:/cache
      - /mnt/media/movies:/media/movies:ro
      - /mnt/media/tv:/media/tv:ro
      - /mnt/media/music:/media/music:ro
    environment:
      JELLYFIN_PublishedServerUrl: http://192.168.1.100:8096
    # GPU passthrough for hardware transcoding
    # devices:
    #   - /dev/dri:/dev/dri  # Intel QSV / VA-API
    restart: unless-stopped

volumes:
  jellyfin-config:
  jellyfin-cache:
```

### Media Organization

```
/media/
├── movies/
│   ├── Inception (2010)/
│   │   └── Inception (2010).mkv
│   └── The Matrix (1999)/
│       └── The Matrix (1999).mp4
├── tv/
│   ├── Breaking Bad/
│   │   ├── Season 01/
│   │   │   ├── Breaking Bad S01E01.mkv
│   │   │   └── Breaking Bad S01E02.mkv
│   │   └── Season 02/
│   └── The Office/
└── music/
    ├── Artist Name/
    │   └── Album Name/
    │       ├── 01 - Track.flac
    │       └── 02 - Track.flac
```

## Client Apps

| Platform | App |
|----------|-----|
| Web | Built-in web client |
| Android | Jellyfin for Android |
| iOS | Jellyfin for iOS / Swiftfin |
| Android TV | Jellyfin for Android TV |
| Apple TV | Swiftfin |
| Fire TV | Jellyfin for Fire TV |
| Roku | Jellyfin for Roku |
| Desktop | Jellyfin Media Player (MPV-based) |
| Samsung/LG TV | Web client via browser |

## Key Features

### Hardware Transcoding

Enable GPU-accelerated transcoding for smooth streaming:

```yaml
# Intel QSV (most common for home servers)
devices:
  - /dev/dri:/dev/dri

# NVIDIA
runtime: nvidia
environment:
  - NVIDIA_VISIBLE_DEVICES=all
```

Supported codecs: H.264, H.265/HEVC, VP9, AV1 (depending on GPU)

### Plugins

Jellyfin has a plugin system for extending functionality:
- **OpenSubtitles**: Auto-download subtitles
- **Fanart**: Enhanced artwork
- **Trakt**: Sync watch history
- **LDAP**: Enterprise authentication
- **Webhook**: Notifications on events

## Jellyfin vs Alternatives

| Feature | Jellyfin | Plex | Emby |
|---------|----------|------|------|
| Open Source | Yes (GPL-2.0) | No | Partially |
| Cost | Free | Free + Premium ($5/mo) | Free + Premium ($5/mo) |
| HW Transcoding | Free | Plex Pass only | Emby Premiere |
| Live TV | Free | Plex Pass only | Emby Premiere |
| Central auth | No (self-managed) | Required | Optional |
| Tracking | None | Usage data | Usage data |
| Mobile sync | Via plugins | Plex Pass | Emby Premiere |

## FAQ

**Q: Jellyfin or Plex?**
A: Plex is easier to start with and has a more polished client experience, but paid features unlock hardware transcoding and advanced functionality. Jellyfin is fully free and open source with no central auth server, but initial setup is a bit more involved. Pick Jellyfin for privacy and autonomy; pick Plex for ease of use.

**Q: What server specs do I need?**
A: Direct Play needs very little. For transcoding, aim for at least an Intel i5 or a machine with a dGPU. QSV transcoding on Intel 8th-gen+ is highly efficient and can handle 3–5 concurrent transcode streams.

**Q: 4K HDR support?**
A: 4K Direct Play is supported. HDR transcoding (tone mapping) needs a capable GPU (NVIDIA or Intel 10th-gen+ recommended). If the client supports 4K HDR direct play, the server doesn't need to transcode.

## Source & Thanks

- GitHub: [jellyfin/jellyfin](https://github.com/jellyfin/jellyfin) — 50.2K+ ⭐ | GPL-2.0
- Website: [jellyfin.org](https://jellyfin.org)

---
Source: https://tokrepo.com/en/workflows/jellyfin-free-software-media-system-78fb00a4
Author: Script Depot