cleanyourtv/tools/screendiff.md

tools/screendiff.py

Check that a before and an after screenshot are identical outside the regions you mask, and write the pair side by side with private details blurred. Every performance PR claims "no visible change"; this proves it.

tools/venv/bin/pip install -r tools/requirements-perf.txt     # Pillow
tools/venv/bin/python tools/screendiff.py shots/before.png shots/after.png \
    --mask 90,40,900,220 --blur 1265,125,1525,197 --out shots/before-after.png

Exit status	Printed	Meaning
0	identical (1 region masked): ...	No pixel outside the masks differs by more than 8
1	different: N pixels differ ..., inside x0,y0,x1,y1	Find out why before posting
2	an error	Different sizes, a box outside the picture, an unreadable screenshot (the before or the after one is named, and a picture that was cut short counts), an --out or --diff it cannot write, one that names either of the two screenshots - the pair would be written over the picture being compared - and one that was given an empty name - --out "$OUT" with OUT unset: leave the option out to compare without writing it

Option	Notes
--mask x0,y0,x1,y1	Left out of the comparison. Repeatable. Only for what changes by itself: clock, greeting, stats line, wallpaper caption.
--blur x0,y0,x1,y1	Pixelated in both screenshots of the pair. Repeatable. For the Wi-Fi name, account pictures. It doesn't affect the comparison.
--out PNG	The labelled pair, at --scale (default 0.5). A name that is the before or the after file is refused before either is read, so a mistyped --out cannot overwrite a screenshot.
--diff PNG	The differing pixels, white on black. The same rule: neither screenshot may be named.
--labels	The two labels over the pair, comma-separated (Before,After by default); anything but two is refused.
--threshold N	Channel difference to ignore (default 8, compression noise).

Boxes

Boxes are x0,y0,x1,y1 in the screenshot's pixels. On a 1080p TV with the default layout:

• Greeting, clock and date: 90,40,900,220.
• Network name: about 1265,125,1525,197.

The top bar moves with config, and the Hebrew layout mirrors it. Read the Wi-Fi pill's bounds on your TV:

tools/venv/bin/python -I tools/tv.py 'uiautomator dump /data/local/tmp/ui.xml >/dev/null; grep -o "id/btnWifi\"[^>]*bounds=\"[^\"]*\"" /data/local/tmp/ui.xml; rm /data/local/tmp/ui.xml'

Rules

• Take both screenshots the same way. Same key presses, same wait, same theme and wallpaper: tools/tv.py --screenshot shots/before.png HOME DPAD_RIGHT.
• Never mask a region your change touches.
• Don't raise --threshold to make a difference go away. If something did change, say what in the PR.
• Compare Home, not Live TV, HDMI or Netflix. Those capture as empty on most TVs.

The whole before/after method for a pull request is in docs/workflows/perf-ab.md.