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

tests/test-cases/test1-movie-23976fps.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * test1-movie-23976fps.js
+ * Validates: mediaAnalyzerGOP + audioSelectorClamping on a 23.976fps Film.
+ * File: Radarr path, AC3 ITA 448k 5.1, EAC3 ENG 640k 5.1
+ *
+ * Expected:
+ *   gopKeyint        = "48"
+ *   isMovie          = "true"
+ *   isAnimation      = "false"
+ *   vBitrate         = "3000k"
+ *   audioItaCodecName = "ac3"
+ *   audioEngCodecName = "eac3"  (EAC3 score > AC3 score)
+ *   audioItaOpusBitrate = "448" (clamped: min(640, 448) = 448)
+ *   audioEngOpusBitrate = "640" (clamped: min(640, 640) = 640)
+ */
+
+const path = require('path');
+const { buildMockArgs, cleanupWorkDir, assertEqual } = require('../mock-tdarr-runtime');
+const { plugin: analyzerPlugin } = require('../../LocalFlowPlugins/utility/mediaAnalyzerGOP/1.0.0/index');
+const { plugin: audioPlugin }    = require('../../LocalFlowPlugins/audio/audioSelectorClamping/1.0.0/index');
+
+const FILE = path.resolve('tests/samples/media/toshiba/Radarr/Film Test (2023)/Film Test (2023).mkv');
+
+async function run() {
+  console.log('\n=== TEST 1: 23.976fps Film (AC3 ITA + EAC3 ENG) ===\n');
+
+  // ── Step 1: mediaAnalyzerGOP ──────────────────────────────────────────────
+  console.log('Running mediaAnalyzerGOP...');
+  const args1 = buildMockArgs({
+    filePath: FILE,
+    inputs: {
+      moviePathPatterns: '/Radarr',
+      animeSeries:       '',
+      filmBitrate:       '3000',
+      seriesBitrate:     '3000',
+      animeBitrateHd:    '2000',
+      animeBitrateSd:    '1000',
+    },
+  });
+
+  const out1 = await analyzerPlugin(args1);
+  const vars = out1.variables;
+
+  assertEqual(out1.outputNumber, 1,       'outputNumber');
+  assertEqual(vars.gopKeyint,   '48',     'gopKeyint (2 x 23.976 = 47.95 -> 48)');
+  assertEqual(vars.isMovie,     'true',   'isMovie (Radarr path)');
+  assertEqual(vars.isAnimation, 'false',  'isAnimation (no anime match)');
+  assertEqual(vars.vBitrate,    '3000k',  'vBitrate (film default)');
+  assertEqual(vars.x265Tune,    '',       'x265Tune (live-action)');
+
+  // ── Step 2: audioSelectorClamping ────────────────────────────────────────
+  console.log('\nRunning audioSelectorClamping...');
+  const args2 = buildMockArgs({
+    filePath: FILE,
+    variables: vars,
+    inputs: {
+      filmMultiChannelBitrate:    '640',
+      seriesMultiChannelThreshold:'384',
+      stereoBitrateMax:           '128',
+    },
+  });
+
+  const out2 = await audioPlugin(args2);
+  const vars2 = out2.variables;
+
+  assertEqual(out2.outputNumber,          1,      'outputNumber (tracks found)');
+  assertEqual(vars2.audioHasIta,          'true', 'audioHasIta');
+  assertEqual(vars2.audioHasEng,          'true', 'audioHasEng');
+  assertEqual(vars2.audioItaCodecName,    'ac3',  'ITA codec = ac3');
+  assertEqual(vars2.audioEngCodecName,    'eac3', 'ENG codec = eac3 (wins by score)');
+  assertEqual(vars2.audioItaOpusBitrate,  '448',  'ITA Opus = 448k (min(640,448))');
+  assertEqual(vars2.audioEngOpusBitrate,  '640',  'ENG Opus = 640k (min(640,640))');
+
+  cleanupWorkDir(args1);
+  cleanupWorkDir(args2);
+  console.log('\n=== TEST 1 PASSED ===\n');
+}
+
+module.exports = run;

tests/test-cases/test2-anime-25fps.js

@@ -0,0 +1,72 @@
+'use strict';
+/**
+ * test2-anime-25fps.js
+ * Validates mediaAnalyzerGOP + audioSelectorClamping on anime 25fps.
+ * File: Sonarr path, EAC3 ITA 640k 5.1, "Naruto" in animeSeries list.
+ * Note: DTS detection logic is fully covered in unit tests (quick-logic-test.js).
+ *
+ * Expected:
+ *   gopKeyint        = "50"
+ *   isAnimation      = "true"
+ *   isMovie          = "false"
+ *   x265Tune         = "animation"
+ *   vBitrate         = "2000k"  (anime HD 720p)
+ *   audioItaCodecName = "eac3"
+ *   audioItaOpusBitrate = "384" (series: 640k >= 384 threshold -> 384k)
+ *   audioHasEng      = "false"
+ */
+
+const path = require('path');
+const { buildMockArgs, cleanupWorkDir, assertEqual } = require('../mock-tdarr-runtime');
+const { plugin: analyzerPlugin } = require(require('path').join(process.cwd(), 'LocalFlowPlugins/utility/mediaAnalyzerGOP/1.0.0/index'));
+const { plugin: audioPlugin }    = require(require('path').join(process.cwd(), 'LocalFlowPlugins/audio/audioSelectorClamping/1.0.0/index'));
+
+const FILE = path.resolve('tests/samples/media/toshiba/Sonarr/Naruto S01/Naruto S01E01.mkv');
+
+async function run() {
+  console.log('\n=== TEST 2: 25fps Anime EAC3 ITA (Naruto, Sonarr) ===\n');
+
+  console.log('Running mediaAnalyzerGOP...');
+  const args1 = buildMockArgs({
+    filePath: FILE,
+    inputs: {
+      moviePathPatterns: '/Radarr',
+      animeSeries:       'Naruto|One Piece',
+      filmBitrate:       '3000',
+      seriesBitrate:     '3000',
+      animeBitrateHd:    '2000',
+      animeBitrateSd:    '1000',
+    },
+  });
+  const out1 = await analyzerPlugin(args1);
+  const vars = out1.variables;
+  assertEqual(vars.gopKeyint,   '50',        'gopKeyint (2 x 25 = 50)');
+  assertEqual(vars.isMovie,     'false',     'isMovie=false (Sonarr path)');
+  assertEqual(vars.isAnimation, 'true',      'isAnimation=true (Naruto in path)');
+  assertEqual(vars.x265Tune,    'animation', 'x265Tune=animation');
+  assertEqual(vars.vBitrate,    '2000k',     'vBitrate=2000k (anime 720p HD)');
+
+  console.log('\nRunning audioSelectorClamping...');
+  const args2 = buildMockArgs({
+    filePath: FILE,
+    variables: vars,
+    inputs: {
+      filmMultiChannelBitrate:    '640',
+      seriesMultiChannelThreshold:'384',
+      stereoBitrateMax:           '128',
+    },
+  });
+  const out2 = await audioPlugin(args2);
+  const vars2 = out2.variables;
+  assertEqual(out2.outputNumber,         1,      'outputNumber=1 (ITA found)');
+  assertEqual(vars2.audioHasIta,         'true', 'audioHasIta=true');
+  assertEqual(vars2.audioHasEng,         'false','audioHasEng=false');
+  assertEqual(vars2.audioItaCodecName,   'eac3', 'ITA codec=eac3');
+  assertEqual(vars2.audioItaOpusBitrate, '384',  'ITA Opus=384k (series: 640k >= 384 threshold)');
+
+  cleanupWorkDir(args1);
+  cleanupWorkDir(args2);
+  console.log('\n=== TEST 2 PASSED ===\n');
+}
+
+module.exports = run;

tests/test-cases/test3-ultrawide.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * test3-ultrawide.js
+ * Validates: transcode2PassX265 scale filter on 3840x1600 input.
+ * Expected output: 1920x800 (no letterbox, even dimensions).
+ */
+
+const path   = require('path');
+const fs     = require('fs');
+const { execSync } = require('child_process');
+const { buildMockArgs, cleanupWorkDir, assert, assertEqual } = require('../mock-tdarr-runtime');
+const { plugin: analyzerPlugin }   = require('../../LocalFlowPlugins/utility/mediaAnalyzerGOP/1.0.0/index');
+const { plugin: audioPlugin }      = require('../../LocalFlowPlugins/audio/audioSelectorClamping/1.0.0/index');
+const { plugin: transcodePlugin }  = require('../../LocalFlowPlugins/video/transcode2PassX265/1.0.0/index');
+
+const FILE   = path.resolve('tests/samples/test3_ultrawide.mkv');
+const FFMPEG  = process.env.FFMPEG_PATH  || 'ffmpeg';
+const FFPROBE = process.env.FFPROBE_PATH || 'ffprobe';
+
+async function run() {
+  console.log('\n=== TEST 3: Ultrawide 3840x1600 Scale Filter ===\n');
+
+  // Analyzer
+  const args1 = buildMockArgs({
+    filePath: FILE,
+    inputs: { moviePathPatterns: '/Radarr', animeSeries: '', filmBitrate: '3000',
+              seriesBitrate: '3000', animeBitrateHd: '2000', animeBitrateSd: '1000' },
+  });
+  const out1 = await analyzerPlugin(args1);
+  const vars = out1.variables;
+  assertEqual(vars.videoHeight, '1600', 'Source videoHeight = 1600');
+
+  // Audio selector
+  const args2 = buildMockArgs({
+    filePath: FILE, variables: vars,
+    inputs: { filmMultiChannelBitrate: '640', seriesMultiChannelThreshold: '384', stereoBitrateMax: '128' },
+  });
+  const out2 = await audioPlugin(args2);
+
+  // Transcode (Pass 1 + Pass 2)
+  console.log('Running transcode2PassX265 (this may take a minute)...');
+  const args3 = buildMockArgs({
+    filePath: FILE,
+    variables: out2.variables,
+    inputs: { x265Preset: 'ultrafast', outputContainer: 'mkv' },
+    ffmpegPath: FFMPEG,
+  });
+
+  const out3 = await transcodePlugin(args3);
+  const outFile = out3.outputFileObj._id;
+
+  assert(fs.existsSync(outFile), `Output file exists: ${outFile}`);
+
+  // Verify dimensions with ffprobe
+  const probeOut = execSync(
+    `${FFPROBE} -v quiet -print_format json -show_streams -select_streams v:0 "${outFile}"`,
+    { encoding: 'utf8' },
+  );
+  const { streams } = JSON.parse(probeOut);
+  const w = streams[0].width;
+  const h = streams[0].height;
+
+  console.log(`  Output dimensions: ${w}x${h}`);
+  assert(w === 1920, `Width = 1920 (got ${w})`);
+  assert(h === 800,  `Height = 800 (got ${h})`);
+  assert(w % 2 === 0, 'Width is even');
+  assert(h % 2 === 0, 'Height is even');
+
+  cleanupWorkDir(args1);
+  cleanupWorkDir(args2);
+  cleanupWorkDir(args3);
+  console.log('\n=== TEST 3 PASSED ===\n');
+}
+
+module.exports = run;

tests/test-cases/test4-subtitles.js

@@ -0,0 +1,50 @@
+'use strict';
+
+/**
+ * test4-subtitles.js
+ * Validates: extractSubtitlesAndOcr produces correctly named SRT files.
+ * Source: MKV with 2 ITA SRT streams (forced + SDH).
+ * Expected: .ita.forced.srt and .ita.hearing_impaired.srt in source dir.
+ */
+
+const path = require('path');
+const fs   = require('fs');
+const { buildMockArgs, cleanupWorkDir, assert } = require('../mock-tdarr-runtime');
+const { plugin: subPlugin } = require('../../LocalFlowPlugins/subtitles/extractSubtitlesAndOcr/1.0.0/index');
+
+const FILE      = path.resolve('tests/samples/test4_subtitles.mkv');
+const SOURCE_DIR = path.dirname(FILE);
+const BASE_NAME  = path.basename(FILE, '.mkv');
+
+async function run() {
+  console.log('\n=== TEST 4: Subtitle Extraction (forced + SDH) ===\n');
+
+  const args = buildMockArgs({
+    filePath: FILE,
+    inputs: { subtitleEditPath: 'SubtitleEdit', languages: 'ita,eng' },
+  });
+
+  await subPlugin(args);
+
+  // Check that forced SRT was created
+  const forcedSrt = path.join(SOURCE_DIR, `${BASE_NAME}.ita.forced.srt`);
+  const sdhSrt    = path.join(SOURCE_DIR, `${BASE_NAME}.ita.sdh.srt`);
+
+  console.log('  Checking for:', path.basename(forcedSrt));
+  assert(fs.existsSync(forcedSrt), `Forced SRT exists: ${path.basename(forcedSrt)}`);
+
+  console.log('  Checking for:', path.basename(sdhSrt));
+  // Note: disposition hearing_impaired maps to 'sdh' suffix
+  // If not found, check for .ita.default.srt variant (FFmpeg disposition naming may vary)
+  const sdhExists   = fs.existsSync(sdhSrt);
+  const altSdhExists = fs.existsSync(path.join(SOURCE_DIR, `${BASE_NAME}.ita.default.srt`));
+  assert(sdhExists || altSdhExists, `SDH/hearing-impaired SRT exists`);
+
+  // Cleanup generated subtitle files
+  [forcedSrt, sdhSrt].forEach((f) => { try { fs.unlinkSync(f); } catch (_) {} });
+
+  cleanupWorkDir(args);
+  console.log('\n=== TEST 4 PASSED ===\n');
+}
+
+module.exports = run;