PickleRick/Tdarr-plugin
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7ee5a5bc48e14bf043e8a6fc72ebe99e28051c4a
Tdarr-plugin/docs/integration-guide.md
T
PickleRick 7ee5a5bc48
Build / Lint & Test (push) Successful in 28s
Details
Save uncommitted changes
2026-09-21 23:38:34 +02:00

280 lines
9.5 KiB
Markdown
Raw Blame History

# 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`
uses the operating system's native file-copy path, reports interval speed,
verifies the destination size, and retries failed writes.
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
```
Reference in new issue View Git Blame Copy Permalink