feat: Tdarr Local Flow Plugin Suite v1.0

7 atomic plugins for automated x265 transcoding pipeline: - utility/mediaAnalyzerGOP : GOP calc, FPS detection, film/series/anime routing - utility/setAnimationFlag : manual animation flag override - utility/extractChaptersXml : mkvextract chapters to XML - audio/audioSelectorClamping : codec scoring, clamped Opus bitrates, 2 outputs - audio/backupSourceAudio : lossless DTS/TrueHD ITA backup (-c:a copy) - subtitles/extractSubtitlesAndOcr : SRT extract + SubtitleEdit OCR for PGS - video/transcode2PassX265 : 2-pass x265, Lanczos 1080p bound, Opus mux Test suite: 34 unit tests + 3 integration tests (FFmpeg real files) FlowHelpers mock for local testing included Docs: integration-guide.md with canvas wiring and deploy instructions
2026-09-18 23:23:05 +02:00
commit c2074be826
@@ -0,0 +1,245 @@
+# Tdarr Local Flow Plugins — Integration Guide
+
+## Panoramica
+
+Questa guida descrive come assemblare i 7 plugin nel canvas Flow di Tdarr, configurare i worker Windows e verificare il corretto funzionamento.
+
+---
+
+## 1. Struttura Cartelle Generata
+
+```
+/docker/tdarr/server/Tdarr/Plugins/FlowPlugins/
+└── LocalFlowPlugins/
+    ├── utility/
+    │   ├── mediaAnalyzerGOP/1.0.0/index.js
+    │   ├── setAnimationFlag/1.0.0/index.js
+    │   └── extractChaptersXml/1.0.0/index.js
+    ├── audio/
+    │   ├── audioSelectorClamping/1.0.0/index.js
+    │   └── backupSourceAudio/1.0.0/index.js
+    ├── subtitles/
+    │   └── extractSubtitlesAndOcr/1.0.0/index.js
+    └── video/
+        └── transcode2PassX265/1.0.0/index.js
+```
+
+---
+
+## 2. Deploy sul Server Docker
+
+Copia la cartella `LocalFlowPlugins/` nel volume montato del server Tdarr:
+
+```bash
+# Dalla macchina host Docker
+docker cp ./LocalFlowPlugins/ tdarr-server:/home/tdarr/data/plugins/FlowPlugins/
+
+# Oppure se usi un volume bind mount
+cp -r ./LocalFlowPlugins/ /docker/tdarr/server/Tdarr/Plugins/FlowPlugins/
+```
+
+Poi **riavvia il server Tdarr** per indicizzare i nuovi plugin:
+```bash
+docker restart tdarr-server
+```
+
+---
+
+## 3. Configurazione Worker Windows
+
+### 3.1 Software richiesto
+
+| Software | Download | Note |
+|---|---|---|
+| FFmpeg | https://ffmpeg.org/download.html | Aggiungi `ffmpeg.exe` al PATH |
+| MKVToolNix | https://mkvtoolnix.download/ | Include `mkvextract.exe` |
+| SubtitleEdit | https://www.nikse.dk/subtitleedit | Solo per OCR PGS/VOBSUB |
+
+### 3.2 Configurazione percorsi in Tdarr
+
+Nella Web UI: **Settings → Nodes → [tuo worker Windows]**
+
+| Campo | Valore esempio |
+|---|---|
+| FFmpeg Path | `C:\Tools\ffmpeg\bin\ffmpeg.exe` |
+| FFprobe Path | `C:\Tools\ffmpeg\bin\ffprobe.exe` |
+| MKVPropedit Path | `C:\Program Files\MKVToolNix\mkvpropedit.exe` |
+
+> Il plugin `extractChaptersXml` deriva automaticamente il path di `mkvextract.exe` dalla stessa cartella di `mkvpropedit.exe`.
+
+### 3.3 Configurazione PATH Windows
+
+Aggiungi al PATH di sistema:
+- `C:\Tools\ffmpeg\bin`
+- `C:\Program Files\MKVToolNix`
+- `C:\Program Files\SubtitleEdit` (solo per OCR)
+
+---
+
+## 4. Assemblaggio del Flow nel Canvas
+
+### 4.1 Ordine dei nodi
+
+```
+[mediaAnalyzerGOP]
+       │
+       │  (Facoltativo — solo per anime non rilevati automaticamente)
+       ├──▶ [setAnimationFlag]
+       │           │
+       │           └──▶ (ricongiunge)
+       │
+       ▼
+[audioSelectorClamping]
+       │
+       ├──▶ Output 2 (Nessuna traccia ITA/ENG)
+       │         └──▶ [Nodo di gestione errore / Fine]
+       │
+       └──▶ Output 1 (Tracce trovate)
+                 ▼
+         [extractChaptersXml]
+                 ▼
+         [extractSubtitlesAndOcr]
+                 ▼
+         [backupSourceAudio]
+                 ▼
+         [transcode2PassX265]
+                 ▼
+               [Fine]
+```
+
+### 4.2 Connessioni nel Canvas
+
+1. Apri **Tdarr Web UI → Libraries → [tua library] → Flow**
+2. Clicca **"Add Plugin"** e cerca per categoria:
+   - `utility` → trovi `Media Analyzer & GOP Calculator`
+   - `audio` → trovi `Audio Selector & Opus Bitrate Clamping`
+   - ecc.
+3. Trascina i nodi e collega le uscite/ingressi nell'ordine sopra indicato.
+
+> **Nota**: I plugin compaiono nelle rispettive categorie (`utility`, `audio`, `subtitles`, `video`) nella sidebar del canvas.
+
+---
+
+## 5. Configurazione Input dei Plugin
+
+### `mediaAnalyzerGOP` — Valori raccomandati
+
+| Input | Valore raccomandato |
+|---|---|
+| Movie Library Path Patterns | `/Radarr` |
+| Anime Series Names | `Naruto\|One Piece\|Attack on Titan\|...` |
+| Film Bitrate (kbps) | `3000` |
+| Series Bitrate (kbps) | `3000` |
+| Anime HD Bitrate (kbps) | `2000` |
+| Anime SD Bitrate (kbps) | `1000` |
+
+### `audioSelectorClamping` — Valori raccomandati
+
+| Input | Valore |
+|---|---|
+| Film Multichannel Bitrate (kbps) | `640` |
+| Series Multichannel Threshold (kbps) | `384` |
+| Stereo Max Bitrate (kbps) | `128` |
+
+### `extractSubtitlesAndOcr` — Valori raccomandati
+
+| Input | Valore |
+|---|---|
+| SubtitleEdit Executable Path | `SubtitleEdit` (nel PATH) |
+| Languages to Extract | `ita,eng` |
+
+### `transcode2PassX265` — Valori raccomandati
+
+| Input | Valore |
+|---|---|
+| x265 Preset | `slow` |
+| Output Container | `mkv` |
+
+---
+
+## 6. Variabili di Flusso (args.variables)
+
+Questa tabella mostra tutte le variabili che i plugin si passano a vicenda:
+
+| Variabile | Prodotta da | Consumata da |
+|---|---|---|
+| `gopKeyint` | mediaAnalyzerGOP | transcode2PassX265 |
+| `gopMinKeyint` | mediaAnalyzerGOP | transcode2PassX265 |
+| `isAnimation` | mediaAnalyzerGOP / setAnimationFlag | audioSelectorClamping |
+| `isMovie` | mediaAnalyzerGOP | audioSelectorClamping |
+| `vBitrate` | mediaAnalyzerGOP / setAnimationFlag | transcode2PassX265 |
+| `vMaxRate` | mediaAnalyzerGOP / setAnimationFlag | transcode2PassX265 |
+| `vBufSize` | mediaAnalyzerGOP / setAnimationFlag | transcode2PassX265 |
+| `x265Tune` | mediaAnalyzerGOP / setAnimationFlag | transcode2PassX265 |
+| `videoHeight` | mediaAnalyzerGOP | setAnimationFlag |
+| `videoFps` | mediaAnalyzerGOP | (info only) |
+| `audioHasIta` | audioSelectorClamping | backupSourceAudio, transcode2PassX265 |
+| `audioItaStreamIndex` | audioSelectorClamping | backupSourceAudio, transcode2PassX265 |
+| `audioItaOpusBitrate` | audioSelectorClamping | transcode2PassX265 |
+| `audioItaChannels` | audioSelectorClamping | (info only) |
+| `audioItaCodecName` | audioSelectorClamping | backupSourceAudio |
+| `audioHasEng` | audioSelectorClamping | transcode2PassX265 |
+| `audioEngStreamIndex` | audioSelectorClamping | transcode2PassX265 |
+| `audioEngOpusBitrate` | audioSelectorClamping | transcode2PassX265 |
+| `audioEngCodecName` | audioSelectorClamping | (info only) |
+| `chaptersXmlPath` | extractChaptersXml | (reserved for future use) |
+| `audioBackupPath` | backupSourceAudio | (info only) |
+
+---
+
+## 7. Output dei File per Ogni Job
+
+Per ogni file sorgente `/media/toshiba/Radarr/Film (2023)/Film (2023).mkv`:
+
+```
+/media/toshiba/Radarr/Film (2023)/
+  ├── Film (2023).mkv              ← sostituito dal trascodificato (gestito da Tdarr)
+  ├── Film (2023).ita.srt          ← estratto da extractSubtitlesAndOcr
+  ├── Film (2023).eng.srt          ← estratto da extractSubtitlesAndOcr
+  ├── Film (2023).ita.forced.srt   ← (se traccia forced presente)
+  ├── Film (2023).eng.sdh.srt      ← (se traccia SDH presente)
+  └── Film (2023).ita.dts          ← backup (solo se codec DTS)
+      o Film (2023).ita.thd        ← backup (solo se codec TrueHD)
+```
+
+---
+
+## 8. Troubleshooting
+
+### Plugin non visibili nel canvas
+- Riavvia il server Tdarr dopo aver copiato i file
+- Verifica che il path sia esattamente `FlowPlugins/LocalFlowPlugins/<categoria>/<nome>/1.0.0/index.js`
+
+### `mkvextract` non trovato
+- Assicurati che MKVToolNix sia installato e che `mkvpropedit.exe` sia configurato nelle impostazioni del nodo
+
+### OCR SubtitleEdit non funziona
+- Verifica che `SubtitleEdit.exe` sia nel PATH di sistema del worker Windows
+- Oppure specifica il path assoluto nell'input del plugin (es. `C:\Program Files\SubtitleEdit\SubtitleEdit.exe`)
+- Le tracce PGS richiede che SubtitleEdit sia in modalità CLI (non GUI)
+
+### Pass 1 FFmpeg fallisce su Windows
+- Il device null su Windows è `NUL` (senza path) — gestito automaticamente dal plugin
+- Verifica che il worker abbia scrittura su `workDir`
+
+### Opus non disponibile in FFmpeg
+- Verifica con: `ffmpeg -encoders | grep opus`
+- Usa build FFmpeg con `--enable-libopus`
+
+---
+
+## 9. Test in Locale
+
+```bash
+# Prerequisiti: Node.js, FFmpeg nel PATH
+cd c:\Users\david\Desktop\Projects\Tdarr_plugin
+
+# 1. Genera file di test (richiede FFmpeg)
+node tests/generate-test-files.js
+
+# 2. Esegui test suite (escluso Test 3 che fa encode reale)
+node tests/run-tests.js --skip-transcode
+
+# 3. Esegui test completo incluso encode x265
+node tests/run-tests.js
+```