Skip to content

keycodes

keycodes

macOS key codes and modifier flags for the global dictation hotkey.

Pure data + classification, deliberately importable without PyObjC so the push-to-talk state machine can be unit-tested headlessly. The live event tap (hotkey.py) maps real CGEvents onto the vocabulary defined here.

Functions:

normalize_hotkey 

normalize_hotkey(name: str) -> str

Return a supported hotkey name, falling back to the default.

Mirrors the forgiving parse Diapason applies to its hotkey setting: an unknown or empty value must not leave dictation unbound, it falls back to Control.

Source code in src/diapason/desktop/keycodes.py 
42
43
44
45
46
47
48
49
50
def normalize_hotkey(name: str) -> str:
    """Return a supported hotkey name, falling back to the default.

    Mirrors the forgiving parse Diapason applies to its ``hotkey`` setting: an
    unknown or empty value must not leave dictation unbound, it falls back to
    Control.
    """
    key = (name or "").strip().lower()
    return key if key in SUPPORTED_HOTKEYS else DEFAULT_HOTKEY

keycode_matches 

keycode_matches(hotkey: str, keycode: int) -> bool

True when keycode is one of the physical keys for hotkey.

Source code in src/diapason/desktop/keycodes.py 
53
54
55
def keycode_matches(hotkey: str, keycode: int) -> bool:
    """True when *keycode* is one of the physical keys for *hotkey*."""
    return keycode in KEYCODES.get(normalize_hotkey(hotkey), set())

is_bare_press 

is_bare_press(hotkey: str, flags: int) -> bool

True when flags show the bound modifier down and no OTHER modifier.

A push-to-talk key must fire on the key alone. If the user is holding Command as well (Cmd+Control), that is a chord meant for the app in front, not a dictation trigger, so we let it through untouched.

Source code in src/diapason/desktop/keycodes.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def is_bare_press(hotkey: str, flags: int) -> bool:
    """True when *flags* show the bound modifier down and no OTHER modifier.

    A push-to-talk key must fire on the key alone. If the user is holding
    Command as well (Cmd+Control), that is a chord meant for the app in front,
    not a dictation trigger, so we let it through untouched.
    """
    hotkey = normalize_hotkey(hotkey)
    own = FLAG_MASKS[hotkey]
    if not (flags & own):
        return False
    others = 0
    for name, mask in FLAG_MASKS.items():
        if name != hotkey:
            others |= mask
    return not (flags & others)

classify_flags_change 

classify_flags_change(
    hotkey: str, keycode: int, flags: int
) -> Optional[str]

Interpret a flagsChanged event as "down", "up" or None.

macOS reports modifier presses as flagsChanged events carrying the new flag state, not as key-down/up. The bound key is down when its own flag bit is set on an event for its keycode, and up when the same keycode arrives with its bit cleared.

Source code in src/diapason/desktop/keycodes.py 
76
77
78
79
80
81
82
83
84
85
86
87
def classify_flags_change(hotkey: str, keycode: int, flags: int) -> Optional[str]:
    """Interpret a flagsChanged event as ``"down"``, ``"up"`` or ``None``.

    macOS reports modifier presses as ``flagsChanged`` events carrying the new
    flag state, not as key-down/up. The bound key is *down* when its own flag
    bit is set on an event for its keycode, and *up* when the same keycode
    arrives with its bit cleared.
    """
    if not keycode_matches(hotkey, keycode):
        return None
    own = FLAG_MASKS[normalize_hotkey(hotkey)]
    return "down" if (flags & own) else "up"