Getting Started with SL5 Aura

Prerequisites: You have completed the setup script and configured your hotkey. If not, see the Installation section in README.md.

Step 1: Your First Dictation

  1. Start Aura (if not already running):

    ./scripts/restart_venv_and_run-server.sh

    Wait for the startup sound — that means Aura is ready.

  2. Click into any text field (editor, browser, terminal).

  3. Press your hotkey, say “Hello World”, press the hotkey again.

  4. Watch the text appear.

Nothing happened? Check log/aura_engine.log for errors. Common fix for CachyOS/Arch: sudo pacman -S mimalloc

Step 2: Write Your First Rule

The fastest way to add a personal rule:

  1. Open config/maps/plugins/sandbox/de-DE/FUZZY_MAP_pre.py

  2. Add a rule inside FUZZY_MAP_pre = [...]:

    ('Hello World', r'hello world', 0, {'flags': re.IGNORECASE})
#  ^ output        ^ pattern        ^ threshold (ignored for regex)

  3. Save — Aura reloads automatically. No restart needed.

  4. Dictate hello world and watch it become Hello World.

See docs/FuzzyMapRuleGuide.md for the full rule reference.

The Oma-Modus (Beginner Shortcut)

Don’t know regex yet? No problem.

  1. Open any empty FUZZY_MAP_pre.py in the sandbox

  2. Write just a plain word on its own line (no quotes, no tuple):

    raspberry

  3. Save — the Auto-Fix system detects the bare word and automatically converts it into a valid rule entry.

  4. You can then edit the replacement text manually.

This is called Oma-Modus — designed for users who want results without learning regex first .

Step 3: Learn with Koans

Koans are small exercises that each teach one concept. They live in config/maps/koans_deutsch/ and config/maps/koans_english/.

Start here:

Folder

What you learn

00_koan_oma-modus

Auto-Fix, first rule without regex

01_koan_erste_schritte

Your first rule, pipeline basics

02_koan_listen

Working with lists

03_koan_schwierige_namen

Fuzzy matching for hard-to-recognize names

04_koan_kleine_helfer

Useful shortcuts

Each koan folder contains a FUZZY_MAP_pre.py with commented examples. Uncomment a rule, save, dictate the trigger phrase — done.

Step 4: Go Further

What

Where

Full rule reference

docs/FuzzyMapRuleGuide.md

Create your own plugin

docs/CreatingNewPluginModules.md

Run Python scripts from rules

docs/advanced-scripting.md

DEV_MODE + log filter setup

docs/Developer_Guide/dev_mode_setup.md

Context-aware rules (only_in_windows)

docs/FuzzyMapRuleGuide.md