# 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.*