HTTP Transcription Service¶
What This Feature Does¶
The HTTP Transcription Service runs a local helper process that exposes an OpenAI-compatible transcription endpoint backed by OpenScreech local ASR.
Open its dedicated window from OpenScreech Home, the menu-bar Settings submenu, or App Settings → Management.
Design Rationale¶
The service exists so non-OpenScreech clients can reuse local transcription capabilities through a familiar API shape.
Benefits:
- decouples app UI from API request load
- supports local automation and integrations
- allows optional token protection and request capture
Managed Controls¶
| Control | Purpose |
|---|---|
| Enable local API | Start/stop helper lifecycle |
| Process transcriptions with a profile | Optionally run each request through a selected profile's processing pipeline |
| Profile | Choose the profile used when profile processing is enabled |
| Bind address | Choose loopback, specific interface, or all interfaces |
| Port | Listener port (default 8765) |
| Endpoint path override | Customize transcription path while keeping same backend |
| Require token | Enforce bearer auth |
| Token + regenerate | Manage API token lifecycle |
| Save requests | Persist request artifacts for audit/debug |
| Save folder | Configure capture location |
| Request history | Browse saved request artifacts or reveal their folder in Finder |
| Server URL + example cURL | Copy the effective endpoint or an example client request |
| Status + helper log | Runtime health visibility |
Endpoint Surface¶
| Endpoint | Method | Notes |
|---|---|---|
/health |
GET | Liveness check |
/v1/audio/transcriptions |
POST | OpenAI-compatible subset (or configured path override) |
Supported Request Shape¶
multipart/form-data fields:
file(required)model(required)response_format(jsonortext)
Supported model aliases include:
whisper-1openscreech-parakeet-v3
Transformation Examples¶
Example 1: response_format=text¶
If the audio says:
open screech local api test successful
A response_format=text request returns plain transcript text like:
open screech local api test successful
Example 2: response_format=json¶
The same audio with response_format=json returns JSON-wrapped text (OpenAI-compatible shape), for example:
{"text":"open screech local api test successful"}
Security and Network Posture¶
| Bind Mode | Exposure Level | Recommendation |
|---|---|---|
127.0.0.1 |
Local machine only | Best default |
| Specific interface | Local network segment | Use only on trusted networks |
0.0.0.0 |
All interfaces | Use with caution and token enforcement |
Example cURL¶
curl --silent --show-error \
-X POST "http://127.0.0.1:8765/v1/audio/transcriptions" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@/path/to/audio.m4a" \
-F "model=whisper-1" \
-F "response_format=json"
Operational Guidance¶
- Use loopback binding unless remote clients are explicitly required.
- Keep
Require Tokenenabled for any non-loopback exposure. - Enable request saving during integration debugging, then disable if storage churn is unnecessary.
- Use helper log/status to diagnose startup issues.
Profile Processing Queue¶
When profile processing is enabled, primary request work begins in arrival order. Each request waits only for the selected final-output chain, Auto Tag, and Trigger Routing match detection before its response becomes ready.
Once that response is ready, the next queued request can begin while the earlier request's ordered Trigger Routing actions, Screechback, Saved Outputs, and Notes continue in the background. Actions remain sequential inside each request's Trigger Routing block, but blocks from different requests may overlap. A side-branch failure is recorded without invalidating an independent successful response; a failure in the selected final-output ancestry fails the request.
Screechback has one playback channel, so a newer spoken response replaces an earlier response that is still being generated or played.
Common Pitfalls¶
| Pitfall | Symptom | Fix |
|---|---|---|
| Port conflict | Service fails to start | Change port and retry |
| Invalid path override | Requests 404 or fail routing | Use path-only override like /v1/audio/transcriptions |
| Token mismatch | 401/authorization failures | Regenerate token and update clients |
| Overexposed bind config | Unexpected remote access | Return to loopback or enforce token/network boundaries |
Validation Checklist¶
- Service status reaches
Running. /healthsucceeds.- Transcription request succeeds with expected response format.
- Request history appears when saving is enabled.
In-App Help Cues For This Feature¶
In HTTP Transcription Service, use ? help beside:
- bind address
- endpoint path override
- token requirement
- save request behavior
Quick Tips¶
- Network binding and authentication are separate controls. Choosing loopback limits reachability, while requiring a token controls who can use an address they can reach.
- Saved request artifacts can contain uploaded audio, filenames, client information, and processed text. Use them for diagnosis, then disable or manage retention deliberately.
See Also¶
- Trigger Routing Libraries
- Add Transcription to Your App
- Output Formats Explained
- Run Tools with Voice Commands
- Troubleshooting
- In-App Help Cues (? Buttons and Hover Tooltips)
Visual Notes¶
- TODO: add screenshot of the HTTP Transcription Service window with its status label.
- TODO: add screenshot of
Show Example cURLpopover. - TODO: add GIF hitting
/healththen a transcription request.