Skip to content

Add Transcription to Your App

Goal

Use OpenScreech's local HTTP service so other tools (scripts, apps, automations) can send audio and receive transcripts.

When To Use This

  • You want transcription from shell scripts or local tools.
  • You want an OpenAI-compatible API shape without sending audio to a cloud service.
  • You want one transcription backend shared by multiple local workflows.

Why This Pattern Exists

Hotkey dictation is designed for interactive capture and paste.

The HTTP service exists for programmatic workflows.

It lets you integrate OpenScreech with:

  • local scripts
  • automation tools
  • custom apps
  • developer workflows

Preset: Safe Local Development Setup

Setting Where Value Why
Enable local API HTTP Transcription Service On Starts helper process
Bind address HTTP Transcription Service Loopback (127.0.0.1) Only this machine can access it
Port HTTP Transcription Service 8765 Default; easy script reuse
Require Token HTTP Transcription Service On Basic protection even on localhost
Save Requests HTTP Transcription Service On while testing, Off later Useful debugging during integration

First Request (End-to-End)

  1. Enable service and confirm status is Running.
  2. Copy the token from the HTTP Transcription Service window.
  3. Run:
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"
  1. Confirm response contains transcript text.

Preset: Trusted LAN Client Setup

Use this only when another trusted machine needs access.

Setting Value
Bind address Specific local interface (not 0.0.0.0 unless necessary)
Require Token On
Port Custom if needed to avoid conflicts
Save Requests On during rollout for debugging

Security note:

  • Prefer specific interface binding over 0.0.0.0.
  • Rotate token if shared broadly.

Transformation Examples

Example 1: Plain Text Response

Request uses response_format=text.

Audio says:

open screech api transcription check

Response body:

open screech api transcription check

Example 2: JSON Response

Request uses response_format=json.

Response body shape:

{"text":"open screech api transcription check"}

Operational Checklist

  • Service status is Running.
  • Health endpoint works (GET /health).
  • Token-auth request succeeds.
  • Request history appears when Save Requests is enabled.

Common Issues

Problem Likely Cause Fix
Connection refused Service not running or wrong port Check status and port
401 unauthorized Missing/wrong token Regenerate token and update client
404 on transcriptions Path override mismatch Use the effective endpoint shown in the HTTP Transcription Service window
No transcription output Missing model or bad audio input Re-check preflight/model and input file

Quick Tips

  • Binding to 0.0.0.0 changes who can reach the service; it does not enable authentication. Keep token enforcement on whenever requests can arrive from another machine.
  • Save Requests is valuable during integration, but the captured artifacts can be sensitive. Turn it off after debugging unless you have a deliberate retention policy.

See Also

Visual Notes

  • TODO: add screenshot of the HTTP Transcription Service window configured for safe local mode.
  • TODO: add screenshot of successful Show Example cURL output.
  • TODO: add GIF from enabling service to first successful API response.