Help & Support

Selection

Single-click to select items. Double-click to open folders. Ctrl+click for multi-select. Press Space to toggle selection on focused item.

Keyboard Shortcuts

Press ? anytime to see all keyboard shortcuts. Quick keys: 1/2/3 for tabs, P to pause, D to download.

Speed Limit Updates Live

Change speed limit in settings and it applies to active downloads within 10 seconds.

Download Order

Choose how items are queued: complete shows first, round-robin by season/episode, or alphabetically.

Getting Started

1. Go to Settings → API Integration
2. Enable API Access
3. Click Generate New Key
4. Copy and save your API key securely

Authentication

Include your API key in requests:
Header: X-Api-Key: your_key
Query: ?apikey=your_key

API Endpoints

GET /api/v1/status - Queue status, speeds, disk
GET /api/v1/queue - Current downloads
POST /api/v1/queue/add - Add download
POST /api/v1/queue/pause - Pause downloads
GET /api/v1/history - Download history
GET /api/v1/docs - Full documentation

NZB360 Setup

1. Open NZB360 → Settings → Downloaders
2. Add Custom Downloader
3. Enter your JellyLooter URL
4. Add header: X-Api-Key: your_key

Classic (Default)

Standard poster grid with ratings, quality badges, and full details. Best for general browsing.

Compact

Smaller posters with tighter spacing - fits 2x more items on screen. All badges still visible.

Cards

Horizontal cards showing poster alongside title. Great when you need to read names easily.

List View

Vertical list with small thumbnails. Fastest scrolling and selection for large libraries.

Minimal

Posters only - maximum density. Hover over items to reveal badges and title.

Large Posters

Oversized posters with emphasis on artwork. Best for visual browsing and appreciating cover art.

CPU Threads

Limit FFmpeg to specific thread count (1-16) during transcoding. Lower values reduce CPU usage but increase transcode time. "Auto" uses all available threads.

Process Priority (nice)

Low: Background task, won't interfere with other apps
Normal: Standard system priority
High: Faster processing, may impact other apps

I/O Priority (ionice)

Idle: Only access disk when system is idle
Low: Reduced disk priority
Normal: Standard disk access

Memory Buffer

Download buffer size. Larger = faster downloads, more RAM. Recommended: 16 MB for low-power devices, 64 MB for most systems, 256 MB for fast connections.

Recommended Presets

NAS/Raspberry Pi: Low CPU, Idle I/O, 16 MB buffer
Shared desktop: Normal CPU, Low I/O, 32 MB buffer
Dedicated server: High CPU, Normal I/O, 256 MB buffer

Docker Users

For hard limits, also set --memory and --cpus flags in your container config. These app-level settings work within those container limits.

How It Works

Without per-server workers, all downloads go through a single queue. Server B waits while Server A downloads. With per-server workers enabled, each server gets its own dedicated worker pool.

Configuration

Enable in Settings → Pro Settings → Per-Server Workers. Choose 1-10 workers per server (matches your concurrent download limit). Total concurrent downloads = number of servers × workers per server.

Best Practices

1-2 workers: Conservative - good for slow connections or limited bandwidth
3-5 workers: Balanced - recommended for most setups
6-10 workers: Aggressive - best with fast connections and powerful hardware

Example

With 3 servers and 4 workers each, you can have up to 12 simultaneous downloads - 4 from each server running in parallel.

/ Focus search box
1 Go to Browse tab
2 Go to Sync tab
3 Go to Settings tab
Esc Clear selection / Close modal

Space Toggle selection on hovered item
Ctrl+A Select all items on page
Enter Download selected items

P Pause / Resume downloads
D Download selected items
R Refresh current view

Download All Button

Collections (BoxSets) and Playlists show a "Download All" button on their poster. Click it to queue all movies/episodes in that collection with a single click.

Recursive Downloads

When you download a collection, JellyLooter automatically resolves all nested items (series → seasons → episodes) and queues them in your preferred order.

Why Use Provider IDs?

Including IMDB/TVDB/TMDB IDs in folder names helps Jellyfin, Plex, Sonarr, and Radarr correctly identify your media - especially for anime, foreign films, or titles with common names.

Available Formats

Choose from 6 naming formats in Settings → Advanced Settings:
Standard - Movie (2010) / Show Name
IDs (Space) - Movie (2010) tt1234567 12345
IDs (Braces) - Movie (2010) {imdb-tt1234567} {tmdb-12345}
IDs (Brackets) - Movie (2010) [imdb-tt1234567]
TMDB Only - Movie (2010) {tmdb-12345}
IMDB Only - Movie (2010) tt1234567

Live Preview

The settings page shows a live preview of how your folders will be named for both movies and TV shows as you select different formats.

API Keys

Get free API keys from these providers to enable metadata lookup:
TMDB - Best for movies & TV, includes IMDB IDs
TVDB - Best for TV shows & anime
OMDb - IMDB data fallback (1,000/day limit)

Lookup Timing

Choose when metadata is fetched in Settings → Advanced Settings:
On Browse - Slower browsing, but IDs shown before download
On Download - Faster browsing, IDs fetched at download time

Metadata Caching (Pro)

Pro users get automatic metadata caching - once an item is looked up, the result is stored locally for instant access on repeat browsing.

Fallback Chain

JellyLooter first checks the remote server for IDs. If missing, it queries TMDB → TVDB → OMDb until it finds what it needs.

Download Statistics Widget

The stats widget at the top of the page shows:
Total Downloaded - All-time bytes downloaded (persists across restarts)
This Session - Files downloaded since container started
Current Speed - Combined speed of active downloads
In Queue - Pending downloads waiting to start
When transcoding is enabled, a Transcode Savings panel shows space saved.

Auto-Retry Failed Downloads

Enable in Advanced Settings to automatically retry downloads that fail due to connection errors, timeouts, or server issues. Configure:
Retry attempts - How many times to retry (1-10, default 3)
Retry delay - Seconds between retries (5-300, default 30)

Download Limit Override (Pro)

Pro users can enable "Override download limit" to allow more than 10 concurrent downloads (up to 50). ⚠️ Warning: High concurrent downloads can overload remote servers, cause rate limiting or bans, and affect other users on shared servers. Use responsibly.

Connection Settings

Connection timeout - How long to wait for server response (default 30s)
Chunk size - Download buffer size in KB (default 64KB, higher = faster but more memory)

Transcode Presets

Choose from 6 encoding presets in Pro Settings:
Original - No transcoding, keep source file
H.264 - Compatible with most devices (.mp4)
H.265/HEVC - Smaller files, modern devices (.mkv)
AVI - Legacy compatible MPEG-4 + MP3 (.avi)
Mobile - 720p H.264 for phones/tablets
4K Optimized - High quality H.265 for 4K content

Hardware Acceleration

JellyLooter supports NVIDIA NVENC, Intel QuickSync, and AMD VAAPI. For NVENC, use Dockerfile.nvidia and pass --gpus all to Docker. The app auto-detects available encoders and falls back to software if needed.

Separate Workers

Downloads and transcodes run in parallel with separate worker pools. Configure 1-10 download workers and 1-5 transcode workers. This means downloads continue while files are being transcoded.

Cache Drive

Enable "Use cache drive" to transcode files to a fast SSD first, then move them to the final destination. This reduces wear on slower drives, improves performance with network storage (NAS/SMB/NFS), and keeps partial files separate from your media library.

Clear Cache

Use the "Clear Cache" button to remove partial/failed transcode files from the cache drive. The cache status shows how many files and total size are currently stored.

Skip if Larger

Enable "Skip if larger" to automatically keep the original file when transcoding would increase file size. This prevents wasted space from inefficient transcodes (e.g., highly compressed originals).

Transcode Statistics

Track your transcoding efficiency: files processed, files skipped (larger), total space saved, and average reduction percentage. Stats persist across restarts and can be reset anytime.

Queue Limit

The transcode queue is limited to 10 pending files to prevent memory issues. Downloads will pause if the queue is full and resume automatically when space is available.

Basic vs Advanced View

Use the dropdown in the Activity Log panel to switch between views:
Basic - Shows only downloads: started, progress, completed, failed
Advanced - Shows everything: metadata lookups, cache operations, API calls, debug info

Copy Logs

Click the clipboard button (📋) in the Activity Log header to copy all log lines to your clipboard. Useful for sharing logs when troubleshooting or reporting issues.

History View

Click the "History" button to see your download history - all completed downloads with filenames, sizes, and timestamps.

Export Configuration

Go to Settings → Advanced Settings → Backup & Restore and click "Export Config". This downloads a JSON file with all your settings. API keys are masked (***MASKED***) for security.

Import Configuration

Click "Import Config" and select a previously exported JSON file. Your existing API keys are preserved if the imported ones are masked. Great for migrating to a new server or restoring after reinstall.

Pro Feature

Download resume is available for Pro license holders. Interrupted downloads can be resumed from where they left off.

How It Works

Downloads in progress are saved as .partial files. If JellyLooter restarts or a download is interrupted, it will automatically resume from the last saved position.

Auto-Save

Progress is saved every 30 seconds during download. After completion, the .partial extension is removed and the file is renamed to its final name.

Endpoint

Access at /health or /api/health (no authentication required). Perfect for Docker healthchecks and monitoring systems.

Response Data

Returns JSON with: version, uptime, queue status (active/pending/paused), disk space, server connectivity, cache info, and license tier.

Docker Healthcheck

Add to your docker-compose.yml:
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
  interval: 30s

Rating Overlays

Show IMDB/TMDB ratings on poster images. To toggle: Settings → Advanced Settings → "Show ratings on posters". Ratings are pulled from your Jellyfin/Emby server's metadata.

Quality Badges

Show resolution (4K, 1080p, 720p), HDR, Dolby Vision, and Atmos badges on posters. To toggle: Settings → Advanced Settings → "Show quality badges". Quality info is detected from the media file's video/audio streams.

Content Ratings

Content ratings (PG-13, R, TV-MA, etc.) appear in the top-right corner of posters when available. These are always shown when rating data exists in your server's metadata.

Theme

Toggle dark/light theme in Settings → Appearance. Pro users can also use custom themes (Jellyfin, Plex, Emby, Christmas) or create custom color schemes.

How It Works

JellyLooter caches your Sonarr/Radarr library and uses the exact folder names when downloading. For example, if Radarr has "Inception (2010) {tmdb-27205}", your downloads will use that exact folder name. Click "Refresh" in Pro Settings to update the cache.

Authentication Issues

If using username/password auth, try deleting and re-adding the server. The user_id must be stored correctly.

Slow Downloads

Check your speed limit setting. Set to 0 for unlimited. Also check network connection to remote server.

Download Errors

Check the Activity Log for details. Common issues: disk full, permissions, network timeout.

Cache Not Updating

Click "Rebuild Cache" in the Activity Log panel. This rescans your local library for duplicate detection.

Ratings Not Showing

Ratings come from your Jellyfin/Emby server's metadata. Make sure your library has been scanned and has metadata. Also check that "Show ratings on posters" is enabled in Advanced Settings.

Quality Badges Not Showing

Quality info requires media analysis. In Jellyfin, go to your library settings and enable "Extract chapter images" or run a full library scan. The MediaStreams data must be present for badges to appear.

vwidmer

Beta testing, bug reports, and feature suggestions for transcoding, *arr integration, and download improvements

nwithan8

Fixed jellylooter.xml for Unraid Community Apps compatibility