Skip to content

Profiles

What A Profile Is (In Plain English)

A profile is a saved behavior preset for dictation.

Think of it like a "mode" for OpenScreech.

  • One profile can be for everyday writing.
  • Another can be for coding notes.
  • Another can be for voice commands.

When you switch profile, you are telling OpenScreech: "process my speech this way."

For normal dictation, the hotkey selects the starting profile. Assign that relationship in Manage Hotkeys.... A profile's quick-switch key can change the profile during an active session, but it does not start dictation by itself.

Why Profiles Exist

People speak for different reasons, and one setup does not fit all situations.

Examples:

  • While writing, you may want auto-paste and light cleanup.
  • While automating commands, you may want trigger routing and no auto-paste.
  • While capturing structured notes, you may want saved transcript variants, tags, and audio.

Profiles let you separate these behaviors so they do not conflict.

Meeting Recording and Transcribe File(s) are separate workflows with their own preferences. They can share processors from the LLM Post-Processing Library, but they do not inherit a live-dictation profile.

Quick Mental Model

When you finish dictating, OpenScreech can run this profile-controlled flow:

  1. Speech-to-text (ASR)
  2. Word replacements (rule-based cleanup)
  3. LLM post-processing (optional rewriting/formatting)
  4. Auto Tag (optional deterministic labels)
  5. Trigger routing (optional actions like HTTP/shell)
  6. Screechback (optional local speech playback)
  7. Paste, temporary history, saved output artifacts, or Notes

A profile controls how each step behaves.

Profile Sections Explained

1) Profile Section

This is your core runtime behavior.

Setting What It Means Beginner Recommendation
Name Label for this profile in menus and editors. Use clear names like Writer, Commands, or Quick Paste.
Quick switch key Key to switch to this profile quickly. Set only for profiles you switch often.
Overlay position Where overlay appears on screen at start of dictation. Start with Center or Bottom Center.
Save dragged overlay position Remembers where you dragged overlay. Keep On unless you want fixed dropdown position only.
Background/Text/Meter color Visual theme for overlay. Optional; useful for distinguishing profiles quickly.
Meter smoothing How stable vs reactive the audio meter looks. Middle value is usually best.
Show peak marker Shows recent loudest point on meter. Keep On if you watch levels.
Auto paste into active window Paste result automatically when done. On for writing, usually Off for command profiles.
Add transcriptions to temporary history Keeps finished paste-ready outputs available in the History menu and for Left/Right Arrow overlay recall. Keep On unless privacy workflow says otherwise.

Plain-English tip: If you only change one thing to feel immediate value, set Name and Auto paste intentionally.

2) Word Replacements Section

This is deterministic cleanup before LLM.

Setting What It Means Beginner Recommendation
Enable word replacements Turn rule-based replacements on/off. Keep On for most writing profiles.
Word Replacement Library Choose which rule set to use. Start with a small library and expand slowly.

When to use this:

  • Fix product names (open screech -> OpenScreech)
  • Normalize acronyms (api -> API)
  • Add spoken formatting helpers (new paragraph -> blank line)

3) LLM Section

This is optional model-based text transformation after word replacements. Profiles select reusable processors from the LLM Post-Processing Library and arrange them as stages.

Setting What It Means Beginner Recommendation
Enable LLM Post-Processing Master switch for the profile's complete graph. Start Off, then enable after testing.
Capture Selected Text Captures selected text once from the frontmost application when hotkey dictation starts. Leave Off unless a stage prompt uses {{SELECTED_TEXT}}.
Add Processor Adds a reusable library processor as a profile stage. For a simple workflow, add processors in the order they should run.
Stage Enabled Makes that stage's request or passes its input through unchanged. Disable temporarily without rewiring downstream stages.
Use Selected Text Allows this stage to replace {{SELECTED_TEXT}} in its processor's system prompt. Enable only on stages that need the selected text.
Input Source Original word-replaced text or the output of an earlier stage. Keep the default previous-stage input for a normal sequence.
Final Output Text sent to auto tag, trigger routing, paste, saves, and the HTTP response. Keep the last stage unless you intentionally want a side branch or Original.
Manage Library Opens reusable endpoint, model, prompt, timeout, key, and wrapping settings. Give processors task-focused names such as Grammar Cleanup.

Important behavior:

  • The first stage defaults to Original text. Each later stage defaults to the preceding stage.
  • When several stages directly select the same newly available input, their requests initiate in profile order and then continue concurrently without waiting for sibling results.
  • One stage can feed several later stages.
  • Disabled stages make no network request and expose their selected input as their output.
  • Each LLM stage becomes ready when its own selected input is available. Groups becoming ready from different stage outputs initiate independently, and a failure blocks only dependent stages.
  • The selected final-output branch controls when the primary transcript is ready. Unrelated LLM branches may continue in the background Processing Run.
  • A Processing Run begins with capture or server-profile processing and remains active until every configured stage has succeeded, failed, been blocked, skipped, or been cancelled.
  • Output artifacts are written independently as they become available; a failed write is recorded without cancelling successful sibling writes.
  • Selecting Original as final output keeps paste input effectively plain text even when side stages ran.
  • Library settings are shared. Editing a processor changes every profile stage that references it.
  • Selected text is captured only when the profile and at least one enabled stage request it.
  • Capture happens once from the frontmost app at hotkey activation. OpenScreech first reads through macOS Accessibility and, if needed, presses the app's enabled Copy menu item through Accessibility without simulating keyboard input. The fallback briefly uses the clipboard and restores it when doing so will not overwrite a concurrent change.
  • OpenScreech does not monitor selections or the clipboard in the background.
  • {{SELECTED_TEXT}} is exact and case-sensitive. It becomes an empty string when no selection is available.
  • A participating remote processor receives the selected text as part of its prompt.
  • The processor tester uses simulated selected text; use the diagnostic prompt in the LLM Post-Processing Guide to test capture from another application.

4) Trigger Routing Section

This runs actions when matching phrases are found.

Setting What It Means Beginner Recommendation
Enable trigger routing Turn route matching/action execution on/off. Keep Off unless you actively use automations.
Trigger Routing Library Which route set to use. Use a dedicated library per workflow.
Disable auto paste on trigger routing If a route matches, skip normal paste without waiting for its action to finish. Strongly recommended for command/automation profiles.

Plain-English warning: Trigger routing is powerful. Keep it in dedicated profiles to avoid accidental actions while normal dictating.

5) Screechback Section

Screechback turns a selected text result into local speech as an independent Processing Run branch. Synthesis and playback do not delay paste, temporary history, Saved Outputs, Notes, or ordered Trigger Routing actions.

Setting What It Means Beginner Recommendation
Enable Screechback Generates and plays speech after profile processing. Leave Off until the model and voice pass a test.
Text source Uses the final profile output or one configured LLM-stage result. Choose a concise summary stage for useful spoken feedback.
Speech model Selects a downloaded FluidAudio text-to-speech model. Match the language and desired speed/quality.
Voice Selects one voice or style included with the model. Compare realistic text with Test Screechback….
Language Selects pronunciation language for Supertonic-3. Match the selected text source.

The choices remain editable when Screechback is disabled. Selecting a speech model checks that model's installed state. The profile shows its status, upstream download source, local destination, Show in Finder, and a confirmed Delete Model & Voices… action; missing or deleted resources can be downloaded there or under App Settings → Local Speech Models & Voices. In-app downloads and deletions update status immediately.

Screechback and Trigger Routing run independently after their inputs are known. Trigger actions do not currently provide response text as a Screechback source; the available sources are the final profile output and configured LLM stages.

See Screechback for model, voice, testing, privacy, and current-boundary details.

6) Paste Section

This controls how OpenScreech inserts output into other apps.

Setting What It Means Beginner Recommendation
Paste input format Semantic type of output text: plain, markdown, html. If unsure, use Plain Text.
Paste format Final clipboard/paste format: plain, rich text, html, auto. Start with Auto or Plain Text based on target app behavior.

Simple interpretation:

  • Input format = what the text is
  • Paste format = how you deliver it

If results look strange in your app, set both to plain text first.

How this works on macOS:

  • OpenScreech writes content to the macOS pasteboard (clipboard).
  • Apps read the pasteboard and choose the format they support/prefer.
  • With Auto (Multi-format), OpenScreech provides multiple clipboard representations (for example plain text + rich text + HTML), and the destination app picks one.

Practical rule:

  • Destination app behavior is part of the result.
  • Same dictation can paste differently in different apps because each app chooses different clipboard types.

Temporary History and Recall

When Add transcriptions to temporary history is enabled, OpenScreech keeps up to 10 finalized results in memory:

  • Use the menu History list to copy a result to the clipboard.
  • During an active dictation overlay, press Left Arrow to browse backward and Right Arrow to move forward.
  • The overlay shows Recalling · n back and previews the exact result selected for paste.
  • Arrow-key release does not paste. Complete using the profile hotkey's normal push-and-hold or toggle action.
  • Recall reuses the stored text and paste formatting without running the profile's transcription or processing pipeline again.
  • Moving right past the newest recalled result returns to fresh Listening; Escape cancels.

Temporary history is memory-only and is cleared when OpenScreech exits.

Example (LLM returns markdown):

## Sprint Update
- Fixed login bug
- Added tests

Example 1: Markdown-aware writing app

Profile:

  • Paste input format = Markdown
  • Paste format = Auto

Likely result:

  • App interprets markdown semantics and may render a heading + bullet list.

Example 2: Visual Studio Code (plain editor behavior)

Profile:

  • Paste input format = Markdown
  • Paste format = Plain Text (recommended for predictable code/editor paste)

Likely result:

  • VS Code receives literal markdown text:
## Sprint Update
- Fixed login bug
- Added tests

Why this is useful:

  • Keeps source markdown literal in code/docs files.
  • Avoids rich-text/HTML surprises in developer editors.

Quick presets:

Destination App Type Paste Input Format Paste Format
Markdown-aware note app Markdown Auto
Code editor (VS Code, etc.) Markdown or Plain Text Plain Text
Unknown/mixed app Plain Text Auto (or Plain Text for strict predictability)

7) Auto Tag Section

Auto Tag attaches deterministic labels after LLM processing and before trigger routing. It does not rewrite the text.

Setting What It Means Beginner Recommendation
Enable Auto Tag Runs phrase-to-tag matching on the final processed text. Keep Off until you have a clear organization need.
Auto Tag Library Selects the reusable rules to evaluate. Start with a few specific phrases and tags.
Inline fallback rules Profile-specific rules used when the selected library has no rules. Prefer a shared library for normal use.

Tags become persistent when the profile writes a Note. See Auto Tag for matching details.

8) Notes Section

Notes keep a complete capture together as a searchable bundle instead of separating artifacts by type.

Setting What It Means Beginner Recommendation
Save to Notes Creates a persistent note from available capture artifacts and updates it as later selected output and tags arrive. Enable when a capture should outlive temporary history.
Notes folder Category beneath the Notes root, with / available for nested folders. Start with Inbox.
Artifact toggles Choose audio, original, word-replaced, and LLM transcript variants. Keep the original transcript and add only variants you use.

Temporary history, Notes, and Saved Outputs are independent. See Notes for search, storage, root-folder, and deletion behavior.

9) Saved Outputs Section

This controls optional file saving for dictation artifacts.

Setting What It Means Beginner Recommendation
Enable Saved Outputs Turn file artifact saving on/off. Keep Off unless you need archives/logs.
Root Directory Main folder for saved files. Use a dedicated folder you can find easily.
Subdirectories Per-artifact folders under root. Keep defaults at first; simplify later if needed.
Save only if duration >= (ms) Ignore very short captures. Keep around 1000ms initially.
Artifact toggles Choose what to save (audio/transcripts variants). Enable only what you actually use.

Why this exists: It prevents clutter and lets advanced users keep audit trails.

Beginner Preset (Start Here)

If this all feels new, create one profile called General with:

  • Auto paste: On
  • Temporary history: On
  • Word replacements: On (small library)
  • LLM: Off at first
  • Trigger routing: Off
  • Screechback: Off until a speech model and voice have been tested
  • Paste input format: Plain Text
  • Paste format: Auto
  • Notes: Off until you want persistent captures
  • Saved outputs: Off

Use this for a few days. Then enable one advanced feature at a time.

Common Confusions and Easy Answers

Confusion Easy Answer
"Do I need multiple profiles?" Not at first. Start with one good General profile.
"Why did my output not paste?" Auto paste may be off, or suppressed by trigger-routing setting.
"Why did text look different than I said?" Word replacements and/or LLM processing changed it.
"Why didn't profile switch move overlay?" Overlay position is chosen at start of dictation session.
"Why do I get plain text even with markdown selected?" If LLM is off, behavior is effectively plain text.
"Why didn't Screechback speak?" Check the hotkey's profile, enable switch, model status, selected source, and Mac output volume.

Suggested Baseline Profile Set (When You Are Ready)

Profile Purpose LLM Trigger Routing Screechback Auto Paste
General Everyday dictation Optional Off Off On
Writer Structured writing On Off Optional On
Developer Commands Automation triggers Usually Off On Off Off or suppressed on route
Voice Notes Persistent searchable captures Optional Off Optional Optional

Use the separate Meeting Recording workflow for long sessions, recording audio, diarisation, and caption artifacts.

Managing Profiles (Add, Remove, Order, Duplicate, Import, Export)

This is how profile management actions behave in OpenScreech.

Add Profile

What it does:

  • Creates a new profile named like Profile N.
  • Uses the currently selected profile as the template for most settings.
  • Selects the new profile immediately.

Why this is useful:

  • Fast way to create a variation without configuring everything from scratch.

Plain-English implication:

  • If your current profile has unusual settings, the new one will inherit them.

Remove Profile

What it does:

  • Deletes the currently selected profile.
  • Automatically selects the first remaining profile.

Important rule:

  • You cannot remove the last remaining profile.

Why this is useful:

  • Prevents the app from ending up with no usable profile.

Reorder Profiles (Move Up / Move Down)

What it does:

  • Changes profile order in the Profiles list and Profiles menu.
  • Reordering swaps positions.

What ordering affects:

  • Visual/menu order (what users see first in profile lists).
  • The first profile in order is treated as the default profile context in some startup/default behaviors.

What ordering does not do:

  • It does not automatically change your hotkey assignments.

Beginner recommendation:

  • Keep your most-used profile near the top.

Duplicate Profile

What it does:

  • Creates a copy directly below the source profile.
  • Copies nearly all settings.
  • Clears quick-switch key on the duplicate to avoid key conflicts.
  • Selects the duplicate immediately.

Why this is useful:

  • Safest way to experiment with "variant" profiles.

Import Profiles

What it does:

  • Adds selected profiles from JSON into your existing list.
  • If an imported profile ID already exists, OpenScreech creates a new ID.
  • If an imported quick-switch key conflicts with existing profiles, the imported key is cleared (Unassigned).

Why this is useful:

  • Merge shared/team presets without breaking existing profile identity or key uniqueness.

After import, always check:

  • Quick-switch keys
  • Hotkey mappings, which are managed separately
  • Referenced post-processors and any credentials their endpoints require
  • LLM endpoint/API key values
  • Library assignments

Export Profiles

What it does:

  • Writes selected profiles to JSON.
  • Includes selected-profile metadata in export when relevant.
  • Bundles every LLM processor referenced by the selected profiles' stages.
  • Preserves those processors' prompts, API keys, and Custom Header values.

Security implication:

  • Profile JSON is unencrypted and may contain working credentials. Store and share it securely.

Why this is useful:

  • Backup before major edits.
  • Share curated profile packs with collaborators.

Profile Management Example (Safe Editing Workflow)

  1. Select Writer profile.
  2. Click Duplicate -> new profile appears as Writer Copy.
  3. Rename to Writer - Experiment.
  4. Change only one variable (for example, enable LLM).
  5. Test for a day.
  6. Keep, reorder, or remove based on results.

This pattern avoids accidental regression in your stable profile.

Import and Export

Profiles can be imported/exported as JSON.

Use this when:

  • You want backups before major changes.
  • You want to share a team preset.
  • You are moving to another machine.

After import, re-check quick-switch keys, hotkey mappings, referenced post-processors, and any credentials required by their endpoints. See Settings Backup, Import, and Export for the complete portability and sensitive-data details.

Validation Checklist

  • Profile name clearly states purpose.
  • The intended hotkey maps to this profile.
  • Auto paste behavior matches your intent.
  • LLM and trigger routing are only enabled where needed.
  • Paste settings behave correctly in your target app.
  • Notes settings retain only the artifacts you intend.
  • Saved-output folder paths are valid if enabled.

In-App Help Cues For This Feature

In Manage Profiles..., many settings include:

  • ? inline help with click popovers
  • hover tooltips for additional context

If you forget a setting meaning while editing a profile, check the nearby ? first.

Glossary (Beginner-Friendly)

Term Meaning
ASR Automatic speech recognition. Converts your voice to text.
LLM Language model. Can rewrite, clean, or transform text.
Trigger routing If certain words appear, OpenScreech can run an action (HTTP/shell).
Auto paste Automatically inserts output into the app you are currently using.
Overlay Small on-screen panel that shows dictation status and preview text.
Temporary history Short in-app memory of recent transcriptions (up to 10).
Wrap tags Optional text added before/after transcript before sending to LLM.
Paste source format What your text "means" semantically (plain text, markdown, html).
Paste format What format is sent to target app (plain, rich text, html, auto).

See the full glossary for processing, storage, recording, caption, and service terminology.

Transformation Examples (Input -> Output)

These examples show what actually changes as each feature is enabled.

Example A: Word Replacements Only

Input speech (ASR text):

open screech api docs new paragraph bullet point first task

Profile settings:

  • Word Replacements: On
  • LLM: Off
  • Trigger Routing: Off

Word replacement rules:

  • open screech -> OpenScreech
  • api -> API
  • new paragraph -> \n\n
  • bullet point -> -

Output text:

OpenScreech API docs

- first task

Example B: Word Replacements + LLM Cleanup

Input speech (ASR text):

today we reviewed the release timeline and we need to confirm qa by friday

Profile settings:

  • Word Replacements: On
  • LLM: On
  • LLM prompt intent: improve punctuation and readability
  • Trigger Routing: Off

Possible output text:

Today we reviewed the release timeline, and we need to confirm QA by Friday.

What changed:

  • Casing and punctuation improved
  • Acronym normalized (qa -> QA)
  • Meaning preserved

Example C: Trigger Routing Match With Auto-Paste Suppressed

Input speech (post-LLM text):

run tests for auth module

Profile settings:

  • Trigger Routing: On
  • Route trigger: run tests
  • Disable auto paste on trigger routing: On

Route template:

echo {{AFTER_TRIGGER}}

Rendered command:

echo for auth module

Result:

  • Command/action runs
  • Text is not pasted into active app (because suppression is enabled)

Example D: Paste Format Difference

Output text from pipeline:

# Summary
- Item one

If Paste input format = Plain Text and Paste format = Plain Text:

  • destination receives literal # Summary and - Item one

If Paste input format = Markdown and Paste format = Auto:

  • destination may receive formatted heading/list (depends on app support)

Quick Tips

  • Selecting a profile in the editor does not change existing hotkey mappings. If runtime behavior surprises you, check the hotkey's Profile field first.
  • Duplicate a known-good profile before experimenting. The copy preserves the working pipeline but clears its quick-switch key to avoid a conflict.

See Also

Visual Notes

  • TODO: add screenshot of profile editor with numbered callouts for each section.
  • TODO: add screenshot explaining Paste input format vs Paste format.
  • TODO: add screenshot of a simple General profile preset.
  • TODO: add GIF showing profile switch and behavior differences.