blackBarRemover/README.md

Jellyfin Black Bar Remover

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

Features · Requirements · Getting started · Configuration · Architecture · Documentation · Credits · License

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 script that can be used to inject the FFmpeg -vf crop filter during active transcoding.

Requirements

• Jellyfin Server 10.11 or 12.0+ (.NET 9 / .NET 10).
• FFmpeg installed on the server.

Previously documented compatibility

The previous README records testing on the following versions; this documentation update does not revalidate runtime compatibility:

• Jellyfin 10.11.x (.NET 9.0)
• Jellyfin 12.0 / 13.0 Unstable (.NET 10.0)

Getting started

Install from the Jellyfin repository

Tip

Plugin Repository URL:

https://gitea.labus.uk/karol/blackBarRemover/raw/branch/master/manifest.json

1. Open your Jellyfin Dashboard and navigate to Dashboard -> Plugins -> Repositories (Repositories tab).
2. Click the + icon to add a new repository.
3. Enter Black Bar Remover as the Repository Name.
4. Copy and paste the Repository URL above into the Repository URL field, then click Save.
5. Switch to the Catalog tab, find Black Bar Remover (under the Playback category), and click Install.
6. Restart your Jellyfin server.

Install manually from releases

1. Go to the Releases tab on the Gitea repository page.
2. Download the latest BlackBarRemover_vX.X.zip file.
3. Extract the contents of the ZIP file into a new folder named BlackBarRemover inside your Jellyfin plugins directory (e.g., /var/lib/jellyfin/plugins/BlackBarRemover/).
4. Restart the Jellyfin server.

Build from source

1. Clone this repository.

2. Ensure you have the .NET 9.0 SDK and/or .NET 10.0 SDK installed (the project multi-targets both net9.0 and net10.0).

3. Build the plugin for all targets:

   dotnet build JellyfinPlugin/JellyfinPlugin.csproj -c Release
   

   Or build for a specific target framework:

   # For Jellyfin 10.11 (.NET 9.0)
   dotnet build JellyfinPlugin/JellyfinPlugin.csproj -c Release -f net9.0
   
   # For Jellyfin 12.0 / 13.0 Unstable (.NET 10.0)
   dotnet build JellyfinPlugin/JellyfinPlugin.csproj -c Release -f net10.0
   

4. Copy the compiled DLLs from JellyfinPlugin/bin/Release/net9.0/ (for Jellyfin 10.11) or JellyfinPlugin/bin/Release/net10.0/ (for Jellyfin 12.0+) into a new folder named BlackBarRemover inside your Jellyfin plugins directory (e.g., /var/lib/jellyfin/plugins/BlackBarRemover/).

5. Restart the Jellyfin server.

Configuration

1. Go to Dashboard -> Plugins -> Black Bar Remover.
2. Set your Crop Detect Limit (Default is 0.094). If your web-dl rips have noisy black bars that are not being cropped, increase this value to 0.15 or 0.20.
3. Set Max Parallel Scans (Default is 4, Range 1 - 16). Controls how many video files are scanned concurrently during library tasks to maximize multi-core CPU utilization.
4. Set Client Subtitle Offset (Default is 5.0 vh, Range 0.0 - 25.0 vh). Adjusts the vertical offset of subtitles when CSS crop is active in the Web player.
5. Select your preferred Playback Mode:
   • Auto: Lightweight CSS clipping for Web browser DirectPlay; FFmpeg transcoding for native apps.
   • Client: Uses CSS injection in the web player.
   • Server: Requires setting up the FFmpeg wrapper.
6. Live Subtitle Adjustment during Playback: While watching a video in Jellyfin Web with CSS crop enabled, you can press Alt + ArrowUp or Alt + ArrowDown to adjust the subtitle vertical position on the fly in real-time with on-screen feedback!
7. Important for existing libraries: The plugin automatically scans new files when they are added to Jellyfin. For your existing library, go to Dashboard -> Scheduled Tasks and run the "Scan Missing Black Bars (Black Bar Remover)" task manually. It will scan all existing movies and episodes in the background.

Server-side wrapper

In Auto or Server mode, startup generates a wrapper at BlackBarRemover/ffmpeg inside the Jellyfin plugins directory and installs it at /usr/lib/jellyfin-ffmpeg/ffmpeg. The original executable is retained as ffmpeg.original. The Jellyfin process needs write permissions for those paths. If playback fails, check the wrapper's REAL_FFMPEG path and the Jellyfin logs.

Client-side script

The plugin injects /BlackBarRemover/ClientScript.js into Jellyfin Web HTML responses at request time. Reload the web player after enabling the plugin. If the script does not load, check the Jellyfin logs and the browser network panel for the script request.

Architecture

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.

Documentation

README style guide.

Credits

This plugin, including its logic, FFmpeg integrations, and documentation, was generated entirely with the assistance of an advanced AI agent (Google Antigravity / Gemini) during a pair-programming session.

License

No project-level license file is currently included in this repository. Third-party components retain their own licenses.