# 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
    │   ├── finalizeMedia/1.0.0/index.js
    │   ├── copyToWorkDir/2.0.0/index.js
    │   ├── replaceOriginalFile/1.0.0/index.js
    │   └── replaceOriginalFile/2.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`.

`copyToWorkDir` crea la copia temporanea con suffisso `_old` e conserva il
percorso originale in `variables.originalLibraryFile`. La versione 2.0.0
trasmette il progresso della copia e verifica la dimensione finale.

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

```
[copyToWorkDir 2.0.0] (recommended for network libraries)
                 ▼
[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]
               ▼
         [replaceOriginalFile 2.0.0]
               ▼
         [finalizeMedia]
```
`copyToWorkDir` 2.0.0 is optional but recommended when the source library is on
a network share. Place it before the first analysis/transcode node; it records
the library path for `replaceOriginalFile` 2.0.0.
Both progress-enabled copy operations verify the destination size and retry
failed writes twice after removing the partial destination. Their `Copy method`
input defaults to `auto` (the operating system's native file-copy path), with
`stream` available as a fallback for problematic SMB/CIFS mounts. Stream mode
supports 4 MB, 16 MB, and 64 MB buffers.
Both progress-enabled plugins require
`FlowHelpers/1.0.0/copyWithProgress.js`; the installer downloads it
automatically.

### 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` |

### `finalizeMedia` — Valori raccomandati

| Input | Valore |
|---|---|
| Remove Empty Source Directory | `true` |

Collegare dopo `Move To Directory`. Il nodo normalizza i codici lingua dei
sottotitoli, controlla titoli/dispositions tramite i metadati ffprobe,
preferisce i text agli image e rimuove i duplicati SRT e XML dei capitoli.

---

## 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 |
| `gopSceneCut` | 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)_chapters.xml     ← estratto da extractChaptersXml
  └── 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
```