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¶
- Choose action type.
- Configure fields/templates.
- Enter sample transcription.
- Inspect rendered command preview.
- Run
Test Command. - 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 Commandbefore adding more.
Safety Guidance¶
- Keep command routes in dedicated profiles.
- Start with harmless commands and local endpoints.
- Enable
Disable auto paste on trigger routingfor 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¶
- Profiles
- HTTP Transcription Service
- Run Tools with Voice Commands
- Troubleshooting
- In-App Help Cues (? Buttons and Hover Tooltips)
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 Commandand showing response output.