{"id":26523155,"url":"https://github.com/cleverdevil/jellytools","last_synced_at":"2025-06-20T20:41:36.143Z","repository":{"id":282632176,"uuid":"949192229","full_name":"cleverdevil/jellytools","owner":"cleverdevil","description":"A tool to generate fancy animated library cards for use with Jellyfin's UI.","archived":false,"fork":false,"pushed_at":"2025-04-21T07:26:48.000Z","size":19616,"stargazers_count":14,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-13T21:11:28.372Z","etag":null,"topics":["jellyfin","jellyfin-web"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cleverdevil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-15T22:03:08.000Z","updated_at":"2025-06-12T13:18:25.000Z","dependencies_parsed_at":"2025-03-15T23:19:59.591Z","dependency_job_id":"47ea6377-6edd-4879-9336-651864a115f2","html_url":"https://github.com/cleverdevil/jellytools","commit_stats":null,"previous_names":["cleverdevil/jellytools"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cleverdevil/jellytools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cleverdevil%2Fjellytools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cleverdevil%2Fjellytools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cleverdevil%2Fjellytools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cleverdevil%2Fjellytools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cleverdevil","download_url":"https://codeload.github.com/cleverdevil/jellytools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cleverdevil%2Fjellytools/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261014092,"owners_count":23097174,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jellyfin","jellyfin-web"],"created_at":"2025-03-21T14:01:16.910Z","updated_at":"2025-06-20T20:41:31.130Z","avatar_url":"https://github.com/cleverdevil.png","language":"Python","readme":"# Jellytools\n\nA Python package for enhancing Jellyfin Media Servers.\n\n## Demo\n\nWatch how Jellytools transforms your Jellyfin interface with beautiful animated library cards:\n\nhttps://github.com/user-attachments/assets/b8130d64-9e72-478f-8c00-27c0aafda385\n\n## Features\n\n- Generate animated library cards from media posters in high-quality MP4 video format\n- Multiple animation styles: grid, waterfall, spiral, mosaic, vortex, cascade, explode, kaleidoscope, and shockwave\n- Synchronize collections and artwork from Plex to Jellyfin\n- Generate custom JavaScript for Jellyfin to add video backgrounds to library cards\n\n## Installation\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/cleverdevil/jellytools.git\ncd jellytools\n\n# Install the package\npip install -e .\n```\n\n### Dependencies\n\n- Python 3.7+\n- FFmpeg (for video generation)\n- Required Python packages (automatically installed):\n  - pygame\n  - opencv-python\n  - plexapi\n  - requests\n  - click\n\n## Quick Start\n\n1. Create a configuration file by copying the example:\n\n```bash\n# Copy the example config\ncp config.py.example config.py\n\n# Or initialize a new one\njellytools init\n```\n\n2. Edit the `config.py` file with your Jellyfin/Plex server details (this file is gitignored for security)\n\n3. Generate library card animations:\n\n```bash\njellytools generate\n```\n\n4. Generate JavaScript for the Jellyfin Custom JavaScript Plugin:\n\n```bash\njellytools generate-js\n```\n\n## Configuration\n\nThe configuration file (`config.py`) contains the following settings:\n\n```python\n# Jellyfin server configuration (primary)\nJELLYFIN_URL = \"http://localhost:8096\"\n# Authentication options (use either API key or username/password)\nJELLYFIN_API_KEY = \"your-jellyfin-api-key\"\n# Alternative authentication\n# JELLYFIN_USERNAME = \"your-jellyfin-username\"\n# JELLYFIN_PASSWORD = \"your-jellyfin-password\"\nJELLYFIN_LIBRARIES = [\"Movies\", \"TV Shows\", \"Collections\"]\n\n# Plex server configuration (used for syncing)\nPLEX_URL = \"http://localhost:32400\"\nPLEX_TOKEN = \"your-plex-token\"\nPLEX_LIBRARIES = [\"Movies\", \"TV Shows\"]\n\n# General configuration\nPOSTER_DIRECTORY = \"posters\"\nFONT_PATH = \"./assets/font.ttf\"\nCAPITALIZE_TEXT = True\n\n# Animation configuration\nDEFAULT_ANIMATION_TYPE = \"grid\"\nDEFAULT_OUTPUT_DIR = \"output\"\n\n# All animation types\nALL_ANIMATIONS = [\n    \"grid\",\n    \"spiral\",\n    \"waterfall\",\n    \"cascade\",\n    \"kaleidoscope\",\n    \"explode\",\n    \"vortex\",\n    \"mosaic\",\n    \"shockwave\",\n]\n\n# Per-library animation configuration\nLIBRARY_ANIMATIONS = {\n    \"Movies\": {\"animation_types\": ALL_ANIMATIONS},\n    \"TV Shows\": {\"animation_types\": ALL_ANIMATIONS},\n    \"Collections\": {\"animation_types\": ALL_ANIMATIONS},\n}\n```\n\n## Usage\n\n### List Available Libraries\n\n```bash\njellytools libraries\n```\n\n### Show Animation Configuration\n\n```bash\njellytools animations\n```\n\nThis command displays:\n- The default animation type\n- All available animation types\n- The animation configurations for each library\n- Which libraries are using multiple animation types\n\n### Generate Library Cards\n\n```bash\n# Basic usage (using default animation or per-library configuration)\njellytools generate\n\n# Specify animation type (overrides configuration)\njellytools generate --animation-type spiral\n\n# Customize output\njellytools generate --animation-type waterfall --output-dir my_animations\n\n# Skip steps\njellytools generate --skip-hi-res --skip-download\n\n# Skip thumbnail generation\njellytools generate --skip-thumbnails\n\n# Skip low-resolution video generation\njellytools generate --skip-low-res\n```\n\n### Generate JavaScript for Jellyfin\n\nGenerate JavaScript for the Jellyfin Custom JavaScript Plugin that adds hover-triggered videos to library cards:\n\n```bash\n# Basic usage\njellytools generate-js\n\n# Allow videos to replay each time the element is hovered over\njellytools generate-js --replay\n\n# Keep text labels visible instead of hiding them\njellytools generate-js --show-labels\n\n# Specify output file\njellytools generate-js --output my-override.js\n```\n\nThe 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.\n\n### Sync Collections and Artwork from Plex to Jellyfin\n\nBy default, `jellytools sync` will:\n- Clean existing collections in Jellyfin\n- Create new collections in Jellyfin based on Plex collections\n- Sync all artwork types (posters, backdrops, banners) for all media\n- Skip previously synced items (incremental sync using SQLite database)\n- Match items between Plex and Jellyfin using IMDb IDs when available, with title-based matching as fallback for items without IMDb IDs\n\n```bash\n# Sync everything (default behavior)\njellytools sync\n\n# Only sync primary/poster images (skip backdrops and banners)\njellytools sync --primary-only\n\n# Skip collections and only sync artwork\njellytools sync --skip-collections\n\n# Preserve existing collections (don't delete them)\njellytools sync --preserve-collections\n\n# Only sync collections, skip all artwork\njellytools sync --skip-images\n\n# Only clean existing collections in Jellyfin\njellytools sync --clean-only\n\n# Sync all artwork but skip collections\njellytools sync --skip-collections --sync-images --all-artwork\n\n# Force sync all items (clears database and syncs everything)\njellytools sync --force\n```\n\n### Command-line Options\n\n```\nGeneral Options:\n  -c, --config TEXT               Path to configuration file\n  -v, --verbose                   Enable verbose output\n  --help                          Show this message and exit\n\nGenerate Command Options:\n  -a, --animation-type [grid|waterfall|spiral|mosaic|vortex|cascade|explode|kaleidoscope|shockwave]\n                                  Animation type to use (overrides config)\n  --skip-hi-res                   Skip generating high-resolution MP4\n  --skip-low-res                  Skip generating 480p low-resolution MP4\n  --skip-download                 Skip downloading posters from servers\n  --skip-thumbnails               Skip generating PNG thumbnails of the last frame\n  -o, --output-dir OUTPUT_DIR     Output directory for videos\n\nGenerate JavaScript Options:\n  -o, --output TEXT               Output file for the JavaScript (default: jellyfin-override.js)\n  --replay/--no-replay            Allow videos to replay each time the element is hovered over (default: false)\n  --hide-labels/--show-labels     Hide the text labels for library cards (default: true)\n\nSync Command Options:\n  --skip-images/--sync-images     Skip syncing any images (faster) [default: sync images]\n  --all-artwork/--primary-only    Sync all artwork types including backdrops and banners [default: all artwork]\n  --sync-collections/--skip-collections  Sync collections from Plex to Jellyfin [default: sync collections]\n  --clean-collections/--preserve-collections  Clean existing collections before syncing [default: clean collections]\n  --force                         Force sync all items by clearing sync database [default: incremental sync]\n  --verbose, -v                  Enable verbose logging output\n  --clean-only                    Only clean existing collections without creating new ones\n```\n\n## Animation Types\n\nJellytools provides a variety of animations for your library cards:\n\n### Grid\nA structured grid arrangement of posters with subtle movements.\n\nhttps://github.com/user-attachments/assets/5198c308-1f21-4a88-b382-c0ce3ad4abaa\n\n### Waterfall\nPosters cascade from the top of the screen into a structured grid.\n\nhttps://github.com/user-attachments/assets/e9c32492-ec47-4383-b436-360aae267728\n\n### Spiral\nPosters begin in a horizontal line, form a spiral, then transition to a grid.\n\nhttps://github.com/user-attachments/assets/1f1da585-6e00-4af9-993f-2c8db4ccba09\n\n### Mosaic\nCreates a mosaic pattern that zooms and reveals.\n\nhttps://github.com/user-attachments/assets/814a7e87-f146-43d4-a797-44446e7077ad\n\n### Vortex\nPosters swirl in a vortex pattern before arranging into a grid.\n\nhttps://github.com/user-attachments/assets/6b23c9fb-d2eb-498d-8872-688abe1dfd35\n\n### Cascade\nPosters cascade in from the sides in an alternating pattern.\n\nhttps://github.com/user-attachments/assets/d719bb88-fe16-4ef0-a069-8c7187794643\n\n### Explode\nPosters explode outward from the center before organizing into a grid.\n\nhttps://github.com/user-attachments/assets/dff5be18-c5ab-4825-b473-2e42e19541ea\n\n### Kaleidoscope\nA mesmerizing kaleidoscope effect with rotating poster patterns.\n\nhttps://github.com/user-attachments/assets/d7a1be8b-fb7c-4f00-b1ce-dd58242f9980\n\n### Shockwave\nPosters ripple in a shockwave pattern from the center.\n\nhttps://github.com/user-attachments/assets/2322c281-946f-4715-81ca-7b5dca8c8a31\n\n## Jellyfin Custom JavaScript Plugin\n\nTo use the generated JavaScript with Jellyfin, you need to install the Custom JavaScript plugin:\n\n1. Install the [Jellyfin Custom JavaScript Plugin](https://github.com/johnpc/jellyfin-plugin-custom-javascript)\n2. Go to your Jellyfin dashboard\n3. Navigate to Plugins \u003e Custom JavaScript\n4. Paste the contents of the generated JavaScript file\n5. Save the settings\n6. Refresh your Jellyfin interface\n\n## Credits\n\nThis project was developed by [Jonathan LaCour](https://cleverdevil.io) in collaboration with [Claude Code](https://claude.ai/code).\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","funding_links":[],"categories":["👾 Other"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcleverdevil%2Fjellytools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcleverdevil%2Fjellytools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcleverdevil%2Fjellytools/lists"}