Eclipse Cleaner

Clean up and stabilize a shaky solar-eclipse timelapse — and maybe rescue a video you thought was lost.

🇫🇷 Version française

🔰 Never used Python or a terminal? Follow the guide for absolute beginners (Windows) — copy-paste only, no experience needed, no code to write.

This project began with the capture of the solar eclipse of August 12, 2026. My equipment setup was far from ideal — people kept walking in front of my gear — but I still managed to capture the eclipse. Then I opened the video produced by my smart telescope, and my heart sank: it was unusable. Very unstable, with long masked sequences followed by tracking-recovery phases and abrupt brightness adjustments.

I tried to fix it with the tools available (SIRIL and PIPP), but I probably didn't know how to use them well enough — or it was simply too much to ask of them. So I set out to build a tool of my own, with the help of my favorite AI assistant. Here it is.

Original (straight from the smart telescope)	Cleaned with Eclipse Cleaner

Both clips play at 6× speed.

Original lunar eclipse footage	Cleaned with Eclipse Cleaner (--preset moon)

Both clips play at 6× speed. Lunar eclipse footage kindly shared by a Seestar user — thank you!

• Adapts to what's actually eclipsing — sun, moon, or a planetary transit each fail differently, so an eclipse-type preset picks the right measurement strategy and sorting defaults for each. The type is detected automatically and always overridable. See Eclipse types and presets.
• Sorts the frames — only irreparable frames are rejected: blur, darkness, glare, failed disk localization. A badly framed frame is not a defective frame; the stabilizer fixes the position.
• Locks the solar disk to the center — a fixed-radius directed Hough vote finds the disk even on a thin crescent, and tolerates clouds masking part of the limb.
• Moves the frame like a camera operator would — the crop window is planned, bounded softly against the source edges, and absorbs the tracking re-acquisition jumps (hundreds of pixels in a single frame) instead of jerking.
• Removes auto-exposure flicker — brightness is corrected frame by frame toward the sequence median, and white balance is stabilized toward its own trajectory, never toward neutral: a red solar filter stays red, a sunset stays warm, and removing the filter mid-sequence stays a real change. (--sans-couleur disables the color part.)
• Bridges short gaps with linear interpolation, and never invents footage for long ones: a real hole stays a clean cut.
• A review viewer in your browser — inspect every frame, overrule the automatic sorting with one keystroke, then re-render. Bilingual (English/French), served on 127.0.0.1 only. It shows a loading state while a newly picked video is probed, and offers a collapsible raw-video player to watch the source itself.

Everything adapts to your video: resolution, aspect ratio, frame rate and apparent solar radius are measured, not assumed, and every threshold can be overridden from the command line.

On Windows you can skip Python entirely: each release ships a standalone eclipse-cleaner-…-windows-x64.exe — download it from the latest release and double-click. Details (and the SmartScreen warning to expect) in the beginners guide.

Otherwise: requires Python 3.12+ — check with python --version first: on a system whose default python is older (Homebrew, some Linux distros), the install fails with an unrelated-looking dependency error rather than a clear version message. The ffmpeg binary is bundled through imageio-ffmpeg: nothing else to install on your system.

python -m pip install git+https://github.com/bebkill/Eclipse-Cleaner.git

This git+ form requires git to be installed (it usually isn't, on Windows). No git? Use the zip form instead — same result:

python -m pip install https://github.com/bebkill/Eclipse-Cleaner/archive/refs/heads/main.zip

Or from a clone:

git clone https://github.com/bebkill/Eclipse-Cleaner.git
cd Eclipse-Cleaner
python -m pip install .

⚠️ Don't miss the trailing dot in pip install . — it means "install from this directory".

Once installed, run the tool with:

python -m eclipse viewer

This form always works. The install also creates a shorter eclipse-cleaner command, but it is only found if your Python Scripts directory is on the PATH — on Windows it often isn't. If your terminal answers "'eclipse-cleaner' is not recognized…", nothing is broken: just use python -m eclipse instead. (An install through pipx install git+https://github.com/bebkill/Eclipse-Cleaner.git sets up the PATH for you, if you prefer the short command.)

python -m eclipse viewer

This opens a local page in your browser. Click Browse… to pick your video, then run the three steps from the page:

1. Extract the thumbnails (for review);
2. Analyze the frames (measurements and automatic verdicts);
3. Produce the final video → written into the video's work folder: eclipse.mp4 gives eclipse.mp4-eclipse/eclipse-clean.mp4 (optionally with a numbered PNG sequence, in eclipse.mp4-eclipse/frames/).

Everything the page derives from a video — the analysis cache, your review decisions, the review thumbnails, the render and the PNG export — lives in one work folder created next to it, <source>-eclipse/: a folder holding several eclipses stays readable, and two videos can never share a cache or a review. The rendered -clean.mp4 keeps a name of its own inside that folder, since it is the file you copy out. Work files left loose next to a video by an earlier version are moved into the folder the first time the viewer opens that video, and it says so on the terminal. A rendered video moves only when the descriptor written beside it names this video: the old render name was shared between a source and its transcode, so an unvouched one is left exactly where it is.

Under the render button, the stabilize color checkbox (on by default) removes the frame-to-frame white-balance oscillations of automatic exposure, toward the sequence's own tint — never toward neutral. Its collapsible parameters section holds the fine-tuning: the tint-reference window (typical: 31 frames, capped at the sequence length — beyond that the reference saturates and a larger window changes nothing) and the max correction per channel (typical: 0.25, i.e. ±25 %). Brightness is always normalized, checkbox or not. Changing a parameter marks an existing render as to redo, so the banner never claims a stale output is current.

The central thumbnail shows the crop frame: the exact rectangle the render will cut out of the current frame. Its position is always automatic — it follows the tracked disk, so there is nothing to place by hand — but its size can be dragged from the handle in its bottom-right corner, staying centered and locked to the output's aspect ratio. A label under the thumbnail reads auto or custom (W×H), with a ↺ button to snap back to the recommended size. The choice is remembered per video (in its work folder) and is exactly what the render uses, the same value --taille would set from the command line.

Between steps 2 and 3, review the sorting: the timeline shows kept frames in green, rejected ones in red, your own overrides in blue. Press k on any frame to keep or discard it — each change is saved immediately, and the render applies your decisions automatically.

Progress bars, cancellation, and task state all live server-side: closing the tab loses nothing.

python -m eclipse run input.mp4 output.mp4

Or in two steps, so you can re-render with different thresholds without re-analyzing:

python -m eclipse analyze input.mp4 --cache analysis.json
python -m eclipse render input.mp4 output.mp4 --cache analysis.json --blur-rel 0.35

The CLI flags are in French (see Known limitations); here is what they mean:

A solar crescent, a shadowed moon and a small bright planetary disc do not fail the same way: a threshold set tuned for one can leave another with an empty light mask or an inverted vote. A preset therefore fixes, per eclipse type, both the pass-1 measurement strategies (baked into the analysis cache) and the pass-2 sorting defaults (which plain CLI flags can still override without invalidating the cache):

• lit mode — how the illuminated region is thresholded to estimate the apparent radius: percentile (midway between the frame's background and its 99th percentile, the historic behavior) or max (relative to the frame's peak instead), needed when the subject can be small or largely shadowed.
• radius mode — area turns the lit region's area into a radius (exact for a full disc, but drifts as an eclipse's umbra advances) or scan, which finds the radius that maximizes the directed Hough-vote confidence (accurate to within about ±1.5 % on the calibration videos even as the umbra grows).
• vote — the Hough-vote regime used to find the disc center: bright (a lit disc), dark (a dark disc ringed by light — a solar totality, where the limb gradient points outward), or dual (evaluates both per frame and keeps the sharper peak, needed when a video crosses from crescent to totality and back).
• custom reproduces the tool's original, pre-eclipse-types behavior exactly (byte-identical on the reference solar sequence).

For a custom analysis, or to understand what moving a preset's own defaults does, here is what the code documents about each sorting/analysis threshold:

Automatic detection, and how to override it. analyze and run probe a spread of sample frames across the source and print the detected type before analyzing — the CLI prints, for example, Type d'eclipse detecte : moon. Detection looks at the sky background (bright daylight/halo vs. a black sky), the disc's own internal contrast (a shadow crossing it), a size cutoff for a small planetary disc, and, as a tie-break, a warm color cast (a filtered sun). It is a suggestion, never applied silently and never final: pass --preset sun|moon|planetary|custom on the command line to force one, or use the selector in the viewer's Source panel, which shows the type currently in force: as long as nothing has been chosen there, the type the cache was analyzed under applies, or, failing that, the suggestion. Because the preset drives pass-1 measurement strategies, changing it — from the CLI or the viewer — always requires a fresh analysis: the cache records its own preset and refuses to be reused under a different one, with a message describing what to relaunch.

• Command-line messages are in French (the viewer itself is fully bilingual). Internationalizing the CLI is a welcome contribution.
• Clipped highlights cannot be reconstructed — exposure is re-leveled, but detail lost to saturation stays lost.
• A solar totality's corona can be blown out by brightness normalization. Photometry itself is untouched by the eclipse-type feature; this is an existing limitation that a totality simply makes more visible.
• The planetary preset has never been calibrated against real footage — only against synthetic frames. If you have real planetary or transit footage, open an issue with a sample: it's the fastest way to get it tuned.
• On a partial-only solar video, automatic detection selects the sun preset, whose sorting is slightly stricter than the historic (custom) behavior — 1661 vs. 1726 frames kept on the reference sequence. Pass --preset custom to reproduce the exact pre-preset result.
• Two color renditions can coexist in one film if a solar filter was removed mid-sequence. That is what really happened in front of the camera, so it is kept, like cloud crossings.
• The viewer's Browse… dialog needs a graphical session (it uses the system file dialog via tkinter). On a headless machine, pass the video path on the command line instead.
• On macOS, the Browse… dialog now opens through the system's native panel (osascript), which sidesteps the main-thread crash the viewer used to hit there (#4) — see acknowledgments. The command-line fallback still applies on the rare system where osascript itself is unavailable: python -m eclipse viewer path/to/video.mp4.
• The test suite is developed on Windows; four Windows-specific tests skip themselves automatically on Linux/macOS.

What's being considered next (SER input, raw Bayer AVI, choice of output format…) lives in the roadmap.

python -m pip install -e ".[dev]"
python -m pytest

Assertions run against synthetic frames with known ground truth; no real video is required.

This program saved my video, and I hope it can help other eclipse chasers in the same situation. Don't hesitate to share your results, comments, and suggestions for improving this humble program — issues and pull requests are very welcome.

And if, like me, it rescued your eclipse video, you can support the project:

Thanks to @mireianievas (#1), who diagnosed the macOS crash in the Browse… dialog and prototyped the osascript fix now shipping (co-authored), and who first prototyped dynamic cropping in her fork — the prompt behind the crop-frame control described above.

MIT — free to use, modify, and share.

Clear skies! 🌘