Jellytools

A Python package for enhancing Jellyfin Media Servers.

Demo

Watch how Jellytools transforms your Jellyfin interface with beautiful animated library cards:

demo.mp4

Features

• Generate animated library cards from media posters in high-quality MP4 video format
• Multiple animation styles: grid, waterfall, spiral, mosaic, vortex, cascade, explode, kaleidoscope, and shockwave
• Synchronize collections and artwork from Plex to Jellyfin
• Generate custom JavaScript for Jellyfin to add video backgrounds to library cards

Installation

From Source

# Clone the repository
git clone https://github.com/cleverdevil/jellytools.git
cd jellytools

# Install the package
pip install -e .

Dependencies

• Python 3.7+
• FFmpeg (for video generation)
• Required Python packages (automatically installed):
  • pygame
  • opencv-python
  • plexapi
  • requests
  • click

Quick Start

1. Create a configuration file by copying the example:

# Copy the example config
cp config.py.example config.py

# Or initialize a new one
jellytools init

2. Edit the config.py file with your Jellyfin/Plex server details (this file is gitignored for security)

3. Generate library card animations:

jellytools generate

4. Generate JavaScript for the Jellyfin Custom JavaScript Plugin:

jellytools generate-js

Configuration

The configuration file (config.py) contains the following settings:

# Jellyfin server configuration (primary)
JELLYFIN_URL = "http://localhost:8096"
# Authentication options (use either API key or username/password)
JELLYFIN_API_KEY = "your-jellyfin-api-key"
# Alternative authentication
# JELLYFIN_USERNAME = "your-jellyfin-username"
# JELLYFIN_PASSWORD = "your-jellyfin-password"
JELLYFIN_LIBRARIES = ["Movies", "TV Shows", "Collections"]

# Plex server configuration (used for syncing)
PLEX_URL = "http://localhost:32400"
PLEX_TOKEN = "your-plex-token"
PLEX_LIBRARIES = ["Movies", "TV Shows"]

# General configuration
POSTER_DIRECTORY = "posters"
FONT_PATH = "./assets/font.ttf"
CAPITALIZE_TEXT = True

# Animation configuration
DEFAULT_ANIMATION_TYPE = "grid"
DEFAULT_OUTPUT_DIR = "output"

# All animation types
ALL_ANIMATIONS = [
    "grid",
    "spiral",
    "waterfall",
    "cascade",
    "kaleidoscope",
    "explode",
    "vortex",
    "mosaic",
    "shockwave",
]

# Per-library animation configuration
LIBRARY_ANIMATIONS = {
    "Movies": {"animation_types": ALL_ANIMATIONS},
    "TV Shows": {"animation_types": ALL_ANIMATIONS},
    "Collections": {"animation_types": ALL_ANIMATIONS},
}

Usage

List Available Libraries

jellytools libraries

Show Animation Configuration

jellytools animations

This command displays:

• The default animation type
• All available animation types
• The animation configurations for each library
• Which libraries are using multiple animation types

Generate Library Cards

# Basic usage (using default animation or per-library configuration)
jellytools generate

# Specify animation type (overrides configuration)
jellytools generate --animation-type spiral

# Customize output
jellytools generate --animation-type waterfall --output-dir my_animations

# Skip steps
jellytools generate --skip-hi-res --skip-download

# Skip thumbnail generation
jellytools generate --skip-thumbnails

# Skip low-resolution video generation
jellytools generate --skip-low-res

Generate JavaScript for Jellyfin

Generate JavaScript for the Jellyfin Custom JavaScript Plugin that adds hover-triggered videos to library cards:

# Basic usage
jellytools generate-js

# Allow videos to replay each time the element is hovered over
jellytools generate-js --replay

# Keep text labels visible instead of hiding them
jellytools generate-js --show-labels

# Specify output file
jellytools generate-js --output my-override.js

The JavaScript will add hidden videos to Jellyfin library cards while maintaining their original appearance. The videos will play when a user hovers over a library card.

Sync Collections and Artwork from Plex to Jellyfin

By default, jellytools sync will:

• Clean existing collections in Jellyfin
• Create new collections in Jellyfin based on Plex collections
• Sync all artwork types (posters, backdrops, banners) for all media
• Skip previously synced items (incremental sync using SQLite database)
• Match items between Plex and Jellyfin using IMDb IDs when available, with title-based matching as fallback for items without IMDb IDs

# Sync everything (default behavior)
jellytools sync

# Only sync primary/poster images (skip backdrops and banners)
jellytools sync --primary-only

# Skip collections and only sync artwork
jellytools sync --skip-collections

# Preserve existing collections (don't delete them)
jellytools sync --preserve-collections

# Only sync collections, skip all artwork
jellytools sync --skip-images

# Only clean existing collections in Jellyfin
jellytools sync --clean-only

# Sync all artwork but skip collections
jellytools sync --skip-collections --sync-images --all-artwork

# Force sync all items (clears database and syncs everything)
jellytools sync --force

Command-line Options

General Options:
  -c, --config TEXT               Path to configuration file
  -v, --verbose                   Enable verbose output
  --help                          Show this message and exit

Generate Command Options:
  -a, --animation-type [grid|waterfall|spiral|mosaic|vortex|cascade|explode|kaleidoscope|shockwave]
                                  Animation type to use (overrides config)
  --skip-hi-res                   Skip generating high-resolution MP4
  --skip-low-res                  Skip generating 480p low-resolution MP4
  --skip-download                 Skip downloading posters from servers
  --skip-thumbnails               Skip generating PNG thumbnails of the last frame
  -o, --output-dir OUTPUT_DIR     Output directory for videos

Generate JavaScript Options:
  -o, --output TEXT               Output file for the JavaScript (default: jellyfin-override.js)
  --replay/--no-replay            Allow videos to replay each time the element is hovered over (default: false)
  --hide-labels/--show-labels     Hide the text labels for library cards (default: true)

Sync Command Options:
  --skip-images/--sync-images     Skip syncing any images (faster) [default: sync images]
  --all-artwork/--primary-only    Sync all artwork types including backdrops and banners [default: all artwork]
  --sync-collections/--skip-collections  Sync collections from Plex to Jellyfin [default: sync collections]
  --clean-collections/--preserve-collections  Clean existing collections before syncing [default: clean collections]
  --force                         Force sync all items by clearing sync database [default: incremental sync]
  --verbose, -v                  Enable verbose logging output
  --clean-only                    Only clean existing collections without creating new ones

Animation Types

Jellytools provides a variety of animations for your library cards:

Grid

A structured grid arrangement of posters with subtle movements.

grid.mp4

Waterfall

Posters cascade from the top of the screen into a structured grid.

waterfall.mp4

Spiral

Posters begin in a horizontal line, form a spiral, then transition to a grid.

spiral.mp4

Mosaic

Creates a mosaic pattern that zooms and reveals.

mosaic.mp4

Vortex

Posters swirl in a vortex pattern before arranging into a grid.

vortex.mp4

Cascade

Posters cascade in from the sides in an alternating pattern.

cascade.mp4

Explode

Posters explode outward from the center before organizing into a grid.

explode.mp4

Kaleidoscope

A mesmerizing kaleidoscope effect with rotating poster patterns.

kaleidoscope.mp4

Shockwave

Posters ripple in a shockwave pattern from the center.

shockwave.mp4

Jellyfin Custom JavaScript Plugin

To use the generated JavaScript with Jellyfin, you need to install the Custom JavaScript plugin:

1. Install the Jellyfin Custom JavaScript Plugin
2. Go to your Jellyfin dashboard
3. Navigate to Plugins > Custom JavaScript
4. Paste the contents of the generated JavaScript file
5. Save the settings
6. Refresh your Jellyfin interface

Credits

This project was developed by Jonathan LaCour in collaboration with Claude Code.

License

This project is licensed under the MIT License - see the LICENSE file for details.