Create spoken macros and snippets¶

If you type the same boilerplate over and over — a signature, a standard reply, a code stub — you can bind it to a spoken trigger phrase. Say the trigger and YazSes types the expansion. Two features do this, both off by default, and they are invoked differently — one matches the trigger on its own, the other needs a verb in front of it. That difference is called out where it matters below.

Say-Macro (macros) — the fuller mechanism: triggers live in a dedicated macros.toml, support text and snippet expansions, and can place the caret with a ${cursor} marker and substitute ${clipboard}, ${date}, ${time}, and ${author}.
Voice Snippets (snippets) — a lightweight inline expander: trigger → template pairs configured directly in config.toml under [snippets]. It runs through the spoken-command router, so you say insert <trigger> (or expand <trigger>, or snippet <trigger>) rather than the trigger on its own.

Both match on the whole utterance, anchored at both ends, so a trigger appearing inside ordinary prose never fires mid-dictation.

Say-Macro¶

1. Enable the feature¶

yazses features enable macros

2. Write your macros¶

Create macros.toml next to config.toml (~/.config/yazses/macros.toml). Each macro is a [[macro]] table:

# ~/.config/yazses/macros.toml
[[macro]]
trigger = "insert my signature"
type = "text"
text = "Best regards,\nMohsen"

[[macro]]
trigger = "new python function"
type = "snippet"
snippet = "def ${cursor}():\n    pass"

[[macro]]
trigger = "today's date"
type = "text"
text = "${date}"

type = "text" or type = "snippet" — both type their body; snippet is meant for code and supports the ${cursor} marker, which leaves the caret where you put it after typing.
Placeholders ${clipboard}, ${date}, ${time}, ${author} are substituted at expansion time. ${author} comes from [macros] author.

3. Point the config at the file (optional) and restart¶

[macros] path defaults to macros.toml (relative to the config dir), so the file above is found automatically. To use a different location or set the author:

# config.toml
[macros]
enabled = true            # written by `yazses features enable macros`
path = "macros.toml"      # relative to config dir, or an absolute path
author = "Mohsen"         # value substituted for ${author}

yazses restart            # apply

A broken macro entry is skipped and logged — it never breaks the daemon.

Voice Snippets¶

For simple text expansions without a separate file, use [snippets] in config.toml. Snippets run in command mode, so bind a command key first (any key other than your dictation key):

yazses hotkey command right_ctrl
yazses features enable snippets

# config.toml
[snippets]
enabled = true
[snippets.entries]
"my signature" = "Best regards,\nMohsen"
"my address" = "1 Example Street, Bologna"

yazses restart

Hold the command key and say insert my signature — YazSes types the stored template. Said on the dictation key, the same words are typed as text.

Write the trigger without the verb

The verb is part of how you invoke a snippet, not part of the trigger. YazSes strips a leading insert, expand, snippet or paste snippet and matches what is left, so an entry keyed "insert my signature" can never fire — you would have to say "insert insert my signature". Key it "my signature".

The verb is also required: saying my signature on its own dictates those two words, which is what stops a snippet trigger from firing inside ordinary prose.