# Media Server (Jellyfin) in Docker

Deploy Jellyfin for live TV, movies, and media streaming to smart TVs.

## When to Use

User wants to:
- Watch live TV / IPTV on a smart TV
- Stream movies/shows from a local server
- Serve media to multiple devices on the LAN

## Docker Deployment

```bash
mkdir -p /home/$USER/jellyfin/{config,cache,media,movies,tvshows,live-tv}

cat > /home/$USER/jellyfin/docker-compose.yml <<'EOF'
services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    network_mode: host
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/config
      - ./cache:/cache
      - ./media:/media
      - ./movies:/media/movies
      - ./tvshows:/media/tvshows
      - ./live-tv:/media/live-tv
    restart: unless-stopped
EOF

cd /home/$USER/jellyfin && sudo docker compose up -d
```

### Why `network_mode: host`

Media servers benefit from host networking because:
- Smart TVs and devices on the LAN can discover the server via mDNS/SSDP
- Avoids port mapping complexity for DLNA
- Better streaming performance (no Docker NAT overhead)

### Verification

```bash
docker ps | grep jellyfin
curl -s -o /dev/null -w "%{http_code}" http://localhost:8096
# 302 = running, 503 = still starting
```

## First-Time Setup

1. Open `http://SERVER_IP:8096` in a browser
2. Create admin account
3. Add media libraries (point to `/media/movies`, `/media/tvshows`, etc.)
4. For IPTV: go to **Dashboard** → **Live TV** → add M3U tuner source

## Smart TV Client Installation

### Android TV (Xiaomi, TCL, etc.)
1. Download APK from https://github.com/jellyfin/jellyfin-android/releases
2. Copy to USB drive → install via TV's file manager
3. Open app → enter server URL: `http://SERVER_LAN_IP:8096`

### LG WebOS
- Available in LG Content Store (search "Jellyfin")

### Samsung Tizen
- Requires sideloading: https://github.com/jellyfin/jellyfin-tizen

## IPTV Live Sources

After setup, add live TV sources:
- Dashboard → Live TV → Live TV Providers
- Add M3U file/URL for channel list
- Add XMLTV file/URL for program guide (EPG)

Public M3U sources are available online but frequently change. Search for "IPTV m3u 直播源" for Chinese channels.

## Pitfalls

### P1: First request returns 503
Jellyfin takes 10-30 seconds to initialize. Wait and retry.

### P2: TV can't find server
- Ensure `network_mode: host` (not port mapping)
- Check firewall: `sudo ufw allow 8096`
- Verify TV and server are on same subnet

### P3: Playback buffering/stuttering
- Hardware transcoding requires GPU passthrough (`--device /dev/dri:/dev/dri`)
- Without GPU, CPU transcoding is limited to ~1-2 1080p streams
- For direct play (no transcoding), ensure media format is TV-compatible (H.264/H.265 + AAC)

### P4: Docker socket permission denied
Same as Docker install P8. Use `sudo docker compose` or fix socket permissions.