Skip to content

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.txt output.
  • Transcribe File(s) selects one processor for optional per-file .llm.txt output.

Where It Runs in the Pipeline

When enabled, LLM runs after ASR and after word replacements.

Primary dependency order:

  1. ASR transcript
  2. Word replacements (if enabled)
  3. Profile LLM processor graph (if enabled)
  4. Auto Tag and Trigger Routing match detection on the selected final output
  5. 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 library
  • Test 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:

  1. Turn on Capture Selected Text for the profile.
  2. Turn on Use Selected Text for each stage that needs it.
  3. Keep Send system prompt enabled 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:

  1. Enable LLM post-processing and Capture Selected Text on the profile.
  2. Enable the stage and its Use Selected Text checkbox.
  3. Select distinctive text in the target application before pressing the profile hotkey.
  4. Dictate a short, unrelated phrase and complete the capture.
  5. Check the LLM output:
  6. The distinctive selected text means Accessibility capture worked.
  7. NO_SELECTED_TEXT_CAPTURED means OpenScreech could not obtain a usable selection from the target application or control.
  8. 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.
  1. Create or select a processor in the LLM Post-Processing Library.
  2. Configure its provider, endpoint, model, timeout, prompt, and optional wrapping.
  3. Select that processor in the target profile stage, Recording Settings, or the Transcribe File(s) window.
  4. Use Test Processor... in the library or Test LLM Post-Processing... in the consuming workflow.
  5. Enter a realistic sample transcript and inspect the outgoing request.
  6. For profile selected-text prompts, add {{SELECTED_TEXT}}, enable both selected-text controls, and use realistic simulated selected text.
  7. Adjust the prompt until output is reliable.
  8. 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.json output 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

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.