karol/blackBarRemover
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity

docs: standardize README and add repository documentation guide

Browse Source
This commit is contained in:
karol
2026-10-24 12:56:42 +02:00
parent 86ec128ec8
commit 6c0bfaffb1
2 changed files with 107 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+33 -20
View File
@@ -1,30 +1,33 @@
# Jellyfin Black Bar Remover Plugin
# Jellyfin Black Bar Remover
A Jellyfin plugin that automatically detects and removes black bars (letterboxing/pillarboxing) from video files.
[Features](#features) · [Requirements](#requirements) · [Getting started](#getting-started) · [Configuration](#configuration) · [Architecture](#architecture) · [Documentation](#documentation) · [Credits](#credits) · [License](#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.sh` script that can be used to inject the FFmpeg `-vf crop` filter during active transcoding.
- **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.
## Tested Versions
### Previously documented compatibility
The previous README records testing on the following versions; this documentation update does not revalidate runtime compatibility:
This plugin has been verified and tested on:
- **Jellyfin 10.11.x** (.NET 9.0)
- **Jellyfin 12.0 / 13.0 Unstable** (.NET 10.0)
## Installation
## Getting started
### Method 1: Jellyfin Repository (Recommended & Easiest)
### Install from the Jellyfin repository
> [!TIP]
> **Plugin Repository URL**:
@@ -39,22 +42,25 @@ This plugin has been verified and tested on:
5. Switch to the **Catalog** tab, find **Black Bar Remover** (under the *Playback* category), and click **Install**.
6. Restart your Jellyfin server.
### Method 2: Manual Installation from Releases
### 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.
### Method 3: Building from Source
### 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:
```bash
dotnet build JellyfinPlugin/JellyfinPlugin.csproj -c Release
```
Or build for a specific target framework:
```bash
# For Jellyfin 10.11 (.NET 9.0)
dotnet build JellyfinPlugin/JellyfinPlugin.csproj -c Release -f net9.0
@@ -62,10 +68,11 @@ This plugin has been verified and tested on:
# 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 & Initial Scan
## 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`.
@@ -78,20 +85,26 @@ This plugin has been verified and tested on:
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.
### Activating the Server-Side Wrapper (Automatic)
### Server-side wrapper
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.
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.
### Activating the Client-Side CSS (Automatic)
### Client-side script
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>
```
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.
## How it works
## 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.
---
*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.*
## Documentation
[README style guide](docs/README-STYLE.md).
## 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.