HyperDupScale

HyperDupScale adalah aplikasi desktop (Flutter) dengan backend Go berperforma tinggi untuk deteksi duplikat file (exact dan perceptual) serta upscale gambar. Target: mampu menangani >1 juta file tanpa UI hang.

Arsitektur

• UI: Flutter desktop (Windows). Komunikasi ke backend lewat FFI (dart:ffi) ke DLL Go (-buildmode=c-shared); satu proses, latensi rendah.
• Backend (Go):
• Scanner: streaming walk, worker pool, async cache writer.
  • Dedup logic: size+mtime cache -> hash parsial -> hash penuh SHA-256; opsi perceptual hash (aHash 8x8).
  • Cache store: BoltDB (file -db) menyimpan size/mtime + hash parsial/penuh/pHash untuk reuse scan berikutnya.
  • Upscaler orchestrator: worker pool, memanggil CLI eksternal (mis. real-esrgan-ncnn-vulkan) atau fallback copy untuk dry-run/placeholder.
• Distribusi: Bundle Flutter + DLL Go + model/CLI upscale dalam installer/zip Windows; tidak perlu runtime eksternal (hanya VC++ redist umum).

Pipeline Scanner (Exact)

1. Discovery streaming: walk folder; filter ekstensi/hidden/temp. Batas worker I/O (mis. 8-16).
2. Cache check (Bolt): jika size+mtime sama, reuse hash parsial/penuh tanpa baca disk.
3. Hash parsial: untuk grup size>1, baca N byte awal (default 1 MB) streaming; simpan ke cache.
4. Hash penuh: kandidat dengan hash_partial sama -> hitung SHA-256 full streaming; simpan ke cache.
5. Grup duplikat: grup berdasarkan hash_full; hasilkan daftar grup untuk UI.
6. Summary mode: hasil bisa diringkas (count saja) untuk skala jutaan file.
7. Error handling: tandai skipped/error, lanjut tanpa memblokir.

Pipeline Perceptual (Gambar)

• Jalankan hanya pada MIME gambar. Hitung aHash 8x8 (64-bit). Simpan phash di cache.
• Bandingkan dengan jarak Hamming <= ambang (user-set, mis. 0-16).
• Mode:
  • exact: hanya hash penuh.
  • perceptual: hanya pHash untuk gambar.
  • hybrid: exact dulu, lalu perceptual untuk gambar yang belum punya pasangan exact.

Orchestrator Upscale (eksternal CLI)

• Input: daftar file, output dir, scale, model, path CLI (mis. real-esrgan-ncnn-vulkan), suffix output, opsi overwrite, concurrency.
• Worker pool jalan paralel; tiap file memanggil CLI eksternal dengan argumen -i/-o/-s/-n (heuristik Real-ESRGAN). Jika cli_path kosong atau dry_run true, fallback copy sebagai placeholder.
• Hasil per file: status ok/skipped/error + pesan error jika ada.

UI Flutter (folder ui/)

• Mode tab: Remove Duplicate, Upscale, Remove Duplicate & Upscale (form sesuai mode).
• Folder/file picker: roots scan, output dir, input files, input folder (opsi recursive + filter ekstensi) untuk upscale.
• Downloader bawaan Real-ESRGAN NCNN Vulkan (Win64) dari GitHub; unduh + ekstrak ke upscaler/, otomatis set cli_path.
• Progress dengan ETA dan progress bar (throttled agar UI tidak lag).
• Ready-to-ship build: distribute\hyperdupscale_ui\ berisi exe UI, DLL backend, CLI, Flutter engine, dan data. Zip folder ini untuk user tanpa install tambahan.

Cache Store (BoltDB)

• File DB diatur via flag/parameter -db (default hyperdupscale.db).
• Menyimpan size, mtime, hash_partial, hash_full, phash per path untuk reuse scan berikutnya.

FFI Interface (sketsa C API)

• Build Go: go build -buildmode=c-shared -tags hdsffi -o hyperdupscale.dll -ldflags "-s -w".
• Ekspor fungsi (contoh):

  // go:export HDS_Init
  int HDS_Init(const char* db_path);
  
  // go:export HDS_ScanAsync
  // starts scan; returns handle id; progres di-poll
  int HDS_ScanAsync(const char* roots_json, const char* options_json);
  
  // go:export HDS_PollProgress
  // fills buffer with JSON progress; returns bytes written or <0 on error
  int HDS_PollProgress(int handle, char* buf, int buf_len);
  
  // go:export HDS_GetResults
  // returns JSON result for a completed scan handle
  int HDS_GetResults(int handle, char* buf, int buf_len);
  
  // go:export HDS_Stop
  int HDS_Stop(int handle);

• Dart memanggil lewat DynamicLibrary.open("hyperdupscale.dll"); gunakan isolate untuk polling progres agar main isolate UI tidak blok.
• Struktur bisa diganti ke struct/flatbuffer jika mau lebih efisien; JSON cukup untuk iterasi awal.

Perf & Windows

• Baca file streaming chunked (mis. 1-4 MB), batasi jumlah file besar paralel.
• Gunakan worker pool; hindari menyimpan semua path di memori.
• Handle path panjang (\\?\\ prefix jika perlu), izin baca, file terkunci.
• Benchmark dataset sintetik 1M file (campuran kecil/besar); ukur RAM, MB/s, waktu total; uji cache hit (scan kedua jauh lebih cepat).

Build & Distribusi

• CLI (tanpa cgo): go build → menghasilkan hyperdupscale.exe (scan via CLI, lihat hyperdupscale -h).
• Backend Go (FFI): butuh C toolchain (gcc/clang). Contoh dengan WinLibs portable:
  • Unduh dan ekstrak WinLibs (mingw64) ke tools/mingw64
  • set PATH=C:\WORKSPACE\DuplicateAndUpscaler\tools\mingw64\bin;%PATH%
  • set CGO_ENABLED=1
  • go build -buildmode=c-shared -tags hdsffi -o hyperdupscale.dll -ldflags "-s -w"
• Frontend Flutter: flutter build windows; bundle hyperdupscale.dll + model/CLI upscale di folder bundel.
• Installer: MSI/EXE; sertakan README dan opsi karantina folder default.
• Build script: pwsh build.ps1 akan menghasilkan hyperdupscale.exe (CLI) dan hyperdupscale.dll (FFI) di direktori kerja; DLL dipakai oleh Flutter FFI, EXE untuk testing lokal.

CLI cepat

• Jalankan: hyperdupscale -mode exact -partial-bytes 1048576 -phash-threshold 8 -max-workers 0 -db hyperdupscale.db <path>
• Flags:
  • -mode exact|perceptual|hybrid
  • -partial-bytes (default 1MB)
  • -phash-threshold (default 8)
  • -include-ext ".jpg,.png" / -exclude-ext ".tmp,.log"
• -max-workers (default NumCPU*4 jika 0)
• -delete-workers (default mengikuti max-workers)
• -action scan|delete (default scan; delete akan hapus duplikat, keep first seen)
• -result-mode summary|full (default summary, full mengembalikan semua grup)
• -cache-mode async|sync|off (default async)
• -cache-batch (default 512, hanya untuk async)
• -cache-flush-ms (default 200, hanya untuk async)
• -hash-buffer-bytes (default 4MB)
  • -db path ke Bolt cache (default hyperdupscale.db)
• Upscale CLI: hyperdupscale -upscale -inputs "a.jpg,b.png" -output-dir out -scale 4 -upscaler-cli path\\to\\real-esrgan-ncnn-vulkan.exe -suffix _upscaled -overwrite
  • Opsional: -dry-run untuk hanya copy sebagai placeholder; -upscale-workers untuk batasi paralelisme.

Next Steps (FFI)

1. Optimalkan matching perceptual (bucketing/index) untuk dataset gambar besar.
2. Flutter: binding FFI + isolate untuk polling; UI form opsi + progres + tabel duplikat virtualized + kontrol upscale.
3. Uji performa dengan dataset besar; sesuaikan worker/IO/chunk; tambahkan logging ringan.