Captures¶
A capture pulls a spoken value out of a phrase and stores it under a name your command can act on. You write one inside a pattern with curly braces.
Take this pattern:
{system:engines;weapons;systems} is a capture named system that matches one of
three words. Say "power to weapons" and Amri stores weapons in system. Your
command reads system and does the right thing for each value.
Three kinds of capture¶
| Kind | Written as | Matches |
|---|---|---|
| Set | {name:a;b;c} |
one of a fixed list of words |
| Range | {name:min..max} |
a whole number in a range, e.g. {count:1..20} |
| Free | {name...} |
anything you say, transcribed as text |
A set capture is the common one and the most reliable: the recogniser only
listens for the words you list, so it rarely mishears. A free capture (the
trailing ...) is for open text like a search or a message, and it has to be held
behind a push-to-talk so Amri knows when you stop talking.
A range can count in steps other than one. {speed:10..100,10} matches 10,
20, 30, and so on up to 100, which keeps a wide range from expanding into a
long list of phrases.
Using a captured value¶
Once stored, a value can:
- branch the response, so a different action runs for each value,
- be aliased with synonyms, so several spoken words collapse to one stored value,
- be remapped with
[command.map]before it is used.
Example¶
Say "power to engines", "power to weapons", or "power to systems", each pressing a different key:
[[command]]
name = "power_priority"
description = "Divert power to a system."
[command.trigger]
pattern = "power to {system:engines;weapons;systems}"
[command.response.system]
engines = "amri.input.tap('up')"
weapons = "amri.input.tap('left')"
systems = "amri.input.tap('right')"
The response table matches on the value you said, so one command produces a different key press per value without a script.
Naming
Capture names are lowercase with underscores. Choose a name that reads well
where you use it, like system or fire_group, not x.