Version v0.35 ยท supported
[WIP]
Pending copyedit and approval.
API reference
Every function Amri exposes to Lua, grouped by namespace. This page is generated from the authoritative API definition, so it always matches the shipping engine. It lists signatures; the concept pages explain how to use them: Functions, Variables and scopes, The command context, Speech and prompts, and Tasks.
Reading a signature
Square brackets mark an optional argument, so amri.input.press(key[, ms]) takes a key and an optional duration. A name followed by ... takes a list. Some functions need a grant before they will run; the description says which.
amri.log
| Function |
Description |
amri.log.info(msg) |
Log at info level. |
amri.log.warn(msg) |
Log at warn level. |
amri.log.error(msg) |
Log at error level. |
amri.log.debug(msg) |
Log at debug level (suppressed unless the debug level is active). |
amri.log.level([lvl]) |
Get the current log level, or set it when lvl is given. |
| Function |
Description |
amri.input.tap(key) |
Tap a key (press+release). |
amri.input.press(key[, ms]) |
Press and hold a key. |
amri.input.release(key) |
Release a held key. |
amri.input.hold(key) |
Hold a key until released. |
amri.input.text(str) |
Type a printable string. |
amri.input.axis(name, value) |
Set a device axis value. |
| Function |
Description |
amri.input.mouse.tap(btn) |
Tap a mouse button. |
amri.input.mouse.press(btn[, ms]) |
Press a mouse button. |
amri.input.mouse.release(btn) |
Release a mouse button. |
amri.input.mouse.hold(btn) |
Hold a mouse button. |
amri.input.mouse.move(dx, dy) |
Move the mouse (relative). |
amri.input.mouse.scroll(amt[, axis]) |
Scroll the wheel. |
| Function |
Description |
amri.input.button.tap(btn) |
Tap a device button. |
amri.input.button.press(btn[, ms]) |
Press a device button. |
amri.input.button.release(btn) |
Release a device button. |
amri.input.button.hold(btn) |
Hold a device button. |
amri.vars
| Function |
Description |
amri.vars.get(name) |
Read a variable up the scope chain. |
amri.vars.set([scope, ] name, val) |
Write a variable. |
amri.profile
| Function |
Description |
amri.profile.get() |
Name of the active profile. |
amri.profile.switch(name) |
Switch the active profile. |
amri.profile.release() |
Release an override profile. |
amri.profile.previous() |
Name of the previous profile. |
amri.profile.reload() |
Reload profiles from disk. |
amri.profile.category
| Function |
Description |
amri.profile.category.enable(name) |
Enable a category. |
amri.profile.category.disable(name) |
Disable a category. |
amri.profile.category.toggle(name) |
Toggle a category; returns the new state. |
amri.profile.category.enabled(name) |
Whether a category is enabled. |
amri.speech.dictate
| Function |
Description |
amri.speech.dictate.start() |
Start a dictation window. |
amri.speech.dictate.stop() |
Stop dictation. |
amri.speech.dictate.active() |
Whether dictation is active. |
amri.speech
| Function |
Description |
amri.speech.speak(text[, opts]) |
Speak text via TTS (opts: voice, volume, barge_in); queued behind other speech, returns immediately. |
amri.speech.speak_sync(text[, opts]) |
Speak text and block this script until it finishes playing in turn (opts: voice, volume, barge_in). |
amri.speech.stop() |
Stop the current TTS utterance. |
amri.speech.speaking() |
Whether TTS is currently speaking. |
amri.speech.voices() |
List the installed TTS voice names (filestems) available as speak{voice=...}; empty when TTS is unavailable. |
amri.speech.listen(on) |
Mute (false) or resume (true) command listening. |
amri.speech.listening() |
Whether command listening is currently active. |
amri.speech.ask(responses[, opts]) |
Constrained spoken prompt: block until one of responses is heard (returns it) or timeout seconds pass (nil). |
amri.sound
| Function |
Description |
amri.sound.play(path[, opts]) |
Play a sound file; returns a handle (opts: volume). |
amri.sound.stop(handle) |
Stop a playing sound by handle. |
amri.sound.stop_all() |
Stop all sounds started via amri.sound. |
amri.sound.preload(path) |
Decode + cache a sound for low-latency play; returns ok. |
amri.commands
| Function |
Description |
amri.commands.add{pattern=..., inline=|script=} |
Register a NEW dynamic command (append-only) and return a handle; adding a pattern that already exists is an error -- use commands.set to replace it. |
amri.commands.set(group, list) |
Atomically (re)define a named dynamic-command group; idempotent -- re-setting the same group replaces its commands. |
amri.commands.hooks
| Function |
Description |
amri.commands.hooks.before(fn) |
Register a callback fired BEFORE every command runs; fn receives { name = }. If ANY before-hook returns false the command is cancelled (its body does not run). Profile-scoped; multiple allowed, fired in registration order. |
amri.commands.hooks.after(fn) |
Register a callback fired AFTER every command completes; fn receives (cmd, result) where cmd = { name = } and result = { success = }. Does NOT fire when a before-hook cancelled the command. Profile-scoped; multiple allowed. |
amri.synonyms
| Function |
Description |
amri.synonyms.add(canonical, alias[, {persist=bool}]) |
Register a spoken nickname alias for an existing command phrase canonical; saying the alias fires that command. Returns true, or nil + an error message (unrecognizable/duplicate nickname, or a canonical that is not a complete command). persist=true also saves it across sessions (default false = this session only). |
amri.synonyms.remove(canonical, alias) |
Remove a nickname previously added for a command. Idempotent. |
amri.synonyms.list(canonical) |
List the nicknames registered for a command phrase (empty when none). |
amri.synonyms.clear() |
Drop every capture alias (e.g. to reconfigure a per-mission roster). |
amri.file
| Function |
Description |
amri.file.read(path) |
Read a file inside the profile sandbox; nil if unreadable. |
amri.file.exists(path) |
Whether a file exists inside the profile sandbox. |
amri.sys
| Function |
Description |
amri.sys.active_window() |
The focused window {title, app_id, process, pid}, or nil. |
amri.sys.window_focused(pattern) |
Whether the focused window matches a glob (title/app_id/process). |
amri.sys.process_exists(name) |
Whether a running process matches name (a glob; /proc comm, 15-char truncated). |
amri.sys.key_pressed(key) |
Whether a key is currently held down. |
amri.sys.mouse_button(button) |
Whether a mouse button is currently held down. |
amri.sys.lock_state(name) |
Whether a lock key ("caps"/"num"/"scroll") is currently ON. |
amri.sys.run{argv...[, capture=true]} |
Run an argv command (no shell); returns exit_code[, stdout]. Grant: run. |
amri.sys.shell(command[, capture]) |
Run a shell command string (sh -c); returns exit_code[, stdout]. Grant: shell. |
amri.sys.kill(pid[, signal]) |
Send a signal (default SIGTERM) to a pid; returns true on success. Grant: kill. |
amri.sys.exec_async{argv...} |
Launch a detached command (fire-and-forget, no shell); returns pid. Grant: run. |
amri.sys.gamepad
| Function |
Description |
amri.sys.gamepad.button(i) |
Whether gamepad button index i (0-based) is held. |
amri.sys.gamepad.axis(i) |
Raw value of gamepad axis index i (0-based; device-dependent range). |
amri.steam
| Function |
Description |
amri.steam.app_installed(appid) |
Whether the given Steam AppID is installed on this machine; false when Steam is unavailable. |
amri.steam.running_game() |
The running Steam game as {app_id, name, install_path}, or nil when no Steam game is running; name/install_path are empty strings when the install data cannot be resolved. |
amri.task
| Function |
Description |
amri.task.start(name[, args]) |
Launch a command as a background task; returns a handle. |
amri.task.start_sync(name[, args]) |
Launch and wait for a command. |
amri.task.stop(name) |
Stop all instances of a named task. |
amri.task.running(name) |
Whether a named task is running. |
amri.task.abort_all() |
Stop every background task. |
amri.task.panic() |
Emergency stop: abort tasks + release holds. |
amri.task.cancelled() |
Whether the current task has a pending cancel request; lets a cooperative loop exit before the forced unwind. False outside a task. |
amri.task.spawn(fn[, label]) |
Spawn a background task from a function (not a named command) and return a task handle (:cancel/:wait/:is_running). Args are captured by the closure; runs in the profile's sandbox. |
amri.task.while_held(control, name[, args]) |
Gate a task on a held control: the control's rising edge starts the named task (once), its release cancels it (cancel-at-yield unwind). control is a [[push_to_talk]] binding name. Returns the GATE handle -- :cancel() stops the gate and its current child; :is_running() reports whether the gate is armed. The modal-gated-loop primitive. |
Globals
| Function |
Description |
sleep_ms(ms) |
Sleep the current script for ms milliseconds. |
exit() |
Stop the current script immediately. |
using(...) |
Bring amri.* namespaces into the current chunk, e.g. using("input, speech"). |