Version v0.35 · supported

[WIP] Pending copyedit and approval.

Functions

A function is an action Amri provides. You call one from Lua as a command's response, and Amri carries it out: a keypress, a mouse move, a profile switch, a line of speech.

Functions live under the amri. namespace, grouped by area: amri.input for keys and mouse, amri.speech for listening and speaking, amri.sound for audio, amri.profile for switching profiles and categories, and more. The full list of names and signatures is in the API reference.

The inline form

For a single action, write the call inline with lua = "...". This is the common case and needs no separate file:

[[command]]
name = "toggle_mute"
description = "Toggle mute."
lua = "amri.input.tap('mute')"
[command.trigger]
pattern = "[mute;unmute]"

amri.input.tap('mute') presses and releases the mute key. Change the argument to target a different key, and the API reference lists the input names you can pass.

The script form

When the response is more than one line, or has to make a decision, move it into a Lua file and point at it with script = "...". The file sits beside the profile and runs when the command fires:

[[command]]
name = "search"
description = "Search for whatever was said."
script = "search.lua"
[command.trigger]
pattern = "search [for;] {query...}"

Inside the script, the captured value is available as ctx.captures.query. See Captures for passing a spoken value into a function as an argument.

Return values need a script

Some functions hand back a value: amri.sound.play(path) returns a handle you can later stop, and amri.speech.ask(responses) returns the word that was heard. To use a returned value you have to store it and act on it, which the inline one-liner cannot do. Use a script:

-- confirm.lua
local answer = amri.speech.ask({ "confirm", "abort" })
if answer == "confirm" then
  amri.input.tap("delete")
else
  amri.log.info("cancelled")
end

amri.speech.ask blocks until it hears one of the listed responses and returns it, or returns nil on timeout. The script reads that return value and branches. The inline form has nowhere to keep the result, so anything that reads a return value belongs in a file.

One response form per command

A command uses lua, or script, or a [command.response] table, but not more than one at a time. Reach for lua for a single call, a response table to branch on a capture, and script when the logic outgrows a line.