74 lines
4.4 KiB
Markdown
74 lines
4.4 KiB
Markdown
# 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: Jellyfin Repository (Recommended & Easiest)
|
|
|
|
1. Open your Jellyfin Dashboard and navigate to **Plugins** -> **Repositories**.
|
|
2. Click the `+` icon to add a new repository.
|
|
3. Enter `Black Bar Remover` as the name.
|
|
4. Enter `https://gitea.labus.uk/karol/blackBarRemover/raw/branch/manifest/manifest.json` as the Repository URL and save.
|
|
5. Go back to the **Catalog** tab, find "Black Bar Remover" under the Playback category, and click **Install**.
|
|
6. Restart the Jellyfin server.
|
|
|
|
### Method 2: Manual Installation 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.
|
|
|
|
### Method 3: Building from Source
|
|
|
|
1. Clone this repository.
|
|
2. Build the plugin using the .NET 9 SDK:
|
|
```bash
|
|
dotnet build JellyfinPlugin/JellyfinPlugin.csproj -c Release
|
|
```
|
|
3. Copy the compiled DLLs from `JellyfinPlugin/bin/Release/net9.0/` into a new folder named `BlackBarRemover` inside your Jellyfin plugins directory.
|
|
4. Restart the Jellyfin server.
|
|
|
|
### Configuration & Initial Scan
|
|
|
|
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.
|
|
4. **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.
|
|
|
|
### Activating the Server-Side Wrapper (Automatic)
|
|
|
|
If you select "Server" or "Both" mode, the plugin automatically generates a wrapper script and dynamically injects it into Jellyfin's `EncoderAppPath` configuration during startup. It takes over the transcoding process effortlessly. If it ever points to the wrong real FFmpeg, you can adjust it in the wrapper script.
|
|
|
|
### 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**:
|
|
```html
|
|
<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.
|
|
|
|
---
|
|
*Note: 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.*
|