LLM Post-Processing Guide (Ollama and OpenAI-Compatible)¶
What This Feature Does¶
LLM post-processing takes transcript text and sends it to a language model for optional rewriting.
Common uses:
- punctuation and grammar cleanup
- formatting into markdown
- meeting summaries
- style normalization
- using text selected in the frontmost app as prompt context
- sending the same transcript to multiple endpoints
- building cleanup, extraction, and formatting branches
In practical terms, this can be as small as cleaning a dictated prompt before it is pasted into Codex or Claude Code, or as involved as sending the same transcript to several specialist endpoints for required analysis.
This feature appears in multiple places in OpenScreech:
- Profiles select processors for live-dictation graph stages.
- Meeting Recording selects one processor for its optional
.llm.txtoutput. - Transcribe File(s) selects one processor for optional per-file
.llm.txtoutput.
Where It Runs in the Pipeline¶
When enabled, LLM runs after ASR and after word replacements.
Primary dependency order:
- ASR transcript
- Word replacements (if enabled)
- Profile LLM processor graph (if enabled)
- Auto Tag and Trigger Routing match detection on the selected final output
- Primary delivery: paste/History or an HTTP response
Independent work does not wait for that whole list to finish. Raw, original, and word-replaced artifacts can start saving before LLM completion. Unrelated LLM branches, ordered Trigger Routing actions, Screechback, Saved Outputs, and Notes can continue after the primary transcript is ready.
Shared Processor Library¶
Named provider, endpoint, model, prompt-delivery, timeout, credential, custom-header, and wrapping configurations live in the reusable LLM Post-Processing Library. Profiles, Meeting Recording, and Transcribe File(s) store references to those processors rather than copying their configuration.
This means:
- editing a processor immediately updates every workflow that selects it
- Meeting Recording and Transcribe File(s) can select the same processor or different processors
- each workflow keeps its own enable and output-payload toggles
Edit Processor...opens the selected entry in the libraryTest LLM Post-Processing...stays live as the processor or selection changes- processors referenced by profiles, Meeting Recording, or Transcribe File(s) cannot be deleted
Profile Graphs¶
Each profile builds its processing graph from stage instances that reference shared processors.
Every stage selects one input:
Original text: the transcript after word replacements- the output of any preceding stage
Only preceding stages are offered, so self-references, forward references, and cycles cannot be created.
The profile separately selects its final output from Original text or any stage. All configured stages still execute, including branches that are not selected as the final text.
Simple Sequence¶
New stages default to the preceding stage, so the ordinary setup remains straightforward:
Original → Grammar Cleanup → Markdown Formatter → Final
Parallel Branches and Fan-Out¶
Selecting the same input for multiple stages creates parallel work:
Original → Grammar Cleanup ─┬→ Markdown Formatter → Final
└→ Extract Tasks
Original ─────────────────────→ Archive Endpoint
When a stage's selected input becomes available, that stage becomes ready. If several stages directly select the same newly available input, OpenScreech initiates their requests in profile order. After each request is submitted, the next ready request is initiated immediately; it does not wait for a sibling's response or result. The submitted requests continue concurrently and do not become dependent on one another.
Each stage output becoming available is a separate readiness event. If different stage outputs become available at nearly the same time, their downstream groups initiate independently; there is no graph-wide submission queue. A dependent stage still starts only after its own selected source produces an output. The selected final-output branch determines when the primary transcript is ready, while unrelated branches may continue afterward as part of the same Processing Run.
Branches are useful for specialist work such as classification, action extraction, or policy review. They are not independent saved-output channels: only the profile's selected final result continues into normal transcript saving, and side-stage results are not separately saved.
Screechback is one exception to that delivery limitation: it can select any configured stage as its spoken text source even when another stage is the final profile output. It still does not persist that side-stage text as a separate transcript artifact.
Enabling and Disabling Stages¶
The profile has a master LLM switch and every stage has its own enabled switch. A disabled stage:
- makes no LLM request
- returns its selected input as its stage output
- keeps downstream dependencies connected
This makes it safe to temporarily turn off one processor without rebuilding the graph.
Using Selected Text¶
A profile can capture the text selected in the frontmost application when hotkey dictation starts. This context is available to individual stages through {{SELECTED_TEXT}}.
The prompt and selected-text controls must be enabled:
- Turn on
Capture Selected Textfor the profile. - Turn on
Use Selected Textfor each stage that needs it. - Keep
Send system promptenabled for the selected processor.
Add {{SELECTED_TEXT}} anywhere in the referenced processor's system prompt. Every exact, case-sensitive occurrence is replaced with the captured text. If the application exposes no selection, the variable is replaced with an empty string.
OpenScreech captures the selection once from the frontmost application when hotkey dictation starts. It first reads the focused control through macOS Accessibility without inspecting the control's complete value. If that does not provide a selection, it can press the application's enabled Copy menu item through Accessibility without simulating keyboard input. This capture is available only to interactive hotkey dictation; file transcription, long-form recording, and HTTP transcription do not inspect the frontmost app.
Selected text is sent to every endpoint used by a participating stage, so review it before using remote OpenAI-compatible processors.
Test Selected-Text Capture¶
The processor tester's Simulated Selected Text field verifies prompt substitution and the LLM request, but it does not read a selection from another application. To test the complete macOS Accessibility capture path, temporarily use this system prompt:
This is a strict variable-substitution test.
Ignore the user message completely. Never copy or transform the user message.
The captured value is between BEGIN_CAPTURE and END_CAPTURE.
BEGIN_CAPTURE
{{SELECTED_TEXT}}
END_CAPTURE
If there are no characters between the markers, return exactly:
NO_SELECTED_TEXT_CAPTURED
Otherwise, return only the characters between the markers exactly as provided.
Then:
- Enable LLM post-processing and
Capture Selected Texton the profile. - Enable the stage and its
Use Selected Textcheckbox. - Select distinctive text in the target application before pressing the profile hotkey.
- Dictate a short, unrelated phrase and complete the capture.
- Check the LLM output:
- The distinctive selected text means Accessibility capture worked.
NO_SELECTED_TEXT_CAPTUREDmeans OpenScreech could not obtain a usable selection from the target application or control.- The dictated phrase means the model ignored the diagnostic instruction and used its separate user message.
Native text controls and web-rendered content can expose selections differently. OpenScreech checks the focused element and a bounded number of its ancestors, supporting direct selected text, selected character ranges, and web-view text-marker ranges. If the normal lookup fails, OpenScreech asks the frontmost app to expose its standard Accessibility surface and re-queries immediately. Electron apps can also expose a supported manual Accessibility mode; OpenScreech enables it only for the synchronous query and restores only the setting it changed.
As a final fallback, OpenScreech presses the target app's enabled Copy menu item through Accessibility without simulating keyboard input. It snapshots the clipboard, waits for at most 200 milliseconds at capture start, and restores the snapshot only when doing so will not overwrite a concurrent clipboard change. This runs only for profiles and enabled processors that request selected text; there is no ongoing selection or clipboard monitoring.
If capture fails:
- Confirm OpenScreech still has Accessibility permission in System Settings.
- Confirm both selected-text controls are enabled and the exact, case-sensitive
{{SELECTED_TEXT}}variable is present. - Select the text before activating the hotkey and keep the target application frontmost.
- Confirm the target application's standard Copy command is enabled for the selection.
- Try a native text control such as Notes to distinguish OpenScreech configuration from application-specific Accessibility support.
- Remember that an empty capture deliberately replaces
{{SELECTED_TEXT}}with an empty string; the dictated transcript remains a separate LLM user message.
Failure and Output Behavior¶
- A failed stage blocks only stages that depend on it. Successful sibling branches continue normally.
- A failure in the selected final-output ancestry prevents primary transcript delivery; an unrelated side-branch failure does not.
- The selected final stage result is the existing saved LLM transcript.
- Individual side-stage results are not currently written as separate artifacts.
- When Original is the final output, OpenScreech treats it as plain-text paste input.
Provider Options¶
| Provider | Plain-English Meaning | Typical Use |
|---|---|---|
| Ollama | Local model runtime on your machine | Privacy/local workflows |
| OpenAI-Compatible | Any API endpoint that follows OpenAI-like request shape | Hosted or self-hosted remote services |
Processor Settings¶
| Setting | What It Means | Recommendation |
|---|---|---|
| Profile/stage enable controls | Turn the graph or an individual profile stage on/off | Start the profile Off, then enable after testing |
| Provider | Ollama or OpenAI-compatible endpoint | Use what your environment already supports |
| Endpoint URL | Server address | Keep default for Ollama; verify for hosted endpoints |
| API Key | Auth token if required | Required for most hosted services |
| Timeout (s) | Max wait time for model response | 30-60 good starting range |
| Model | Specific model name | Start with smaller model, scale up if needed |
| System Prompt | Instructions to model; supports the exact {{SELECTED_TEXT}} variable |
Keep specific and short |
| Send system prompt | Includes the System Prompt as a separate system message; enabled by default |
Disable when the endpoint or agent should receive only the user message |
| Custom Headers | Additional enabled HTTP headers for OpenAI-compatible processing and model-list requests | Use for gateway routing or non-standard authentication; leave empty otherwise |
| Wrapping Tags (prefix/suffix) | Extra text added around transcript before request | Leave empty unless your prompt expects tags |
Custom Headers appear only for OpenAI-compatible processors. Use Add Header to create a row, its checkbox to temporarily exclude it, and the trash button to remove it. Blank header names and disabled rows are not sent. If an enabled custom header has the same name as a generated header such as Authorization or Content-Type, the custom value takes precedence. Header names containing common credential terms such as authorization, API key, token, or secret are redacted in the request preview, but remain sensitive configuration data in settings exports.
Individual processor exports, profile exports that reference a processor, and full settings exports all preserve the prompt-delivery setting and complete Custom Header rows. They also preserve API keys and real header values in unencrypted transfer files. See Settings Backup, Import, and Export before storing or sharing an export.
How Workflow Selection Works¶
The library is shared, but processor selection is per workflow:
- A profile can reference multiple processors and connect them as a graph.
- Meeting Recording selects one processor for completed meeting transcripts.
- Transcribe File(s) selects one processor for completed file transcripts.
Selecting the same processor intentionally shares future edits. Selecting different processors keeps the workflows independent. Long-form and file workflows do not capture text from the frontmost application, so {{SELECTED_TEXT}} is rendered as an empty string for those requests.
Meeting Recording also selects one Processor Input. Original Transcript is the backward-compatible default. Saved transcript text, speaker-labelled transcript, and word-level timing inputs become available only when their matching recording outputs are enabled. OpenScreech sends the selected representation as the chat request's user message after applying the processor's optional wrapping tags. The processor's instructions remain a separate system message unless Send system prompt is disabled.
Transformation Examples¶
Example 1: Cleanup Only¶
Input transcript:
today we need to finalize the release notes and check qa
Prompt intent:
- add punctuation
- keep meaning
Output:
Today we need to finalize the release notes and check QA.
Example 2: Markdown Structuring¶
Input transcript:
release checklist item one update docs item two run tests item three cut tag
Prompt intent:
- turn into concise markdown list
Possible output:
## Release Checklist
- Update docs
- Run tests
- Cut tag
Example 3: Meeting Summary¶
Input transcript: long meeting transcript
Prompt intent:
- summarize as decisions, action items, open questions
Possible output structure:
Decisions
- ...
Action Items
- ...
Open Questions
- ...
Starter Prompts¶
Safe Cleanup Prompt¶
Clean up punctuation and capitalization only.
Do not add new facts.
Return plain text.
Structured Notes Prompt¶
Convert the transcript into concise markdown notes.
Use short headings and bullet points.
Do not invent facts.
Meeting Summary Prompt¶
Summarize this meeting transcript.
Return sections: Decisions, Action Items, Risks, Open Questions.
Preserve names and dates exactly when present.
Testing Workflow (Recommended)¶
- Create or select a processor in the LLM Post-Processing Library.
- Configure its provider, endpoint, model, timeout, prompt, and optional wrapping.
- Select that processor in the target profile stage,
Recording Settings, or the Transcribe File(s) window. - Use
Test Processor...in the library orTest LLM Post-Processing...in the consuming workflow. - Enter a realistic sample transcript and inspect the outgoing request.
- For profile selected-text prompts, add
{{SELECTED_TEXT}}, enable both selected-text controls, and use realistic simulated selected text. - Adjust the prompt until output is reliable.
- Only then enable LLM output in the target workflow.
Common Pitfalls¶
| Pitfall | Symptom | Fix |
|---|---|---|
| Prompt too vague | Inconsistent output style | Add explicit output rules and format |
| Model too small for task | Weak summaries or formatting | Try a stronger model |
| Timeout too low | Frequent request failures | Increase timeout |
| Selected text missing | {{SELECTED_TEXT}} becomes empty or is not sent |
Enable capture on the profile, enable use on the stage, enable Send system prompt, and select text before starting dictation |
| Editing a shared processor unexpectedly changes another workflow | Multiple workflows select the same processor | Select or duplicate a different processor when independent behavior is required |
{{SELECTED_TEXT}} is empty in Meeting/File output |
Those workflows do not capture frontmost-app selection | Use selected-text context only in participating profile stages |
| Over-trusting output | Added details not in source | Use stronger "do not invent facts" constraints |
Quality and Safety Tips¶
- Keep source transcript artifacts (
.txt) for reference. - Compare LLM output with source when accuracy matters.
- For high-trust workflows, prefer conservative prompts.
- Use
.llm-request.jsonoutput in long-form/file workflows when debugging prompt/provider issues.
In-App Help Cues For This Feature¶
Use:
- the library's
?buttons for provider, timeout, model, prompt, and wrapping guidance - the processor picker help in Meeting and Transcribe File(s)
- hover text on edit, refresh, and test actions for quick reminders
Quick Tips¶
- A processor is a shared library object. Editing it immediately changes every profile, Meeting, or File workflow that references it; duplicate it first when one workflow needs to diverge.
- Every enabled side branch runs and reports its own outcome, but a side-branch failure blocks only its descendants and does not invalidate a successful selected final-output branch.
See Also¶
- After Your First Dictation
- Profiles
- Long-Form Recording
- Transcribe File(s)
- Output Formats Explained
- In-App Help Cues (? Buttons and Hover Tooltips)
- Dictate into Documents
- Record and Summarise Meetings
- Dictate Prompts for AI Tools
- Multi-Stage LLM Workflows
- Screechback
- Hear Summaries and Responses
- Glossary
Visual Notes¶
- TODO: add screenshot of profile LLM settings with field callouts.
- TODO: add screenshot of the Meeting processor picker and live test window.
- TODO: add screenshot of the File Transcription processor picker and live test window.
- TODO: add before/after image pair for cleanup and markdown outputs.