PickleRick/Tdarr-plugin
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
febd68973beb7a07688d1c75d2843914b8d44c47
Tdarr-plugin/docs/integration-guide.md
T
PickleRick febd68973b
Build / Lint & Test (push) Successful in 43s
Details
Save uncommitted changes
2026-09-21 22:33:52 +02:00

9.4 KiB
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:

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

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. They use larger buffers to avoid slow small-write behavior on SMB/CIFS mounts. 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

# 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