Skip to content

v94

Choose a tag to compare

View all tags
@github-actions github-actions released this 04 Sep 10:27
· 104 commits to main since this release
94
7afd355

New features and improvements

  • Vision hints: hint.type=ui-vision hints what is on the screen instead of what the application reports: mousemaster captures the area and puts a hint on each group of content that stands out from its background. So it also covers games, canvases, remote desktops and anything else that exposes no accessibility information, at the cost of not knowing what an element is.

    ui-hint-mode.hint.type=ui-vision
ui-hint-mode.hint.ui-area=active-screen
ui-hint-mode.hint.vision-density=4

    Vision hints read the same ui-area as accessibility hints and share every selection, click and appearance property with them. vision-density (1 to 8, default 4) turns the detection up: more hints, on smaller things. A whole screen is detected in tens of milliseconds (#85). On macOS the capture asks for the Screen Recording permission the first time.

    hint.type=ui is now hint.type=ui-accessibility. The old name still loads, with a warning.

  • Hint box gradients (experimental): hint.box-color takes several colors and interpolates through them in OkLab. Keywords sit anywhere among the colors, in any order, and choose the direction (top-to-bottom by default, the four diagonals, center-to-edge, center-to-corner, ...), what one sweep covers (across-hint, across-subgrid, across-all-hints, across-area by default, across-screen, across-all-screens) and what shares a single color (per-hint by default, per-subgrid, or per-pixel for a ramp that continues from one box into the next).

    ui-hint-mode.hint.box-color=across-area per-pixel center-to-edge #F97316 #EAB308 #84CC16 #22C55E #14B8A6 #06B6D4 #3B82F6
    mousemaster UI hints with radial hint box color gradient

    One gradient across every hint on the screen: it ramps inside each box and continues into the next (per-pixel), and reaches the last color at every edge (center-to-edge), so a hint's color says how far out it sits.

  • Accessibility hints find more, faster: a hint is kept only where a click reaches its element, so an invisible full-screen overlay no longer swallows the hints behind it, and a fully covered window is skipped rather than walked, halving the scan (#96). A Chromium window is woken before it is walked, so it reports its page instead of almost nothing (#90). On macOS, hints too close together are dropped, as on Windows.

  • UI hints from anywhere: both neo-mousekeys configurations open them with leftalt + ; instead of leftalt + f, without activating mousemaster first. esc returns to the mode they were opened from, so opening them while disabled leaves it disabled (#85).

  • Faster startup, snappier hints: the Qt libraries are extracted once and reused, which was most of the startup time — 1.2 s down to 0.5 s, and much more at sign-in (#97). Hint label layout is cached, an unchanged hint mesh is not rebuilt, and an unchanged configuration file is not reloaded. The hint background appears with the hints instead of dimming the screen ahead of them, and the indicator does not switch to the hint mode's until the UI hint scan is over.

  • A hint mesh that comes up empty can leave its mode: the built-in virtual key ishintmeshempty is pressed when a UI hint scan finds nothing, so a combo can go back instead of leaving you in a mode showing an empty dimmed screen (#90). The shipped configurations all do this now.

    ui-hint-mode.to.normal-mode=_{ishintmeshempty}

  • Fixes:

    • Locking and unlocking the screen resets the key state, so a key held through Win+L no longer blocks combos afterwards, and a movement key no longer keeps the cursor sliding across the lock screen (#95).
    • The overlay windows no longer stay topmost while hidden, which was making the shell demote the taskbar, so any window dragged to the bottom edge covered it (#101).
    • Hint text is measured through the font its metrics came from, so a label sits centered in its box.
    • A hint label keeps its vertical alignment when there is no cell padding.
    • Outside a grid, a hint border is drawn under the labels rather than over them.
    • The hint background is drawn exactly over the hint mesh area, with rounded corners (background-border-radius, default 8, matching Windows' own window corners).
    • The fade settings are read each time a fade starts, so a fade that branches on a combo, or an edit to the file, takes effect right away.
    • A fully faded render-as-cursor indicator is invisible instead of opaque black.
    • A system cursor that is already the one displayed is not reinstalled.
    • On macOS, the autorelease pool is drained every iteration; it was leaking memory.

  • Also: the last key events are kept for at least 128 events and 15 seconds rather than by count alone, so a key whose release never arrived is still in the buffer when the stuck-key check reports it (#93), and logging.level=TRACE shows the built-in virtual keys that DEBUG leaves out. The documentation was corrected throughout and its deprecated sections dropped. In the author configuration, a click animation and a drag now survive the hint click that started them, and the indicator dims away over the idle timeout.

Installation on Windows

  1. Download mousemaster.exe (a portable executable).
  2. Download one of the existing configuration files:
  3. Place the executable and the configuration file in the same directory.
  4. Rename the configuration file to mousemaster.properties.
  5. Run mousemaster.exe: make sure to run it as administrator if you want the mousemaster overlay to be displayed on top of everything else.
  6. Feel free to open a GitHub Issue or join the Discord if you need help creating your own configuration. If you have ideas for a better configuration that you would like to share, I'd love to hear from you.
  7. If you enjoy mousemaster, consider making a donation or stop by the Discord to show your support!

Installation on macOS

mousemaster reads the keyboard through the Karabiner virtual HID device, so that driver and a few permissions are needed.

  1. Install Karabiner-Elements, which installs the virtual HID device, and allow its system extension when macOS asks.
  2. Download and unzip mousemaster-macos.zip, then put mousemaster.app in /Applications.
  3. mousemaster is not signed or notarized, and macOS refuses to start a quarantined app that is not notarized. A browser download marks it as quarantined, so clear that before the first launch: xattr -dr com.apple.quarantine /Applications/mousemaster.app. Or let macOS refuse it once, then allow it under System Settings > Privacy & Security > Security, where an Open Anyway button appears for it.
  4. Download one of the configuration files above, place it in /Applications next to mousemaster.app, and rename it to mousemaster.properties.
  5. Run it from a terminal, as root, which the virtual HID device requires. The configuration is read from the working directory, so start it from where you put it: cd /Applications && sudo mousemaster.app/Contents/MacOS/mousemaster
  6. Grant the permissions macOS asks for, under System Settings > Privacy & Security, then quit and relaunch:
    • Input Monitoring, to read the keys you press. Always needed.
    • Accessibility, only for UI hints (hint.type=ui).
    • Screen Recording, only for zoom (mode.zoom).

License

mousemaster.exe and mousemaster.app embed Qt and QtJambi, used under the GNU Lesser General Public License. Run mousemaster with --licenses for the third-party notices and the full license texts.

Assets 10
Loading