57 lines
3.0 KiB
Markdown
57 lines
3.0 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: Building from Source
|
|
|
|
1. Clone this repository.
|
|
2. Build the plugin using the .NET 10 SDK:
|
|
```bash
|
|
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**:
|
|
```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.
|