Comet Enhancer

Windows desktop app for video and image enhancement — AI upscaling, restoration, colour and encoding. Python backend with a pywebview UI, packaged via PyInstaller and Inno Setup.

Built for a specific job: making old home movies and scanned family photographs look better, without sending anything to a cloud service. Everything runs locally on your GPU.

Status: personal project, published in the open. It is used daily by its author on one machine. It is not a supported product, there is no release channel, and the installer is not code-signed — Windows SmartScreen will warn you. Build it yourself if that matters.

⚠️ Before you use this commercially

Comet Enhancer's own code is MIT. The neural-network models it downloads are not, and one of them is NonCommercial:

Model	Licence	Commercial use
4xRealWebPhoto_v4_dat2 (photos)	CC-BY-4.0	✅ yes, with attribution
4xNomos2_hq_dat2 (scans)	CC-BY-4.0	✅ yes, with attribution
2xLiveActionV1_SPAN (video)	CC-BY-NC-SA-4.0	🔴 no

NonCommercial restricts running the model, not merely sharing it. Using the live-action upscaler on footage you are paid for is a breach no matter what licence this repository carries. It is labelled in the UI and is not the default. Full detail, attribution and sourcing in THIRD-PARTY-NOTICES.md.

What it does

• Video — transcode (x264/x265/AV1, NVENC/QSV/AMF/CPU), deinterlace, deblock, deband, denoise, stabilise, film grain, SDR→HDR, A/B compare, and range renders where the 30-second preview and the full run are the same code path.
• Restoration — deflicker, faded-colour recovery, audio cleanup, and an optional plugin tier for dust, scratches, dot-crawl and motion-compensated denoise.
• AI — neural upscale and DPIR deblock/denoise via VapourSynth + vs-mlrt on DirectML, plus RIFE frame interpolation.
• Images — batch photo/scan enhancement with EXIF and transparency preserved, EXIF orientation handled correctly, and a target-resolution mode that renders high then downsamples.

Requirements

• Windows 10/11 with the Edge WebView2 Runtime (ships with Windows 11; the app checks and tells you if it is missing)
• ffmpeg and ffprobe on PATH — winget install Gyan.FFmpeg
• A DirectML-capable GPU for the AI features. The ffmpeg-only paths work without one.
• ~2 GB of disk for the AI pack, downloaded on first use into %APPDATA%\CometEnhancer

Build from source

py -m pip install -r requirements.txt
.\update.ps1                  # preflight -> build -> installer in dist\
.\update.ps1 -Install -Launch # ...and install + run it

update.ps1 is the normal path. It runs preflight (dependency import test, py_compile, the static gates, node --check), syncs the version into installer.iss, builds the PyInstaller onedir via build.ps1, and compiles the Inno Setup installer.

py app.py runs the UI in dev, but cannot reach the AI pack — that lives under %APPDATA% and is only resolvable from a frozen build.

Checks

update.ps1 runs these in preflight, so a build cannot be produced from a tree that fails them.

• py tools\check.py — 10 static gates (syntax, version parity, undefined CSS tokens, element-id parity, dead-identifier regressions, bridge-safety, installer/app mutex parity, same-volume temp placement, public-repo readiness). ~2 s, no GPU required.
• py tools\check.py --strict — a gate that could not run (e.g. no node on PATH) becomes a failure instead of a skip. A skip is never counted as a pass.
• py tools\check.py --public — adds the Tier-1 licence gate, which fails while any NonCommercial asset is referenced. See LICENCES.md.
• py tools\test_imagemeta.py — 57 checks on EXIF preservation, alpha detection and cross-volume temp placement. Install Pillow for real evidence; without it the read-back checks downgrade to self-checking and say so.

Every gate exists because the corresponding bug already shipped at least once. That is the point of them.

Licence

MIT — see LICENSE.

This covers the source in this repository only. It contains no third-party code and no model weights: 59 tracked files, zero binaries. The runtimes it uses — VapourSynth (LGPL-2.1), vs-mlrt (GPL-3.0), several GPL-2.0 VapourSynth plugins — are downloaded at run time from their own release channels and invoked as separate operating-system processes over a pipe. None of them are redistributed here.

THIRD-PARTY-NOTICES.md records every component, its licence, its source, how it is invoked, and the one point in that analysis that is genuinely unsettled.

Documentation

• BACKLOG.md — start here. Everything open, ranked, with the gates at the top, and a section for things deliberately not fixed with the reason for each.
• CLAUDE.md — current state and accumulated gotchas, written for whoever picks this up next.
• THIRD-PARTY-NOTICES.md / LICENCES.md — licensing.
• APPROACH.md — architecture rationale.
• ROADMAP-next-round.md — historical only. Its build-vs-buy thesis was falsified; do not plan from it.

Layout

• app.py — application entry point and backend/UI bridge
• core/ — enhancement engine (enhance_core.py, ai_deps.py, imagemeta.py)
• ui/ — web UI (HTML/CSS/JS, no framework, no build step)
• tools/ — gates, tests and probes
• assets/ — icons and logos
• docs/ — research and design notes

Build artefacts (dist/, build/, dist-archive/), downloaded binaries (bin/) and runtime state (settings.json, *.log, gpu_cache.json) are excluded from version control — see .gitignore.