Listening modes¶

By default Amri listens all the time. You can instead gate the microphone behind a key you hold, so Amri only listens while that key is down. This is set in engine.toml, the engine configuration file you control.

Always listening¶

This is the default. With no push-to-talk bindings in engine.toml, Amri listens continuously: voice-activity detection decides when you are speaking, and a finished phrase fires the matching command. Nothing extra is needed to get this behaviour.

Push-to-talk¶

Push-to-talk (PTT) gates the microphone behind a held key. Amri listens only while that key is down, then stops when you release it. This keeps stray speech from firing commands, which is useful in a shared space or on voice chat.

You turn it on by adding a [[push_to_talk]] table to engine.toml. Each table defines one binding with a name and a key. As soon as one binding exists, that key gates listening.

# engine.toml, the file you control
[[push_to_talk]]
name = "talk"
key  = "right_alt"

You can define more than one binding. Each needs a unique name; a duplicate name is a configuration error and Amri refuses to start.

Field	Required	Effect
`name`	yes	The binding's name. Profiles reference it by this.
`key`	yes	The key or button that opens the microphone while held.
`device_name`	no	Glob to scope the binding to one input device by name. `*` matches every device (the default).
`device_path`	no	Exact kernel event node, `/dev/input/eventN`, to bind one specific device.

The key value uses the same input names as an input trigger, for example right_alt, left_ctrl, or a device button.

Scoping to one device¶

If two keyboards or a game controller expose the same key, add device_name to bind the key on one device only. The value is a glob matched against the device name:

[[push_to_talk]]
name = "talk"
key  = "btn_pinkie"
device_name = "*X56*"     # only the throttle whose name contains X56

Use device_path instead when you know the exact event node. It must start with /dev/input/event; any other shape is rejected at load.

Profiles reference bindings by name¶

A binding is defined once in engine.toml, then a profile, category, or command refers to it by name. That is the authoring side of push-to-talk: which commands listen behind which binding, and how the setting inherits. See Push-to-talk for the profile-side gate.

Bindings live only in engine.toml

A binding can only be defined in engine.toml, never in a profile. A profile you import can reference a binding by name, but it cannot create one, because a binding reads a physical input device.

Built-in Amri commands¶

A small set of built-in commands begins with the word Amri, for example Amri default profile, and they merge into every profile you load. They are ordinary spoken commands, not a separate hotword system, and they stay present even when a command profile is push-to-talk gated. See System overrides for the built-in set and how a profile can override it.

Push-to-talk: the profile-side listen gate.
Audio: choosing the input device and voice-activity sensitivity.