From bfdeb3cbb71a240c4157c1834427e4a3c8d6c803 Mon Sep 17 00:00:00 2001
From: Sheersh Jaiswal <sheershjaiswal@gmail.com>
Date: Thu, 5 Nov 2026 15:04:17 +0530
Subject: [PATCH 1/3] test: add unit and integration suites; fix bugs they
 uncovered

Tests: ~300 new Python tests (mocked units, CLI handlers, real-ffmpeg
integration) and Flutter tests for models, app state, scan and transcode.

Fixes:
- compress --report x.json wrote HTML instead of JSON
- --quality-check compared the output to itself
- ContentType.UNKNOWN aliased LIVE_ACTION; add preset_key mapping
- duplicate finder missed matches across 4s duration buckets
- report size formatting truncated fractions; escape HTML in reports
- content_classifier failed to import on Python 3.9
---
 desktop/test/app_state_test.dart       | 167 ++++++++++++++++++++
 desktop/test/compression_job_test.dart |  43 +++++
 desktop/test/ffmpeg_and_scan_test.dart |  92 +++++++++++
 desktop/test/models_extended_test.dart | 109 +++++++++++++
 mediacrush/cli/commands.py             |  20 ++-
 mediacrush/core/content_classifier.py  |   9 +-
 mediacrush/core/deduplicator.py        |  25 +--
 mediacrush/core/reporter.py            |   9 +-
 tests/conftest.py                      | 100 ++++++++++++
 tests/test_classifier_ppm.py           | 115 ++++++++++++++
 tests/test_cli_parser.py               |  67 ++++++++
 tests/test_commands.py                 | 210 +++++++++++++++++++++++++
 tests/test_content_classifier.py       |   3 +-
 tests/test_dedupe_logic.py             |  94 +++++++++++
 tests/test_formatters.py               |  51 ++++++
 tests/test_hardware_mocked.py          |  93 +++++++++++
 tests/test_integration_ffmpeg.py       | 183 +++++++++++++++++++++
 tests/test_presets_args.py             | 113 +++++++++++++
 tests/test_probe_parsing.py            | 141 +++++++++++++++++
 tests/test_quality_mocked.py           |  85 ++++++++++
 tests/test_queue_extra.py              |  77 +++++++++
 tests/test_reporter_extra.py           |  56 +++++++
 tests/test_safety_finalize.py          |  94 +++++++++++
 tests/test_scanner_scan.py             | 143 +++++++++++++++++
 tests/test_transcoder.py               | 165 +++++++++++++++++++
 tests/test_watcher.py                  | 117 ++++++++++++++
 tests/test_worker.py                   |  78 +++++++++
 27 files changed, 2433 insertions(+), 26 deletions(-)
 create mode 100644 desktop/test/app_state_test.dart
 create mode 100644 desktop/test/compression_job_test.dart
 create mode 100644 desktop/test/ffmpeg_and_scan_test.dart
 create mode 100644 desktop/test/models_extended_test.dart
 create mode 100644 tests/conftest.py
 create mode 100644 tests/test_classifier_ppm.py
 create mode 100644 tests/test_cli_parser.py
 create mode 100644 tests/test_commands.py
 create mode 100644 tests/test_dedupe_logic.py
 create mode 100644 tests/test_formatters.py
 create mode 100644 tests/test_hardware_mocked.py
 create mode 100644 tests/test_integration_ffmpeg.py
 create mode 100644 tests/test_presets_args.py
 create mode 100644 tests/test_probe_parsing.py
 create mode 100644 tests/test_quality_mocked.py
 create mode 100644 tests/test_queue_extra.py
 create mode 100644 tests/test_reporter_extra.py
 create mode 100644 tests/test_safety_finalize.py
 create mode 100644 tests/test_scanner_scan.py
 create mode 100644 tests/test_transcoder.py
 create mode 100644 tests/test_watcher.py
 create mode 100644 tests/test_worker.py

diff --git a/desktop/test/app_state_test.dart b/desktop/test/app_state_test.dart
new file mode 100644
index 0000000..ac3133b
--- /dev/null
+++ b/desktop/test/app_state_test.dart
@@ -0,0 +1,167 @@
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:path/path.dart' as p;
+import 'package:desktop/models/hardware_engine.dart';
+import 'package:desktop/state/app_state.dart';
+
+void main() {
+  late Directory tmp;
+  late AppState state;
+  int notifications = 0;
+
+  setUp(() {
+    tmp = Directory.systemTemp.createTempSync('mc_state_');
+    state = AppState();
+    notifications = 0;
+    state.addListener(() => notifications++);
+  });
+
+  tearDown(() {
+    state.dispose();
+    if (tmp.existsSync()) tmp.deleteSync(recursive: true);
+  });
+
+  File make(String name, int bytes) {
+    final f = File(p.join(tmp.path, name))..createSync(recursive: true);
+    f.writeAsBytesSync(List.filled(bytes, 0));
+    return f;
+  }
+
+  group('initial state', () {
+    test('is empty and idle', () {
+      expect(state.items, isEmpty);
+      expect(state.isScanning, isFalse);
+      expect(state.isCompressing, isFalse);
+      expect(state.job, isNull);
+      expect(state.preset, 'anime');
+      expect(state.outputFolder, isNull);
+      expect(state.totalCandidates, 0);
+      expect(state.savingsPercentage, 0.0);
+      expect(state.hardware.name, 'libx265');
+    });
+  });
+
+  group('setters notify listeners', () {
+    test('preset', () {
+      state.setPreset('saver');
+      expect(state.preset, 'saver');
+      expect(notifications, 1);
+    });
+
+    test('output folder', () {
+      state.setOutputFolder('/out');
+      expect(state.outputFolder, '/out');
+      expect(notifications, 1);
+    });
+
+    test('hardware', () {
+      state.setHardware(HardwareEngine.fromCliName('nvenc'));
+      expect(state.hardware.vendor, 'NVIDIA');
+      expect(notifications, 1);
+    });
+  });
+
+  group('addFiles', () {
+    test('adds existing files with estimate and default output folder', () {
+      final f = make('a.mkv', 1000);
+      state.addFiles([f.path]);
+      expect(state.items, hasLength(1));
+      expect(state.items.first.fileName, 'a.mkv');
+      expect(state.items.first.originalBytes, 1000);
+      expect(state.items.first.estimatedBytes, 450);
+      expect(state.outputFolder, p.join(tmp.path, 'crushed'));
+      expect(notifications, 1);
+    });
+
+    test('ignores missing files and duplicates', () {
+      final f = make('a.mkv', 100);
+      state.addFiles([f.path, f.path, p.join(tmp.path, 'ghost.mkv')]);
+      expect(state.items, hasLength(1));
+    });
+
+    test('empty list is a no-op and does not notify', () {
+      state.addFiles([]);
+      expect(notifications, 0);
+    });
+
+    test('keeps an explicitly chosen output folder', () {
+      state.setOutputFolder('/custom');
+      state.addFiles([make('a.mkv', 10).path]);
+      expect(state.outputFolder, '/custom');
+    });
+
+    test('aggregates totals and savings', () {
+      state.addFiles([make('a.mkv', 1000).path, make('b.mkv', 3000).path]);
+      expect(state.totalCandidates, 2);
+      expect(state.totalOriginalBytes, 4000);
+      expect(state.totalEstimatedBytes, 1800);
+      expect(state.totalSavedBytes, 2200);
+      expect(state.savingsPercentage, closeTo(55.0, 1e-9));
+    });
+  });
+
+  group('scanFolder', () {
+    test('finds only video files recursively and sets folders', () async {
+      make('a.mkv', 10);
+      make('sub/b.MP4', 10);
+      make('notes.txt', 10);
+      await state.scanFolder(tmp.path);
+      expect(state.items.map((i) => i.fileName).toSet(), {'a.mkv', 'b.MP4'});
+      expect(state.selectedFolder, tmp.path);
+      expect(state.outputFolder, p.join(tmp.path, 'crushed'));
+      expect(state.isScanning, isFalse);
+      expect(notifications, greaterThanOrEqualTo(2)); // scanning on, scanning off
+    });
+
+    test('missing folder yields no items', () async {
+      await state.scanFolder(p.join(tmp.path, 'nope'));
+      expect(state.items, isEmpty);
+      expect(state.isScanning, isFalse);
+    });
+
+    test('rescan replaces previous items', () async {
+      make('a.mkv', 10);
+      await state.scanFolder(tmp.path);
+      File(p.join(tmp.path, 'a.mkv')).deleteSync();
+      await state.scanFolder(tmp.path);
+      expect(state.items, isEmpty);
+    });
+  });
+
+  group('clearItems', () {
+    test('empties list and selection', () async {
+      make('a.mkv', 10);
+      await state.scanFolder(tmp.path);
+      state.clearItems();
+      expect(state.items, isEmpty);
+      expect(state.selectedFolder, isNull);
+    });
+  });
+
+  group('compression control', () {
+    test('startCompression with nothing queued does nothing', () async {
+      await state.startCompression();
+      expect(state.job, isNull);
+      expect(state.isCompressing, isFalse);
+    });
+
+    test('pauseCompression is safe when idle and notifies', () {
+      state.pauseCompression();
+      expect(state.isCompressing, isFalse);
+      expect(notifications, 1);
+    });
+
+    test('a bogus input fails the item without crashing and finishes the job', () async {
+      // Input exists on disk but is not a real video, so ffmpeg (or its absence) must fail cleanly.
+      final f = make('fake.mkv', 2048);
+      state.addFiles([f.path]);
+      state.setOutputFolder(p.join(tmp.path, 'out'));
+      await state.startCompression();
+      expect(state.isCompressing, isFalse);
+      expect(state.job!.isRunning, isFalse);
+      expect(state.job!.completedFiles, 0);
+      expect(state.items.first.status.name, 'failed');
+    }, timeout: const Timeout(Duration(seconds: 60)));
+  });
+}
diff --git a/desktop/test/compression_job_test.dart b/desktop/test/compression_job_test.dart
new file mode 100644
index 0000000..5b11df2
--- /dev/null
+++ b/desktop/test/compression_job_test.dart
@@ -0,0 +1,43 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:desktop/models/compression_job.dart';
+
+void main() {
+  group('CompressionJob', () {
+    test('defaults', () {
+      final j = CompressionJob(totalFiles: 3);
+      expect(j.completedFiles, 0);
+      expect(j.overallProgress, 0.0);
+      expect(j.isRunning, isFalse);
+      expect(j.isPaused, isFalse);
+      expect(j.currentSpeedMultiplier, 1.0);
+      expect(j.totalSavedBytes, 0);
+    });
+
+    test('totalSavedBytes is the difference', () {
+      final j = CompressionJob(totalFiles: 1, originalTotalBytes: 1000, finalTotalBytes: 400);
+      expect(j.totalSavedBytes, 600);
+      expect(j.overallSavingsPercentage, closeTo(60.0, 1e-9));
+    });
+
+    test('totalSavedBytes never negative when output grows', () {
+      final j = CompressionJob(totalFiles: 1, originalTotalBytes: 100, finalTotalBytes: 500);
+      expect(j.totalSavedBytes, 0);
+      expect(j.overallSavingsPercentage, 0.0);
+    });
+
+    test('percentage is zero when nothing to compress', () {
+      expect(CompressionJob(totalFiles: 0).overallSavingsPercentage, 0.0);
+      expect(CompressionJob(totalFiles: 1, originalTotalBytes: -5).overallSavingsPercentage, 0.0);
+    });
+
+    test('fields are mutable for live progress', () {
+      final j = CompressionJob(totalFiles: 2)
+        ..completedFiles = 1
+        ..overallProgress = 0.5
+        ..isRunning = true;
+      expect(j.completedFiles, 1);
+      expect(j.overallProgress, 0.5);
+      expect(j.isRunning, isTrue);
+    });
+  });
+}
diff --git a/desktop/test/ffmpeg_and_scan_test.dart b/desktop/test/ffmpeg_and_scan_test.dart
new file mode 100644
index 0000000..2727ee0
--- /dev/null
+++ b/desktop/test/ffmpeg_and_scan_test.dart
@@ -0,0 +1,92 @@
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:path/path.dart' as p;
+import 'package:desktop/models/hardware_engine.dart';
+import 'package:desktop/services/mediacrush_cli.dart';
+import 'package:desktop/services/transcode_service.dart';
+import 'package:desktop/utils/ffmpeg_locator.dart';
+
+void main() {
+  group('FfmpegLocator', () {
+    test('always returns a non-empty binary name/path', () async {
+      expect(await FfmpegLocator.getFfmpegPath(), isNotEmpty);
+      expect(await FfmpegLocator.getFfprobePath(), isNotEmpty);
+    });
+
+    test('path lookups are stable (cached)', () async {
+      expect(await FfmpegLocator.getFfmpegPath(), await FfmpegLocator.getFfmpegPath());
+    });
+
+    test('availability agrees with the resolved binary', () async {
+      final available = await FfmpegLocator.isFfmpegAvailable();
+      final path = await FfmpegLocator.getFfmpegPath();
+      final res = await Process.run(path, ['-version']).then((r) => r.exitCode == 0, onError: (_) => false);
+      expect(available, res);
+    });
+  });
+
+  group('MediaCrushCli.scanDirectory', () {
+    late Directory tmp;
+    final cli = MediaCrushCli();
+
+    setUp(() => tmp = Directory.systemTemp.createTempSync('mc_scan_'));
+    tearDown(() => tmp.deleteSync(recursive: true));
+
+    void touch(String rel, [int bytes = 4]) {
+      File(p.join(tmp.path, rel))
+        ..createSync(recursive: true)
+        ..writeAsBytesSync(List.filled(bytes, 1));
+    }
+
+    test('every supported extension is picked up (case-insensitive)', () async {
+      for (final ext in MediaCrushCli.videoExtensions) {
+        touch('v$ext');
+        touch('UP${ext.toUpperCase()}');
+      }
+      final items = await cli.scanDirectory(tmp.path);
+      expect(items, hasLength(MediaCrushCli.videoExtensions.length * 2));
+    });
+
+    test('ignores non-video files', () async {
+      touch('a.txt');
+      touch('b.jpg');
+      touch('c.srt');
+      expect(await cli.scanDirectory(tmp.path), isEmpty);
+    });
+
+    test('recurses and records size + 45% estimate', () async {
+      touch('deep/er/clip.mkv', 2000);
+      final items = await cli.scanDirectory(tmp.path);
+      expect(items.single.originalBytes, 2000);
+      expect(items.single.estimatedBytes, 900);
+      expect(items.single.fileName, 'clip.mkv');
+    });
+
+    test('empty directory', () async {
+      expect(await cli.scanDirectory(tmp.path), isEmpty);
+    });
+  });
+
+  group('TranscodeService', () {
+    test('returns false and leaves no output for a missing input', () async {
+      final tmp = Directory.systemTemp.createTempSync('mc_tc_');
+      addTearDown(() => tmp.deleteSync(recursive: true));
+      final out = p.join(tmp.path, 'out.mp4');
+      final progress = <double>[];
+      final ok = await TranscodeService().transcode(
+        inputPath: p.join(tmp.path, 'missing.mkv'),
+        outputPath: out,
+        engine: HardwareEngine.fallback(),
+        preset: 'film',
+        onProgress: progress.add,
+      );
+      expect(ok, isFalse);
+      expect(File(out).existsSync(), isFalse);
+    }, timeout: const Timeout(Duration(seconds: 60)));
+
+    test('cancel is safe with no active process', () {
+      TranscodeService().cancel();
+    });
+  });
+}
diff --git a/desktop/test/models_extended_test.dart b/desktop/test/models_extended_test.dart
new file mode 100644
index 0000000..8cdd51a
--- /dev/null
+++ b/desktop/test/models_extended_test.dart
@@ -0,0 +1,109 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:desktop/models/hardware_engine.dart';
+import 'package:desktop/models/media_item.dart';
+
+MediaItem item({int original = 1000, int estimated = 450, int fin = 0, MediaStatus status = MediaStatus.pending}) =>
+    MediaItem(
+      path: '/a.mkv',
+      fileName: 'a.mkv',
+      codec: 'H.264',
+      resolution: '1080p',
+      originalBytes: original,
+      estimatedBytes: estimated,
+      finalBytes: fin,
+      status: status,
+    );
+
+void main() {
+  group('HardwareEngine.fromCliName', () {
+    const table = {
+      'hevc_nvenc': ['hevc_nvenc', 'NVIDIA', 'HEVC'],
+      'nvenc': ['hevc_nvenc', 'NVIDIA', 'HEVC'],
+      'av1_nvenc': ['av1_nvenc', 'NVIDIA', 'AV1'],
+      'hevc_videotoolbox': ['hevc_videotoolbox', 'Apple', 'HEVC'],
+      'videotoolbox': ['hevc_videotoolbox', 'Apple', 'HEVC'],
+      'hevc_amf': ['hevc_amf', 'AMD', 'HEVC'],
+      'amf': ['hevc_amf', 'AMD', 'HEVC'],
+      'hevc_qsv': ['hevc_qsv', 'Intel', 'HEVC'],
+      'qsv': ['hevc_qsv', 'Intel', 'HEVC'],
+      'hevc_vaapi': ['hevc_vaapi', 'Linux/Mesa', 'HEVC'],
+      'vaapi': ['hevc_vaapi', 'Linux/Mesa', 'HEVC'],
+    };
+
+    table.forEach((input, expected) {
+      test('maps "$input"', () {
+        final e = HardwareEngine.fromCliName(input);
+        expect([e.name, e.vendor, e.codec], expected);
+        expect(e.isHardware, isTrue);
+        expect(e.typicalFps, greaterThan(0));
+      });
+    });
+
+    test('is case-insensitive', () {
+      expect(HardwareEngine.fromCliName('HEVC_NVENC').vendor, 'NVIDIA');
+    });
+
+    test('unknown and empty names fall back to CPU', () {
+      for (final n in ['', 'libx264', 'garbage']) {
+        final e = HardwareEngine.fromCliName(n);
+        expect(e.name, 'libx265');
+        expect(e.isHardware, isFalse);
+        expect(e.vendor, 'CPU');
+      }
+    });
+
+    test('fallback is software HEVC', () {
+      final f = HardwareEngine.fallback();
+      expect(f.codec, 'HEVC');
+      expect(f.isHardware, isFalse);
+    });
+  });
+
+  group('MediaItem.formatBytes', () {
+    test('zero and negative', () {
+      expect(MediaItem.formatBytes(0), '0 B');
+      expect(MediaItem.formatBytes(-10), '0 B');
+    });
+
+    test('unit boundaries', () {
+      expect(MediaItem.formatBytes(1), '1.0 B');
+      expect(MediaItem.formatBytes(1023), '1023.0 B');
+      expect(MediaItem.formatBytes(1536), '1.5 KB');
+      expect(MediaItem.formatBytes(1024 * 1024 * 1024 * 1024), '1.0 TB');
+    });
+
+    test('caps at TB', () {
+      expect(MediaItem.formatBytes(1024 * 1024 * 1024 * 1024 * 2048), endsWith('TB'));
+    });
+  });
+
+  group('MediaItem.savingsRatio', () {
+    test('uses estimate while pending', () {
+      expect(item().savingsRatio, closeTo(0.55, 1e-9));
+    });
+
+    test('uses actual size once completed', () {
+      expect(item(fin: 200, status: MediaStatus.completed).savingsRatio, closeTo(0.8, 1e-9));
+    });
+
+    test('falls back to estimate when completed with unknown final size', () {
+      expect(item(fin: 0, status: MediaStatus.completed).savingsRatio, closeTo(0.55, 1e-9));
+    });
+
+    test('never negative if estimate exceeds original', () {
+      expect(item(estimated: 2000).savingsRatio, 0.0);
+    });
+
+    test('zero for empty files', () {
+      expect(item(original: 0, estimated: 0).savingsRatio, 0.0);
+    });
+
+    test('defaults', () {
+      final i = item();
+      expect(i.status, MediaStatus.pending);
+      expect(i.progress, 0.0);
+      expect(i.outputPath, isNull);
+      expect(i.error, isNull);
+    });
+  });
+}
diff --git a/mediacrush/cli/commands.py b/mediacrush/cli/commands.py
index 60ac867..8e3696b 100644
--- a/mediacrush/cli/commands.py
+++ b/mediacrush/cli/commands.py
@@ -14,6 +14,7 @@
 from mediacrush.core.quality import QualityChecker
 from mediacrush.core.queue import JobQueue, QueueEntry
 from mediacrush.core.reporter import CompressionReporter
+from mediacrush.core.safety import SafetyManager
 from mediacrush.core.scanner import LibraryScanner
 from mediacrush.core.transcoder import TranscodeEngine
 from mediacrush.core.watcher import FolderWatcher
@@ -71,7 +72,7 @@ def _execute_compression_batch(candidates, active_enc, args) -> None:
     for idx, cand in enumerate(candidates, 1):
         f_path = cand.metadata.path
         preset = cand.local_preset or (
-            ContentClassifier.detect(f_path).value if args.preset == "auto" else args.preset
+            ContentClassifier.detect(f_path).preset_key if args.preset == "auto" else args.preset
         )
         console.print(f"\n[bold cyan][{idx}/{len(candidates)}][/bold cyan] Compressing: [white]{f_path.name}[/white] [dim]({preset})[/dim]")
 
@@ -105,9 +106,19 @@ def _execute_compression_batch(candidates, active_enc, args) -> None:
             console.print(f"[bold green][OK] Completed![/bold green] Saved ~{format_bytes(saved)}")
 
             if args.quality_check:
-                score = QualityChecker.score(f_path, f_path)
+                # The source is replaced in place, so compare against the .crushed copy
+                # (side-by-side) or the .bak backup; otherwise there is nothing to compare.
+                if in_place:
+                    original = f_path.with_name(f"{f_path.name}.bak") if args.keep_backup else None
+                    encoded = f_path
+                else:
+                    original = f_path
+                    encoded = SafetyManager.get_output_path(f_path, False)
+                score = QualityChecker.score(original, encoded) if original else None
                 if score:
                     console.print(f"[magenta]Quality:[/magenta] VMAF: {score.vmaf} | SSIM: {score.ssim} ({score.verdict})")
+                elif original is None:
+                    console.print("[dim]Quality check skipped: use --side-by-side or --keep-backup to keep the original.[/dim]")
         else:
             console.print(f"[bold red][FAIL] Failed to optimize {f_path.name}[/bold red]")
 
@@ -119,7 +130,10 @@ def _execute_compression_batch(candidates, active_enc, args) -> None:
 
     if reporter and args.report:
         rep_p = Path(args.report)
-        rep_p.suffix.lower() == ".json" and reporter.write_json(rep_p) or reporter.write_html(rep_p)
+        if rep_p.suffix.lower() == ".json":
+            reporter.write_json(rep_p)
+        else:
+            reporter.write_html(rep_p)
         console.print(f"[cyan]Report written to:[/cyan] {rep_p}")
     console.print(f"\n[bold green]Batch complete![/bold green] Total reclaimed space: [bold green]{format_bytes(total_saved)}[/bold green]")
 
diff --git a/mediacrush/core/content_classifier.py b/mediacrush/core/content_classifier.py
index 5f7d866..85f14db 100644
--- a/mediacrush/core/content_classifier.py
+++ b/mediacrush/core/content_classifier.py
@@ -1,5 +1,7 @@
 """Automatic media content classification (Animation vs Live-Action)."""
 
+from __future__ import annotations
+
 from enum import Enum
 from pathlib import Path
 import subprocess
@@ -11,7 +13,12 @@ class ContentType(str, Enum):
     """Categorized content types for preset auto-selection."""
     ANIME = "anime"
     LIVE_ACTION = "film"
-    UNKNOWN = "film"
+    UNKNOWN = "unknown"
+
+    @property
+    def preset_key(self) -> str:
+        """Preset to use for this content type; unknown content is treated as live action."""
+        return "anime" if self is ContentType.ANIME else "film"
 
 
 class ContentClassifier:
diff --git a/mediacrush/core/deduplicator.py b/mediacrush/core/deduplicator.py
index c7f60fe..f3e70bb 100644
--- a/mediacrush/core/deduplicator.py
+++ b/mediacrush/core/deduplicator.py
@@ -45,28 +45,19 @@ def find(cls, target_path: Path) -> List[DuplicateGroup]:
             if meta and meta.duration_seconds > 10:
                 probed.append(meta)
 
-        # Bucket by duration bucket (rounded to nearest 4 seconds)
-        duration_buckets: Dict[int, List[MediaMetadata]] = {}
+        # Cluster by duration: sorted sweep, a file joins the open cluster if within 3s of its first member
+        probed.sort(key=lambda m: m.duration_seconds)
+        clusters: List[List[MediaMetadata]] = []
         for m in probed:
-            bucket_key = int(round(m.duration_seconds / 4.0)) * 4
-            duration_buckets.setdefault(bucket_key, []).append(m)
+            if clusters and abs(clusters[-1][0].duration_seconds - m.duration_seconds) <= 3.0:
+                clusters[-1].append(m)
+            else:
+                clusters.append([m])
 
         groups: List[DuplicateGroup] = []
         res_rank = {"4K": 3, "1080p": 2, "720p": 1}
 
-        for _, bucket in duration_buckets.items():
-            if len(bucket) < 2:
-                continue
-
-            # Within duration bucket, match if durations are within 3s
-            cluster: List[MediaMetadata] = []
-            for item in bucket:
-                if not cluster:
-                    cluster.append(item)
-                else:
-                    if abs(cluster[0].duration_seconds - item.duration_seconds) <= 3.0:
-                        cluster.append(item)
-
+        for cluster in clusters:
             if len(cluster) >= 2:
                 # Pick best: highest resolution rank, then largest file
                 sorted_files = sorted(
diff --git a/mediacrush/core/reporter.py b/mediacrush/core/reporter.py
index 213a279..9d642fc 100644
--- a/mediacrush/core/reporter.py
+++ b/mediacrush/core/reporter.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from html import escape
 import json
 from dataclasses import asdict, dataclass
 from pathlib import Path
@@ -79,11 +80,11 @@ def write_html(self, output_path: Path) -> None:
         output_path.write_text(html, encoding="utf-8")
 
     @staticmethod
-    def _fmt(b: int) -> str:
+    def _fmt(b: float) -> str:
         for unit in ("B", "KB", "MB", "GB"):
             if b < 1024:
                 return f"{b:.1f} {unit}"
-            b //= 1024
+            b /= 1024
         return f"{b:.1f} TB"
 
     @staticmethod
@@ -92,7 +93,7 @@ def _build_row(e: ReportEntry) -> str:
         orig = CompressionReporter._fmt(e.original_bytes)
         final = CompressionReporter._fmt(e.final_bytes)
         return (
-            f"<tr><td>{e.file}</td><td>{orig}</td><td>{final}</td>"
-            f"<td>{e.savings_pct:.1f}%</td><td>{e.encoder}</td>"
+            f"<tr><td>{escape(e.file)}</td><td>{orig}</td><td>{final}</td>"
+            f"<td>{e.savings_pct:.1f}%</td><td>{escape(e.encoder)}</td>"
             f"<td>{e.duration_s:.1f}</td><td>{status}</td></tr>\n"
         )
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..1bd108d
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,100 @@
+"""Shared fixtures and helpers for the MediaCrush test suite."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import List, Optional
+
+import pytest
+
+from mediacrush.core.probe import MediaMetadata, StreamInfo
+
+HAS_FFMPEG = bool(shutil.which("ffmpeg") and shutil.which("ffprobe"))
+requires_ffmpeg = pytest.mark.skipif(not HAS_FFMPEG, reason="ffmpeg/ffprobe not installed")
+
+
+def make_meta(
+    path: str = "/fake/video.mkv",
+    codec: str = "h264",
+    width: int = 1920,
+    height: int = 1080,
+    duration: float = 1400.0,
+    size_mb: float = 500,
+    video_bitrate: int = 8_000_000,
+    overall_bitrate: Optional[int] = None,
+    audio: int = 1,
+    subs: int = 0,
+    hdr: Optional[str] = None,
+    primaries: str = "unknown",
+    transfer: str = "unknown",
+) -> MediaMetadata:
+    """Builds MediaMetadata without touching disk or ffprobe."""
+    audios: List[StreamInfo] = [StreamInfo(i + 1, "audio", "aac", "en", None, 2) for i in range(audio)]
+    subtitles: List[StreamInfo] = [StreamInfo(i + 10, "subtitle", "ass", "en") for i in range(subs)]
+    return MediaMetadata(
+        path=Path(path),
+        duration_seconds=duration,
+        file_size_bytes=int(size_mb * 1024 * 1024),
+        video_codec=codec,
+        width=width,
+        height=height,
+        fps=24.0,
+        video_bitrate=video_bitrate,
+        overall_bitrate=overall_bitrate if overall_bitrate is not None else video_bitrate + 192_000,
+        audio_streams=audios,
+        subtitle_streams=subtitles,
+        hdr_format=hdr,
+        color_primaries=primaries,
+        color_transfer=transfer,
+    )
+
+
+@pytest.fixture
+def meta_factory():
+    return make_meta
+
+
+def generate_video(
+    path: Path,
+    seconds: float = 12,
+    size: str = "320x240",
+    audio: bool = True,
+    codec: str = "libx264",
+    pattern: str = "testsrc2",
+    extra: Optional[List[str]] = None,
+) -> Path:
+    """Creates a real, tiny test video with ffmpeg (requires ffmpeg)."""
+    cmd = ["ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"{pattern}{':' if '=' in pattern else '='}s={size}:r=24:d={seconds}"]
+    if audio:
+        cmd += ["-f", "lavfi", "-i", f"sine=frequency=440:duration={seconds}"]
+    cmd += ["-c:v", codec, "-pix_fmt", "yuv420p"]
+    if audio:
+        cmd += ["-c:a", "aac", "-shortest"]
+    cmd += (extra or []) + [str(path)]
+    subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=120)
+    return path
+
+
+@pytest.fixture
+def video_factory(tmp_path):
+    """Returns a callable that writes real videos into tmp_path."""
+    def _make(name: str = "clip.mp4", **kwargs) -> Path:
+        return generate_video(tmp_path / name, **kwargs)
+    return _make
+
+
+@pytest.fixture
+def cli_args():
+    """Builds an argparse.Namespace mirroring `mediacrush compress` flags."""
+    import argparse
+
+    def _make(**overrides):
+        base = dict(
+            path=".", preset="auto", side_by_side=False, keep_backup=False,
+            dry_run=False, report=None, pause=False, quality_check=False,
+        )
+        base.update(overrides)
+        return argparse.Namespace(**base)
+    return _make
diff --git a/tests/test_classifier_ppm.py b/tests/test_classifier_ppm.py
new file mode 100644
index 0000000..c303de6
--- /dev/null
+++ b/tests/test_classifier_ppm.py
@@ -0,0 +1,115 @@
+"""Unit tests for ContentClassifier PPM analysis and detect() control flow."""
+
+import random
+from unittest.mock import patch
+
+import pytest
+
+from mediacrush.core.content_classifier import ContentClassifier, ContentType
+
+
+def write_ppm(path, w, h, pixel_fn, maxval=255, magic=b"P6", comment=False):
+    body = bytearray()
+    for i in range(w * h):
+        body += bytes(pixel_fn(i))
+    hdr = magic + b"\n" + (b"# c\n" if comment else b"") + f"{w} {h}\n{maxval}\n".encode()
+    path.write_bytes(hdr + bytes(body))
+    return path
+
+
+class TestAnalyzePpm:
+    def test_flat_color_is_one_color(self, tmp_path):
+        p = write_ppm(tmp_path / "a.ppm", 64, 64, lambda i: (10, 20, 30))
+        assert ContentClassifier._analyze_frame_ppm(p) == pytest.approx(1 / 4096)
+
+    def test_noise_has_high_ratio(self, tmp_path):
+        rnd = random.Random(1)
+        p = write_ppm(tmp_path / "n.ppm", 320, 180, lambda i: (rnd.randrange(256),) * 3 if False else (rnd.randrange(256), rnd.randrange(256), rnd.randrange(256)))
+        assert ContentClassifier._analyze_frame_ppm(p) > 0.5
+
+    def test_quantization_merges_close_colors(self, tmp_path):
+        p = write_ppm(tmp_path / "q.ppm", 4, 4, lambda i: (16 + (i % 15), 0, 0))  # all share top nibble 1
+        assert ContentClassifier._analyze_frame_ppm(p) == pytest.approx(1 / 4096)
+
+    def test_comment_line_skipped(self, tmp_path):
+        p = write_ppm(tmp_path / "c.ppm", 2, 2, lambda i: (0, 0, 0), comment=True)
+        assert ContentClassifier._analyze_frame_ppm(p) is not None
+
+    def test_wrong_magic(self, tmp_path):
+        p = write_ppm(tmp_path / "b.ppm", 2, 2, lambda i: (0, 0, 0), magic=b"P3")
+        assert ContentClassifier._analyze_frame_ppm(p) is None
+
+    def test_wrong_maxval(self, tmp_path):
+        p = write_ppm(tmp_path / "m.ppm", 2, 2, lambda i: (0, 0, 0), maxval=65535)
+        assert ContentClassifier._analyze_frame_ppm(p) is None
+
+    def test_truncated_data(self, tmp_path):
+        p = tmp_path / "t.ppm"
+        p.write_bytes(b"P6\n10 10\n255\n" + b"\0" * 5)
+        assert ContentClassifier._analyze_frame_ppm(p) is None
+
+    def test_missing_file(self, tmp_path):
+        assert ContentClassifier._analyze_frame_ppm(tmp_path / "none.ppm") is None
+
+    def test_garbage_header(self, tmp_path):
+        p = tmp_path / "g.ppm"
+        p.write_bytes(b"P6\nabc def\n255\n")
+        assert ContentClassifier._analyze_frame_ppm(p) is None
+
+
+class TestDetect:
+    def test_missing_file_unknown(self, tmp_path):
+        assert ContentClassifier.detect(tmp_path / "x.mkv") == ContentType.UNKNOWN
+
+    def test_exception_returns_unknown(self, tmp_path):
+        f = tmp_path / "x.mkv"
+        f.write_bytes(b"1")
+        with patch("mediacrush.core.content_classifier.subprocess.run", side_effect=OSError):
+            assert ContentClassifier.detect(f) == ContentType.UNKNOWN
+
+    def test_no_frames_unknown(self, tmp_path):
+        f = tmp_path / "x.mkv"
+        f.write_bytes(b"1")
+        with patch("mediacrush.core.content_classifier.subprocess.run"):
+            assert ContentClassifier.detect(f) == ContentType.UNKNOWN
+
+    @pytest.mark.parametrize("ratio,expected", [(0.05, ContentType.ANIME), (0.17, ContentType.ANIME),
+                                                (0.18, ContentType.LIVE_ACTION), (0.6, ContentType.LIVE_ACTION)])
+    def test_threshold(self, tmp_path, ratio, expected):
+        f = tmp_path / "x.mkv"
+        f.write_bytes(b"1")
+
+        def fake_run(cmd, **kw):
+            from pathlib import Path
+            Path(cmd[-1].replace("%02d", "01")).write_bytes(b"")
+
+        with patch("mediacrush.core.content_classifier.subprocess.run", side_effect=fake_run), \
+             patch.object(ContentClassifier, "_analyze_frame_ppm", return_value=ratio):
+            assert ContentClassifier.detect(f) == expected
+
+    def test_all_frames_unparsable_unknown(self, tmp_path):
+        f = tmp_path / "x.mkv"
+        f.write_bytes(b"1")
+
+        def fake_run(cmd, **kw):
+            from pathlib import Path
+            Path(cmd[-1].replace("%02d", "01")).write_bytes(b"")
+
+        with patch("mediacrush.core.content_classifier.subprocess.run", side_effect=fake_run), \
+             patch.object(ContentClassifier, "_analyze_frame_ppm", return_value=None):
+            assert ContentClassifier.detect(f) == ContentType.UNKNOWN
+
+
+class TestContentTypeEnum:
+    def test_values_are_valid_preset_keys(self):
+        from mediacrush.core.presets import PresetManager
+        for t in ContentType:
+            assert t.preset_key in PresetManager.PRESETS
+
+    def test_unknown_maps_to_film_preset(self):
+        assert ContentType.UNKNOWN.preset_key == "film"
+        assert ContentType.LIVE_ACTION.preset_key == "film"
+        assert ContentType.ANIME.preset_key == "anime"
+
+    def test_unknown_is_distinct_member(self):
+        assert ContentType.UNKNOWN is not ContentType.LIVE_ACTION
diff --git a/tests/test_cli_parser.py b/tests/test_cli_parser.py
new file mode 100644
index 0000000..e10e0c5
--- /dev/null
+++ b/tests/test_cli_parser.py
@@ -0,0 +1,67 @@
+"""Unit tests for the argparse CLI surface and main() routing."""
+
+import pytest
+
+from mediacrush.cli import main as cli_main
+from mediacrush.cli.main import build_parser
+
+
+@pytest.fixture
+def parser():
+    return build_parser()
+
+
+class TestParser:
+    def test_command_required(self, parser):
+        with pytest.raises(SystemExit):
+            parser.parse_args([])
+
+    def test_unknown_command(self, parser):
+        with pytest.raises(SystemExit):
+            parser.parse_args(["explode"])
+
+    def test_compress_defaults(self, parser):
+        a = parser.parse_args(["compress", "/x"])
+        assert (a.preset, a.side_by_side, a.keep_backup, a.dry_run, a.report, a.pause, a.quality_check) == \
+               ("auto", False, False, False, None, False, False)
+
+    def test_compress_all_flags(self, parser):
+        a = parser.parse_args(["compress", "/x", "--preset", "saver", "--side-by-side", "--keep-backup",
+                               "--dry-run", "--report", "r.json", "--pause", "--quality-check"])
+        assert a.preset == "saver" and a.side_by_side and a.keep_backup and a.dry_run
+        assert a.report == "r.json" and a.pause and a.quality_check
+
+    def test_compress_rejects_bad_preset(self, parser):
+        with pytest.raises(SystemExit):
+            parser.parse_args(["compress", "/x", "--preset", "ultra"])
+
+    def test_compress_requires_path(self, parser):
+        with pytest.raises(SystemExit):
+            parser.parse_args(["compress"])
+
+    def test_watch_default_and_no_auto(self, parser):
+        assert parser.parse_args(["watch", "/x"]).preset == "anime"
+        with pytest.raises(SystemExit):
+            parser.parse_args(["watch", "/x", "--preset", "auto"])
+
+    @pytest.mark.parametrize("cmd", ["detect", "resume", "gui"])
+    def test_no_arg_commands(self, parser, cmd):
+        assert parser.parse_args([cmd]).command == cmd
+
+    def test_find_dupes(self, parser):
+        a = parser.parse_args(["find-dupes", "/lib", "--report", "o.html"])
+        assert a.path == "/lib" and a.report == "o.html"
+
+
+class TestMainRouting:
+    @pytest.mark.parametrize("argv,name", [
+        (["detect"], "cmd_detect"), (["scan", "/x"], "cmd_scan"), (["compress", "/x"], "cmd_compress"),
+        (["watch", "/x"], "cmd_watch"), (["resume"], "cmd_resume"),
+        (["find-dupes", "/x"], "cmd_find_dupes"), (["gui"], "cmd_gui"),
+    ])
+    def test_dispatch(self, monkeypatch, argv, name):
+        called = []
+        monkeypatch.setattr(cli_main, name, lambda args: called.append(args.command))
+        monkeypatch.setattr("sys.argv", ["mediacrush"] + argv)
+        cli_main.main()
+        assert called == [argv[0]]
diff --git a/tests/test_commands.py b/tests/test_commands.py
new file mode 100644
index 0000000..2986a55
--- /dev/null
+++ b/tests/test_commands.py
@@ -0,0 +1,210 @@
+"""Integration-style tests for CLI command handlers with core services mocked."""
+
+import argparse
+import json
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from rich.console import Console
+
+from conftest import make_meta
+from mediacrush.cli import commands, formatters
+from mediacrush.core.deduplicator import DuplicateGroup
+from mediacrush.core.hardware import EncoderInfo
+from mediacrush.core.scanner import CandidateFile, ScanReport
+
+ENC = EncoderInfo("hevc", "libx265", "CPU", None, "CPU x265")
+
+
+@pytest.fixture(autouse=True)
+def quiet_console(monkeypatch):
+    c = Console(record=True, width=200)
+    monkeypatch.setattr(commands, "console", c)
+    monkeypatch.setattr(formatters, "console", c)
+    return c
+
+
+def cand(path, size_mb=1000, preset=None):
+    m = make_meta(str(path), size_mb=size_mb)
+    return CandidateFile(m, "r", m.file_size_bytes // 3, m.file_size_bytes * 2 // 3, preset)
+
+
+def report(tmp_path, cands):
+    return ScanReport(tmp_path, cands, 0, sum(c.metadata.file_size_bytes for c in cands),
+                      sum(c.estimated_size_bytes for c in cands))
+
+
+class TestDetect:
+    def test_prints_table(self, quiet_console):
+        with patch.object(commands.HardwareDetector, "discover_encoders", return_value=[ENC]), \
+             patch.object(commands.HardwareDetector, "get_best_encoder", return_value=ENC):
+            commands.cmd_detect(argparse.Namespace())
+        assert "libx265" in quiet_console.export_text()
+
+
+class TestScan:
+    def test_missing_path_exits_1(self, tmp_path):
+        with pytest.raises(SystemExit) as e:
+            commands.cmd_scan(argparse.Namespace(path=str(tmp_path / "nope")))
+        assert e.value.code == 1
+
+    def test_scan_prints_report(self, tmp_path, quiet_console):
+        with patch.object(commands.LibraryScanner, "scan_path", return_value=report(tmp_path, [cand(tmp_path / "a.mkv")])):
+            commands.cmd_scan(argparse.Namespace(path=str(tmp_path)))
+        assert "a.mkv" in quiet_console.export_text()
+
+
+class TestCompress:
+    def _run(self, tmp_path, args, rep, transcode=True):
+        with patch.object(commands.HardwareDetector, "get_best_encoder", return_value=ENC), \
+             patch.object(commands.LibraryScanner, "scan_path", return_value=rep), \
+             patch.object(commands.TranscodeEngine, "transcode", return_value=transcode) as tc, \
+             patch.object(commands.ContentClassifier, "detect") as det:
+            det.return_value = MagicMock(preset_key="anime")
+            commands.cmd_compress(args)
+        return tc, det
+
+    def test_missing_path_exits(self, cli_args, tmp_path):
+        with pytest.raises(SystemExit):
+            commands.cmd_compress(cli_args(path=str(tmp_path / "nope")))
+
+    def test_nothing_to_do(self, cli_args, tmp_path, quiet_console):
+        tc, _ = self._run(tmp_path, cli_args(path=str(tmp_path)), report(tmp_path, []))
+        tc.assert_not_called()
+        assert "already optimized" in quiet_console.export_text()
+
+    def test_dry_run_never_transcodes(self, cli_args, tmp_path):
+        tc, _ = self._run(tmp_path, cli_args(path=str(tmp_path), dry_run=True), report(tmp_path, [cand(tmp_path / "a.mkv")]))
+        tc.assert_not_called()
+
+    def test_auto_preset_uses_classifier(self, cli_args, tmp_path):
+        tc, det = self._run(tmp_path, cli_args(path=str(tmp_path)), report(tmp_path, [cand(tmp_path / "a.mkv")]))
+        det.assert_called_once()
+        assert tc.call_args.kwargs["preset_key"] == "anime"
+
+    def test_explicit_preset_skips_classifier(self, cli_args, tmp_path):
+        tc, det = self._run(tmp_path, cli_args(path=str(tmp_path), preset="saver"), report(tmp_path, [cand(tmp_path / "a.mkv")]))
+        det.assert_not_called()
+        assert tc.call_args.kwargs["preset_key"] == "saver"
+
+    def test_folder_override_wins(self, cli_args, tmp_path):
+        tc, det = self._run(tmp_path, cli_args(path=str(tmp_path), preset="saver"),
+                            report(tmp_path, [cand(tmp_path / "a.mkv", preset="film")]))
+        assert tc.call_args.kwargs["preset_key"] == "film"
+        det.assert_not_called()
+
+    def test_side_by_side_flag(self, cli_args, tmp_path):
+        tc, _ = self._run(tmp_path, cli_args(path=str(tmp_path), preset="film", side_by_side=True),
+                          report(tmp_path, [cand(tmp_path / "a.mkv")]))
+        assert tc.call_args.kwargs["in_place"] is False
+
+    def test_failure_is_reported_not_raised(self, cli_args, tmp_path, quiet_console):
+        self._run(tmp_path, cli_args(path=str(tmp_path), preset="film"), report(tmp_path, [cand(tmp_path / "a.mkv")]), transcode=False)
+        assert "Failed" in quiet_console.export_text()
+
+    def test_processes_every_candidate(self, cli_args, tmp_path):
+        cs = [cand(tmp_path / f"{i}.mkv") for i in range(3)]
+        tc, _ = self._run(tmp_path, cli_args(path=str(tmp_path), preset="film"), report(tmp_path, cs))
+        assert tc.call_count == 3
+
+
+class TestPauseQueue:
+    def test_pause_queues_remaining(self, cli_args, tmp_path):
+        qfile = tmp_path / "q.json"
+        cs = [cand(tmp_path / f"{i}.mkv") for i in range(3)]
+        from mediacrush.core.queue import JobQueue
+        with patch.object(commands, "JobQueue", side_effect=lambda: JobQueue(qfile)), \
+             patch.object(commands.TranscodeEngine, "transcode", return_value=True) as tc:
+            commands._execute_compression_batch(cs, ENC, cli_args(preset="film", pause=True))
+        assert tc.call_count == 1
+        saved = json.loads(qfile.read_text())
+        assert [Path(e["path"]).name for e in saved] == ["1.mkv", "2.mkv"]
+        assert all(e["status"] == "pending" and e["preset"] == "film" for e in saved)
+
+
+class TestReports:
+    def _batch(self, tmp_path, cli_args, name):
+        rp = tmp_path / name
+        with patch.object(commands.TranscodeEngine, "transcode", return_value=True):
+            commands._execute_compression_batch([cand(tmp_path / "a.mkv")], ENC, cli_args(preset="film", report=str(rp)))
+        return rp
+
+    def test_html_report(self, tmp_path, cli_args):
+        rp = self._batch(tmp_path, cli_args, "r.html")
+        assert "<html" in rp.read_text(encoding="utf-8")
+
+    def test_json_report_is_json(self, tmp_path, cli_args):
+        rp = self._batch(tmp_path, cli_args, "r.json")
+        json.loads(rp.read_text(encoding="utf-8"))
+
+
+class TestQualityCheck:
+    def _run(self, tmp_path, cli_args, **flags):
+        f = tmp_path / "a.mkv"
+        f.write_bytes(b"x")
+        with patch.object(commands.TranscodeEngine, "transcode", return_value=True), \
+             patch.object(commands.QualityChecker, "score", return_value=None) as sc:
+            commands._execute_compression_batch([cand(f)], ENC, cli_args(preset="film", quality_check=True, **flags))
+        return f, sc
+
+    def test_side_by_side_compares_source_to_crushed(self, tmp_path, cli_args):
+        f, sc = self._run(tmp_path, cli_args, side_by_side=True)
+        sc.assert_called_once_with(f, f.with_name("a.crushed.mkv"))
+
+    def test_in_place_with_backup_compares_backup_to_output(self, tmp_path, cli_args):
+        f, sc = self._run(tmp_path, cli_args, keep_backup=True)
+        sc.assert_called_once_with(f.with_name("a.mkv.bak"), f)
+
+    def test_in_place_without_backup_skips_check(self, tmp_path, cli_args, quiet_console):
+        _, sc = self._run(tmp_path, cli_args)
+        sc.assert_not_called()
+        assert "Quality check skipped" in quiet_console.export_text()
+
+
+class TestResume:
+    def test_empty_queue(self, quiet_console, tmp_path):
+        with patch.object(commands, "JobQueue") as JQ:
+            JQ.return_value.load.return_value = []
+            commands.cmd_resume(argparse.Namespace())
+        assert "No pending jobs" in quiet_console.export_text()
+
+    def test_marks_done_and_failed(self, tmp_path):
+        from mediacrush.core.queue import QueueEntry
+        entries = [QueueEntry(str(tmp_path / "ok.mkv"), "film", True, "pending"),
+                   QueueEntry(str(tmp_path / "bad.mkv"), "film", True, "pending"),
+                   QueueEntry(str(tmp_path / "old.mkv"), "film", True, "done")]
+        rep = lambda p: report(tmp_path, [cand(p)])
+        with patch.object(commands, "JobQueue") as JQ, \
+             patch.object(commands.HardwareDetector, "get_best_encoder", return_value=ENC), \
+             patch.object(commands.LibraryScanner, "scan_path", side_effect=rep), \
+             patch.object(commands.TranscodeEngine, "transcode", side_effect=[True, False]):
+            JQ.return_value.load.return_value = entries
+            commands.cmd_resume(argparse.Namespace())
+            q = JQ.return_value
+        q.mark_done.assert_called_once_with(str(tmp_path / "ok.mkv"))
+        q.mark_failed.assert_called_once_with(str(tmp_path / "bad.mkv"))
+
+
+class TestFindDupes:
+    def test_none_found(self, quiet_console, tmp_path):
+        with patch.object(commands.DuplicateDetector, "find", return_value=[]):
+            commands.cmd_find_dupes(argparse.Namespace(path=str(tmp_path)))
+        assert "No duplicate" in quiet_console.export_text()
+
+    def test_prints_clusters(self, quiet_console, tmp_path):
+        keep, dup = make_meta("/l/keep.mkv", size_mb=900), make_meta("/l/dup.mkv", size_mb=300)
+        g = DuplicateGroup([keep, dup], keep, dup.file_size_bytes)
+        with patch.object(commands.DuplicateDetector, "find", return_value=[g]):
+            commands.cmd_find_dupes(argparse.Namespace(path=str(tmp_path)))
+        t = quiet_console.export_text()
+        assert "keep.mkv" in t and "dup.mkv" in t and "Total reclaimable" in t
+
+
+class TestWatchAndGui:
+    def test_watch_starts_watcher(self, tmp_path):
+        with patch.object(commands.HardwareDetector, "get_best_encoder", return_value=ENC), \
+             patch.object(commands, "FolderWatcher") as FW:
+            commands.cmd_watch(argparse.Namespace(path=str(tmp_path), preset="film"))
+        FW.assert_called_once_with(Path(tmp_path), "film", ENC)
+        FW.return_value.start.assert_called_once()
diff --git a/tests/test_content_classifier.py b/tests/test_content_classifier.py
index d6b944a..e3ed298 100644
--- a/tests/test_content_classifier.py
+++ b/tests/test_content_classifier.py
@@ -12,7 +12,8 @@ def test_enum_values(self):
         """Verifies enum preset mappings."""
         self.assertEqual(ContentType.ANIME.value, "anime")
         self.assertEqual(ContentType.LIVE_ACTION.value, "film")
-        self.assertEqual(ContentType.UNKNOWN.value, "film")
+        self.assertEqual(ContentType.UNKNOWN.value, "unknown")
+        self.assertEqual(ContentType.UNKNOWN.preset_key, "film")
 
     def test_analyze_frame_ppm_flat_colors(self):
         """Synthetic PPM with flat colors should have low unique color ratio."""
diff --git a/tests/test_dedupe_logic.py b/tests/test_dedupe_logic.py
new file mode 100644
index 0000000..20e7741
--- /dev/null
+++ b/tests/test_dedupe_logic.py
@@ -0,0 +1,94 @@
+"""Unit tests for DuplicateDetector name normalization and clustering (probe mocked)."""
+
+from unittest.mock import patch
+
+import pytest
+
+from conftest import make_meta
+from mediacrush.core.deduplicator import DuplicateDetector
+
+
+def run_find(tmp_path, metas):
+    """Creates empty files named after metas and maps probe results by name."""
+    by_name = {}
+    for m in metas:
+        (tmp_path / m.path.name).write_bytes(b"x")
+        by_name[m.path.name] = m
+    with patch("mediacrush.core.deduplicator.MediaProbe.inspect", side_effect=lambda p: by_name.get(p.name)):
+        return DuplicateDetector.find(tmp_path)
+
+
+class TestNormalize:
+    @pytest.mark.parametrize("a,b", [
+        ("Movie.1080p.x265.mkv", "movie 720p x264.mkv"),
+        ("My_Show-WEB-DL.AAC", "my show"),
+    ])
+    def test_tags_stripped(self, a, b):
+        assert DuplicateDetector._normalize_name(a).split() [:2] == DuplicateDetector._normalize_name(b).split()[:2]
+
+    def test_separators_collapsed(self):
+        assert DuplicateDetector._normalize_name("A._-B") == "a b"
+
+
+class TestFind:
+    def test_empty_dir(self, tmp_path):
+        assert DuplicateDetector.find(tmp_path) == []
+
+    def test_nonexistent_path(self, tmp_path):
+        assert DuplicateDetector.find(tmp_path / "nope") == []
+
+    def test_pair_detected_best_kept(self, tmp_path):
+        hi = make_meta("/a/hi.mkv", duration=1400, size_mb=900, width=1920, height=1080)
+        lo = make_meta("/a/lo.mkv", duration=1401, size_mb=300, width=1280, height=720)
+        groups = run_find(tmp_path, [hi, lo])
+        assert len(groups) == 1
+        assert groups[0].recommended_keep.path.name == "hi.mkv"
+        assert groups[0].removable_size_bytes == lo.file_size_bytes
+
+    def test_same_resolution_largest_kept(self, tmp_path):
+        a = make_meta("/a/a.mkv", duration=1400, size_mb=100)
+        b = make_meta("/a/b.mkv", duration=1400, size_mb=500)
+        g = run_find(tmp_path, [a, b])[0]
+        assert g.recommended_keep.path.name == "b.mkv"
+
+    def test_different_durations_not_duplicates(self, tmp_path):
+        a = make_meta("/a/a.mkv", duration=1400)
+        b = make_meta("/a/b.mkv", duration=2400)
+        assert run_find(tmp_path, [a, b]) == []
+
+    def test_short_clips_ignored(self, tmp_path):
+        a = make_meta("/a/a.mkv", duration=8)
+        b = make_meta("/a/b.mkv", duration=8)
+        assert run_find(tmp_path, [a, b]) == []
+
+    def test_unprobeable_files_ignored(self, tmp_path):
+        (tmp_path / "bad.mkv").write_bytes(b"x")
+        with patch("mediacrush.core.deduplicator.MediaProbe.inspect", return_value=None):
+            assert DuplicateDetector.find(tmp_path) == []
+
+    def test_non_video_ignored(self, tmp_path):
+        (tmp_path / "notes.txt").write_text("x")
+        with patch("mediacrush.core.deduplicator.MediaProbe.inspect") as probe:
+            DuplicateDetector.find(tmp_path)
+        probe.assert_not_called()
+
+    def test_recurses_into_subfolders(self, tmp_path):
+        sub = tmp_path / "sub"
+        sub.mkdir()
+        a, b = make_meta("/a/a.mkv", duration=1400), make_meta("/a/b.mkv", duration=1400)
+        (tmp_path / "a.mkv").write_bytes(b"x")
+        (sub / "b.mkv").write_bytes(b"x")
+        with patch("mediacrush.core.deduplicator.MediaProbe.inspect",
+                   side_effect=lambda p: {"a.mkv": a, "b.mkv": b}[p.name]):
+            assert len(DuplicateDetector.find(tmp_path)) == 1
+
+    def test_single_file_target(self, tmp_path):
+        f = tmp_path / "a.mkv"
+        f.write_bytes(b"x")
+        with patch("mediacrush.core.deduplicator.MediaProbe.inspect", return_value=make_meta("/a/a.mkv")):
+            assert DuplicateDetector.find(f) == []  # one file cannot duplicate itself
+
+    def test_near_duplicates_across_bucket_boundary(self, tmp_path):
+        a = make_meta("/a/a.mkv", duration=1401.9)
+        b = make_meta("/a/b.mkv", duration=1402.1)
+        assert len(run_find(tmp_path, [a, b])) == 1
diff --git a/tests/test_formatters.py b/tests/test_formatters.py
new file mode 100644
index 0000000..ac99960
--- /dev/null
+++ b/tests/test_formatters.py
@@ -0,0 +1,51 @@
+"""Unit tests for CLI formatters."""
+
+from pathlib import Path
+
+import pytest
+from rich.console import Console
+
+from conftest import make_meta
+from mediacrush.cli import formatters
+from mediacrush.core.hardware import EncoderInfo
+from mediacrush.core.scanner import CandidateFile, ScanReport
+
+
+@pytest.mark.parametrize("size,out", [
+    (0, "0.0 MB"), (1024**2, "1.0 MB"), (5 * 1024**2, "5.0 MB"),
+    (1024**3 - 1, "1024.0 MB"), (1024**3, "1.00 GB"), (int(2.5 * 1024**3), "2.50 GB"),
+])
+def test_format_bytes(size, out):
+    assert formatters.format_bytes(size) == out
+
+
+@pytest.fixture
+def captured(monkeypatch):
+    c = Console(record=True, width=200)
+    monkeypatch.setattr(formatters, "console", c)
+    return c
+
+
+def test_banner(captured):
+    formatters.print_banner()
+    assert "MediaCrush" in captured.export_text()
+
+
+def test_encoder_table_marks_active(captured):
+    a = EncoderInfo("hevc", "hevc_nvenc", "NVIDIA", "cuda", "")
+    b = EncoderInfo("hevc", "libx265", "CPU", None, "")
+    formatters.print_encoders_table([a, b], a)
+    text = captured.export_text()
+    assert "hevc_nvenc" in text and "libx265" in text and text.count("Active") == 1
+
+
+def test_scan_report_table(captured):
+    cand = CandidateFile(make_meta("/lib/Show.mkv", size_mb=1000), "r", 300 * 1024**2, 700 * 1024**2)
+    formatters.print_scan_report(ScanReport(Path("/lib"), [cand], 2, cand.metadata.file_size_bytes, cand.estimated_size_bytes))
+    t = captured.export_text()
+    assert "Show.mkv" in t and "H264" in t and "1080p" in t and "70.0%" in t and "Skipped 2" in t
+
+
+def test_scan_report_empty(captured):
+    formatters.print_scan_report(ScanReport(Path("/lib"), [], 0, 0, 0))
+    assert "Found: 0" in captured.export_text()
diff --git a/tests/test_hardware_mocked.py b/tests/test_hardware_mocked.py
new file mode 100644
index 0000000..c5fcd02
--- /dev/null
+++ b/tests/test_hardware_mocked.py
@@ -0,0 +1,93 @@
+"""Unit tests for HardwareDetector command construction and encoder selection."""
+
+import subprocess
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from mediacrush.core.hardware import EncoderInfo, HardwareDetector
+
+NAMES = [c.encoder_name for c in HardwareDetector.PROBE_CANDIDATES]
+
+
+class TestCandidates:
+    def test_names_unique(self):
+        assert len(NAMES) == len(set(NAMES))
+
+    def test_cpu_fallbacks_present_for_hevc_av1_h264(self):
+        cpu = {c.codec for c in HardwareDetector.PROBE_CANDIDATES if c.vendor == "CPU"}
+        assert cpu == {"hevc", "av1", "h264"}
+
+    def test_cpu_candidates_come_last(self):
+        vendors = [c.vendor for c in HardwareDetector.PROBE_CANDIDATES]
+        first_cpu = vendors.index("CPU")
+        assert all(v == "CPU" for v in vendors[first_cpu:])
+
+    def test_hardware_candidates_have_hwaccel(self):
+        for c in HardwareDetector.PROBE_CANDIDATES:
+            assert (c.hwaccel is None) == (c.vendor == "CPU")
+
+
+class TestTestEncoder:
+    def _run(self, cand, rc=0, exc=None):
+        with patch("mediacrush.core.hardware.subprocess.run") as run:
+            if exc:
+                run.side_effect = exc
+            else:
+                run.return_value = MagicMock(returncode=rc)
+            ok = HardwareDetector.test_encoder(cand)
+        return ok, run
+
+    def test_success(self):
+        assert self._run(HardwareDetector.PROBE_CANDIDATES[0])[0] is True
+
+    def test_failure_returncode(self):
+        assert self._run(HardwareDetector.PROBE_CANDIDATES[0], rc=1)[0] is False
+
+    @pytest.mark.parametrize("exc", [subprocess.TimeoutExpired("ffmpeg", 4), FileNotFoundError(), OSError()])
+    def test_exceptions_mean_unsupported(self, exc):
+        assert self._run(HardwareDetector.PROBE_CANDIDATES[0], exc=exc)[0] is False
+
+    def test_vaapi_adds_device_flags(self):
+        cand = next(c for c in HardwareDetector.PROBE_CANDIDATES if c.encoder_name == "hevc_vaapi")
+        _, run = self._run(cand)
+        cmd = run.call_args[0][0]
+        assert "-vaapi_device" in cmd and "format=nv12,hwupload" in cmd
+
+    def test_non_vaapi_has_no_device_flags(self):
+        _, run = self._run(HardwareDetector.PROBE_CANDIDATES[0])
+        assert "-vaapi_device" not in run.call_args[0][0]
+
+    def test_command_uses_encoder_and_null_sink(self):
+        cand = HardwareDetector.PROBE_CANDIDATES[3]
+        _, run = self._run(cand)
+        cmd = run.call_args[0][0]
+        assert cmd[cmd.index("-c:v") + 1] == cand.encoder_name
+        assert cmd[-3:] == ["-f", "null", "-"]
+
+
+class TestSelection:
+    def _avail(self, *names):
+        return [c for c in HardwareDetector.PROBE_CANDIDATES if c.encoder_name in names]
+
+    def test_prefers_requested_codec_first_match(self):
+        with patch.object(HardwareDetector, "discover_encoders", return_value=self._avail("hevc_nvenc", "libx265", "libx264")):
+            assert HardwareDetector.get_best_encoder("hevc").encoder_name == "hevc_nvenc"
+
+    def test_other_codec(self):
+        with patch.object(HardwareDetector, "discover_encoders", return_value=self._avail("hevc_nvenc", "libsvtav1")):
+            assert HardwareDetector.get_best_encoder("av1").encoder_name == "libsvtav1"
+
+    def test_falls_back_to_any_working(self):
+        with patch.object(HardwareDetector, "discover_encoders", return_value=self._avail("libx264")):
+            assert HardwareDetector.get_best_encoder("hevc").encoder_name == "libx264"
+
+    def test_nothing_available_returns_cpu_default(self):
+        with patch.object(HardwareDetector, "discover_encoders", return_value=[]):
+            e = HardwareDetector.get_best_encoder()
+        assert isinstance(e, EncoderInfo) and e.encoder_name == "libx265" and e.hwaccel is None
+
+    def test_discover_filters_failures(self):
+        with patch.object(HardwareDetector, "test_encoder", side_effect=lambda c: c.vendor == "CPU"):
+            found = HardwareDetector.discover_encoders()
+        assert found and all(c.vendor == "CPU" for c in found)
diff --git a/tests/test_integration_ffmpeg.py b/tests/test_integration_ffmpeg.py
new file mode 100644
index 0000000..d982d67
--- /dev/null
+++ b/tests/test_integration_ffmpeg.py
@@ -0,0 +1,183 @@
+"""Integration tests that run the real ffmpeg/ffprobe pipeline on tiny generated clips.
+
+Skipped automatically when ffmpeg/ffprobe are not installed.
+"""
+
+import json
+
+import pytest
+
+from conftest import generate_video, requires_ffmpeg
+from mediacrush.core.content_classifier import ContentClassifier, ContentType
+from mediacrush.core.deduplicator import DuplicateDetector
+from mediacrush.core.hardware import EncoderInfo, HardwareDetector
+from mediacrush.core.probe import MediaProbe
+from mediacrush.core.safety import SafetyManager
+from mediacrush.core.scanner import LibraryScanner
+from mediacrush.core.transcoder import TranscodeEngine
+
+pytestmark = requires_ffmpeg
+
+X264 = EncoderInfo("h264", "libx264", "CPU", None, "x264")
+
+
+def cpu_hevc():
+    """A CPU encoder that actually works on this machine (libx265 may be absent)."""
+    for c in HardwareDetector.PROBE_CANDIDATES:
+        if c.vendor == "CPU" and c.codec == "hevc" and HardwareDetector.test_encoder(c):
+            return c
+    return None
+
+
+@pytest.fixture(scope="module")
+def src_dir(tmp_path_factory):
+    d = tmp_path_factory.mktemp("media")
+    generate_video(d / "clip.mp4", seconds=12, size="640x360")
+    return d
+
+
+@pytest.fixture
+def clip(tmp_path, src_dir):
+    dst = tmp_path / "clip.mp4"
+    dst.write_bytes((src_dir / "clip.mp4").read_bytes())
+    return dst
+
+
+class TestProbeReal:
+    def test_reads_real_metadata(self, clip):
+        m = MediaProbe.inspect(clip)
+        assert m is not None
+        assert m.video_codec == "h264" and (m.width, m.height) == (640, 360)
+        assert m.duration_seconds == pytest.approx(12, abs=0.5)
+        assert m.fps == pytest.approx(24, abs=0.1)
+        assert len(m.audio_streams) == 1 and m.audio_streams[0].codec_name == "aac"
+        assert m.hdr_format is None and m.file_size_bytes == clip.stat().st_size
+
+    def test_corrupt_file_returns_none(self, tmp_path):
+        bad = tmp_path / "bad.mkv"
+        bad.write_bytes(b"this is not a video" * 100)
+        assert MediaProbe.inspect(bad) is None
+
+    def test_silent_video_has_no_audio(self, tmp_path):
+        v = generate_video(tmp_path / "silent.mp4", seconds=2, audio=False)
+        assert MediaProbe.inspect(v).audio_streams == []
+
+
+class TestHardwareReal:
+    def test_cpu_encoder_discoverable(self):
+        names = {e.encoder_name for e in HardwareDetector.discover_encoders()}
+        assert names & {"libx264", "libx265", "libsvtav1"}
+
+    def test_best_encoder_is_functional(self):
+        best = HardwareDetector.get_best_encoder()
+        if best.description != "CPU Fallback":
+            assert HardwareDetector.test_encoder(best)
+
+
+class TestClassifierReal:
+    def test_flat_animation_like_clip_detected_as_anime(self, tmp_path):
+        v = generate_video(tmp_path / "flat.mp4", seconds=12, pattern="color=c=blue", extra=[])
+        assert ContentClassifier.detect(v) == ContentType.ANIME
+
+    def test_noisy_clip_is_live_action(self, tmp_path):
+        v = tmp_path / "noise.mp4"
+        import subprocess
+        subprocess.run(["ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "color=c=gray:s=320x180:r=24:d=6,noise=alls=100:allf=t+u",
+                        "-c:v", "libx264", "-qp", "0", "-pix_fmt", "yuv444p", str(v)], check=True, timeout=60)
+        assert ContentClassifier.detect(v) in (ContentType.LIVE_ACTION, ContentType.UNKNOWN)  # both map to 'film'
+
+
+class TestScannerReal:
+    def test_small_clip_skipped_as_under_40mb(self, src_dir):
+        r = LibraryScanner.scan_path(src_dir)
+        assert r.candidates == [] and r.skipped_count == 1
+
+
+class TestDedupeReal:
+    def test_identical_clips_detected(self, tmp_path, src_dir):
+        data = (src_dir / "clip.mp4").read_bytes()
+        (tmp_path / "a.mp4").write_bytes(data)
+        (tmp_path / "b.mp4").write_bytes(data)
+        groups = DuplicateDetector.find(tmp_path)
+        assert len(groups) == 1 and len(groups[0].files) == 2
+        assert groups[0].removable_size_bytes == len(data)
+
+
+class TestTranscodeEndToEnd:
+    """Full pipeline: probe -> preset args -> ffmpeg -> verify -> finalize."""
+
+    @pytest.fixture(autouse=True)
+    def _relax_min_size(self, monkeypatch):
+        # Tiny generated clips are far below the production 1 MB sanity floor, so swap in a
+        # verifier that keeps the duration/audio/readability checks but drops the size floor.
+        monkeypatch.setattr(SafetyManager, "verify_transcode",
+                            classmethod(lambda cls, meta, staging: self._verify_ignoring_size(meta, staging)))
+
+    @staticmethod
+    def _verify_ignoring_size(source_meta, staging):
+        out = MediaProbe.inspect(staging)
+        if not out:
+            return False, "unreadable"
+        if abs(source_meta.duration_seconds - out.duration_seconds) > 1.5:
+            return False, "duration"
+        if source_meta.audio_streams and not out.audio_streams:
+            return False, "audio"
+        return True, "ok"
+
+    def test_in_place_transcode(self, clip):
+        meta = MediaProbe.inspect(clip)
+        progress = []
+        ok = TranscodeEngine().transcode(meta, X264, "film", in_place=True, progress_callback=progress.append)
+        assert ok is True
+        assert clip.exists() and not SafetyManager.get_staging_path(clip).exists()
+        out = MediaProbe.inspect(clip)
+        assert out.duration_seconds == pytest.approx(meta.duration_seconds, abs=1.5)
+        assert len(out.audio_streams) == 1
+        if progress:
+            assert progress[-1].percent <= 100.0
+
+    def test_side_by_side_keeps_original(self, clip):
+        original = clip.read_bytes()
+        meta = MediaProbe.inspect(clip)
+        assert TranscodeEngine().transcode(meta, X264, "saver", in_place=False) is True
+        assert clip.read_bytes() == original
+        assert (clip.parent / "clip.crushed.mkv").exists()
+
+    def test_keep_backup(self, clip):
+        original = clip.read_bytes()
+        meta = MediaProbe.inspect(clip)
+        assert TranscodeEngine().transcode(meta, X264, "film", in_place=True, keep_backup=True) is True
+        assert (clip.parent / "clip.mp4.bak").read_bytes() == original
+
+    def test_bad_encoder_fails_and_preserves_source(self, clip):
+        original = clip.read_bytes()
+        meta = MediaProbe.inspect(clip)
+        bogus = EncoderInfo("hevc", "no_such_encoder", "X", None, "")
+        assert TranscodeEngine().transcode(meta, bogus, "film") is False
+        assert clip.read_bytes() == original
+        assert not SafetyManager.get_staging_path(clip).exists()
+
+    def test_hevc_cpu_when_available(self, clip):
+        enc = cpu_hevc()
+        if enc is None:
+            pytest.skip("no working CPU HEVC encoder")
+        meta = MediaProbe.inspect(clip)
+        assert TranscodeEngine().transcode(meta, enc, "anime", in_place=False) is True
+        assert MediaProbe.inspect(clip.parent / "clip.crushed.mkv").video_codec in {"hevc", "av1"}
+
+
+class TestCliEndToEnd:
+    def test_scan_command_on_real_dir(self, src_dir, capsys, monkeypatch):
+        import argparse
+        from rich.console import Console
+        from mediacrush.cli import commands, formatters
+        c = Console(record=True, width=200)
+        monkeypatch.setattr(commands, "console", c)
+        monkeypatch.setattr(formatters, "console", c)
+        commands.cmd_scan(argparse.Namespace(path=str(src_dir)))
+        assert "Skipped 1" in c.export_text()
+
+    def test_main_entry_scan(self, src_dir, monkeypatch):
+        from mediacrush.cli import main as m
+        monkeypatch.setattr("sys.argv", ["mediacrush", "scan", str(src_dir)])
+        m.main()  # must not raise
diff --git a/tests/test_presets_args.py b/tests/test_presets_args.py
new file mode 100644
index 0000000..97ad254
--- /dev/null
+++ b/tests/test_presets_args.py
@@ -0,0 +1,113 @@
+"""Unit tests for PresetManager.build_ffmpeg_args per encoder / preset / HDR."""
+
+import pytest
+
+from conftest import make_meta
+from mediacrush.core.hardware import EncoderInfo
+from mediacrush.core.presets import PresetManager
+
+
+def enc(name, vendor="X", hw=None):
+    return EncoderInfo("hevc", name, vendor, hw, name)
+
+
+def val(args, flag):
+    return args[args.index(flag) + 1]
+
+
+class TestCommonArgs:
+    @pytest.mark.parametrize("name", [
+        "hevc_nvenc", "hevc_amf", "hevc_qsv", "hevc_mf", "hevc_videotoolbox",
+        "h264_videotoolbox", "hevc_vaapi", "libx265", "libsvtav1",
+    ])
+    def test_every_encoder_maps_streams_and_copies_audio_subs(self, name):
+        args = PresetManager.build_ffmpeg_args(enc(name), "film")
+        assert args[:2] == ["-map", "0"]
+        assert val(args, "-c:v") == name
+        assert val(args, "-c:a") == "copy"
+        assert val(args, "-c:s") == "copy"
+        assert val(args, "-map_metadata") == "0"
+
+    def test_unknown_preset_falls_back_to_anime(self):
+        a = PresetManager.build_ffmpeg_args(enc("libx265"), "bogus")
+        b = PresetManager.build_ffmpeg_args(enc("libx265"), "anime")
+        assert a == b
+
+    def test_all_args_are_strings(self):
+        for name in ("hevc_nvenc", "libx265", "hevc_videotoolbox"):
+            assert all(isinstance(x, str) for x in PresetManager.build_ffmpeg_args(enc(name), "saver"))
+
+    def test_saver_is_more_aggressive_than_film(self):
+        assert PresetManager.PRESETS["saver"].cpu_crf > PresetManager.PRESETS["film"].cpu_crf
+        assert PresetManager.PRESETS["saver"].nvenc_cq > PresetManager.PRESETS["film"].nvenc_cq
+
+
+class TestEncoderSpecific:
+    def test_nvenc_uses_cq_and_vbr(self):
+        a = PresetManager.build_ffmpeg_args(enc("hevc_nvenc"), "saver")
+        assert val(a, "-cq") == "24" and val(a, "-rc") == "vbr" and val(a, "-b:v") == "0"
+
+    def test_amf_uses_cqp(self):
+        a = PresetManager.build_ffmpeg_args(enc("hevc_amf"), "film")
+        assert val(a, "-rc") == "cqp" and val(a, "-qp_i") == "20"
+
+    def test_qsv_global_quality(self):
+        assert val(PresetManager.build_ffmpeg_args(enc("hevc_qsv"), "anime"), "-global_quality") == "20"
+
+    def test_vaapi_includes_device_and_hwupload(self):
+        a = PresetManager.build_ffmpeg_args(enc("hevc_vaapi"), "anime")
+        assert "-vaapi_device" in a and "hwupload" in val(a, "-vf")
+
+    @pytest.mark.parametrize("preset,q", [("anime", "70"), ("film", "65"), ("saver", "55")])
+    def test_videotoolbox_quality_per_preset(self, preset, q):
+        a = PresetManager.build_ffmpeg_args(enc("hevc_videotoolbox"), preset)
+        assert val(a, "-q:v") == q and val(a, "-tag:v") == "hvc1"
+
+    def test_h264_videotoolbox_has_no_hvc1_tag(self):
+        a = PresetManager.build_ffmpeg_args(enc("h264_videotoolbox"), "film")
+        assert "-tag:v" not in a
+
+    def test_x265_animation_tune_only_for_anime(self):
+        assert "-tune" in PresetManager.build_ffmpeg_args(enc("libx265"), "anime")
+        assert "-tune" not in PresetManager.build_ffmpeg_args(enc("libx265"), "film")
+        assert val(PresetManager.build_ffmpeg_args(enc("libx265"), "film"), "-crf") == "20"
+
+    def test_svtav1_crf_offset(self):
+        a = PresetManager.build_ffmpeg_args(enc("libsvtav1"), "film")
+        assert val(a, "-crf") == "22"
+
+    def test_unrecognized_encoder_still_valid(self):
+        a = PresetManager.build_ffmpeg_args(enc("mystery"), "film")
+        assert val(a, "-c:v") == "mystery"
+
+
+class TestHdr:
+    def test_hdr_flags_added(self):
+        m = make_meta(hdr="HDR10", primaries="bt2020", transfer="smpte2084")
+        a = PresetManager.build_ffmpeg_args(enc("hevc_nvenc"), "film", meta=m)
+        assert val(a, "-color_primaries") == "bt2020"
+        assert val(a, "-color_trc") == "smpte2084"
+        assert val(a, "-colorspace") == "bt2020nc"
+        assert "-x265-params" not in a
+
+    def test_x265_hdr_params(self):
+        m = make_meta(hdr="HDR10", primaries="bt2020", transfer="smpte2084")
+        a = PresetManager.build_ffmpeg_args(enc("libx265"), "film", meta=m)
+        assert "hdr-opt=1" in val(a, "-x265-params")
+
+    def test_sdr_no_hdr_flags(self):
+        a = PresetManager.build_ffmpeg_args(enc("libx265"), "film", meta=make_meta())
+        assert "-color_primaries" not in a
+
+    def test_videotoolbox_main10_for_hdr(self):
+        m = make_meta(hdr="HDR10", primaries="bt2020", transfer="smpte2084")
+        a = PresetManager.build_ffmpeg_args(enc("hevc_videotoolbox"), "film", meta=m)
+        assert val(a, "-profile:v") == "main10"
+
+    def test_videotoolbox_main10_for_anime_even_sdr(self):
+        a = PresetManager.build_ffmpeg_args(enc("hevc_videotoolbox"), "anime", meta=make_meta())
+        assert val(a, "-pix_fmt") == "p010le"
+
+    def test_videotoolbox_film_sdr_stays_8bit(self):
+        a = PresetManager.build_ffmpeg_args(enc("hevc_videotoolbox"), "film", meta=make_meta())
+        assert "-pix_fmt" not in a
diff --git a/tests/test_probe_parsing.py b/tests/test_probe_parsing.py
new file mode 100644
index 0000000..5c8654a
--- /dev/null
+++ b/tests/test_probe_parsing.py
@@ -0,0 +1,141 @@
+"""Unit tests for MediaProbe ffprobe JSON parsing (subprocess mocked)."""
+
+import json
+import subprocess
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from mediacrush.core.probe import MediaMetadata, MediaProbe
+
+
+def _probe(tmp_path, payload=None, side_effect=None):
+    f = tmp_path / "a.mkv"
+    f.write_bytes(b"x" * 100)
+    with patch("mediacrush.core.probe.subprocess.run") as run:
+        if side_effect is not None:
+            run.side_effect = side_effect
+        else:
+            run.return_value = MagicMock(stdout=json.dumps(payload))
+        return MediaProbe.inspect(f), run
+
+
+BASE = {
+    "format": {"duration": "100.5", "size": "5000", "bit_rate": "400000"},
+    "streams": [
+        {"index": 0, "codec_type": "video", "codec_name": "h264", "width": 1920, "height": 1080,
+         "r_frame_rate": "24000/1001", "bit_rate": "350000"},
+        {"index": 1, "codec_type": "audio", "codec_name": "aac", "channels": 6, "tags": {"language": "jpn", "title": "Main"}},
+        {"index": 2, "codec_type": "subtitle", "codec_name": "ass", "tags": {"language": "eng"}},
+    ],
+}
+
+
+class TestResolutionLabel:
+    @pytest.mark.parametrize("w,h,label", [
+        (3840, 2160, "4K"), (3840, 1600, "4K"), (1920, 1080, "1080p"), (1920, 800, "1080p"),
+        (1280, 720, "720p"), (1280, 534, "720p"), (640, 480, "640x480"), (0, 0, "0x0"),
+    ])
+    def test_labels(self, w, h, label):
+        m = MediaMetadata(Path("x"), 1, 1, "h264", w, h, 24, 0, 0)
+        assert m.resolution_label == label
+
+
+class TestInspectParsing:
+    def test_full_parse(self, tmp_path):
+        meta, run = _probe(tmp_path, BASE)
+        assert meta.duration_seconds == 100.5
+        assert meta.file_size_bytes == 5000
+        assert meta.overall_bitrate == 400000
+        assert (meta.video_codec, meta.width, meta.height) == ("h264", 1920, 1080)
+        assert meta.video_bitrate == 350000
+        assert meta.fps == pytest.approx(23.976, abs=1e-3)
+        assert len(meta.audio_streams) == 1 and meta.audio_streams[0].channels == 6
+        assert meta.audio_streams[0].language == "jpn" and meta.audio_streams[0].title == "Main"
+        assert len(meta.subtitle_streams) == 1 and meta.subtitle_streams[0].codec_name == "ass"
+        assert meta.hdr_format is None
+
+    def test_missing_file_returns_none(self, tmp_path):
+        assert MediaProbe.inspect(tmp_path / "nope.mkv") is None
+
+    def test_empty_file_returns_none(self, tmp_path):
+        f = tmp_path / "empty.mkv"
+        f.touch()
+        assert MediaProbe.inspect(f) is None
+
+    def test_ffprobe_failure_returns_none(self, tmp_path):
+        meta, _ = _probe(tmp_path, side_effect=subprocess.CalledProcessError(1, "ffprobe"))
+        assert meta is None
+
+    def test_ffprobe_missing_binary_returns_none(self, tmp_path):
+        meta, _ = _probe(tmp_path, side_effect=FileNotFoundError())
+        assert meta is None
+
+    def test_ffprobe_timeout_returns_none(self, tmp_path):
+        meta, _ = _probe(tmp_path, side_effect=subprocess.TimeoutExpired("ffprobe", 15))
+        assert meta is None
+
+    def test_invalid_json_returns_none(self, tmp_path):
+        f = tmp_path / "a.mkv"
+        f.write_bytes(b"x")
+        with patch("mediacrush.core.probe.subprocess.run", return_value=MagicMock(stdout="not json")):
+            assert MediaProbe.inspect(f) is None
+
+    def test_no_video_stream_defaults(self, tmp_path):
+        meta, _ = _probe(tmp_path, {"format": {"duration": "5"}, "streams": []})
+        assert meta.video_codec == "unknown"
+        assert meta.width == 0 and meta.height == 0
+        assert meta.fps == 24.0
+
+    def test_size_falls_back_to_stat(self, tmp_path):
+        meta, _ = _probe(tmp_path, {"format": {"duration": "5"}, "streams": []})
+        assert meta.file_size_bytes == 100
+
+    @pytest.mark.parametrize("rate,expected", [("30/1", 30.0), ("0/0", 24.0), ("garbage", 24.0), ("60000/1001", 59.94)])
+    def test_fps_parsing(self, tmp_path, rate, expected):
+        payload = {"format": {}, "streams": [{"index": 0, "codec_type": "video", "r_frame_rate": rate}]}
+        meta, _ = _probe(tmp_path, payload)
+        assert meta.fps == pytest.approx(expected, abs=0.01)
+
+    def test_bitrate_from_tags_bps(self, tmp_path):
+        payload = {"format": {}, "streams": [{"index": 0, "codec_type": "video", "tags": {"BPS": "1234567"}}]}
+        meta, _ = _probe(tmp_path, payload)
+        assert meta.video_bitrate == 1234567
+
+    def test_non_numeric_bitrate_is_zero(self, tmp_path):
+        payload = {"format": {}, "streams": [{"index": 0, "codec_type": "video", "bit_rate": "N/A"}]}
+        meta, _ = _probe(tmp_path, payload)
+        assert meta.video_bitrate == 0
+
+
+class TestHdrDetection:
+    def _video(self, **kw):
+        s = {"index": 0, "codec_type": "video", "codec_name": "hevc", "width": 3840, "height": 2160}
+        s.update(kw)
+        return {"format": {"duration": "1"}, "streams": [s]}
+
+    def test_hdr10_from_color_tags(self, tmp_path):
+        meta, _ = _probe(tmp_path, self._video(color_primaries="bt2020", color_trc="smpte2084"))
+        assert meta.hdr_format == "HDR10"
+        assert meta.color_primaries == "bt2020"
+
+    def test_hlg_detected_as_hdr10(self, tmp_path):
+        meta, _ = _probe(tmp_path, self._video(color_primaries="bt2020", color_trc="arib-std-b67"))
+        assert meta.hdr_format == "HDR10"
+
+    def test_dolby_vision(self, tmp_path):
+        meta, _ = _probe(tmp_path, self._video(side_data_list=[{"side_data_type": "DOVI configuration record"}]))
+        assert meta.hdr_format == "DolbyVision"
+
+    def test_hdr10_plus(self, tmp_path):
+        meta, _ = _probe(tmp_path, self._video(side_data_list=[{"side_data_type": "HDR Dynamic Metadata SMPTE2094-40 (HDR10+)"}]))
+        assert meta.hdr_format == "HDR10+"
+
+    def test_sdr_bt709(self, tmp_path):
+        meta, _ = _probe(tmp_path, self._video(color_primaries="bt709", color_trc="bt709"))
+        assert meta.hdr_format is None
+
+    def test_bt2020_sdr_transfer_not_hdr(self, tmp_path):
+        meta, _ = _probe(tmp_path, self._video(color_primaries="bt2020", color_trc="bt709"))
+        assert meta.hdr_format is None
diff --git a/tests/test_quality_mocked.py b/tests/test_quality_mocked.py
new file mode 100644
index 0000000..be9113b
--- /dev/null
+++ b/tests/test_quality_mocked.py
@@ -0,0 +1,85 @@
+"""Unit tests for QualityChecker verdicts and log parsing (ffmpeg mocked)."""
+
+import json
+from unittest.mock import patch
+
+import pytest
+
+from mediacrush.core.quality import QualityChecker, QualityScore
+
+
+@pytest.mark.parametrize("vmaf,verdict", [
+    (100, "Excellent"), (92.0, "Excellent"), (91.99, "Good"), (80.0, "Good"),
+    (79.9, "Acceptable"), (65.0, "Acceptable"), (64.9, "Poor"), (0, "Poor"),
+])
+def test_verdict_boundaries(vmaf, verdict):
+    assert QualityChecker._calculate_verdict(vmaf) == verdict
+
+
+class TestScore:
+    def test_missing_inputs(self, tmp_path):
+        f = tmp_path / "a.mkv"
+        f.write_bytes(b"x")
+        assert QualityChecker.score(f, tmp_path / "none.mkv") is None
+        assert QualityChecker.score(tmp_path / "none.mkv", f) is None
+
+    def test_combines_vmaf_ssim(self, tmp_path):
+        f = tmp_path / "a.mkv"
+        f.write_bytes(b"x")
+        with patch.object(QualityChecker, "_run_vmaf", return_value=93.456), \
+             patch.object(QualityChecker, "_run_ssim", return_value=0.98765):
+            s = QualityChecker.score(f, f)
+        assert s == QualityScore(93.46, 0.9877, "Excellent")
+
+    def test_vmaf_failure_returns_none(self, tmp_path):
+        f = tmp_path / "a.mkv"
+        f.write_bytes(b"x")
+        with patch.object(QualityChecker, "_run_vmaf", return_value=None):
+            assert QualityChecker.score(f, f) is None
+
+    def test_ssim_failure_uses_default(self, tmp_path):
+        f = tmp_path / "a.mkv"
+        f.write_bytes(b"x")
+        with patch.object(QualityChecker, "_run_vmaf", return_value=70.0), \
+             patch.object(QualityChecker, "_run_ssim", return_value=None):
+            assert QualityChecker.score(f, f).ssim == 0.95
+
+
+class TestLogParsing:
+    def test_vmaf_json(self, tmp_path):
+        log = tmp_path / "v.json"
+        log.write_text(json.dumps({"pooled_metrics": {"vmaf": {"mean": 88.5}}}))
+        with patch("mediacrush.core.quality.subprocess.run"):
+            assert QualityChecker._run_vmaf(tmp_path / "s", tmp_path / "e", log) == 88.5
+
+    def test_vmaf_no_log(self, tmp_path):
+        with patch("mediacrush.core.quality.subprocess.run"):
+            assert QualityChecker._run_vmaf(tmp_path / "s", tmp_path / "e", tmp_path / "none.json") is None
+
+    def test_vmaf_corrupt_log(self, tmp_path):
+        log = tmp_path / "v.json"
+        log.write_text("{{")
+        with patch("mediacrush.core.quality.subprocess.run"):
+            assert QualityChecker._run_vmaf(tmp_path / "s", tmp_path / "e", log) is None
+
+    def test_vmaf_ffmpeg_missing(self, tmp_path):
+        with patch("mediacrush.core.quality.subprocess.run", side_effect=FileNotFoundError):
+            assert QualityChecker._run_vmaf(tmp_path / "s", tmp_path / "e", tmp_path / "l") is None
+
+    def test_ssim_average(self, tmp_path):
+        log = tmp_path / "s.txt"
+        log.write_text("n:1 Y:1 U:1 V:1 All:0.90 (10)\nn:2 Y:1 U:1 V:1 All:1.00 (20)\n")
+        with patch("mediacrush.core.quality.subprocess.run"):
+            assert QualityChecker._run_ssim(tmp_path / "s", tmp_path / "e", log) == pytest.approx(0.95)
+
+    def test_ssim_empty_log(self, tmp_path):
+        log = tmp_path / "s.txt"
+        log.write_text("")
+        with patch("mediacrush.core.quality.subprocess.run"):
+            assert QualityChecker._run_ssim(tmp_path / "s", tmp_path / "e", log) is None
+
+    def test_windows_paths_normalized_in_filter(self, tmp_path):
+        with patch("mediacrush.core.quality.subprocess.run") as run:
+            QualityChecker._run_vmaf(tmp_path / "s", tmp_path / "e", tmp_path / "v.json")
+        filt = run.call_args[0][0][run.call_args[0][0].index("-lavfi") + 1]
+        assert "\\" not in filt
diff --git a/tests/test_queue_extra.py b/tests/test_queue_extra.py
new file mode 100644
index 0000000..c849cfb
--- /dev/null
+++ b/tests/test_queue_extra.py
@@ -0,0 +1,77 @@
+"""Additional JobQueue tests: persistence across instances and corrupt-file recovery."""
+
+import json
+
+import pytest
+
+from mediacrush.core.queue import JobQueue, QueueEntry
+
+
+def e(path, status="pending"):
+    return QueueEntry(path, "anime", True, status)
+
+
+@pytest.fixture
+def qfile(tmp_path):
+    return tmp_path / "nested" / "queue.json"
+
+
+def test_missing_file_loads_empty(qfile):
+    assert JobQueue(qfile).load() == []
+
+
+def test_push_creates_parent_dirs(qfile):
+    JobQueue(qfile).push(e("/a"))
+    assert qfile.exists()
+
+
+def test_persists_across_instances(qfile):
+    JobQueue(qfile).push(e("/a"))
+    q2 = JobQueue(qfile)
+    assert [x.path for x in q2.load()] == ["/a"]
+
+
+def test_corrupt_json_recovers_empty(qfile):
+    qfile.parent.mkdir(parents=True)
+    qfile.write_text("{{{")
+    assert JobQueue(qfile).load() == []
+
+
+def test_unexpected_schema_recovers_empty(qfile):
+    qfile.parent.mkdir(parents=True)
+    qfile.write_text(json.dumps([{"unknown": 1}]))
+    assert JobQueue(qfile).load() == []
+
+
+def test_status_transitions_persist(qfile):
+    q = JobQueue(qfile)
+    for p in ("/a", "/b", "/c"):
+        q.push(e(p))
+    q.mark_done("/a")
+    q.mark_failed("/b")
+    q2 = JobQueue(qfile)
+    q2.load()
+    assert [x.path for x in q2.pending()] == ["/c"]
+    assert {x.path: x.status for x in q2.load()} == {"/a": "done", "/b": "failed", "/c": "pending"}
+
+
+def test_mark_unknown_path_is_noop(qfile):
+    q = JobQueue(qfile)
+    q.push(e("/a"))
+    q.mark_done("/zzz")
+    assert q.pending()[0].path == "/a"
+
+
+def test_clear_done_keeps_failed_and_pending(qfile):
+    q = JobQueue(qfile)
+    q.push(e("/a", "done"))
+    q.push(e("/b", "failed"))
+    q.push(e("/c"))
+    q.clear_done()
+    q2 = JobQueue(qfile)
+    assert sorted(x.path for x in q2.load()) == ["/b", "/c"]
+
+
+def test_default_queue_file_under_home():
+    from mediacrush.core import queue as qm
+    assert qm._QUEUE_FILE.name == "queue.json" and qm._QUEUE_FILE.parent.name == ".mediacrush"
diff --git a/tests/test_reporter_extra.py b/tests/test_reporter_extra.py
new file mode 100644
index 0000000..28b47d9
--- /dev/null
+++ b/tests/test_reporter_extra.py
@@ -0,0 +1,56 @@
+"""Additional reporter tests: JSON round-trip, HTML structure, formatting, known defects."""
+
+import json
+
+import pytest
+
+from mediacrush.core.reporter import CompressionReporter, ReportEntry
+
+
+def filled():
+    r = CompressionReporter()
+    r.add_result("a.mkv", 1000, 400, "libx265", 12.34, True)
+    r.add_result("b.mkv", 2000, 2000, "libx265", 1.0, False)
+    return r
+
+
+class TestEntry:
+    @pytest.mark.parametrize("o,f,pct", [(1000, 400, 60.0), (1000, 1000, 0.0), (1000, 1500, 0.0), (0, 0, 0.0)])
+    def test_savings_pct(self, o, f, pct):
+        assert ReportEntry("x", o, f, "e", 1, True).savings_pct == pytest.approx(pct)
+
+
+class TestOutputs:
+    def test_json_round_trip(self, tmp_path):
+        p = tmp_path / "r.json"
+        filled().write_json(p)
+        data = json.loads(p.read_text())
+        assert [d["file"] for d in data] == ["a.mkv", "b.mkv"]
+        assert data[0]["success"] is True and data[1]["success"] is False
+
+    def test_html_contains_rows_and_totals(self, tmp_path):
+        p = tmp_path / "r.html"
+        filled().write_html(p)
+        html = p.read_text(encoding="utf-8")
+        assert html.startswith("<!DOCTYPE html>") and "a.mkv" in html and "b.mkv" in html
+        assert "✓" in html and "✗" in html
+        assert "Total saved" in html and "20.0%" in html
+
+    def test_empty_report_no_division_error(self, tmp_path):
+        p = tmp_path / "e.html"
+        CompressionReporter().write_html(p)
+        assert "0.0%" in p.read_text(encoding="utf-8")
+
+    @pytest.mark.parametrize("b,expected", [(0, "0.0 B"), (1023, "1023.0 B"), (1024, "1.0 KB"), (1024**2, "1.0 MB"), (1024**3, "1.0 GB")])
+    def test_fmt_exact_units(self, b, expected):
+        assert CompressionReporter._fmt(b) == expected
+
+    def test_fmt_keeps_fraction(self):
+        assert CompressionReporter._fmt(1536) == "1.5 KB"
+
+    def test_html_escapes_filenames(self, tmp_path):
+        r = CompressionReporter()
+        r.add_result("<script>alert(1)</script>.mkv", 10, 5, "e", 1, True)
+        p = tmp_path / "x.html"
+        r.write_html(p)
+        assert "<script>alert(1)" not in p.read_text(encoding="utf-8")
diff --git a/tests/test_safety_finalize.py b/tests/test_safety_finalize.py
new file mode 100644
index 0000000..49b797e
--- /dev/null
+++ b/tests/test_safety_finalize.py
@@ -0,0 +1,94 @@
+"""Unit tests for SafetyManager verify/finalize/cleanup using real temp files."""
+
+from unittest.mock import patch
+
+import pytest
+
+from conftest import make_meta
+from mediacrush.core.safety import SafetyManager
+
+
+@pytest.fixture
+def files(tmp_path):
+    src = tmp_path / "movie.mkv"
+    stg = SafetyManager.get_staging_path(src)
+    src.write_bytes(b"ORIGINAL")
+    stg.write_bytes(b"NEW")
+    return src, stg
+
+
+class TestFinalize:
+    def test_in_place_replaces_source(self, files):
+        src, stg = files
+        out = SafetyManager.finalize_transcode(src, stg, in_place=True)
+        assert out == src and src.read_bytes() == b"NEW" and not stg.exists()
+
+    def test_in_place_keep_backup(self, files):
+        src, stg = files
+        SafetyManager.finalize_transcode(src, stg, in_place=True, keep_backup=True)
+        bak = src.with_name("movie.mkv.bak")
+        assert bak.read_bytes() == b"ORIGINAL" and src.read_bytes() == b"NEW"
+
+    def test_side_by_side_preserves_original(self, files):
+        src, stg = files
+        out = SafetyManager.finalize_transcode(src, stg, in_place=False)
+        assert out.name == "movie.crushed.mkv"
+        assert src.read_bytes() == b"ORIGINAL" and out.read_bytes() == b"NEW"
+
+    def test_side_by_side_overwrites_stale_output(self, files):
+        src, stg = files
+        stale = src.with_name("movie.crushed.mkv")
+        stale.write_bytes(b"STALE")
+        SafetyManager.finalize_transcode(src, stg, in_place=False)
+        assert stale.read_bytes() == b"NEW"
+
+
+class TestCleanup:
+    def test_removes_existing(self, files):
+        _, stg = files
+        SafetyManager.cleanup_staging(stg)
+        assert not stg.exists()
+
+    def test_swallows_unlink_errors(self, files):
+        _, stg = files
+        with patch("pathlib.Path.unlink", side_effect=PermissionError):
+            SafetyManager.cleanup_staging(stg)  # must not raise
+
+
+class TestVerify:
+    def _stage(self, tmp_path, size=2_000_000):
+        s = tmp_path / "s.mkv"
+        s.write_bytes(b"\0" * size)
+        return s
+
+    def test_too_small(self, tmp_path):
+        ok, msg = SafetyManager.verify_transcode(make_meta(), self._stage(tmp_path, 10))
+        assert not ok and "small" in msg
+
+    def test_unreadable_output(self, tmp_path):
+        with patch("mediacrush.core.safety.MediaProbe.inspect", return_value=None):
+            ok, msg = SafetyManager.verify_transcode(make_meta(), self._stage(tmp_path))
+        assert not ok and "corruption" in msg
+
+    def test_duration_mismatch(self, tmp_path):
+        out = make_meta(duration=1000.0)
+        with patch("mediacrush.core.safety.MediaProbe.inspect", return_value=out):
+            ok, msg = SafetyManager.verify_transcode(make_meta(duration=1400.0), self._stage(tmp_path))
+        assert not ok and "Duration" in msg
+
+    def test_duration_within_tolerance(self, tmp_path):
+        out = make_meta(duration=1401.4)
+        with patch("mediacrush.core.safety.MediaProbe.inspect", return_value=out):
+            ok, _ = SafetyManager.verify_transcode(make_meta(duration=1400.0), self._stage(tmp_path))
+        assert ok
+
+    def test_audio_lost(self, tmp_path):
+        out = make_meta(audio=0)
+        with patch("mediacrush.core.safety.MediaProbe.inspect", return_value=out):
+            ok, msg = SafetyManager.verify_transcode(make_meta(audio=1), self._stage(tmp_path))
+        assert not ok and "Audio" in msg
+
+    def test_silent_source_without_audio_ok(self, tmp_path):
+        with patch("mediacrush.core.safety.MediaProbe.inspect", return_value=make_meta(audio=0)):
+            ok, _ = SafetyManager.verify_transcode(make_meta(audio=0), self._stage(tmp_path))
+        assert ok
diff --git a/tests/test_scanner_scan.py b/tests/test_scanner_scan.py
new file mode 100644
index 0000000..1659d09
--- /dev/null
+++ b/tests/test_scanner_scan.py
@@ -0,0 +1,143 @@
+"""Unit tests for LibraryScanner.scan_path, folder configs, and estimate bounds."""
+
+import json
+from unittest.mock import patch
+
+import pytest
+
+from conftest import make_meta
+from mediacrush.core.scanner import CandidateFile, LibraryScanner, ScanReport
+
+
+def scan(tmp_path, mapping):
+    """mapping: relative filename -> MediaMetadata|None. Creates files and mocks probe."""
+    for rel in mapping:
+        p = tmp_path / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(b"x")
+    with patch("mediacrush.core.scanner.MediaProbe.inspect", side_effect=lambda p: mapping.get(str(p.relative_to(tmp_path)))):
+        return LibraryScanner.scan_path(tmp_path)
+
+
+class TestScanPath:
+    def test_empty_dir(self, tmp_path):
+        r = scan(tmp_path, {})
+        assert r.candidates == [] and r.skipped_count == 0 and r.total_savings_bytes == 0
+
+    def test_nonexistent(self, tmp_path):
+        r = LibraryScanner.scan_path(tmp_path / "nope")
+        assert r.candidates == []
+
+    def test_candidate_and_skip_counts(self, tmp_path):
+        big = make_meta(codec="h264", size_mb=1000, video_bitrate=9_000_000)
+        small = make_meta(codec="h264", size_mb=10)
+        r = scan(tmp_path, {"big.mkv": big, "small.mkv": small})
+        assert len(r.candidates) == 1 and r.skipped_count == 1
+        assert r.total_current_bytes == big.file_size_bytes
+        assert 0 < r.total_estimated_bytes < r.total_current_bytes
+
+    def test_unprobeable_not_counted_as_skipped(self, tmp_path):
+        r = scan(tmp_path, {"bad.mkv": None})
+        assert r.candidates == [] and r.skipped_count == 0
+
+    def test_ignores_unsupported_extensions(self, tmp_path):
+        (tmp_path / "a.txt").write_text("x")
+        (tmp_path / "b.jpg").write_bytes(b"x")
+        with patch("mediacrush.core.scanner.MediaProbe.inspect") as probe:
+            LibraryScanner.scan_path(tmp_path)
+        probe.assert_not_called()
+
+    def test_extension_case_insensitive(self, tmp_path):
+        r = scan(tmp_path, {"A.MKV": make_meta(size_mb=900)})
+        assert len(r.candidates) == 1
+
+    def test_recursive(self, tmp_path):
+        r = scan(tmp_path, {"a/b/c/deep.mp4": make_meta(size_mb=900)})
+        assert len(r.candidates) == 1
+
+    def test_single_file_target(self, tmp_path):
+        f = tmp_path / "one.mkv"
+        f.write_bytes(b"x")
+        with patch("mediacrush.core.scanner.MediaProbe.inspect", return_value=make_meta(size_mb=900)):
+            r = LibraryScanner.scan_path(f)
+        assert len(r.candidates) == 1
+
+    def test_single_unsupported_file(self, tmp_path):
+        f = tmp_path / "one.txt"
+        f.write_text("x")
+        assert LibraryScanner.scan_path(f).candidates == []
+
+
+class TestFolderConfig:
+    def test_missing_config(self, tmp_path):
+        assert LibraryScanner.load_folder_config(tmp_path) == {}
+
+    def test_valid_config(self, tmp_path):
+        (tmp_path / ".mediacrush.json").write_text('{"preset": "saver"}')
+        assert LibraryScanner.load_folder_config(tmp_path) == {"preset": "saver"}
+
+    def test_corrupt_config_ignored(self, tmp_path):
+        (tmp_path / ".mediacrush.json").write_text("{nope")
+        assert LibraryScanner.load_folder_config(tmp_path) == {}
+
+    def test_preset_override_propagates(self, tmp_path):
+        (tmp_path / ".mediacrush.json").write_text(json.dumps({"preset": "film"}))
+        r = scan(tmp_path, {"a.mkv": make_meta(size_mb=900)})
+        assert r.candidates[0].local_preset == "film"
+
+    def test_config_is_per_folder(self, tmp_path):
+        (tmp_path / "x").mkdir()
+        (tmp_path / "x" / ".mediacrush.json").write_text('{"preset": "saver"}')
+        r = scan(tmp_path, {"x/a.mkv": make_meta("/f/a.mkv", size_mb=900), "b.mkv": make_meta("/f/b.mkv", size_mb=900)})
+        presets = {c.metadata.path.name: c.local_preset for c in r.candidates}
+        assert list(presets.values()).count("saver") == 1 and list(presets.values()).count(None) == 1
+
+    def test_skip_already_hevc_false_disables_skip(self, tmp_path):
+        eff = make_meta(codec="hevc", size_mb=300, video_bitrate=1_800_000)
+        assert len(scan(tmp_path, {"a.mkv": eff}).candidates) == 0
+        (tmp_path / ".mediacrush.json").write_text('{"skip_already_hevc": false}')
+        assert len(scan(tmp_path, {"a.mkv": eff}).candidates) == 1
+
+
+class TestShouldSkipEdges:
+    @pytest.mark.parametrize("codec", ["hevc", "h265", "av1", "HEVC"])
+    def test_modern_codecs_skipped_when_efficient(self, codec):
+        assert LibraryScanner.should_skip(make_meta(codec=codec, size_mb=300, video_bitrate=1_000_000))[0]
+
+    def test_hevc_high_bitrate_not_skipped(self):
+        assert not LibraryScanner.should_skip(make_meta(codec="hevc", size_mb=900, video_bitrate=9_000_000))[0]
+
+    def test_exactly_40mb_not_skipped(self):
+        assert not LibraryScanner.should_skip(make_meta(size_mb=40))[0]
+
+    def test_just_under_40mb_skipped(self):
+        assert LibraryScanner.should_skip(make_meta(size_mb=39.9))[0]
+
+    def test_falls_back_to_overall_bitrate(self):
+        m = make_meta(codec="hevc", size_mb=300, video_bitrate=0, overall_bitrate=1_000_000)
+        assert LibraryScanner.should_skip(m)[0]
+
+
+class TestEstimate:
+    @pytest.mark.parametrize("w,h", [(3840, 2160), (1920, 1080), (1280, 720), (640, 480)])
+    def test_always_between_20_and_70_percent(self, w, h):
+        m = make_meta(width=w, height=h, size_mb=1000, duration=3600)
+        est = LibraryScanner.estimate_savings(m)
+        assert m.file_size_bytes * 0.20 <= est <= m.file_size_bytes * 0.70
+
+    def test_more_audio_streams_not_smaller(self):
+        a = LibraryScanner.estimate_savings(make_meta(size_mb=10_000, duration=600, audio=1))
+        b = LibraryScanner.estimate_savings(make_meta(size_mb=10_000, duration=600, audio=4))
+        assert b >= a
+
+
+class TestModels:
+    def test_savings_percent(self):
+        c = CandidateFile(make_meta(size_mb=100), "r", 40 * 1024 * 1024, 60 * 1024 * 1024)
+        assert c.savings_percent == pytest.approx(60.0)
+
+    def test_savings_percent_zero_size(self):
+        assert CandidateFile(make_meta(size_mb=0), "r", 0, 0).savings_percent == 0.0
+
+    def test_total_savings_never_negative(self, tmp_path):
+        assert ScanReport(tmp_path, [], 0, 10, 50).total_savings_bytes == 0
diff --git a/tests/test_transcoder.py b/tests/test_transcoder.py
new file mode 100644
index 0000000..dba083e
--- /dev/null
+++ b/tests/test_transcoder.py
@@ -0,0 +1,165 @@
+"""Unit tests for TranscodeEngine progress parsing, cancellation, and failure paths."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from conftest import make_meta
+from mediacrush.core.hardware import EncoderInfo
+from mediacrush.core.transcoder import TranscodeEngine, TranscodeProgress
+
+CPU = EncoderInfo("hevc", "libx265", "CPU", None, "cpu")
+HW = EncoderInfo("hevc", "hevc_nvenc", "NVIDIA", "cuda", "nv")
+VAAPI = EncoderInfo("hevc", "hevc_vaapi", "Linux", "vaapi", "va")
+
+
+def fake_popen(lines, returncode=0):
+    p = MagicMock()
+    p.stdout = iter(lines)
+    p.returncode = returncode
+    return p
+
+
+class TestRegexes:
+    def test_time_regex(self):
+        m = TranscodeEngine.TIME_REGEX.search("frame=1 fps=24 time=01:02:03.50 speed=2.0x")
+        assert m.groups() == ("01", "02", "03.50")
+
+    def test_fps_and_speed(self):
+        line = "frame=100 fps= 48.5 q=-0.0 time=00:00:04.00 bitrate=1000kbits/s speed=1.50x"
+        assert TranscodeEngine.FPS_REGEX.search(line).group(1) == "48.5"
+        assert TranscodeEngine.SPEED_REGEX.search(line).group(1) == "1.50"
+
+    def test_no_match_on_noise(self):
+        assert TranscodeEngine.TIME_REGEX.search("Stream mapping:") is None
+
+
+class TestTranscodeFlow:
+    def setup_method(self):
+        self.meta = make_meta(path="/v/movie.mkv", duration=100.0)
+
+    def _run(self, lines, rc=0, verify=(True, "ok"), enc=CPU, cb=None, **kw):
+        engine = TranscodeEngine()
+        with patch("mediacrush.core.transcoder.subprocess.Popen", return_value=fake_popen(lines, rc)) as popen, \
+             patch("mediacrush.core.transcoder.SafetyManager.verify_transcode", return_value=verify), \
+             patch("mediacrush.core.transcoder.SafetyManager.finalize_transcode") as fin, \
+             patch("mediacrush.core.transcoder.SafetyManager.cleanup_staging") as clean:
+            ok = engine.transcode(self.meta, enc, "film", progress_callback=cb, **kw)
+        return ok, popen, fin, clean
+
+    def test_success_finalizes(self):
+        ok, _, fin, _ = self._run(["frame=1 fps=10 time=00:00:50.00 speed=2.0x\n"])
+        assert ok is True
+        fin.assert_called_once()
+
+    def test_progress_values(self):
+        got = []
+        self._run(["frame=1 fps=30 time=00:00:25.00 speed=2.0x\n"], cb=got.append)
+        p: TranscodeProgress = got[0]
+        assert p.percent == pytest.approx(25.0)
+        assert p.fps == 30.0 and p.speed_multiplier == 2.0
+        assert p.current_time_seconds == 25.0 and p.total_time_seconds == 100.0
+        assert p.eta_seconds == pytest.approx(37.5)
+
+    def test_progress_capped_at_100(self):
+        got = []
+        self._run(["time=00:05:00.00 speed=1.0x\n"], cb=got.append)
+        assert got[0].percent == 100.0 and got[0].eta_seconds == 0.0
+
+    def test_missing_fps_speed_defaults(self):
+        got = []
+        self._run(["time=00:00:10.00\n"], cb=got.append)
+        assert got[0].fps == 0.0 and got[0].speed_multiplier == 1.0
+
+    def test_no_callback_ok(self):
+        ok, *_ = self._run(["time=00:00:10.00\n"], cb=None)
+        assert ok
+
+    def test_nonzero_exit_fails_and_cleans(self):
+        ok, _, fin, clean = self._run([], rc=1)
+        assert ok is False
+        fin.assert_not_called()
+        assert clean.call_count >= 2  # pre-clean and post-failure clean
+
+    def test_verification_failure_does_not_finalize(self):
+        ok, _, fin, _ = self._run([], verify=(False, "bad"))
+        assert ok is False
+        fin.assert_not_called()
+
+    def test_popen_exception_returns_false(self):
+        engine = TranscodeEngine()
+        with patch("mediacrush.core.transcoder.subprocess.Popen", side_effect=OSError("no ffmpeg")), \
+             patch("mediacrush.core.transcoder.SafetyManager.cleanup_staging"):
+            assert engine.transcode(self.meta, CPU) is False
+
+    def test_hwaccel_flag_for_hardware_encoder(self):
+        _, popen, *_ = self._run([], enc=HW)
+        cmd = popen.call_args[0][0]
+        assert cmd[cmd.index("-hwaccel") + 1] == "auto"
+
+    def test_no_hwaccel_for_cpu_encoder(self):
+        _, popen, *_ = self._run([], enc=CPU)
+        assert "-hwaccel" not in popen.call_args[0][0]
+
+    def test_no_hwaccel_flag_for_vaapi(self):
+        _, popen, *_ = self._run([], enc=VAAPI)
+        assert "-hwaccel" not in popen.call_args[0][0]
+
+    def test_command_shape(self):
+        _, popen, *_ = self._run([])
+        cmd = popen.call_args[0][0]
+        assert cmd[:2] == ["ffmpeg", "-y"]
+        assert cmd[cmd.index("-i") + 1] == str(self.meta.path)
+        assert cmd[-1].endswith(".mediacrush.temp.mkv")
+
+    def test_finalize_receives_flags(self):
+        _, _, fin, _ = self._run([], in_place=False, keep_backup=True)
+        assert fin.call_args[0][2:] == (False, True)
+
+    def test_process_cleared_after_run(self):
+        engine = TranscodeEngine()
+        with patch("mediacrush.core.transcoder.subprocess.Popen", return_value=fake_popen([])), \
+             patch("mediacrush.core.transcoder.SafetyManager.verify_transcode", return_value=(True, "")), \
+             patch("mediacrush.core.transcoder.SafetyManager.finalize_transcode"), \
+             patch("mediacrush.core.transcoder.SafetyManager.cleanup_staging"):
+            engine.transcode(self.meta, CPU)
+        assert engine._current_process is None
+
+
+class TestCancel:
+    def test_cancel_terminates_process(self):
+        e = TranscodeEngine()
+        e._current_process = MagicMock()
+        e.cancel()
+        e._current_process.terminate.assert_called_once()
+        assert e._is_cancelled
+
+    def test_cancel_without_process_is_safe(self):
+        TranscodeEngine().cancel()
+
+    def test_cancel_mid_stream_returns_false(self):
+        engine = TranscodeEngine()
+        meta = make_meta(duration=100)
+
+        def lines():
+            yield "time=00:00:01.00\n"
+            engine.cancel()
+            yield "time=00:00:02.00\n"
+
+        proc = MagicMock(stdout=lines(), returncode=0)
+        with patch("mediacrush.core.transcoder.subprocess.Popen", return_value=proc), \
+             patch("mediacrush.core.transcoder.SafetyManager.verify_transcode") as ver, \
+             patch("mediacrush.core.transcoder.SafetyManager.finalize_transcode") as fin, \
+             patch("mediacrush.core.transcoder.SafetyManager.cleanup_staging"):
+            assert engine.transcode(meta, CPU) is False
+        ver.assert_not_called()
+        fin.assert_not_called()
+
+    def test_cancel_flag_reset_on_new_run(self):
+        engine = TranscodeEngine()
+        engine._is_cancelled = True
+        with patch("mediacrush.core.transcoder.subprocess.Popen", return_value=fake_popen([])), \
+             patch("mediacrush.core.transcoder.SafetyManager.verify_transcode", return_value=(True, "")), \
+             patch("mediacrush.core.transcoder.SafetyManager.finalize_transcode"), \
+             patch("mediacrush.core.transcoder.SafetyManager.cleanup_staging"):
+            assert engine.transcode(make_meta(), CPU) is True
diff --git a/tests/test_watcher.py b/tests/test_watcher.py
new file mode 100644
index 0000000..7d1fda2
--- /dev/null
+++ b/tests/test_watcher.py
@@ -0,0 +1,117 @@
+"""Unit tests for FolderWatcher and its event handler (watchdog events faked)."""
+
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from rich.console import Console
+
+import mediacrush.core.watcher as w
+from conftest import make_meta
+from mediacrush.core.hardware import EncoderInfo
+from mediacrush.core.scanner import CandidateFile, ScanReport
+
+pytest.importorskip("watchdog")
+
+ENC = EncoderInfo("hevc", "libx265", "CPU", None, "")
+
+
+@pytest.fixture(autouse=True)
+def no_sleep_and_quiet(monkeypatch):
+    monkeypatch.setattr(w.time, "sleep", lambda s: None)
+    monkeypatch.setattr(w, "console", Console(record=True))
+
+
+@pytest.fixture
+def watcher(tmp_path):
+    return w.FolderWatcher(tmp_path, "film", ENC)
+
+
+def ev(path, directory=False, dest=None):
+    return SimpleNamespace(src_path=str(path), is_directory=directory, dest_path=dest)
+
+
+class TestHandler:
+    def test_new_video_processed_once(self, watcher):
+        watcher.process_file = MagicMock()
+        h = w.VideoFileHandler(watcher)
+        h.on_created(ev("/x/a.mkv"))
+        h.on_created(ev("/x/a.mkv"))
+        watcher.process_file.assert_called_once_with(Path("/x/a.mkv"))
+
+    @pytest.mark.parametrize("name", ["note.txt", "a.mediacrush.temp.mkv", "img.jpg"])
+    def test_ignored_files(self, watcher, name):
+        watcher.process_file = MagicMock()
+        w.VideoFileHandler(watcher).on_created(ev(f"/x/{name}"))
+        watcher.process_file.assert_not_called()
+
+    def test_directories_ignored(self, watcher):
+        watcher.process_file = MagicMock()
+        w.VideoFileHandler(watcher).on_created(ev("/x/dir.mkv", directory=True))
+        watcher.process_file.assert_not_called()
+
+    def test_moved_in_uses_dest(self, watcher):
+        watcher.process_file = MagicMock()
+        w.VideoFileHandler(watcher).on_moved(ev("/tmp/x.part", dest="/x/final.mp4"))
+        watcher.process_file.assert_called_once_with(Path("/x/final.mp4"))
+
+    def test_moved_without_dest(self, watcher):
+        watcher.process_file = MagicMock()
+        w.VideoFileHandler(watcher).on_moved(ev("/tmp/x.part", dest=None))
+        watcher.process_file.assert_not_called()
+
+    def test_uppercase_extension(self, watcher):
+        watcher.process_file = MagicMock()
+        w.VideoFileHandler(watcher).on_created(ev("/x/A.MKV"))
+        watcher.process_file.assert_called_once()
+
+
+class TestProcessFile:
+    def _report(self, tmp_path, cands):
+        return ScanReport(tmp_path, cands, 0, 0, 0)
+
+    def test_skips_when_no_candidates(self, watcher, tmp_path):
+        watcher.engine = MagicMock()
+        with patch.object(w.LibraryScanner, "scan_path", return_value=self._report(tmp_path, [])):
+            watcher.process_file(tmp_path / "a.mkv")
+        watcher.engine.transcode.assert_not_called()
+
+    def test_transcodes_candidate_in_place(self, watcher, tmp_path):
+        c = CandidateFile(make_meta(str(tmp_path / "a.mkv")), "r", 1, 10)
+        watcher.engine = MagicMock(transcode=MagicMock(return_value=True))
+        with patch.object(w.LibraryScanner, "scan_path", return_value=self._report(tmp_path, [c])):
+            watcher.process_file(tmp_path / "a.mkv")
+        kw = watcher.engine.transcode.call_args.kwargs
+        assert kw["preset_key"] == "film" and kw["in_place"] is True and kw["encoder"] is ENC
+
+    def test_failure_does_not_raise(self, watcher, tmp_path):
+        c = CandidateFile(make_meta(str(tmp_path / "a.mkv")), "r", 1, 10)
+        watcher.engine = MagicMock(transcode=MagicMock(return_value=False))
+        with patch.object(w.LibraryScanner, "scan_path", return_value=self._report(tmp_path, [c])):
+            watcher.process_file(tmp_path / "a.mkv")
+
+
+class TestLifecycle:
+    def test_requires_watchdog(self, monkeypatch, tmp_path):
+        monkeypatch.setattr(w, "_WATCHDOG_AVAILABLE", False)
+        with pytest.raises(RuntimeError, match="watchdog"):
+            w.FolderWatcher(tmp_path, "film", ENC)
+
+    def test_start_schedules_recursive_and_stop(self, watcher, monkeypatch):
+        obs = MagicMock()
+        monkeypatch.setattr(w, "Observer", lambda: obs)
+        calls = {"n": 0}
+
+        def sleeper(s):
+            calls["n"] += 1
+            if calls["n"] >= 2:
+                watcher.stop()
+        monkeypatch.setattr(w.time, "sleep", sleeper)
+        watcher.start()
+        assert obs.schedule.call_args.kwargs.get("recursive") is True
+        obs.start.assert_called_once()
+        obs.stop.assert_called_once()
+
+    def test_stop_without_start(self, watcher):
+        watcher.stop()  # no observer yet; must not raise
diff --git a/tests/test_worker.py b/tests/test_worker.py
new file mode 100644
index 0000000..a67bf04
--- /dev/null
+++ b/tests/test_worker.py
@@ -0,0 +1,78 @@
+"""Unit tests for the GUI BackgroundWorker (tkinter-free)."""
+
+import threading
+from unittest.mock import MagicMock, patch
+
+from conftest import make_meta
+from mediacrush.core.hardware import EncoderInfo
+from mediacrush.core.scanner import CandidateFile, ScanReport
+from mediacrush.gui.worker import BackgroundWorker
+
+ENC = EncoderInfo("hevc", "libx265", "CPU", None, "")
+
+
+def cand(name, saved=100):
+    return CandidateFile(make_meta(f"/v/{name}"), "r", 1, saved)
+
+
+def run_batch(worker, cands, results):
+    ev = threading.Event()
+    log = {"start": [], "done": [], "total": None}
+    worker._engine.transcode = MagicMock(side_effect=results)
+    worker.start_batch(
+        cands, ENC, "film", True,
+        on_file_start=lambda i, n, f: log["start"].append((i, n, f)),
+        on_progress=lambda p: None,
+        on_file_complete=lambda i, f, ok: log["done"].append((i, f, ok)),
+        on_all_complete=lambda s: (log.__setitem__("total", s), ev.set()),
+    )
+    assert ev.wait(5)
+    return log
+
+
+def test_batch_reports_each_file_and_total():
+    log = run_batch(BackgroundWorker(), [cand("a.mkv", 100), cand("b.mkv", 50)], [True, False])
+    assert log["start"] == [(1, 2, "a.mkv"), (2, 2, "b.mkv")]
+    assert log["done"] == [(1, "a.mkv", True), (2, "b.mkv", False)]
+    assert log["total"] == 100  # failed file contributes no savings
+
+
+def test_not_running_after_completion():
+    w = BackgroundWorker()
+    run_batch(w, [cand("a.mkv")], [True])
+    w._thread.join(2)
+    assert w.is_running is False
+
+
+def test_cancel_stops_batch_and_engine():
+    w = BackgroundWorker()
+    ev = threading.Event()
+    done = []
+    first = threading.Event()
+
+    def slow(*a, **k):
+        first.set()
+        ev.wait(2)
+        return True
+
+    w._engine.transcode = MagicMock(side_effect=slow)
+    w._engine.cancel = MagicMock()
+    fin = threading.Event()
+    w.start_batch([cand("a.mkv"), cand("b.mkv")], ENC, "film", True, lambda *a: None, lambda p: None,
+                  lambda i, f, ok: done.append(f), lambda s: fin.set())
+    first.wait(2)
+    w.cancel()
+    ev.set()
+    assert fin.wait(5)
+    assert done == ["a.mkv"]  # second file never started
+    w._engine.cancel.assert_called_once()
+
+
+def test_start_scan_invokes_callback_with_report(tmp_path):
+    got = threading.Event()
+    box = []
+    rep = ScanReport(tmp_path, [], 0, 0, 0)
+    with patch("mediacrush.gui.worker.LibraryScanner.scan_path", return_value=rep):
+        BackgroundWorker().start_scan(tmp_path, lambda r: (box.append(r), got.set()))
+        assert got.wait(5)
+    assert box == [rep]

From 5feb65b8bd41bab995c1a4fdc5a9a174c447dcf7 Mon Sep 17 00:00:00 2001
From: Sheersh Jaiswal <sheershjaiswal@gmail.com>
Date: Thu, 5 Nov 2026 15:08:42 +0530
Subject: [PATCH 2/3] chore(release): bump version to 1.0.5 across Python,
 Flutter, Windows installer and Linux deb

Also publish a version-less mediacrush_amd64.deb so the website can link to the latest release.
---
 build_desktop_linux.sh                   | 5 +++--
 desktop/lib/services/update_service.dart | 2 +-
 desktop/pubspec.yaml                     | 2 +-
 mediacrush/__init__.py                   | 2 +-
 pyproject.toml                           | 2 +-
 scripts/windows_installer.iss            | 2 +-
 6 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/build_desktop_linux.sh b/build_desktop_linux.sh
index a852fd3..774855b 100644
--- a/build_desktop_linux.sh
+++ b/build_desktop_linux.sh
@@ -63,7 +63,7 @@ EOF
 
 cat << 'EOF' > "$DEB_DIR/DEBIAN/control"
 Package: mediacrush
-Version: 1.0.4
+Version: 1.0.5
 Section: video
 Priority: optional
 Architecture: amd64
@@ -71,7 +71,8 @@ Maintainer: ChromaBeast <sheersh@chromabeast.com>
 Description: Universal Hardware-Accelerated Media Optimizer
 EOF
 
-dpkg-deb --build "$DEB_DIR" ../dist/mediacrush_1.0.4_amd64.deb || true
+dpkg-deb --build "$DEB_DIR" ../dist/mediacrush_1.0.5_amd64.deb || true
+cp ../dist/mediacrush_1.0.5_amd64.deb ../dist/mediacrush_amd64.deb 2>/dev/null || true
 rm -rf "$DEB_DIR"
 
 echo "Linux packages assembled in dist/"
diff --git a/desktop/lib/services/update_service.dart b/desktop/lib/services/update_service.dart
index 9e2aae7..31ef34d 100644
--- a/desktop/lib/services/update_service.dart
+++ b/desktop/lib/services/update_service.dart
@@ -7,7 +7,7 @@ import '../models/update_info.dart';
 class UpdateService {
   static const String repoOwner = 'ChromaBeast';
   static const String repoName = 'mediacrush';
-  static const String currentVersion = '1.0.4';
+  static const String currentVersion = '1.0.5';
 
   /// Queries GitHub Releases API for the latest published release.
   Future<UpdateInfo> checkForUpdates() async {
diff --git a/desktop/pubspec.yaml b/desktop/pubspec.yaml
index cabc729..c73fe95 100644
--- a/desktop/pubspec.yaml
+++ b/desktop/pubspec.yaml
@@ -16,7 +16,7 @@ publish_to: 'none' # Remove this line if you wish to publish to pub.dev
 # https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html
 # In Windows, build-name is used as the major, minor, and patch parts
 # of the product and file versions while build-number is used as the build suffix.
-version: 1.0.4+5
+version: 1.0.5+6
 
 environment:
   sdk: ^3.13.5
diff --git a/mediacrush/__init__.py b/mediacrush/__init__.py
index 7246124..21efa2b 100644
--- a/mediacrush/__init__.py
+++ b/mediacrush/__init__.py
@@ -3,5 +3,5 @@
 Supports NVIDIA NVENC, AMD AMF, Intel QSV, Qualcomm Snapdragon X (MediaFoundation), and CPU.
 """
 
-__version__ = "1.0.4"
+__version__ = "1.0.5"
 __author__ = "Sheersh Jaiswal"
diff --git a/pyproject.toml b/pyproject.toml
index 32e76a3..5efae24 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mediacrush"
-version = "1.0.4"
+version = "1.0.5"
 description = "Universal Hardware-Accelerated Media Optimizer (NVIDIA, AMD, Intel, Qualcomm Snapdragon X, CPU)"
 readme = "README.md"
 requires-python = ">=3.9"
diff --git a/scripts/windows_installer.iss b/scripts/windows_installer.iss
index cca021e..41d8ce4 100644
--- a/scripts/windows_installer.iss
+++ b/scripts/windows_installer.iss
@@ -1,6 +1,6 @@
 ; Inno Setup Script for MediaCrush Native Windows Desktop App
 #define MyAppName "MediaCrush"
-#define MyAppVersion "1.0.4"
+#define MyAppVersion "1.0.5"
 #define MyAppPublisher "ChromaBeast"
 #define MyAppURL "https://github.com/ChromaBeast/mediacrush"
 #define MyAppExeName "MediaCrush.exe"

From 2a0c0fc636cb8806e9f9da4de842839ece2080a0 Mon Sep 17 00:00:00 2001
From: Sheersh Jaiswal <sheershjaiswal@gmail.com>
Date: Thu, 5 Nov 2026 15:22:27 +0530
Subject: [PATCH 3/3] test: use posix paths in scanner test helper so it passes
 on Windows

---
 tests/test_scanner_scan.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_scanner_scan.py b/tests/test_scanner_scan.py
index 1659d09..3dcf2b6 100644
--- a/tests/test_scanner_scan.py
+++ b/tests/test_scanner_scan.py
@@ -15,7 +15,7 @@ def scan(tmp_path, mapping):
         p = tmp_path / rel
         p.parent.mkdir(parents=True, exist_ok=True)
         p.write_bytes(b"x")
-    with patch("mediacrush.core.scanner.MediaProbe.inspect", side_effect=lambda p: mapping.get(str(p.relative_to(tmp_path)))):
+    with patch("mediacrush.core.scanner.MediaProbe.inspect", side_effect=lambda p: mapping.get(p.relative_to(tmp_path).as_posix())):
         return LibraryScanner.scan_path(tmp_path)