Auto-switch¶

Amri can activate a profile on its own when you switch to a game, so the right commands are live without you saying or pressing anything. A profile declares which games it belongs to, and Amri switches to it when one of them takes focus.

How it works¶

Amri watches which application is in focus and which game is running, and picks the profile that claims it. A profile advertises its games with two fields in [profile]:

steam_app_ids is a list of Steam AppIDs (the number Steam uses to identify a game). Amri switches to this profile when a game with a listed AppID is running.
app_match is a list of patterns matched against the focused window's title or process name. Patterns may use * as a wildcard. Amri switches to this profile when the focused window matches one of them.

A profile can carry both. Use app_match for desktop applications such as editors, browsers, and terminals, and steam_app_ids for games.

Amri stays single-active¶

Exactly one profile is active at any moment. When you move from a game to your desktop and back, Amri switches the active profile to follow, and the previous one steps aside. There is no fixed priority between two profiles that both claim the same application: rather than guess, Amri treats that as an ambiguity for you to resolve, not a silent pick.

A held profile-override key (covered elsewhere) outranks auto-switch while it is down, and a configured default profile is the fallback when nothing else claims focus.

Where auto-switch may be unavailable¶

On some systems Amri cannot see which game window is focused. On KDE Plasma running under Wayland, and on the Steam Deck, the desktop does not report game windows to Amri's focus detection, so app_match cannot see a running game there. Steam-launched games are still detected by their AppID on those systems, immediately and reliably. This is the reason to prefer steam_app_ids for games: it works everywhere, while app_match depends on focus detection being available.

Example¶

A profile that activates for Elite Dangerous, matched both by its Steam AppID and by its launcher window:

[profile]
name = "elite_dangerous"
description = "Voice commands for Elite Dangerous."

# Activate when this Steam game is running (works on Plasma Wayland and Deck).
steam_app_ids = [359320]

# Activate when a window whose title or process matches one of these is focused.
app_match = ["*Elite*Dangerous*", "*EDLaunch*"]

AppID over window match for games

When a profile targets a game, list its steam_app_ids. The AppID signal is reliable on every supported system, including the ones where window focus is not reported to Amri. Reserve app_match for desktop applications, or add it alongside the AppID as a second route.