https://github.com/cleverdevil/jellytools
A suite of tools for Jellyfin, including the ability to copy Collections and their poster art from Plex to Jellyfin, and an animated library card generator to make your Jellyfin UI more dynamic..
https://github.com/cleverdevil/jellytools
Last synced: 27 days ago
JSON representation
A suite of tools for Jellyfin, including the ability to copy Collections and their poster art from Plex to Jellyfin, and an animated library card generator to make your Jellyfin UI more dynamic..
- Host: GitHub
- URL: https://github.com/cleverdevil/jellytools
- Owner: cleverdevil
- License: mit
- Created: 2025-03-15T22:03:08.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-03-15T23:14:33.000Z (about 1 month ago)
- Last Synced: 2025-03-15T23:19:54.709Z (about 1 month ago)
- Language: Python
- Size: 18.6 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-jellyfin - jellytools - A CLI tool for synchronizing artwork and collections to Jellyfin from Plex and to generate and embed customizable animated library card videos in the Jellyfin UI. (👾 Other)
README
# Jellytools
A Python package for enhancing Jellyfin Media Servers.
## Demo
Watch how Jellytools transforms your Jellyfin interface with beautiful animated library cards:
https://github.com/user-attachments/assets/b8130d64-9e72-478f-8c00-27c0aafda385
## 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
```bash
# 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:
```bash
# 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:
```bash
jellytools generate
```
4. Generate JavaScript for the Jellyfin Custom JavaScript Plugin:
```bash
jellytools generate-js
```
## Configuration
The configuration file (`config.py`) contains the following settings:
```python
# 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
```bash
jellytools libraries
```
### Show Animation Configuration
```bash
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
```bash
# 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:
```bash
# 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
```bash
# 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.
https://github.com/user-attachments/assets/5198c308-1f21-4a88-b382-c0ce3ad4abaa
### Waterfall
Posters cascade from the top of the screen into a structured grid.
https://github.com/user-attachments/assets/e9c32492-ec47-4383-b436-360aae267728
### Spiral
Posters begin in a horizontal line, form a spiral, then transition to a grid.
https://github.com/user-attachments/assets/1f1da585-6e00-4af9-993f-2c8db4ccba09
### Mosaic
Creates a mosaic pattern that zooms and reveals.
https://github.com/user-attachments/assets/814a7e87-f146-43d4-a797-44446e7077ad
### Vortex
Posters swirl in a vortex pattern before arranging into a grid.
https://github.com/user-attachments/assets/6b23c9fb-d2eb-498d-8872-688abe1dfd35
### Cascade
Posters cascade in from the sides in an alternating pattern.
https://github.com/user-attachments/assets/d719bb88-fe16-4ef0-a069-8c7187794643
### Explode
Posters explode outward from the center before organizing into a grid.
https://github.com/user-attachments/assets/dff5be18-c5ab-4825-b473-2e42e19541ea
### Kaleidoscope
A mesmerizing kaleidoscope effect with rotating poster patterns.
https://github.com/user-attachments/assets/d7a1be8b-fb7c-4f00-b1ce-dd58242f9980
### Shockwave
Posters ripple in a shockwave pattern from the center.
https://github.com/user-attachments/assets/2322c281-946f-4715-81ca-7b5dca8c8a31
## 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](https://github.com/johnpc/jellyfin-plugin-custom-javascript)
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](https://cleverdevil.io) in collaboration with [Claude Code](https://claude.ai/code).
## License
This project is licensed under the MIT License - see the LICENSE file for details.