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)¶
- Enable service and confirm status is
Running. - Copy the token from the HTTP Transcription Service window.
- 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"
- 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.0changes who can reach the service; it does not enable authentication. Keep token enforcement on whenever requests can arrive from another machine. Save Requestsis 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 cURLoutput. - TODO: add GIF from enabling service to first successful API response.