Skip to content

Trigger Routing Libraries

What This Feature Does

Trigger Routing Libraries detect configured phrases in dictation output and execute an action:

  • HTTP/HTTPS request
  • shell command template

Design Rationale

Trigger routing bridges dictation and automation. It allows natural language intent capture while preserving explicit, auditable execution rules.

Core design choices:

  • phrase-based matching for clarity
  • explicit action templates with limited variables
  • preview/test tooling before runtime use

Route Model

Element Description
Route name Human-readable identifier
Route enabled Global toggle for the route
Trigger phrases One or more phrase matchers
Trigger enabled Per-trigger toggle
Match mode Starts With, Contains, Ends With, Any Text
Case sensitivity Per-trigger casing control
Action type HTTP/HTTPS or shell command

Template Variables

Variable Meaning
{{TEXT}} Full processed transcript
{{BEFORE_TRIGGER}} Text before matched trigger
{{AFTER_TRIGGER}} Text after matched trigger
{{TRIGGER}} The matched trigger text

Matching and Split Routing Behavior

Behavior Explanation
Standard mode Evaluates routes independently and executes every enabled route that matches
Split routing enabled Splits one transcript into multiple trigger segments when multiple phrase triggers occur (Any Text does not create split chunks, but can run against each resulting chunk)
Trailing connector trimming Removes connector words (for example and, or) to improve segment quality

Runtime Ordering and Concurrency

Trigger matching stays on the primary processing path so the profile can decide whether Skip auto paste when trigger routing fires applies. That decision uses whether a route matched; it does not wait for the action to succeed or fail.

After matching, the actions for one transcription execute in their configured order inside one background Trigger Routing block. OpenScreech does not reorder or parallelize actions within that block. Paste, temporary history, Saved Outputs, Notes, Screechback, and HTTP responses do not wait for the block to finish. Blocks from separate Processing Runs may overlap, including consecutive HTTP profile requests.

An action failure is recorded on that Processing Run's Trigger Routing stage. It does not cancel independent output or delivery branches.

Transformation Examples

Example 1: HTTP Route Rendering

Input text:

create ticket login page error on safari

Route trigger:

  • phrase: create ticket

Payload template:

{"task":"{{AFTER_TRIGGER}}","source":"voice"}

Rendered payload:

{"task":"login page error on safari","source":"voice"}

Example 2: Shell Route Rendering

Input text:

run script clean build cache

Command template:

echo {{AFTER_TRIGGER}}

Rendered command:

echo clean build cache

Example 3: Split Routing

Input text:

email alice project update and email bob qa summary

With split routing enabled and trailing connector trimming, this can become two routing chunks:

  • segment 1: email alice project update
  • segment 2: email bob qa summary

Each chunk is then evaluated with the normal route-matching behavior, so multiple enabled routes can run per chunk.

Action Configuration Reference

HTTP/HTTPS Action

Field Purpose
Method Request verb (GET, POST, etc.)
Scheme/Host/Port/Path Endpoint construction
Headers Custom request metadata
Payload template Request body template with variables

Shell Command Action

Field Purpose
Command template Rendered shell command with variables

Command Designer Workflow

  1. Choose action type.
  2. Configure fields/templates.
  3. Enter sample transcription.
  4. Inspect rendered command preview.
  5. Run Test Command.
  6. Review response or error output.

This loop is critical for safety and correctness before real runtime use.

Managing Libraries, Routes, and Triggers

In Trigger Routing Libraries..., you can:

  • Add/duplicate/delete libraries
  • Import/export selected libraries
  • Add/rename/enable-disable routes
  • Add/enable-disable trigger phrases per route
  • Move between action types (HTTP or shell) per route

Beginner recommendation:

  • Start with one library and one route.
  • Validate route behavior with Test Command before adding more.

Safety Guidance

  • Keep command routes in dedicated profiles.
  • Start with harmless commands and local endpoints.
  • Enable Disable auto paste on trigger routing for command profiles.
  • Prefer wrapper scripts/services for complex logic instead of very long shell templates.

Common Pitfalls

Pitfall Symptom Fix
Trigger too generic Frequent accidental execution Tighten phrase and match mode
Case sensitivity mismatch Route not firing Align trigger casing strategy
Bad URL composition Test error / invalid URL Validate host/port/path fields
Unsafe shell template Unexpected side effects Use wrapper script and strict inputs

Validation Checklist

  • All routes pass command-designer test with sample transcripts.
  • Trigger phrases are specific enough to avoid false positives.
  • Auto-paste behavior during route matches is intentional.

In-App Help Cues For This Feature

In Trigger Routing Libraries..., check ? help beside:

  • split routing controls
  • route evaluation behavior
  • trigger-route configuration guidance

Quick Tips

  • Standard routing does not stop at the first match. Every enabled route that matches can run, so review overlapping phrases as a set.
  • Use the Command Designer with harmless sample actions first. A successful preview confirms template rendering; running the test confirms the endpoint or shell action itself.

See Also

Visual Notes

  • TODO: add screenshot of route editor with trigger list and action settings.
  • TODO: add screenshot of command designer preview and response pane.
  • TODO: add GIF running Test Command and showing response output.