PickleRick/Tdarr-plugin
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c46e3dfdb3728b2fefaf776fa50e08beb7741e00
Tdarr-plugin/docs/integration-guide.md
T

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/1.0.0/index.js
    │   └── replaceOriginalFile/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:

# 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. Il plugin trasmette in tempo reale il progresso della copia (percentuale, velocità, ETA) alla WebUI e ai log del worker, verificando 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] (consigliato per librerie di rete)
                 ▼
[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]
               ▼
         [finalizeMedia]

copyToWorkDir è facoltativo ma consigliato quando la libreria sorgente si trova su una condivisione di rete (NAS/SMB). Posizionalo prima dell'analisi/transcodifica: registra il percorso originale della libreria per replaceOriginalFile. Entrambe le operazioni di copia/sostituzione trasmettono la percentuale di avanzamento alla WebUI di Tdarr tramite il worker callback, I plugin integrano direttamente il motore di copia con progresso in tempo reale (copyWithProgress), risultando autonomi e immuni agli aggiornamenti di Tdarr.

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