Skip to content
GitHub · 2.7.0

Reference

Keyboard

Press keys when a control is active. The second target this library ships, and the proof that the control standard reaches past a hand.

TOML
[dofs]
close = "vhi.prediction.index" # a finger
walk = "keyboard.hold.letter.w" # held while the control is above 0.5
fire = "keyboard.tap.edit.space" # one press per crossing

Both targets share one file and one ControlBus. Nothing in the map format, the bus or the core distinguishes a key from a finger.

Keyboard controls are discrete DOFs

A key is a two-state discrete control, so every part of “press it when the signal goes over 0.5” already existed:

what you want what does it
activate above a threshold a scalar selects the non-rest state of a two-state control
choose the threshold Capability.activation_threshold, declared by this target as 0.5
override it per control threshold_fraction on the binding
ignore a chattering signal debounce_s on the binding
know when it changed ControlBus delivers discrete edges, not levels

So this module is small: it maps an edge onto a key press and nothing else.

Addresses

keyboard.<mode>.<category>.<key>, mode first, around 220 of them: every key in both modes. The dots are what the editor’s picker builds its tree from, so the address shape is also the shape you navigate.

keyboard
├─ hold key down while the control is active
│ ├─ letter a … z
│ ├─ digit 0 … 9
│ ├─ nav left, right, up, down, home, end, page_up, page_down
│ ├─ edit enter, tab, space, escape, backspace, delete, insert
│ ├─ modifier shift, ctrl, alt, cmd
│ ├─ function f1 … f20
│ ├─ numpad n0 … n9, add, subtract, multiply, divide, decimal
│ ├─ punctuation
│ └─ media
└─ tap one press-and-release per activation
└─ (the same categories)

hold is right for movement: walking, aiming, push-to-talk. tap is right for commands, where one gesture should mean one keystroke however long you hold it.

Reference

KeyboardTarget

KeyboardTarget(backend: Any = None, *, armed: bool = False) -> None

Press keys from control values.

A myogestic.controls.Target: construct it, hand it to a myogestic.controls.ControlBus, and register stop with app.cleanup_hooks.

Parameters

NameTypeDescriptionDefault
backendAny

Anything with press(spec) and release(spec). Defaults to a pynput one, constructed on the first arm rather than here, so importing this module, listing its capabilities and resolving a map all work without the extra installed.

None
armedbool

Start armed. Defaults to False: a resolved map is live the moment it binds, into whatever window has focus.

False

Notes

send acts only on the edges ControlBus reports, never on the level.

Examples

>>> from myogestic.controls import ControlBus, load_control_map, resolve
>>> from myogestic.keyboard import KeyboardTarget, keyboard_capabilities
>>>
>>> control_map = load_control_map({"dofs": {"go": "keyboard.hold.letter.w"}})
>>> controls = resolve(control_map, keyboard_capabilities())
>>> keys = KeyboardTarget()
>>> bus = ControlBus(controls, targets=[keys])
>>> keys.armed # nothing is sent until it is armed
False

capabilities

capabilities() -> tuple[Capability, ...]

The manifest, so this can be handed to an editor like a remote target's client.

claims

claims: frozenset[str]

Which aliases this target drives, for ControlBus's coverage check.

armed

armed: bool

Whether key events actually leave this process.

request_accessibility

request_accessibility() -> str

Ask macOS for the permission this target needs. See request_accessibility.

arm_refusal

arm_refusal: str

Why arm would refuse right now, or "" when it would work.

Asked before the click, so the switch is not a trap. Cheap enough to read every frame — one AXIsProcessTrusted and one module lookup.

arm

arm() -> None

Start sending key events, building the backend if it does not exist yet.

Raises
NameTypeDescriptionDefault
RuntimeError

When the backend cannot be built (normally pynput not installed), or when macOS has not granted Accessibility permission. Raised rather than logged, so no target reports itself armed and then presses nothing.

disarm

disarm() -> None

Stop sending, letting go of anything still held. Idempotent.

Releases first: disarming mid-gesture would otherwise leave a key down with nothing left to lift it.

bind

bind(controls: ControlSet) -> None

Accept the keyboard aliases in controls, and refuse a key that is not real.

Raises
NameTypeDescriptionDefault
ValueError

When an alias routes to a keyboard. address this target does not export. Refused here, on the main thread, rather than discovered as a key that never fires.

send

send(values: Mapping[str, float | str], changed: Mapping[str, str]) -> None

Act on the state changes this tick. Never raises.

Only changed is read: a level would re-press a held key every tick. ControlBus already computes the edge, including the debounce.

stop

stop() -> None

Let go of every held key and disarm. Idempotent.

keyboard_capabilities

keyboard_capabilities() -> tuple[Capability, ...]

Every key this target can press, in both modes.

The manifest a myogestic.controls.resolve call validates a map against, exactly like a remote target's. Around 220 entries — every key twice.

Returns

NameTypeDescriptionDefault
tuple[myogestic.controls.Capability, ...]

Discrete and two-state. A held state travels over its target's own command channel, never on a stream, so nothing may try to route one onto a wire.

Examples

>>> from myogestic.keyboard import keyboard_capabilities
>>> caps = {c.address: c for c in keyboard_capabilities()}
>>> caps["keyboard.hold.letter.a"].states
('up', 'down')
>>> caps["keyboard.tap.edit.space"].activation_threshold
0.5