blackBarRemover/README.md

Jellyfin Black Bar Remover Plugin

A Jellyfin plugin that automatically detects and removes black bars (letterboxing/pillarboxing) from video files.

Features

• Automated Scanning: Hooks into the Jellyfin library scan (ItemAdded / ItemUpdated) to analyze videos in the background using FFmpeg keyframe skipping.
• Robust Detection: Filters out brief format changes (like studio logos or dark transitions) to find the true "safe crop" bounding box for the entire video.
• Native Storage: Saves detected crop parameters natively inside the Jellyfin SQLite database via ProviderIds.
• Dual Playback Modes:
  • Client-Side (CSS Clip): Automatically injects a JavaScript module into the Jellyfin Web UI. The script reads the crop data and uses CSS clip-path and transform to crop the video in the browser without any server-side transcoding overhead (Direct Play).
  • Server-Side (FFmpeg Wrapper): Generates an ffmpeg-wrapper.sh script that can be used to inject the FFmpeg -vf crop filter during active transcoding.

Requirements

• Jellyfin Server 12.0 or newer (.NET 10).
• FFmpeg installed on the server.

Installation

Method 1: Building from Source

1. Clone this repository.
2. Build the plugin using the .NET 10 SDK:

   dotnet build JellyfinPlugin/JellyfinPlugin.csproj -c Release
   

3. Copy the compiled DLLs from JellyfinPlugin/bin/Release/net10.0/ into a new folder named BlackBarRemover inside your Jellyfin plugins directory (e.g., /var/lib/jellyfin/plugins/BlackBarRemover/).
4. Restart the Jellyfin server.

Configuration

1. Go to Dashboard -> Plugins -> Black Bar Remover.
2. Set your Crop Detect Limit (Default is 0.15). If your web-dl rips have noisy black bars that are not being cropped, increase this value to 0.20 or 0.25.
3. Select your preferred Playback Mode:
   • Client: Uses CSS injection in the web player.
   • Server: Requires setting up the FFmpeg wrapper.
   • Both: Attempts both methods depending on the client.

Activating the Server-Side Wrapper (Optional)

If you selected "Server" or "Both" mode:

1. The plugin automatically generates a wrapper script on startup at <PluginsPath>/BlackBarRemover/ffmpeg-wrapper.sh.
2. In the Jellyfin Dashboard, go to Playback -> FFmpeg path.
3. Change the path to point to the generated ffmpeg-wrapper.sh file.

Activating the Client-Side CSS (Automatic)

The plugin attempts to automatically inject its JavaScript into the Jellyfin Web index.html on startup. If it fails due to file permissions, you can manually activate it by adding the following line to Dashboard -> General -> Custom CSS:

<script src="/BlackBarRemover/ClientScript.js"></script>

How it works

When a video is scanned, a background process runs ffmpeg -skip_frame nokey -i <file> -vf cropdetect. It collects all crops and ignores anomalies (appearing in < 5% of frames). The resulting bounding box is saved to the Jellyfin database under the BlackBarCrop provider ID.