A Python package for enhancing Jellyfin Media Servers.
Watch how Jellytools transforms your Jellyfin interface with beautiful animated library cards:
demo.mp4
- 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
- Download poster artwork from Jellyfin libraries
- Generate custom JavaScript for Jellyfin to add video backgrounds to library cards
# Clone the repository git clone https://github.com/cleverdevil/jellytools.git cd jellytools # Install the package pip install -e .
- Python 3.7+
- FFmpeg (for video generation)
- Required Python packages (automatically installed):
- pygame
- opencv-python
- requests
- click
- 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
-
Edit the
config.pyfile with your Jellyfin server details (this file is gitignored for security) -
Generate library card animations:
jellytools generate
- Generate JavaScript for the Jellyfin Custom JavaScript Plugin:
jellytools generate-js
The configuration file (config.py) contains the following settings:
# Jellyfin server configuration 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"] # 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}, }
jellytools libraries
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
# 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 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.
# Download poster artwork for all configured libraries jellytools posters fetch # Clean existing poster artwork before downloading jellytools posters fetch --clean-first # Only download artwork for specific libraries jellytools posters fetch --libraries "Movies,TV Shows" # Clean and download specific libraries jellytools posters fetch --clean-first --libraries "Movies,TV Shows"
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
--skip-existing Skip animations that already exist in the output directory
--libraries Comma-separated list of libraries to process
-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)
Posters Command Options:
--clean-first Remove all existing poster files before downloading
--libraries Comma-separated list of libraries to process
Jellytools provides a variety of animations for your library cards:
A structured grid arrangement of posters with subtle movements.
grid.mp4
Posters cascade from the top of the screen into a structured grid.
waterfall.mp4
Posters begin in a horizontal line, form a spiral, then transition to a grid.
spiral.mp4
Creates a mosaic pattern that zooms and reveals.
mosaic.mp4
Posters swirl in a vortex pattern before arranging into a grid.
vortex.mp4
Posters cascade in from the sides in an alternating pattern.
cascade.mp4
Posters explode outward from the center before organizing into a grid.
explode.mp4
A mesmerizing kaleidoscope effect with rotating poster patterns.
kaleidoscope.mp4
Posters ripple in a shockwave pattern from the center.
shockwave.mp4
To use the generated JavaScript with Jellyfin, you need to install the Custom JavaScript plugin:
- Install the Jellyfin Custom JavaScript Plugin
- Go to your Jellyfin dashboard
- Navigate to Plugins > Custom JavaScript
- Paste the contents of the generated JavaScript file
- Save the settings
- Refresh your Jellyfin interface
This project was developed by Jonathan LaCour.
Jellytools used to contain a feature to sync collections from Plex to Jellyfin. The functionality has been removed to make this project 100% focused on Jellyfin. But, good news, this functionality is now available in Plexyfin.
This project is licensed under the MIT License - see the LICENSE file for details.