Jellyfin Seasonals Plugin

Jellyfin Seasonals is a plugin that adds seasonal themes to your Jellyfin web interface. Depending on the configuration, it automatically selects a theme based on the current date or allows you to manually set a default theme.

This plugin is based on my manual mod (see the legacy branch), which builds up on the awesome work of BobHasNoSoul-jellyfin-mods.

---

Table of Contents

• Jellyfin Seasonals Plugin
  • Table of Contents
  • Features
  • Overview
  • Ideas for additional seasonals
  • Installation
  • Client Compatibility
  • Configuration
  • Automatic Theme Selection
  • Theme Settings
  • Build the plugin by yourself
  • Troubleshooting
    • Effects Not Showing
    • Docker Permission Issues
  • Contributing

---

Features

• Automatic Theme Selection: Dynamically updates the theme based on the date (e.g., snowflakes in December, fireworks for new year's eve).

• Easy Integration: No manual file editing required. The plugin injects everything automatically.

• Configuration UI: Configure settings directly in the Jellyfin Dashboard.

  Have a look at admin plugin configuration:

  

• User Toggle & Menu Location: Optionally allow users to enable/disable seasonal effects from their client browser. Admins can choose the location of the settings button (Navbar, Sidebar, or Both) separately for desktop and mobile clients.

  Have a look at the client side settings menu:

  

• TV Layout Auto-Disable (Performance): Automatically disable Seasonals visual effects on TV display layouts (smart TVs, consoles, etc.) by default to optimize performance and prevent lag. TV users can still manually override this in their client settings.

Overview

Click on the following themes to expand them and see the theme in action:

Easter

Autumn

Santa

Christmas

Fireworks

Halloween

Hearts

Snowfall

Snowflakes

Snowstorm

Summer

TBD ![summer]()

Spring

TBD ![spring]()

Cherry blossom

TBD ![cherry blossom]()

Resurrection by Bioflash257

TBD ![resurrection]()

And many more since version 2.0.0.0!

Ideas for additional seasonals

If you have any (specific) ideas for additional seasonals, feel free to open an issue or create a pull request. See the contributing guidelines for more details.

Installation

This plugin is based on Jellyfin Version 10.11.x

To install this plugin, you will first need to add the repository in Jellyfin.

1. Open your Jellyfin Dashboard.
2. Navigate to Plugins > Manage Repositories.
3. Click the + New Repository button to add a new repository.
4. Enter a name for the repo and paste the following URL into the 'Repository URL' field:

https://raw.githubusercontent.com/CodeDevMLH/jellyfin-plugin-manifest/refs/heads/main/manifest.json

5. Click Add.
6. Go to the Available tab at the top.
7. Find the Seasonals plugin (Under General)
8. Click on it and select Install.
9. Restart your Jellyfin server.
10. You may need to refresh your browser page (F5 or Ctrl+R) to see the changes.

Client Compatibility

Since this plugin relies on modifying the web interface (CSS/JS injection), it only works on clients that use the web wrapper. Native clients that use their own UI rendering engine are not supported.

Configuration

After installation and restart:

1. Go to Dashboard > Plugins > Seasonals.
2. Plugin Settings:
   • Enable Seasonals: Toggle the entire plugin on or off.
   • Automate Season Selection: If enabled, the plugin selects the theme based on active rules. Otherwise, it falls back to the manual Standard Season selected below.
   • Allow Client-Side Toggle: If enabled, users will see a settings button to toggle Seasonals locally (stored in browser local storage).
   • Disable for TVs by Default: If enabled, visual effects are turned off by default on TV display layouts (smart TVs, consoles, etc.) to prevent lag. TV users can manually turn it back on via their client settings.
   • Client Menu Location / Client Menu Location (Mobile): Choose where the client-side settings button is displayed (Navbar, Sidebar, or Both) for desktop and mobile clients.
3. Save your settings.
4. Reload your browser page (F5 or Ctrl+R) to see the changes.

Automatic Theme Selection

If automatic selection is enabled, the following themes are applied based on the date. Specific holiday events take precedence over general seasonal themes.:

Note: Holiday themes (like santa or fireworks) override monthly seasonal themes (like snowflakes).

Theme Settings

Each theme contains additional settings to customize its behavior. Expand the advanced configuration section to configure each theme, adjust parameters like particle count, animation speed etc.

Build the plugin by yourself

If you want to build the plugin yourself:

1. Clone the repository.
2. Ensure you have the .NET SDK installed (NET 8 or 9 depending on your Jellyfin version).
3. Run the build command:

   dotnet build Jellyfin.Plugin.Seasonals/Jellyfin.Plugin.Seasonals.csproj --configuration Release --output bin/Publish
   

4. The compiled DLL and resources will be in bin/Publish.

Troubleshooting

Effects Not Showing

1. Verify plugin installation:

   • Check that the plugin appears in the jellyfin admin panel
   • Ensure that the plugin is enabled and active

2. Clear browser cache:

   • Force refresh browser (Ctrl+F5)
   • Clear jellyfin web client cache (--> mostly you have to clear the whole browser cache)

Docker Permission Issues

If you encounter the message Access was denied when attempting to inject script into index.html. Automatic direct injection failed. Automatic direct insertion failed. The system will now attempt to use the File Transformation plugin. in the log or similar permission errors in Docker:

Option 1: Use File Transformation Plugin (Recommended)

Seasonals now automatically detects and uses the File Transformation plugin (v2.5.0.0+) if it's installed. This eliminates permission issues by transforming content at runtime without modifying files on disk.

Installation Steps:

1. Install the File Transformation plugin from the Jellyfin plugin catalog
2. Restart Jellyfin
3. Seasonals will automatically detect and use it (no configuration needed)
4. Check logs to confirm: Look for "Successfully registered transformation with File Transformation plugin"

Benefits:

• No file permission issues in Docker environments
• Works with read-only web directories
• Survives Jellyfin updates without re-injection
• No manual file modifications required

Option 2: Fix File Permissions

# Find the actual index.html location
docker exec -it jellyfin find / -name index.html

# Fix ownership (replace 'jellyfin' with your container name and adjust user:group if needed)
docker exec -it --user root jellyfin chown jellyfin:jellyfin /jellyfin/jellyfin-web/index.html

# Restart container
docker restart jellyfin

Option 3: Manual Volume Mapping

# Extract index.html from container
docker cp jellyfin:/jellyfin/jellyfin-web/index.html /path/to/jellyfin/config/index.html

# Add to docker-compose.yml volumes section:
volumes:
  - /path/to/jellyfin/config/index.html:/jellyfin/jellyfin-web/index.html

Contributing

Feel free to contribute to this project by creating pull requests or reporting issues. For detailed contribution guidelines, please refer to the CONTRIBUTING.md file.