docs: standardize README and add repository documentation guide

.gitea/workflows/release.yml

@@ -46,60 +46,167 @@ jobs:
           echo "md5_9=$MD5_SUM_9" >> $GITHUB_OUTPUT
           echo "md5_10=$MD5_SUM_10" >> $GITHUB_OUTPUT
 
-      - name: Create Gitea Release
+      - name: Publish Release and Update Manifest
+        env:
+          API_URL: ${{ github.api_url }}
+          REPO: ${{ github.repository }}
+          TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+          MD5_9: ${{ steps.checksum.outputs.md5_9 }}
+          MD5_10: ${{ steps.checksum.outputs.md5_10 }}
         run: |
-          API_URL="${{ github.api_url }}"
-          REPO="${{ github.repository }}"
-          TOKEN="${{ github.token }}"
-          TAG="${{ github.ref_name }}"
+          python3 -c '
+          import os, json, urllib.request, base64, datetime
 
-          IS_PRERELEASE="false"
-          if [[ "$TAG" =~ beta|alpha|^v0\. ]]; then
-            IS_PRERELEASE="true"
-          fi
+          api_url = os.environ["API_URL"]
+          repo = os.environ["REPO"]
+          token = os.environ["TOKEN"]
+          tag = os.environ["TAG"]
+          md5_9 = os.environ["MD5_9"]
+          md5_10 = os.environ["MD5_10"]
 
-          # Check if release exists
-          EXISTING_REL=$(curl -s -H "Authorization: token $TOKEN" "$API_URL/repos/$REPO/releases/tags/$TAG")
-          REL_ID=$(echo "$EXISTING_REL" | grep -o '"id":[0-9]*' | head -1 | cut -d':' -f2)
+          headers = {
+              "Authorization": f"token {token}",
+              "Content-Type": "application/json"
+          }
 
-          if [ -z "$REL_ID" ] || [ "$REL_ID" == "null" ]; then
-            RELEASE_RES=$(curl -s -X POST "$API_URL/repos/$REPO/releases" \
-              -H "Authorization: token $TOKEN" \
-              -H "Content-Type: application/json" \
-              -d "{\"tag_name\":\"$TAG\", \"name\":\"Release $TAG\", \"body\":\"Automated release\", \"draft\":false, \"prerelease\":$IS_PRERELEASE}")
-            REL_ID=$(echo "$RELEASE_RES" | grep -o '"id":[0-9]*' | head -1 | cut -d':' -f2)
-          fi
+          # 1. Get or Create Release
+          rel_url = f"{api_url}/repos/{repo}/releases/tags/{tag}"
+          req = urllib.request.Request(rel_url, headers=headers)
+          rel_data = None
+          try:
+              res = urllib.request.urlopen(req)
+              rel_data = json.loads(res.read().decode("utf-8"))
+          except Exception:
+              pass
 
-          # Delete existing assets for this release if present
-          ASSETS=$(curl -s -H "Authorization: token $TOKEN" "$API_URL/repos/$REPO/releases/$REL_ID/assets")
-          echo "$ASSETS" | grep -o '"id":[0-9]*' | cut -d':' -f2 | while read -r asset_id; do
-            if [ -n "$asset_id" ]; then
-              curl -s -X DELETE -H "Authorization: token $TOKEN" "$API_URL/repos/$REPO/releases/$REL_ID/assets/$asset_id"
-            fi
-          done
+          if not rel_data or "id" not in rel_data:
+              is_pre = "beta" in tag or "alpha" in tag or tag.startswith("v0.")
+              create_url = f"{api_url}/repos/{repo}/releases"
+              body = json.dumps({
+                  "tag_name": tag,
+                  "name": f"Release {tag}",
+                  "body": "Automated release",
+                  "draft": False,
+                  "prerelease": is_pre
+              }).encode("utf-8")
+              create_req = urllib.request.Request(create_url, data=body, headers=headers)
+              res = urllib.request.urlopen(create_req)
+              rel_data = json.loads(res.read().decode("utf-8"))
 
-          # Upload Assets
-          curl -s -X POST "$API_URL/repos/$REPO/releases/$REL_ID/assets" \
-            -H "Authorization: token $TOKEN" \
-            -F "attachment=@BlackBarRemover_${TAG}_jf10.11.zip"
+          rel_id = rel_data["id"]
 
-          curl -s -X POST "$API_URL/repos/$REPO/releases/$REL_ID/assets" \
-            -H "Authorization: token $TOKEN" \
-            -F "attachment=@BlackBarRemover_${TAG}_jf12.0.zip"
+          # 2. Upload Assets
+          for filename in [f"BlackBarRemover_{tag}_jf10.11.zip", f"BlackBarRemover_{tag}_jf12.0.zip"]:
+              if not os.path.exists(filename):
+                  print(f"File {filename} not found, skipping.")
+                  continue
               
-      - name: Update manifest.json
-        run: |
-          git config user.name "Gitea Actions"
-          git config user.email "actions@gitea.local"
+              # Delete existing asset if any
+              for existing_asset in rel_data.get("assets", []) or []:
+                  if existing_asset.get("name") == filename:
+                      del_url = f"{api_url}/repos/{repo}/releases/{rel_id}/assets/{existing_asset['id']}"
+                      del_req = urllib.request.Request(del_url, headers=headers, method="DELETE")
+                      try:
+                          urllib.request.urlopen(del_req)
+                          print(f"Deleted old asset {existing_asset['id']}")
+                      except Exception as e:
+                          print(f"Delete asset notice: {e}")
 
-          git checkout -B manifest
+              # Upload asset
+              with open(filename, "rb") as f:
+                  file_bytes = f.read()
               
-          VERSION="${{ github.ref_name }}"
-          VERSION="${VERSION#v}"
-          CLEAN_VERSION="${VERSION%%-*}"
+              boundary = "----WebKitFormBoundary7MA4YWxkTrZu0gW"
+              body_data = (
+                  f"--{boundary}\r\n"
+                  f"Content-Disposition: form-data; name=\"attachment\"; filename=\"{filename}\"\r\n"
+                  f"Content-Type: application/zip\r\n\r\n"
+              ).encode("utf-8") + file_bytes + f"\r\n--{boundary}--\r\n".encode("utf-8")
               
-          cat > manifest.json <<EOF
-          [
+              upload_headers = {
+                  "Authorization": f"token {token}",
+                  "Content-Type": f"multipart/form-data; boundary={boundary}"
+              }
+              upload_url = f"{api_url}/repos/{repo}/releases/{rel_id}/assets"
+              upload_req = urllib.request.Request(upload_url, data=body_data, headers=upload_headers)
+              try:
+                  urllib.request.urlopen(upload_req)
+                  print(f"Uploaded {filename} successfully.")
+              except Exception as e:
+                  print(f"Asset upload error: {e}")
+
+          # 3. Build manifest.json dynamically from Gitea Releases API
+          rel_list_req = urllib.request.Request(f"{api_url}/repos/{repo}/releases?per_page=100", headers=headers)
+          all_releases = []
+          try:
+              res_list = urllib.request.urlopen(rel_list_req)
+              all_releases = json.loads(res_list.read().decode("utf-8"))
+          except Exception as e:
+              print(f"Notice fetching releases list: {e}")
+
+          all_versions = []
+          for r in all_releases:
+              rel_tag = r.get("tag_name")
+              if not rel_tag:
+                  continue
+              clean_v = rel_tag.lstrip("v").split("-")[0]
+              ts = r.get("published_at") or r.get("created_at") or "2026-09-17T20:00:00Z"
+              assets = r.get("assets", [])
+
+              if rel_tag == tag:
+                  all_versions.append({
+                      "version": clean_v,
+                      "changelog": f"Release {tag} (Jellyfin 12.0)",
+                      "targetAbi": "12.0.0.0",
+                      "sourceUrl": f"https://gitea.labus.uk/karol/blackBarRemover/releases/download/{tag}/BlackBarRemover_{tag}_jf12.0.zip",
+                      "checksum": md5_10,
+                      "timestamp": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+                  })
+                  all_versions.append({
+                      "version": clean_v,
+                      "changelog": f"Release {tag} (Jellyfin 10.11)",
+                      "targetAbi": "10.11.0.0",
+                      "sourceUrl": f"https://gitea.labus.uk/karol/blackBarRemover/releases/download/{tag}/BlackBarRemover_{tag}_jf10.11.zip",
+                      "checksum": md5_9,
+                      "timestamp": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+                  })
+              else:
+                  a12 = next((a for a in assets if "jf12.0" in a.get("name", "")), None)
+                  if a12:
+                      a12_name = a12.get("name")
+                      all_versions.append({
+                          "version": clean_v,
+                          "changelog": f"Release {rel_tag} (Jellyfin 12.0)",
+                          "targetAbi": "12.0.0.0",
+                          "sourceUrl": f"https://gitea.labus.uk/karol/blackBarRemover/releases/download/{rel_tag}/{a12_name}",
+                          "checksum": a12.get("md5") or "",
+                          "timestamp": ts
+                      })
+                  a10 = next((a for a in assets if "jf10.11" in a.get("name", "")), None)
+                  if a10:
+                      a10_name = a10.get("name")
+                      all_versions.append({
+                          "version": clean_v,
+                          "changelog": f"Release {rel_tag} (Jellyfin 10.11)",
+                          "targetAbi": "10.11.0.0",
+                          "sourceUrl": f"https://gitea.labus.uk/karol/blackBarRemover/releases/download/{rel_tag}/{a10_name}",
+                          "checksum": a10.get("md5") or "",
+                          "timestamp": ts
+                      })
+                  if not a12 and not a10 and assets:
+                      alegacy = assets[0]
+                      leg_name = alegacy.get("name")
+                      all_versions.append({
+                          "version": clean_v,
+                          "changelog": f"Release {rel_tag}",
+                          "targetAbi": "10.9.0.0",
+                          "sourceUrl": f"https://gitea.labus.uk/karol/blackBarRemover/releases/download/{rel_tag}/{leg_name}",
+                          "checksum": alegacy.get("md5") or "",
+                          "timestamp": ts
+                      })
+
+          manifest_data = [
               {
                   "guid": "12345678-1234-1234-1234-1234567890ab",
                   "name": "Black Bar Remover",
@@ -108,28 +215,36 @@ jobs:
                   "owner": "karol",
                   "category": "Playback",
                   "imageUrl": "",
-                  "versions": [
-                      {
-                          "version": "$CLEAN_VERSION",
-                          "changelog": "Automated Release ${{ github.ref_name }} (Jellyfin 12.0)",
-                          "targetAbi": "12.0.0.0",
-                          "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/${{ github.ref_name }}/BlackBarRemover_${{ github.ref_name }}_jf12.0.zip",
-                          "checksum": "${{ steps.checksum.outputs.md5_10 }}",
-                          "timestamp": "$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
-                      },
-                      {
-                          "version": "$CLEAN_VERSION",
-                          "changelog": "Automated Release ${{ github.ref_name }} (Jellyfin 10.11)",
-                          "targetAbi": "10.11.0.0",
-                          "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/${{ github.ref_name }}/BlackBarRemover_${{ github.ref_name }}_jf10.11.zip",
-                          "checksum": "${{ steps.checksum.outputs.md5_9 }}",
-                          "timestamp": "$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
+                  "versions": all_versions
               }
           ]
-              }
-          ]
-          EOF
 
-          git add manifest.json
-          git commit -m "Update manifest for ${{ github.ref_name }}"
-          git push -f "https://${TOKEN}@gitea.local.labus.uk/${REPO}.git" manifest
+          b64_manifest = base64.b64encode(json.dumps(manifest_data, indent=4).encode("utf-8")).decode("utf-8")
+
+          # Update on master and manifest branches
+          for target_branch in ["master", "manifest"]:
+              get_mf_url = f"{api_url}/repos/{repo}/contents/manifest.json?ref={target_branch}"
+              req_mf = urllib.request.Request(get_mf_url, headers=headers)
+              file_sha = None
+              try:
+                  res_mf = urllib.request.urlopen(req_mf)
+                  file_sha = json.loads(res_mf.read().decode("utf-8")).get("sha")
+              except Exception:
+                  pass
+
+              put_payload = {
+                  "content": b64_manifest,
+                  "message": f"Update manifest.json for {tag}",
+                  "branch": target_branch
+              }
+              if file_sha:
+                  put_payload["sha"] = file_sha
+
+              put_url = f"{api_url}/repos/{repo}/contents/manifest.json"
+              put_req = urllib.request.Request(put_url, data=json.dumps(put_payload).encode("utf-8"), headers=headers, method="PUT")
+              try:
+                  urllib.request.urlopen(put_req)
+                  print(f"manifest.json updated successfully on branch {target_branch}.")
+              except Exception as e:
+                  print(f"Notice updating branch {target_branch}: {e}")
+          '

JellyfinPlugin/Api/BlackBarService.cs

@@ -61,19 +61,218 @@ 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');
     let currentItemId = null;
     let interceptedItemId = null;
+    let currentCropData = null;
+    window._currentPlayMethod = null;
+    window._isVideoDirect = null;
+    window._configuredSubtitleOffsetVh = {SUB_OFFSET};
+    window._customSubtitleOffsetVh = null;
+
+    function isTranscoding() {
+        if (window._isVideoDirect === false) {
+            return true;
+        }
+        if (window._isVideoDirect === true) {
+            return false;
+        }
+        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;
+            video.getBoundingClientRect = function() {
+                if (video._isCroppedByPlugin && video.parentElement) {
+                    const rect = video.parentElement.getBoundingClientRect();
+                    return {
+                        top: rect.top,
+                        right: rect.right,
+                        bottom: rect.bottom,
+                        left: rect.left,
+                        width: rect.width,
+                        height: rect.height,
+                        x: rect.x !== undefined ? rect.x : rect.left,
+                        y: rect.y !== undefined ? rect.y : rect.top,
+                        toJSON: function() { return this; }
+                    };
+                }
+                return video._origGetBoundingClientRect.apply(this, arguments);
+            };
+        }
+    }
+
+    let lastBottomPercent = 0;
+
+    function updateSubtitleStyles(bottomPercent) {{
+        lastBottomPercent = bottomPercent;
+        let styleEl = document.getElementById('black-bar-remover-sub-style');
+        if (!styleEl) {{
+            styleEl = document.createElement('style');
+            styleEl.id = 'black-bar-remover-sub-style';
+            document.head.appendChild(styleEl);
+        }}
+
+        if (bottomPercent > 0) {{
+            const activeOffset = getActiveOffsetVh();
+            const offsetVh = activeOffset.toFixed(2);
+            styleEl.textContent = 
+                '.videoSubtitles {' +
+                    'display: flex !important;' +
+                    'flex-direction: column !important;' +
+                    'justify-content: flex-end !important;' +
+                    'transform: translateY(-' + offsetVh + 'vh) !important;' +
+                '}' +
+                '.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 {' +
+                    'transform: translateY(-' + offsetVh + 'vh) !important;' +
+                '}';
+            console.log('Black Bar Remover: Subtitle CSS style updated translateY(-' + offsetVh + 'vh)');
+        }} else {{
+            styleEl.textContent = '';
+        }}
+    }}
+
+    function adjustVttCues(bottomPercent) {{
+        const video = document.querySelector('video');
+        if (!video || !video.textTracks) return;
+        const activeOffset = getActiveOffsetVh();
+        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) {{
+                for (let j = 0; j < track.cues.length; j++) {{
+                    const cue = track.cues[j];
+                    if (cue && !cue._pluginAdjusted) {{
+                        cue.snapToLines = false;
+                        cue.line = targetLine;
+                        cue._pluginAdjusted = true;
+                    }}
+                }}
+            }
+        }}
+    }}
 
     function applyCrop(cropData) {
         const video = document.querySelector('video');
         if (!video) return;
+
+        if (isTranscoding()) {
+            console.log('Black Bar Remover: Video is transcoded by server (IsVideoDirect: false), skipping CSS crop.');
+            video.style.position = '';
+            video.style.objectFit = '';
+            video.style.width = '';
+            video.style.height = '';
+            video.style.top = '';
+            video.style.left = '';
+            video.style.clipPath = '';
+            video.style.transform = '';
+            updateSubtitleStyles(0);
+            return;
+        }
+
         const parts = cropData.split(':');
         if (parts.length === 4) {
             const w = parseInt(parts[0]);
@@ -81,21 +280,28 @@ namespace JellyfinPlugin.Api
             const x = parseInt(parts[2]);
             const y = parseInt(parts[3]);
             
-            const topPercent = (y / 1080) * 100;
+            if (h > 0 && h < 1080) {
+                const heightPercent = (1080 / h) * 100;
+                const topPercent = -(y / h) * 100;
                 const bottomPercent = ((1080 - (y + h)) / 1080) * 100;
-            const leftPercent = (x / 1920) * 100;
-            const rightPercent = ((1920 - (x + w)) / 1920) * 100;
 
-            video.style.clipPath = `inset(${topPercent}% ${rightPercent}% ${bottomPercent}% ${leftPercent}%)`;
+                video.style.position = 'absolute';
+                video.style.objectFit = 'fill';
+                video.style.width = '100%';
+                video.style.height = heightPercent.toFixed(2) + '%';
+                video.style.top = topPercent.toFixed(2) + '%';
+                video.style.left = '0%';
+                video.style.transform = 'none';
+                video.style.clipPath = 'none';
 
-            const scaleY = 1 / (1 - (topPercent + bottomPercent)/100);
-            const scaleX = 1 / (1 - (leftPercent + rightPercent)/100);
-            const scale = Math.max(scaleY, scaleX);
-            
-            if (scale > 1.01) {
-                video.style.transform = `scale(${scale})`;
+                if (video.parentElement) {
+                    video.parentElement.style.overflow = 'hidden';
+                }
+
+                updateSubtitleStyles(bottomPercent);
+                adjustVttCues(bottomPercent);
+                console.log('Black Bar Remover: Applied non-scaling crop height:', heightPercent.toFixed(2) + '% top:', topPercent.toFixed(2) + '% subOffset:', (bottomPercent * 0.4 + 2.5).toFixed(2) + 'vh');
             }
-            console.log('Black Bar Remover: Applied crop', cropData, 'scale', scale);
         }
     }
 
@@ -106,6 +312,7 @@ namespace JellyfinPlugin.Api
             .then(crop => {
                 console.log('Black Bar Remover: Received crop data:', crop);
                 if (crop) {
+                    currentCropData = crop;
                     setTimeout(() => applyCrop(crop), 500);
                     setTimeout(() => applyCrop(crop), 2000);
                 }
@@ -117,17 +324,39 @@ namespace JellyfinPlugin.Api
         window._originalFetch = window.fetch;
         window.fetch = async function(...args) {
             const url = typeof args[0] === 'string' ? args[0] : (args[0] && args[0].url);
-            if (url) {
+            if (url && typeof url === 'string') {
                 const match = url.match(/\/Items\/([a-f0-9]{32}|[a-f0-9\-]{36})/i);
                 if (match) {
                     const id = match[1];
                     if (id && id !== interceptedItemId) {
                         interceptedItemId = id;
+                        window._currentPlayMethod = null;
+                        window._isVideoDirect = null;
                         console.log('Black Bar Remover: Intercepted itemId from fetch:', id);
                     }
                 }
             }
-            return window._originalFetch.apply(this, args);
+
+            const res = await window._originalFetch.apply(this, args);
+
+            if (url && typeof url === 'string' && url.includes('/PlaybackInfo')) {
+                try {
+                    const clone = res.clone();
+                    clone.json().then(data => {
+                        if (data && data.MediaSources && data.MediaSources[0]) {
+                            const ms = data.MediaSources[0];
+                            window._currentPlayMethod = ms.PlayMethod;
+                            window._isVideoDirect = ms.IsVideoDirect !== false;
+                            console.log('Black Bar Remover: PlaybackInfo detected -> PlayMethod:', window._currentPlayMethod, 'IsVideoDirect:', window._isVideoDirect);
+                            if (currentCropData) {
+                                applyCrop(currentCropData);
+                            }
+                        }
+                    }).catch(e => {});
+                } catch(e) {}
+            }
+
+            return res;
         };
     }
     
@@ -143,9 +372,27 @@ namespace JellyfinPlugin.Api
                         const id = match[1];
                         if (id && id !== interceptedItemId) {
                             interceptedItemId = id;
+                            window._currentPlayMethod = null;
+                            window._isVideoDirect = null;
                             console.log('Black Bar Remover: Intercepted itemId from XHR:', id);
                         }
                     }
+                    if (url.includes('/PlaybackInfo')) {
+                        xhr.addEventListener('load', function() {
+                            try {
+                                const data = JSON.parse(xhr.responseText);
+                                if (data && data.MediaSources && data.MediaSources[0]) {
+                                    const ms = data.MediaSources[0];
+                                    window._currentPlayMethod = ms.PlayMethod;
+                                    window._isVideoDirect = ms.IsVideoDirect !== false;
+                                    console.log('Black Bar Remover: XHR PlaybackInfo detected -> PlayMethod:', window._currentPlayMethod, 'IsVideoDirect:', window._isVideoDirect);
+                                    if (currentCropData) {
+                                        applyCrop(currentCropData);
+                                    }
+                                }
+                            } catch(e) {}
+                        });
+                    }
                 }
                 return originalOpen.apply(this, [method, url, ...rest]);
             };
@@ -220,19 +467,25 @@ 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;
             console.log('Black Bar Remover: Video element found for intercepted item:', currentItemId);
             fetchCrop(currentItemId);
             checkServerCrop(currentItemId);
+        } else if (video && lastBottomPercent > 0) {
+            updateSubtitleStyles(lastBottomPercent);
+            adjustVttCues(lastBottomPercent);
         } else if (!video) {
             currentItemId = null;
+            lastBottomPercent = 0;
             window._isServerCropping = false;
         }
     }, 2000);
 })();
 ";
+            js = js.Replace("{SUB_OFFSET}", defaultSubOffsetStr);
             return Content(js, "application/javascript");
         }
     }

JellyfinPlugin/Configuration/PluginConfiguration.cs

@@ -10,7 +10,13 @@ namespace JellyfinPlugin.Configuration
         // Czy wtyczka jest aktywna
         public bool IsEnabled { get; set; } = true;
         
-        // Tryb odtwarzania: "Server" (FFmpeg wrapper), "Client" (CSS injection w Web UI), "Both" (Obydwa naraz)
-        public string PlaybackMode { get; set; } = "Both";
+        // 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

@@ -26,11 +26,23 @@
                     <div class="selectContainer">
                         <label class="selectLabel" for="selectPlaybackMode">Black Bar Removal Method:</label>
                         <select is="emby-select" id="selectPlaybackMode" class="emby-select-withcolor">
+                            <option value="Auto">Auto (CSS clip in Web, Transcode on Native Apps / Transcoded streams)</option>
                             <option value="Server">Server Only (FFmpeg Transcoding)</option>
                             <option value="Client">Client Only (CSS Clip in Jellyfin Web)</option>
-                            <option value="Both">Both (Transcoding or CSS, depending on client)</option>
                         </select>
-                        <div class="fieldDescription">Choose how the plugin should remove black bars. Server option forces transcoding (CPU/GPU load), Client option is lightweight but only works in web browsers.</div>
+                        <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>
@@ -53,7 +65,11 @@
                 ApiClient.getPluginConfiguration(BlackBarRemoverConfig.pluginUniqueId).then(function (config) {
                     $('#chkEnablePlugin', page).prop('checked', config.IsEnabled !== false);
                     $('#txtCropLimit', page).val(config.CropDetectLimit || 0.094);
-                    $('#selectPlaybackMode', page).val(config.PlaybackMode || "Both");
+                    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();
                 });
             });
@@ -67,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/PlaybackInfoInterceptorStartupFilter.cs

@@ -60,6 +60,14 @@ namespace JellyfinPlugin
                 return;
             }
 
+            var isAutoMode = config.PlaybackMode == "Auto" || config.PlaybackMode == "Both";
+            if (isAutoMode && IsJellyfinWebClient(context))
+            {
+                // W trybie Auto dla przeglądarki Web pozwalamy na Direct Play (przycięcie wykona skrypt CSS w przeglądarce).
+                await nextMw().ConfigureAwait(false);
+                return;
+            }
+
             // --- HLS STREAM QUERY REWRITE ---
             // If the client requests the m3u8 playlist, we simply tell Jellyfin NOT to allow video stream copy.
             // This elegantly forces transcoding for the BEST supported codec without breaking FFmpeg tags/filters!
@@ -147,5 +155,43 @@ namespace JellyfinPlugin
 
             await nextMw().ConfigureAwait(false);
         }
+
+        private static bool IsJellyfinWebClient(HttpContext context)
+        {
+            if (context.Request.Headers.TryGetValue("X-Emby-Authorization", out var authHeader) ||
+                context.Request.Headers.TryGetValue("Authorization", out authHeader))
+            {
+                var authStr = authHeader.ToString();
+                if (authStr.Contains("Client=\"Jellyfin Web\"", StringComparison.OrdinalIgnoreCase) ||
+                    authStr.Contains("Client=\"Jellyfin%20Web\"", StringComparison.OrdinalIgnoreCase) ||
+                    authStr.Contains("Client=Jellyfin Web", StringComparison.OrdinalIgnoreCase))
+                {
+                    return true;
+                }
+            }
+
+            if (context.Request.Headers.TryGetValue("User-Agent", out var uaHeader))
+            {
+                var ua = uaHeader.ToString();
+                if (ua.Contains("JellyfinMediaPlayer", StringComparison.OrdinalIgnoreCase) ||
+                    ua.Contains("Jellyfin-Android", StringComparison.OrdinalIgnoreCase) ||
+                    ua.Contains("ExoPlayer", StringComparison.OrdinalIgnoreCase) ||
+                    ua.Contains("okhttp", StringComparison.OrdinalIgnoreCase) ||
+                    ua.Contains("Kodi", StringComparison.OrdinalIgnoreCase))
+                {
+                    return false;
+                }
+
+                if (ua.Contains("Mozilla", StringComparison.OrdinalIgnoreCase) ||
+                    ua.Contains("Chrome", StringComparison.OrdinalIgnoreCase) ||
+                    ua.Contains("Safari", StringComparison.OrdinalIgnoreCase) ||
+                    ua.Contains("Firefox", StringComparison.OrdinalIgnoreCase))
+                {
+                    return true;
+                }
+            }
+
+            return false;
+        }
     }
 }

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();
-
-                // Wymuszamy skanowanie, więc nie sprawdzamy czy ma już BlackBarCrop
+                MaxDegreeOfParallelism = maxParallel,
+                CancellationToken = cancellationToken
+            };
 
+            _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++;
-                progress.Report((processed / (double)total) * 100);
-            }
+                int current = Interlocked.Increment(ref processed);
+                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++;
-                    progress.Report((processed / (double)total) * 100);
-                    continue;
+                    int currentSkipped = Interlocked.Increment(ref processed);
+                    progress.Report((currentSkipped / (double)total) * 100);
+                    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++;
-                progress.Report((processed / (double)total) * 100);
-            }
+                int currentDone = Interlocked.Increment(ref processed);
+                progress.Report((currentDone / (double)total) * 100);
+            });
         }
 
         public IEnumerable<TaskTriggerInfo> GetDefaultTriggers()

JellyfinPlugin/WrapperGenerator.cs

@@ -121,7 +121,7 @@ if [ -n ""$INPUT_FILE"" ]; then
                 if [ $next_idx -le $# ]; then
                     next_arg=""${{!next_idx}}""
                 fi
-                NEW_ARGS+=(""$next_arg,crop=$CROP_DATA"")
+                NEW_ARGS+=(""crop=$CROP_DATA,$next_arg"")
                 let i++
                 continue
             fi

README.md

@@ -1,7 +1,9 @@
-# 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.
@@ -9,65 +11,100 @@ A Jellyfin plugin that automatically detects and removes black bars (letterboxin
 - **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.
+    - **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 **12.0** or newer (.NET 10).
+- Jellyfin Server **10.11** or **12.0+** (.NET 9 / .NET 10).
 - FFmpeg installed on the server.
 
-## Installation
+### Previously documented compatibility
 
-### Method 1: Jellyfin Repository (Recommended & Easiest)
+The previous README records testing on the following versions; this documentation update does not revalidate runtime compatibility:
 
-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.
+- **Jellyfin 10.11.x** (.NET 9.0)
+- **Jellyfin 12.0 / 13.0 Unstable** (.NET 10.0)
 
-### Method 2: Manual Installation from Releases
+## Getting started
+
+### Install from the Jellyfin repository
+
+> [!TIP]
+> **Plugin Repository URL**:
+> ```text
+> https://gitea.labus.uk/karol/blackBarRemover/raw/branch/master/manifest.json
+> ```
+
+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. Build the plugin using the .NET 9 SDK:
+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
    ```
-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
+   Or build for a specific target framework:
 
-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.
+   ```bash
+   # For Jellyfin 10.11 (.NET 9.0)
+   dotnet build JellyfinPlugin/JellyfinPlugin.csproj -c Release -f net9.0
 
-### 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>
+   # For Jellyfin 12.0 / 13.0 Unstable (.NET 10.0)
+   dotnet build JellyfinPlugin/JellyfinPlugin.csproj -c Release -f net10.0
    ```
 
-## How it works
+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
+
+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. 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.
+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.
+
+### Server-side wrapper
+
+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.
+
+### Client-side 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.
+
+## 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.

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

@@ -0,0 +1,229 @@
+[
+    {
+        "guid": "12345678-1234-1234-1234-1234567890ab",
+        "name": "Black Bar Remover",
+        "description": "Automatically detects and removes black bars from video files.",
+        "overview": "Automatically detects and removes black bars from video files via CSS or FFmpeg.",
+        "owner": "karol",
+        "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": "",
+                "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": "",
+                "timestamp": "2026-09-17T21:56:15+02:00"
+            },
+            {
+                "version": "0.1.18",
+                "changelog": "Release v0.1.18-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.18-beta/BlackBarRemover_v0.1.18-beta_jf12.0.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T21:51:42+02:00"
+            },
+            {
+                "version": "0.1.18",
+                "changelog": "Release v0.1.18-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.18-beta/BlackBarRemover_v0.1.18-beta_jf10.11.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T21:51:42+02:00"
+            },
+            {
+                "version": "0.1.17",
+                "changelog": "Release v0.1.17-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.17-beta/BlackBarRemover_v0.1.17-beta_jf12.0.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T21:32:32+02:00"
+            },
+            {
+                "version": "0.1.17",
+                "changelog": "Release v0.1.17-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.17-beta/BlackBarRemover_v0.1.17-beta_jf10.11.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T21:32:32+02:00"
+            },
+            {
+                "version": "0.1.11",
+                "changelog": "Release v0.1.11-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.11-beta/BlackBarRemover_v0.1.11-beta_jf12.0.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T21:05:29+02:00"
+            },
+            {
+                "version": "0.1.11",
+                "changelog": "Release v0.1.11-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.11-beta/BlackBarRemover_v0.1.11-beta_jf10.11.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T21:05:29+02:00"
+            },
+            {
+                "version": "0.1.10",
+                "changelog": "Release v0.1.10-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.10-beta/BlackBarRemover_v0.1.10-beta_jf12.0.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T19:54:01+02:00"
+            },
+            {
+                "version": "0.1.10",
+                "changelog": "Release v0.1.10-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.10-beta/BlackBarRemover_v0.1.10-beta_jf10.11.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T19:54:01+02:00"
+            },
+            {
+                "version": "0.1.9",
+                "changelog": "Release v0.1.9-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.9-beta/BlackBarRemover_v0.1.9-beta_jf12.0.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T19:39:22+02:00"
+            },
+            {
+                "version": "0.1.9",
+                "changelog": "Release v0.1.9-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.9-beta/BlackBarRemover_v0.1.9-beta_jf10.11.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T19:39:22+02:00"
+            },
+            {
+                "version": "0.1.8",
+                "changelog": "Release v0.1.8-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.8-beta/BlackBarRemover_v0.1.8-beta_jf12.0.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T18:29:04+02:00"
+            },
+            {
+                "version": "0.1.8",
+                "changelog": "Release v0.1.8-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.8-beta/BlackBarRemover_v0.1.8-beta_jf10.11.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T18:29:04+02:00"
+            },
+            {
+                "version": "0.1.7",
+                "changelog": "Release v0.1.7-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.7-beta/BlackBarRemover_v0.1.7-beta_jf12.0.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T18:23:27+02:00"
+            },
+            {
+                "version": "0.1.7",
+                "changelog": "Release v0.1.7-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.7-beta/BlackBarRemover_v0.1.7-beta_jf10.11.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T18:23:27+02:00"
+            },
+            {
+                "version": "0.1.6",
+                "changelog": "Release v0.1.6-beta (Jellyfin 12.0)",
+                "targetAbi": "12.0.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.6-beta/BlackBarRemover_v0.1.6-beta_jf12.0.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T18:11:37+02:00"
+            },
+            {
+                "version": "0.1.6",
+                "changelog": "Release v0.1.6-beta (Jellyfin 10.11)",
+                "targetAbi": "10.11.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.6-beta/BlackBarRemover_v0.1.6-beta_jf10.11.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T18:11:37+02:00"
+            },
+            {
+                "version": "0.1.2",
+                "changelog": "Release v0.1.2",
+                "targetAbi": "10.9.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.2/BlackBarRemover_v0.1.2.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T14:52:19+02:00"
+            },
+            {
+                "version": "0.1.1",
+                "changelog": "Release v0.1.1",
+                "targetAbi": "10.9.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1.1/BlackBarRemover_v0.1.1.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T14:45:08+02:00"
+            },
+            {
+                "version": "0.1",
+                "changelog": "Release v0.1-beta",
+                "targetAbi": "10.9.0.0",
+                "sourceUrl": "https://gitea.labus.uk/karol/blackBarRemover/releases/download/v0.1-beta/BlackBarRemover_v0.1-beta.zip",
+                "checksum": "",
+                "timestamp": "2026-09-17T14:37:16+02:00"
+            }
+        ]
+    }
+]