Set up hands-free input¶

The hands-free preset is one switch that turns on the camera-driven inputs YazSes already has and wires them to work together:

It adds no new engine. [handsfree] enabled = true is expanded, when the config is loaded, into the ordinary settings of those features, exactly as if you had typed them. You can read every one of them before you turn anything on, and any value you write yourself wins.

Experimental, off by default, and every value is provisional. Nobody has yet measured how these inputs behave across people, rooms and cameras, so the numbers the preset supplies are starting points chosen to do less when unsure (a switch that ignores low-confidence frames, a destructive command that is refused rather than guessed). A default install is unchanged until you run the commands below.

What you need¶

• A webcam.
• The camera features' Python packages. yazses handsfree enable installs them for you unless you pass --no-install; you do not run pip yourself.
• For dwell-click (a click by holding still): the on-screen overlay that draws the progress ring, see Dwell-click needs the overlay.

Set it up¶

1. Read what it will do. This changes nothing and never opens the camera:

yazses handsfree explain

Each line is an ordinary setting, with where it came from (preset or yours) and, for the safety floor, a [safety floor] mark. A text or table value you wrote is described by its kind and size and never printed, so the output is safe to paste into an issue.

1. Turn it on. The preset uses experimental features, so it asks for --force:

yazses handsfree enable --force

This writes one line, [handsfree] enabled = true, and nothing else. It refuses, and writes nothing, if one of your own settings would weaken the safety floor (the global stop, the confirmation of dangerous dictated commands, or refusing a destructive action when gaze cannot choose a window); the message names the key.

1. Apply it:

yazses restart

1. Check what your machine is missing. doctor reports a missing camera, a missing pointer backend or an undecided permission with the reason, instead of leaving a feature that silently does nothing:

yazses doctor
yazses handsfree status

Your desktop may show a one-time permission dialog (for pointer control on some Wayland sessions, and your operating system may ask before a program uses the camera). Answer it; yazses handsfree status says when one is still waiting.

1. Calibrate once so the inputs are judged against your face and screen. Both are optional, and without them the plain thresholds are used and a log line says so:

yazses facegesture calibrate
yazses gaze calibrate

1. Arm it. Hands-free starts paused, and the first arming needs a fresh signal from the camera, so nothing moves the instant the camera comes up. Re-arm from any terminal, the tray, or the hands-free controls in the settings window:

yazses handsfree resume

Every terminal step above is listed; there is no other one. Checking status, pausing and resuming are also in the settings window (yazses settings), which shows the same panel as yazses handsfree status.

Choose only some of the roles¶

All roles default to on. Switch any off under [handsfree] in your config.toml before step 3:

[handsfree]
enabled = true
pointer = false   # no head pointer, so also no dwell-click and no recenter chord
chords = false

The roles are gaze, pointer, dwell, switch, chords and voice_stop. A role you turn off is not set, and the pieces that depended on it are not left waiting for it.

Dwell-click needs the overlay¶

Dwell-click only clicks while the overlay that draws its progress ring is on screen: a click you were never shown coming is the failure this feature is judged on. The preset does not turn the overlay on (it is opt-in). Turn it on yourself:

yazses features enable overlay
yazses restart

Without it the pointer still moves, but dwell-click stays off and yazses headpointer status says why. On a native Wayland session the overlay is not launched by default because it would take keyboard focus and your dictation would be typed into it; the pointer moves and nothing clicks there until you pick another way to commit.

Not part of the preset¶

• The Voice Mouse Grid (click by voice) is designed but not wired into this build, so there is no precision fallback in the preset.
• No face gesture is bound to select, confirm or cancel by the preset. The commit is dwell-click unless you add a [[facegesture.switches]] entry yourself.

Stopping, and getting back¶

Every one of these needs neither a precise pointer nor the camera, except the chord:

A pause or a fault is never undone by itself. To come back, run yazses handsfree resume. The first frame after re-arming only observes: it never moves the pointer or clicks, and nothing recorded while you were stopped is replayed.

yazses handsfree disable writes [handsfree] enabled = false. It keeps your calibration and every setting you wrote yourself, and the rest of your config.toml is untouched.

When a signal fails¶

If the signal an action preferred is not usable, YazSes tries the next rung of this ladder and always tells you when it did not use the first:

1. the preferred signal when it is healthy and confident (for example gaze, for "close this");
2. a lower-risk alternate you chose (a window you named by voice, the pointer already resting on it);
3. the focused window, only for actions that can be undone;
4. "cannot act", with a notification, and nothing is done.

Two rules hold on every rung. A fallback never raises the consequence: the action is never changed, only the target it lands on. And a destructive action only recovers onto a target you chose; an inferred stand-in such as "whatever is focused" is refused. Every irreversible action still asks for confirmation first, on every route. So if gaze cannot tell which window you meant, "close this" closes nothing and says so.

What this does not tell you¶

The preset is software that has been tested against fakes of a camera, a pointer and a desktop. It has not been shown to work for any particular person, face, room or webcam, and its default phrase, thresholds and chords are unmeasured. Check each input in your own setup before you rely on it, and keep yazses handsfree pause within reach. Nothing here leaves your machine: frames stay in memory and are never written to disk or sent anywhere.