docs: standardize README and add repository documentation guide

JellyfinPlugin/Api/BlackBarService.cs

@@ -61,10 +61,27 @@ namespace JellyfinPlugin.Api
             return Content(string.Empty, "text/plain");
         }
 
+        [HttpGet("Config")]
+        [Produces("application/json")]
+        public IActionResult GetConfig()
+        {
+            var config = Plugin.Instance!.Configuration;
+            return Ok(new
+            {
+                cropDetectLimit = config.CropDetectLimit,
+                playbackMode = config.PlaybackMode,
+                subtitleOffsetVh = config.SubtitleOffsetVh,
+                maxParallelScans = config.MaxParallelScans
+            });
+        }
+
         [HttpGet("ClientScript.js")]
         [Produces("application/javascript")]
         public ContentResult GetClientScript()
         {
+            double defaultSubOffset = Plugin.Instance!.Configuration.SubtitleOffsetVh;
+            string defaultSubOffsetStr = defaultSubOffset.ToString(System.Globalization.CultureInfo.InvariantCulture);
+
             string js = @"
 (function() {
     console.log('Black Bar Remover: Script loaded');
@@ -73,6 +90,8 @@ namespace JellyfinPlugin.Api
     let currentCropData = null;
     window._currentPlayMethod = null;
     window._isVideoDirect = null;
+    window._configuredSubtitleOffsetVh = {SUB_OFFSET};
+    window._customSubtitleOffsetVh = null;
 
     function isTranscoding() {
         if (window._isVideoDirect === false) {
@@ -84,6 +103,85 @@ namespace JellyfinPlugin.Api
         return false;
     }
 
+    function fetchServerConfig() {
+        if (!window._originalFetch) return;
+        window._originalFetch('/BlackBarRemover/Config')
+            .then(r => r.json())
+            .then(data => {
+                if (data && typeof data.subtitleOffsetVh === 'number') {
+                    const newOffset = data.subtitleOffsetVh;
+                    if (newOffset !== window._configuredSubtitleOffsetVh) {
+                        window._configuredSubtitleOffsetVh = newOffset;
+                        console.log('Black Bar Remover: Synced configured subtitle offset:', newOffset + 'vh');
+                        if (window._customSubtitleOffsetVh === null && lastBottomPercent > 0) {
+                            updateSubtitleStyles(lastBottomPercent);
+                        }
+                    }
+                }
+            })
+            .catch(e => {});
+    }
+
+    function showSubtitleToast(msg) {
+        let toastEl = document.getElementById('black-bar-remover-sub-toast');
+        if (!toastEl) {
+            toastEl = document.createElement('div');
+            toastEl.id = 'black-bar-remover-sub-toast';
+            toastEl.style.position = 'fixed';
+            toastEl.style.bottom = '15%';
+            toastEl.style.left = '50%';
+            toastEl.style.transform = 'translateX(-50%)';
+            toastEl.style.backgroundColor = 'rgba(0, 0, 0, 0.85)';
+            toastEl.style.color = '#fff';
+            toastEl.style.padding = '8px 16px';
+            toastEl.style.borderRadius = '20px';
+            toastEl.style.fontSize = '0.95rem';
+            toastEl.style.fontWeight = 'bold';
+            toastEl.style.zIndex = '999999';
+            toastEl.style.pointerEvents = 'none';
+            toastEl.style.transition = 'opacity 0.3s ease';
+            document.body.appendChild(toastEl);
+        }
+        toastEl.textContent = msg;
+        toastEl.style.opacity = '1';
+        if (window._toastTimeout) clearTimeout(window._toastTimeout);
+        window._toastTimeout = setTimeout(() => {
+            toastEl.style.opacity = '0';
+        }, 2000);
+    }
+
+    function getActiveOffsetVh() {
+        if (window._customSubtitleOffsetVh !== null && window._customSubtitleOffsetVh !== undefined) {
+            return window._customSubtitleOffsetVh;
+        }
+        if (window._configuredSubtitleOffsetVh !== null && window._configuredSubtitleOffsetVh !== undefined) {
+            return window._configuredSubtitleOffsetVh;
+        }
+        return 5.0;
+    }
+
+    if (!window._subHotkeyBound) {
+        window._subHotkeyBound = true;
+        window.addEventListener('keydown', function(e) {
+            if (e.altKey && (e.key === 'ArrowUp' || e.key === 'ArrowDown')) {
+                const video = document.querySelector('video');
+                if (!video) return;
+                e.preventDefault();
+                let current = getActiveOffsetVh();
+                if (e.key === 'ArrowUp') {
+                    current = Math.min(25.0, current + 0.5);
+                } else if (e.key === 'ArrowDown') {
+                    current = Math.max(0.0, current - 0.5);
+                }
+                window._customSubtitleOffsetVh = Math.round(current * 10) / 10;
+                showSubtitleToast('Subtitle Offset: ' + window._customSubtitleOffsetVh.toFixed(1) + ' vh (Alt+Up/Down)');
+                if (lastBottomPercent > 0) {
+                    updateSubtitleStyles(lastBottomPercent);
+                }
+            }
+        });
+    }
+
     function ensureBoundingBoxHook(video) {
         if (!video._origGetBoundingClientRect) {
             video._origGetBoundingClientRect = video.getBoundingClientRect;
@@ -109,60 +207,53 @@ namespace JellyfinPlugin.Api
 
     let lastBottomPercent = 0;
 
-    function updateSubtitleStyles(bottomPercent) {
+    function updateSubtitleStyles(bottomPercent) {{
         lastBottomPercent = bottomPercent;
         let styleEl = document.getElementById('black-bar-remover-sub-style');
-        if (!styleEl) {
+        if (!styleEl) {{
             styleEl = document.createElement('style');
             styleEl.id = 'black-bar-remover-sub-style';
             document.head.appendChild(styleEl);
-        }
+        }}
 
-        if (bottomPercent > 0) {
+        if (bottomPercent > 0) {{
-            const offsetVh = (bottomPercent * 0.4 + 2.5).toFixed(2);
+            const activeOffset = getActiveOffsetVh();
-            styleEl.textContent = `
+            const offsetVh = activeOffset.toFixed(2);
-                .videoSubtitles {
+            styleEl.textContent = 
-                    display: flex !important;
+                '.videoSubtitles {' +
-                    flex-direction: column !important;
+                    'display: flex !important;' +
-                    justify-content: flex-end !important;
+                    'flex-direction: column !important;' +
-                    transform: translateY(-${offsetVh}vh) !important;
+                    'justify-content: flex-end !important;' +
-                }
+                    'transform: translateY(-' + offsetVh + 'vh) !important;' +
-                .track-text-output,
+                '}' +
-                .custom-subtitle-overlay,
+                '.track-text-output, .custom-subtitle-overlay, .subtitleSyncContainer, .videoSubtitlesContainer, .libassjs-canvas-parent, canvas.libassjs-canvas, .subtitles-octopus-canvas, .htmlvideoplayer::-webkit-media-text-track-container, .htmlvideoplayer::-webkit-media-text-track-display {' +
-                .subtitleSyncContainer,
+                    'transform: translateY(-' + offsetVh + 'vh) !important;' +
-                .videoSubtitlesContainer,
+                '}';
-                .libassjs-canvas-parent,
-                canvas.libassjs-canvas,
-                .subtitles-octopus-canvas,
-                .htmlvideoplayer::-webkit-media-text-track-container,
-                .htmlvideoplayer::-webkit-media-text-track-display {
-                    transform: translateY(-${offsetVh}vh) !important;
-                }
-            `;
             console.log('Black Bar Remover: Subtitle CSS style updated translateY(-' + offsetVh + 'vh)');
-        } else {
+        }} else {{
             styleEl.textContent = '';
-        }
+        }}
-    }
+    }}
 
-    function adjustVttCues(bottomPercent) {
+    function adjustVttCues(bottomPercent) {{
         const video = document.querySelector('video');
         if (!video || !video.textTracks) return;
-        const targetLine = Math.max(10, 92 - Math.round(bottomPercent * 0.4 + 2.5));
+        const activeOffset = getActiveOffsetVh();
-        for (let i = 0; i < video.textTracks.length; i++) {
+        const targetLine = Math.max(10, 95 - Math.round(activeOffset * 1.5));
+        for (let i = 0; i < video.textTracks.length; i++) {{
             const track = video.textTracks[i];
-            if (track && track.cues) {
+            if (track && track.cues) {{
-                for (let j = 0; j < track.cues.length; j++) {
+                for (let j = 0; j < track.cues.length; j++) {{
                     const cue = track.cues[j];
-                    if (cue && !cue._pluginAdjusted) {
+                    if (cue && !cue._pluginAdjusted) {{
                         cue.snapToLines = false;
                         cue.line = targetLine;
                         cue._pluginAdjusted = true;
-                    }
+                    }}
-                }
+                }}
             }
-        }
+        }}
-    }
+    }}
 
     function applyCrop(cropData) {
         const video = document.querySelector('video');
@@ -376,6 +467,7 @@ namespace JellyfinPlugin.Api
     playbackInfoObserver.observe(document.body, { childList: true, subtree: true, characterData: true });
 
     setInterval(() => {
+        fetchServerConfig();
         const video = document.querySelector('video');
         if (video && interceptedItemId && interceptedItemId !== currentItemId) {
             currentItemId = interceptedItemId;
@@ -393,6 +485,7 @@ namespace JellyfinPlugin.Api
     }, 2000);
 })();
 ";
+            js = js.Replace("{SUB_OFFSET}", defaultSubOffsetStr);
             return Content(js, "application/javascript");
         }
     }

JellyfinPlugin/Configuration/PluginConfiguration.cs

@@ -12,5 +12,11 @@ namespace JellyfinPlugin.Configuration
         
         // Tryb odtwarzania: "Server" (FFmpeg wrapper), "Client" (CSS injection w Web UI), "Auto" (Automatyczny: CSS dla Web, FFmpeg dla aplikacji natywnych)
         public string PlaybackMode { get; set; } = "Auto";
+
+        // Maksymalna liczba równoległych wątków skanowania czarnych pasów (1 - 16, domyślnie 4)
+        public int MaxParallelScans { get; set; } = 4;
+
+        // Przesunięcie pionowe napisów w vh w trybie klienckim CSS (0.0 - 25.0, domyślnie 5.0)
+        public double SubtitleOffsetVh { get; set; } = 5.0;
     }
 }

JellyfinPlugin/Configuration/configPage.html

@@ -33,6 +33,18 @@
                         <div class="fieldDescription">Choose how the plugin should remove black bars. Auto mode uses lightweight CSS clipping for Web browser DirectPlay, and falls back to FFmpeg transcoding for native apps or unsupported video formats.</div>
                     </div>
 
+                    <div class="inputContainer">
+                        <label class="inputLabel inputLabelUnfocused" for="txtMaxParallelScans">Max Parallel Scans (1 - 16):</label>
+                        <input type="number" step="1" min="1" max="16" id="txtMaxParallelScans" is="emby-input" required />
+                        <div class="fieldDescription">Number of files to analyze concurrently during library scheduled tasks. Default is 4. Higher values speed up library scans on multi-core CPUs.</div>
+                    </div>
+
+                    <div class="inputContainer">
+                        <label class="inputLabel inputLabelUnfocused" for="txtSubtitleOffsetVh">Client Subtitle Offset (0.0 - 25.0 vh):</label>
+                        <input type="number" step="0.5" min="0.0" max="25.0" id="txtSubtitleOffsetVh" is="emby-input" required />
+                        <div class="fieldDescription">Vertical offset shift for subtitles in Jellyfin Web player (in viewport height % / vh). Default is 5.0. Increase to move subtitles higher up into the video, or decrease if they appear too high.</div>
+                    </div>
+
                     <div>
                         <button is="emby-button" type="submit" class="raised button-submit block emby-button">
                             <span>Save</span>
@@ -56,6 +68,8 @@
                     var mode = config.PlaybackMode || "Auto";
                     if (mode === "Both") mode = "Auto";
                     $('#selectPlaybackMode', page).val(mode);
+                    $('#txtMaxParallelScans', page).val(config.MaxParallelScans || 4);
+                    $('#txtSubtitleOffsetVh', page).val(config.SubtitleOffsetVh !== undefined ? config.SubtitleOffsetVh : 5.0);
                     Dashboard.hideLoadingMsg();
                 });
             });
@@ -69,6 +83,8 @@
                     config.IsEnabled = $('#chkEnablePlugin', form).prop('checked');
                     config.CropDetectLimit = parseFloat($('#txtCropLimit', form).val());
                     config.PlaybackMode = $('#selectPlaybackMode', form).val();
+                    config.MaxParallelScans = parseInt($('#txtMaxParallelScans', form).val(), 10) || 4;
+                    config.SubtitleOffsetVh = parseFloat($('#txtSubtitleOffsetVh', form).val());
                     
                     ApiClient.updatePluginConfiguration(BlackBarRemoverConfig.pluginUniqueId, config).then(function (result) {
                         Dashboard.processPluginConfigurationUpdateResult(result);

JellyfinPlugin/Tasks/LibraryForceRescanTask.cs

@@ -42,15 +42,21 @@ namespace JellyfinPlugin.Tasks
                 .ToList();
 
             int total = items.Count;
+            if (total == 0) return;
+
             int processed = 0;
+            int maxParallel = Math.Clamp(config.MaxParallelScans, 1, 16);
 
-            foreach (var item in items)
+            var parallelOptions = new ParallelOptions
             {
-                cancellationToken.ThrowIfCancellationRequested();
+                MaxDegreeOfParallelism = maxParallel,
-
+                CancellationToken = cancellationToken
-                // Wymuszamy skanowanie, więc nie sprawdzamy czy ma już BlackBarCrop
+            };
 
+            _logger.LogInformation("Starting Force Rescan of {Total} items with {MaxParallel} parallel workers.", total, maxParallel);
 
+            await Parallel.ForEachAsync(items, parallelOptions, async (item, ct) =>
+            {
                 var path = item.Path;
                 if (!string.IsNullOrEmpty(path) && File.Exists(path))
                 {
@@ -65,7 +71,7 @@ namespace JellyfinPlugin.Tasks
                                 item.ProviderIds = new Dictionary<string, string>();
                             }
                             item.ProviderIds["BlackBarCrop"] = cropData;
-                            await _libraryManager.UpdateItemAsync(item, item, ItemUpdateType.MetadataEdit, cancellationToken);
+                            await _libraryManager.UpdateItemAsync(item, item, ItemUpdateType.MetadataEdit, ct);
                             _logger.LogInformation("Found black bars {Crop} in {Path}", cropData, path);
                         }
                     }
@@ -75,9 +81,9 @@ namespace JellyfinPlugin.Tasks
                     }
                 }
 
-                processed++;
+                int current = Interlocked.Increment(ref processed);
-                progress.Report((processed / (double)total) * 100);
+                progress.Report((current / (double)total) * 100);
-            }
+            });
         }
 
         public IEnumerable<TaskTriggerInfo> GetDefaultTriggers()

JellyfinPlugin/Tasks/LibraryRetroactiveScanTask.cs

@@ -42,19 +42,28 @@ namespace JellyfinPlugin.Tasks
                 .ToList();
 
             int total = items.Count;
+            if (total == 0) return;
+
             int processed = 0;
+            int maxParallel = Math.Clamp(config.MaxParallelScans, 1, 16);
 
-            foreach (var item in items)
+            var parallelOptions = new ParallelOptions
             {
-                cancellationToken.ThrowIfCancellationRequested();
+                MaxDegreeOfParallelism = maxParallel,
+                CancellationToken = cancellationToken
+            };
 
+            _logger.LogInformation("Starting Retroactive Scan of {Total} items with {MaxParallel} parallel workers.", total, maxParallel);
+
+            await Parallel.ForEachAsync(items, parallelOptions, async (item, ct) =>
+            {
                 if (item.ProviderIds != null && 
                     item.ProviderIds.TryGetValue("BlackBarCrop", out string? existingCrop) && 
                     !string.IsNullOrEmpty(existingCrop))
                 {
-                    processed++;
+                    int currentSkipped = Interlocked.Increment(ref processed);
-                    progress.Report((processed / (double)total) * 100);
+                    progress.Report((currentSkipped / (double)total) * 100);
-                    continue;
+                    return;
                 }
 
                 var path = item.Path;
@@ -71,7 +80,7 @@ namespace JellyfinPlugin.Tasks
                                 item.ProviderIds = new Dictionary<string, string>();
                             }
                             item.ProviderIds["BlackBarCrop"] = cropData;
-                            await _libraryManager.UpdateItemAsync(item, item, ItemUpdateType.MetadataEdit, cancellationToken);
+                            await _libraryManager.UpdateItemAsync(item, item, ItemUpdateType.MetadataEdit, ct);
                             _logger.LogInformation("Found black bars {Crop} in {Path}", cropData, path);
                         }
                     }
@@ -81,9 +90,9 @@ namespace JellyfinPlugin.Tasks
                     }
                 }
 
-                processed++;
+                int currentDone = Interlocked.Increment(ref processed);
-                progress.Report((processed / (double)total) * 100);
+                progress.Report((currentDone / (double)total) * 100);
-            }
+            });
         }
 
         public IEnumerable<TaskTriggerInfo> GetDefaultTriggers()

README.md

@@ -1,54 +1,66 @@
-# 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).
+    - **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.
+    - **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
 
-1. Open your Jellyfin Dashboard and navigate to **Plugins** -> **Repositories**.
+> [!TIP]
-2. Click the `+` icon to add a new repository.
+> **Plugin Repository URL**:
-3. Enter `Black Bar Remover` as the name.
+> ```text
-4. Enter `https://gitea.labus.uk/karol/blackBarRemover/raw/branch/master/manifest.json` as the Repository URL and save.
+> https://gitea.labus.uk/karol/blackBarRemover/raw/branch/master/manifest.json
-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. 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.
 
-### 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
@@ -56,33 +68,43 @@ 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`.
-3. Select your preferred **Playback Mode**:
+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.
-   - `Both`: Attempts both methods depending on the client.
+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!
-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.
+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**:
+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.
-```html
-<script src="/BlackBarRemover/ClientScript.js"></script>
-```
 
-## 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.
 
----
+## Documentation
-*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.*
+
+[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.

docs/README-STYLE.md

@@ -0,0 +1,74 @@
+# Repository README standard
+
+Version: 1.0. Documentation language: English.
+
+A README should explain the project, help a new reader start it, and point to detailed references. Keep project-specific instructions and existing attribution when applying this standard.
+
+## Original projects
+
+Start with one `# Project name` heading and a short description of what the project does and who it serves. An optional local screenshot or banner may follow. Then add a navigation line linking to the level-two sections present in the document.
+
+Use these level-two headings in this order. Omit sections that do not apply; do not add empty sections or filler just to match the template.
+
+| Section | Content |
+| --- | --- |
+| Features | Concrete capabilities and supported use cases. |
+| Requirements | Runtime, hardware, services, and build prerequisites; distinguish build from runtime needs. |
+| Getting started | Shortest complete path from checkout or download to a working result, including initial setup. |
+| Configuration | Settings, defaults, required values, and example files. Explain prerequisites before commands that need them. |
+| Usage | Common workflows, commands, and expected output or artifact locations. |
+| Architecture | Project layout, interfaces, data model, or hardware overview. |
+| Limitations | Known constraints and validation boundaries; keep critical setup constraints near the affected step too. |
+| Development | Build, test, validation, and release instructions supported by repository files. |
+| Documentation | Links to detailed guides, diagrams, screenshots, and this style guide. |
+| Credits | Contributors, reused work, upstream sources, and existing AI-assistance disclosures. |
+| License | Link to the actual project license; state explicitly when no project-level license file exists. |
+
+Keep specialized content under these headings using `###` and `####`. For example, put power variants under Configuration, pinouts under Architecture, and schematic downloads under Documentation or Architecture. Small component READMEs can use only the relevant sections and link back to the root README.
+
+## Forks
+
+Use the same formatting rules, but introduce the fork before describing the original project. Start with one title, a short fork description, and clearly labeled links to upstream and the fork repository.
+
+Use these headings in order, omitting optional sections when unnecessary:
+
+1. Fork purpose
+2. Changes from upstream
+3. Requirements
+4. Getting started
+5. Configuration
+6. Usage
+7. Architecture
+8. Limitations
+9. Development
+10. Upstream maintenance
+11. Documentation
+12. Credits
+13. License
+
+Explain why the fork exists, list its differences, and identify where to obtain its builds. Clearly label links to upstream builds, contribution channels, and screenshots. Include upstream synchronization instructions based on the actual workflow, and checks needed after merges.
+
+Keep inherited documentation in `README.upstream.md` at the repository root. Keeping it beside the original README preserves relative links to assets. Retain upstream attribution, donations, and license notices there. Label any local corrections; this file is inherited documentation, not a claim to be the latest upstream version. After an upstream merge, refresh the inherited file and review the fork README separately. Do not overwrite the fork's explanation with the upstream README.
+
+Borrowing a component or taking inspiration from another project does not by itself make the entire repository a fork. Explain that relationship under Credits and preserve component licensing.
+
+## Markdown and accuracy
+
+- Write documentation in English. Preserve proper names and UI labels as shown in the product.
+- Use one H1, sentence-case headings, and consecutive heading levels. Do not number headings.
+- Separate paragraphs, headings, lists, tables, and fenced blocks with blank lines.
+- Use `-` for unordered lists. Indent nested content consistently; use four spaces for nested unordered lists.
+- Label fenced blocks: `bash`, `sh`, `powershell`, `python`, `json`, `yaml`, `dotenv`, `text`, or `mermaid` as appropriate.
+- Run commands from the repository root unless a different working directory is explicitly stated.
+- Use placeholders or portable example paths instead of private workstation paths. Never include real tokens, passwords, private keys, or local data.
+- Link to versioned files using relative paths. Use full URLs for other repositories, services, and upstream sources. Avoid sibling-checkout links.
+- Prefer Markdown. Use HTML only when it improves a gallery or layout; provide image alt text.
+- Keep navigation anchors synchronized with headings. Avoid duplicate headings that create ambiguous anchors.
+- Avoid decorative badges, repeated separators, promotional claims, and unsupported claims of production readiness or completed testing.
+- Verify requirements and commands against manifests, scripts, configuration, and workflows. Distinguish previously documented results from checks performed during an edit.
+- Preserve existing technical instructions, screenshots, credits, and license notices when reorganizing. Move long references into `docs/` when useful and update links relative to their new location.
+- Never infer a license from a badge, framework, dependency, or a different repository. License choices require an explicit project decision.
+
+## Maintenance
+
+Update the README alongside changes to installation, configuration, commands, supported hardware, or release behavior. Check local links, navigation, and Markdown structure before committing. Run a command only when its effects are appropriate; a documentation check must not flash hardware, publish a release, send messages, or start an import.

manifest.json

@@ -8,21 +8,69 @@
         "category": "Playback",
         "imageUrl": "",
         "versions": [
+            {
+                "version": "0.1.22",
+                "changelog": "Release v0.1.22-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.22-beta/BlackBarRemover_v0.1.22-beta_jf12.0.zip",
+                "checksum": "55d64618d81ea1091200c5566cd771e5",
+                "timestamp": "2026-09-19T20:27:28Z"
+            },
+            {
+                "version": "0.1.22",
+                "changelog": "Release v0.1.22-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.22-beta/BlackBarRemover_v0.1.22-beta_jf10.11.zip",
+                "checksum": "e18d3599973ebedba08de6494cfed3cb",
+                "timestamp": "2026-09-19T20:27:28Z"
+            },
+            {
+                "version": "0.1.21",
+                "changelog": "Release v0.1.21-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.21-beta/BlackBarRemover_v0.1.21-beta_jf12.0.zip",
+                "checksum": "",
+                "timestamp": "2026-09-18T00:14:20+02:00"
+            },
+            {
+                "version": "0.1.21",
+                "changelog": "Release v0.1.21-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.21-beta/BlackBarRemover_v0.1.21-beta_jf10.11.zip",
+                "checksum": "",
+                "timestamp": "2026-09-18T00:14:20+02:00"
+            },
+            {
+                "version": "0.1.20",
+                "changelog": "Release v0.1.20-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.20-beta/BlackBarRemover_v0.1.20-beta_jf12.0.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T23:45:19+02:00"
+            },
+            {
+                "version": "0.1.20",
+                "changelog": "Release v0.1.20-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.20-beta/BlackBarRemover_v0.1.20-beta_jf10.11.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T23:45:19+02:00"
+            },
             {
                 "version": "0.1.19",
                 "changelog": "Release v0.1.19-beta (Jellyfin 12.0)",
                 "targetAbi": "12.0.0.0",
                 "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.19-beta/BlackBarRemover_v0.1.19-beta_jf12.0.zip",
-                "checksum": "baed36aef30d4cece36d1b36cd67775f",
+                "checksum": "",
-                "timestamp": "2026-09-17T19:57:09Z"
+                "timestamp": "2026-09-17T21:56:15+02:00"
             },
             {
                 "version": "0.1.19",
                 "changelog": "Release v0.1.19-beta (Jellyfin 10.11)",
                 "targetAbi": "10.11.0.0",
                 "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.19-beta/BlackBarRemover_v0.1.19-beta_jf10.11.zip",
-                "checksum": "9bb29cf4ba5e351059a92a9a7ac5b85f",
+                "checksum": "",
-                "timestamp": "2026-09-17T19:57:09Z"
+                "timestamp": "2026-09-17T21:56:15+02:00"
             },
             {
                 "version": "0.1.18",