Skip to content

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 (json or text)

Supported model aliases include:

  • whisper-1
  • openscreech-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 Token enabled 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.
  • /health succeeds.
  • 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

Visual Notes

  • TODO: add screenshot of the HTTP Transcription Service window with its status label.
  • TODO: add screenshot of Show Example cURL popover.
  • TODO: add GIF hitting /health then a transcription request.