Skip to content

docs: add custom ASR shim proxy example#1010

Open
xAlcahest wants to merge 1 commit into
OpenWhispr:mainfrom
xAlcahest:docs/custom-asr-shim-example
Open

docs: add custom ASR shim proxy example#1010
xAlcahest wants to merge 1 commit into
OpenWhispr:mainfrom
xAlcahest:docs/custom-asr-shim-example

Conversation

@xAlcahest

Copy link
Copy Markdown
Collaborator

Summary

OpenWhispr's "Cloud → Custom" transcription assumes the OpenAI wire format: it POSTs multipart/form-data to {BaseUrl}/audio/transcriptions and reads back {"text": "..."}. ASR APIs with a different shape (StepFun StepAudio 2.5, and several Chinese cloud providers) fail with 400/501-type errors and no obvious guidance. This adds an examples/custom-asr-shim/ directory with a small local proxy that bridges the two without touching OpenWhispr: the shim listens on /audio/transcriptions, transcodes the recording with ffmpeg, calls the vendor in its own format, and returns the OpenAI-shaped JSON. shim_template.py is a vendor-neutral skeleton where you fill in one transcribe() function; stepaudio_shim.py is a working StepAudio 2.5 implementation ported from @ErogosZhou's gist.

Closes #972

Changes

  • examples/README.md: index for the examples directory.
  • examples/custom-asr-shim/README.md: the guide — the wire protocol OpenWhispr speaks, the HTTP-vs-HTTPS private-host rule, prerequisites, quick start, and how to adapt it to another vendor.
  • examples/custom-asr-shim/shim_template.py: vendor-neutral shim (ThreadingHTTPServer bound to 127.0.0.1, stdlib multipart parser that avoids the removed cgi module, ffmpeg transcode, 25 MB body guard, temp-file cleanup).
  • examples/custom-asr-shim/stepaudio_shim.py: StepAudio 2.5 shim (raw PCM base64 request, SSE response parsing).
  • examples/custom-asr-shim/test_shim.py: unittest coverage for the multipart parser, the SSE parser, and the HTTP endpoints.
  • examples/custom-asr-shim/.gitignore: ignore Python bytecode.

@xAlcahest xAlcahest requested a review from gabrielste1n June 27, 2026 17:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs] Add example: shim proxy for non-OpenAI-compatible ASR backends

1 participant