Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

docs: add custom ASR shim proxy example (#1220)

Po-Han Shih2186ce2e72b6
diff --git a/README.md b/README.md
index e62607594..937eedeb9 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,10 @@ Visit **[docs.openwhispr.com](https://docs.openwhispr.com)** for:
- [MCP server setup](https://docs.openwhispr.com/integrations/mcp)
- [Troubleshooting](https://docs.openwhispr.com/troubleshooting)
+Repo examples:
+
+- [Custom ASR shim](examples/custom-asr-shim/) for Self-Hosted transcription against non-OpenAI-compatible ASR APIs
+
## Tech stack
React 19, TypeScript, Tailwind CSS v4, Electron 41, better-sqlite3, whisper.cpp, sherpa-onnx, shadcn/ui
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 000000000..f5b6b311d
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,5 @@
+# Examples
+
+Community examples and recipes for extending OpenWhispr without changing its source.
+
+- [custom-asr-shim/](custom-asr-shim/) — a small local proxy that lets OpenWhispr's Self-Hosted transcription talk to ASR backends that do not speak the OpenAI `/audio/transcriptions` protocol (StepFun StepAudio, and any other vendor you adapt it to).
diff --git a/examples/custom-asr-shim/.gitignore b/examples/custom-asr-shim/.gitignore
new file mode 100644
index 000000000..7a60b85e1
--- /dev/null
+++ b/examples/custom-asr-shim/.gitignore
@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc
diff --git a/examples/custom-asr-shim/README.md b/examples/custom-asr-shim/README.md
new file mode 100644
index 000000000..5b2f74f13
--- /dev/null
+++ b/examples/custom-asr-shim/README.md
@@ -0,0 +1,98 @@
+# Custom ASR shim for OpenWhispr
+
+OpenWhispr's Self-Hosted transcription mode assumes the OpenAI wire format: it POSTs `multipart/form-data` to `{Server URL}/audio/transcriptions` and reads back JSON `{"text": "..."}`. Plenty of ASR APIs do not speak that format. StepFun StepAudio 2.5, Alibaba, Baidu, Tencent, and various enterprise speech platforms each have their own request shape, audio encoding, and response envelope. Point OpenWhispr straight at one of them and the call fails with a 400/501-type error because the bytes on the wire do not line up. A small shim that runs on your machine bridges the two: OpenWhispr keeps speaking OpenAI, the shim translates to and from your vendor, and you change nothing inside OpenWhispr.
+
+## How it works
+
+```
+OpenWhispr --multipart audio--> shim (localhost:8765) --vendor format--> ASR API
+OpenWhispr <--{"text": "..."}-- shim <--vendor reply-- ASR API
+```
+
+The shim listens on `/audio/transcriptions` (and `/v1/audio/transcriptions`), transcodes the recording with ffmpeg into whatever the vendor needs, calls the vendor, and returns the OpenAI-shaped JSON OpenWhispr expects.
+
+## What OpenWhispr sends and expects
+
+Request: `POST {Server URL}/audio/transcriptions`, `multipart/form-data`.
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `file` | yes | The recording. Default is WebM/Opus, filename `audio.webm`. May also be ogg/mp4/mp3/wav. Transcode it before sending to the vendor. |
+| `model` | no | The Model string from the Self-Hosted panel, when set. Tolerate empty or missing. |
+| `language` | no | Present only when you pick a non-auto language (ISO code like `en`). |
+| `prompt` | no | A custom-dictionary hint string. |
+
+`Authorization: Bearer <key>` is not part of the Self-Hosted panel. Do not require it from OpenWhispr's side. Hold your vendor API key in an environment variable inside the shim (see `STEP_API_KEY` below).
+
+Self-Hosted transcription is batch HTTP only. OpenWhispr does not send `stream=true` on this path, so the shim returns a single JSON object, not SSE, even if the upstream vendor streams.
+
+Response: HTTP 200 with JSON `{"text": "..."}`. OpenWhispr reads the `.text` field. Empty or missing text shows "No audio detected" to the user. A non-200 status is surfaced as an API error.
+
+## HTTP vs HTTPS
+
+OpenWhispr requires HTTPS for custom endpoints but exempts private and loopback hosts. A shim on `http://localhost:8765` works over plain HTTP. A shim reachable on a public host must use HTTPS (put it behind a TLS reverse proxy, or terminate TLS in the shim).
+
+Plain `http://` is allowed for these hosts:
+
+- `localhost` and any `*.local` hostname
+- `127.0.0.0/8` (loopback) and IPv6 `::1`
+- `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` (private ranges)
+- `169.254.0.0/16` (link-local) and IPv6 `fe80::/10`
+- `100.64.0.0/10` (CGNAT)
+- IPv6 `fc00::/7` (unique local)
+
+## Prerequisites
+
+- Python 3.8 or newer (standard library only, no pip installs)
+- ffmpeg on your PATH
+
+## Quick start
+
+Generic template, after you fill in the `transcribe()` function:
+
+```sh
+python3 shim_template.py
+```
+
+StepAudio 2.5:
+
+```sh
+export STEP_API_KEY=sk-...
+python3 stepaudio_shim.py
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:STEP_API_KEY = "sk-..."
+python stepaudio_shim.py
+```
+
+The StepAudio shim transcribes Chinese by default (`language: zh`) and ignores the language OpenWhispr forwards. Change the `language` value in `stepaudio_shim.py` for other languages.
+
+Then in OpenWhispr:
+
+1. Open **Settings → Transcription**
+2. Choose **Self-Hosted**
+3. Set **Server URL** to `http://localhost:8765`
+4. Optionally set **Model** (passed through as the `model` field; the StepAudio shim ignores it)
+
+The StepAudio shim reads `STEP_API_KEY` from the environment, not from OpenWhispr.
+
+## Adapt it to another vendor
+
+Copy `shim_template.py` and replace the single `transcribe()` function with your vendor's call. Everything else (the HTTP server, the multipart parser, the ffmpeg transcode, the size guard, temp-file cleanup, the response shape) already matches what OpenWhispr expects, so you only touch the one function that talks to your backend. `stepaudio_shim.py` is a worked example of exactly that.
+
+## Tests
+
+`test_shim.py` covers the multipart parser, the StepAudio SSE parser, and the HTTP endpoints (with ffmpeg and the vendor call stubbed out). Standard library only:
+
+```sh
+python3 test_shim.py
+```
+
+## Credit
+
+Thanks to [@ErogosZhou](https://github.com/ErogosZhou) for the original StepAudio shim that this example is built on: https://gist.github.com/ErogosZhou/4eb2c4bab1059b404fb652df7bfe24ac
+
+Addresses issue #972.
diff --git a/examples/custom-asr-shim/shim_template.py b/examples/custom-asr-shim/shim_template.py
new file mode 100644
index 000000000..c12267633
--- /dev/null
+++ b/examples/custom-asr-shim/shim_template.py
@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Generic local shim that lets OpenWhispr's Self-Hosted transcription talk
+to an ASR backend that does NOT speak the OpenAI /audio/transcriptions
+protocol.
+
+The contract OpenWhispr speaks (verified against its source):
+
+ - It POSTs multipart/form-data to {Server URL}/audio/transcriptions.
+ - Fields: `file` (recorded audio, usually WebM/Opus, filename audio.webm),
+ optional `model` (the string from the Self-Hosted panel), optional
+ `language` (ISO code), optional `prompt` (custom-dictionary hint).
+ Self-Hosted transcription is batch HTTP; `stream` is not used on this path.
+ - Do not require Authorization from OpenWhispr. Hold vendor keys in env vars.
+ - It expects HTTP 200 with JSON {"text": "..."}. Empty text shows
+ "No audio detected"; non-200 is surfaced as an API error.
+
+This file is the vendor-neutral template: fill in `transcribe()` with your
+backend's call and everything else works as-is. See README.md for details.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import tempfile
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+PORT = 8765
+MAX_BODY_BYTES = 25 * 1024 * 1024 # reject anything larger than ~25 MB (HTTP 413)
+API_KEY = os.environ.get("SHIM_API_KEY", "") # optional; set if your backend needs it
+
+
+def parse_multipart_form(body: bytes, content_type: str) -> tuple[dict[str, str], dict[str, tuple[str, bytes]]]:
+ """Parse multipart/form-data into (text_fields, files). files maps name -> (filename, bytes).
+ Stdlib-only; works on Python 3.8-3.13+ (the cgi module was removed in 3.13)."""
+ m = re.search(r'boundary="?([^";]+)"?', content_type)
+ if not m:
+ raise ValueError("missing multipart boundary in Content-Type")
+ delim = b"--" + m.group(1).strip().encode()
+ fields: dict[str, str] = {}
+ files: dict[str, tuple[str, bytes]] = {}
+ for chunk in body.split(delim):
+ if not chunk or chunk.startswith(b"--"): # preamble, closing delimiter
+ continue
+ if chunk.startswith(b"\r\n"):
+ chunk = chunk[2:]
+ if chunk.endswith(b"\r\n"):
+ chunk = chunk[:-2]
+ if b"\r\n\r\n" not in chunk:
+ continue
+ raw_headers, content = chunk.split(b"\r\n\r\n", 1)
+ disposition = ""
+ for line in raw_headers.decode("utf-8", "replace").split("\r\n"):
+ if line.lower().startswith("content-disposition:"):
+ disposition = line
+ name_match = re.search(r'name="([^"]*)"', disposition)
+ if not name_match:
+ continue
+ name = name_match.group(1)
+ file_match = re.search(r'filename="([^"]*)"', disposition)
+ if file_match is not None:
+ files[name] = (file_match.group(1), content)
+ else:
+ fields[name] = content.decode("utf-8", "replace")
+ return fields, files
+
+
+def convert_audio(input_path: str) -> str:
+ """Transcode any input container to 16 kHz mono PCM WAV via ffmpeg.
+ Returns the path to a new temp WAV; caller owns cleanup."""
+ fd, out_path = tempfile.mkstemp(suffix=".wav")
+ os.close(fd)
+ try:
+ subprocess.run(
+ ["ffmpeg", "-y", "-i", input_path, "-ar", "16000", "-ac", "1",
+ "-f", "wav", out_path],
+ check=True,
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ )
+ except (subprocess.CalledProcessError, FileNotFoundError):
+ os.remove(out_path)
+ raise
+ return out_path
+
+
+def transcribe(audio_path: str, model: str, language: str | None, prompt: str | None) -> str:
+ """The ONLY function you edit. Call your vendor's ASR backend with the WAV at
+ `audio_path` and return the transcript as a plain string.
+
+ `model`/`language`/`prompt` come straight from OpenWhispr's UI and may be
+ used or ignored. See stepaudio_shim.py for a concrete implementation."""
+ raise NotImplementedError(
+ "Replace transcribe() with your vendor's ASR call; return the transcript string."
+ )
+
+
+class ShimHandler(BaseHTTPRequestHandler):
+ """Handles the single POST endpoint OpenWhispr calls."""
+
+ def _send_json(self, status: int, payload: dict) -> None:
+ body = json.dumps(payload).encode("utf-8")
+ self.send_response(status)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def do_POST(self) -> None: # noqa: N802 (http.server naming)
+ if self.path.rstrip("/") not in ("/audio/transcriptions", "/v1/audio/transcriptions"):
+ self._send_json(404, {"error": "not found"})
+ return
+
+ try:
+ length = int(self.headers.get("Content-Length", "0"))
+ except ValueError:
+ self._send_json(400, {"error": "invalid Content-Length"})
+ return
+ if length <= 0:
+ self._send_json(400, {"error": "empty body"})
+ return
+ if length > MAX_BODY_BYTES:
+ self._send_json(413, {"error": "request body too large"})
+ return
+
+ body = self.rfile.read(length)
+ content_type = self.headers.get("Content-Type", "")
+ try:
+ fields, files = parse_multipart_form(body, content_type)
+ except ValueError as exc:
+ self._send_json(400, {"error": f"bad multipart: {exc}"})
+ return
+
+ if "file" not in files:
+ self._send_json(400, {"error": "missing 'file' field"})
+ return
+
+ filename, file_bytes = files["file"]
+ model = fields.get("model", "")
+ language = fields.get("language") or None
+ prompt = fields.get("prompt") or None
+
+ suffix = os.path.splitext(filename)[1] or ".webm"
+ fd, in_path = tempfile.mkstemp(suffix=suffix)
+ wav_path = None
+ try:
+ with os.fdopen(fd, "wb") as f:
+ f.write(file_bytes)
+ wav_path = convert_audio(in_path)
+ text = transcribe(wav_path, model, language, prompt)
+ self._send_json(200, {"text": text or "", "object": "transcription"})
+ except FileNotFoundError:
+ self._send_json(500, {"error": "ffmpeg not found on PATH"})
+ except subprocess.CalledProcessError:
+ self._send_json(500, {"error": "ffmpeg failed to transcode audio"})
+ except NotImplementedError as exc:
+ self._send_json(500, {"error": str(exc)})
+ except Exception as exc: # surface, never swallow
+ self._send_json(500, {"error": f"transcription failed: {exc}"})
+ finally:
+ for path in (in_path, wav_path):
+ if path and os.path.exists(path):
+ os.remove(path)
+
+
+def main() -> None:
+ server = ThreadingHTTPServer(("127.0.0.1", PORT), ShimHandler)
+ server.daemon_threads = True # let Ctrl+C exit even with a request in flight
+ print(f"Custom ASR shim listening on http://localhost:{PORT}")
+ print("Point OpenWhispr at it: Settings -> Transcription -> Self-Hosted")
+ print(f" Server URL: http://localhost:{PORT}")
+ print(" Vendor API key: hold it in an env var inside transcribe()")
+ print("Press Ctrl+C to stop.")
+ try:
+ server.serve_forever()
+ except KeyboardInterrupt:
+ print("\nShutting down.")
+ finally:
+ server.server_close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/examples/custom-asr-shim/stepaudio_shim.py b/examples/custom-asr-shim/stepaudio_shim.py
new file mode 100644
index 000000000..a6c61fdb9
--- /dev/null
+++ b/examples/custom-asr-shim/stepaudio_shim.py
@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""Local shim that bridges OpenWhispr's Self-Hosted transcription to
+StepFun's StepAudio 2.5 ASR API.
+
+OpenWhispr POSTs OpenAI-style multipart/form-data and expects JSON {"text": ...}.
+StepAudio wants raw PCM (base64) over an SSE endpoint. This shim transcodes the
+recording, calls StepAudio, parses the SSE stream, and hands the transcript back.
+
+Ported from @ErogosZhou's original StepAudio shim:
+https://gist.github.com/ErogosZhou/4eb2c4bab1059b404fb652df7bfe24ac
+
+Run it: export STEP_API_KEY=... then python3 stepaudio_shim.py
+Then in OpenWhispr: Settings -> Transcription -> Self-Hosted,
+Server URL http://localhost:8765. See README.md for the full contract.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+PORT = 8765
+MAX_BODY_BYTES = 25 * 1024 * 1024 # reject anything larger than ~25 MB (HTTP 413)
+ASR_URL = "https://api.stepfun.com/v1/audio/asr/sse"
+API_KEY = os.environ.get("STEP_API_KEY", "")
+REQUEST_TIMEOUT = 120 # seconds for the StepAudio call
+
+
+def parse_multipart_form(body: bytes, content_type: str) -> tuple[dict[str, str], dict[str, tuple[str, bytes]]]:
+ """Parse multipart/form-data into (text_fields, files). files maps name -> (filename, bytes).
+ Stdlib-only; works on Python 3.8-3.13+ (the cgi module was removed in 3.13)."""
+ m = re.search(r'boundary="?([^";]+)"?', content_type)
+ if not m:
+ raise ValueError("missing multipart boundary in Content-Type")
+ delim = b"--" + m.group(1).strip().encode()
+ fields: dict[str, str] = {}
+ files: dict[str, tuple[str, bytes]] = {}
+ for chunk in body.split(delim):
+ if not chunk or chunk.startswith(b"--"): # preamble, closing delimiter
+ continue
+ if chunk.startswith(b"\r\n"):
+ chunk = chunk[2:]
+ if chunk.endswith(b"\r\n"):
+ chunk = chunk[:-2]
+ if b"\r\n\r\n" not in chunk:
+ continue
+ raw_headers, content = chunk.split(b"\r\n\r\n", 1)
+ disposition = ""
+ for line in raw_headers.decode("utf-8", "replace").split("\r\n"):
+ if line.lower().startswith("content-disposition:"):
+ disposition = line
+ name_match = re.search(r'name="([^"]*)"', disposition)
+ if not name_match:
+ continue
+ name = name_match.group(1)
+ file_match = re.search(r'filename="([^"]*)"', disposition)
+ if file_match is not None:
+ files[name] = (file_match.group(1), content)
+ else:
+ fields[name] = content.decode("utf-8", "replace")
+ return fields, files
+
+
+def convert_audio(input_path: str) -> str:
+ """Transcode any input container to raw 16 kHz mono s16le PCM via ffmpeg.
+ StepAudio wants raw PCM here, not a WAV container. Caller owns cleanup."""
+ fd, out_path = tempfile.mkstemp(suffix=".pcm")
+ os.close(fd)
+ try:
+ subprocess.run(
+ ["ffmpeg", "-y", "-i", input_path, "-ar", "16000", "-ac", "1",
+ "-f", "s16le", out_path],
+ check=True,
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ )
+ except (subprocess.CalledProcessError, FileNotFoundError):
+ os.remove(out_path)
+ raise
+ return out_path
+
+
+def parse_sse_transcript(raw: bytes) -> str:
+ """Parse StepAudio's SSE stream. Accumulate transcript.text.delta events and
+ prefer the transcript.text.done full text. Falls back to the `type` field
+ inside the data payload when the event name is absent."""
+ deltas: list[str] = []
+ done_text = ""
+ for block in raw.split(b"\n\n"):
+ if not block.strip():
+ continue
+ event = ""
+ data_parts: list[str] = []
+ for line in block.split(b"\n"):
+ line = line.strip()
+ if line.startswith(b"event:"):
+ event = line[len(b"event:"):].strip().decode("utf-8", "replace")
+ elif line.startswith(b"data:"):
+ data_parts.append(line[len(b"data:"):].strip().decode("utf-8", "replace"))
+ data_str = "".join(data_parts)
+ if not data_str or data_str == "[DONE]":
+ continue
+ try:
+ payload = json.loads(data_str)
+ except json.JSONDecodeError:
+ continue
+ kind = event or payload.get("type", "")
+ if kind == "transcript.text.delta":
+ delta = payload.get("delta")
+ if isinstance(delta, str):
+ deltas.append(delta)
+ elif kind == "transcript.text.done":
+ text = payload.get("text")
+ if isinstance(text, str):
+ done_text = text
+ return done_text or "".join(deltas)
+
+
+def transcribe(audio_path: str, model: str, language: str | None, prompt: str | None) -> str:
+ """Send the raw PCM to StepAudio 2.5 and return the transcript.
+ `model`/`language` from OpenWhispr are available but StepAudio is pinned to
+ its own model + language here; wire them through if you want."""
+ with open(audio_path, "rb") as f:
+ pcm = f.read()
+ audio_b64 = base64.b64encode(pcm).decode("ascii")
+ payload = {
+ "audio": {
+ "data": audio_b64,
+ "input": {
+ "transcription": {
+ "model": "stepaudio-2.5-asr",
+ "language": "zh",
+ "enable_itn": True,
+ },
+ "format": {
+ "type": "pcm",
+ "codec": "pcm_s16le",
+ "rate": 16000,
+ "bits": 16,
+ "channel": 1,
+ },
+ },
+ }
+ }
+ req = urllib.request.Request(
+ ASR_URL,
+ data=json.dumps(payload).encode("utf-8"),
+ headers={
+ "Authorization": f"Bearer {API_KEY}",
+ "Content-Type": "application/json",
+ "Accept": "text/event-stream",
+ },
+ method="POST",
+ )
+ try:
+ with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT) as resp:
+ raw = resp.read()
+ except urllib.error.HTTPError as exc:
+ detail = exc.read().decode("utf-8", "replace")
+ raise RuntimeError(f"StepAudio HTTP {exc.code}: {detail}") from exc
+ except urllib.error.URLError as exc:
+ raise RuntimeError(f"StepAudio request failed: {exc.reason}") from exc
+ return parse_sse_transcript(raw)
+
+
+class ShimHandler(BaseHTTPRequestHandler):
+ """Handles the single POST endpoint OpenWhispr calls."""
+
+ def _send_json(self, status: int, payload: dict) -> None:
+ body = json.dumps(payload).encode("utf-8")
+ self.send_response(status)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def do_POST(self) -> None: # noqa: N802 (http.server naming)
+ if self.path.rstrip("/") not in ("/audio/transcriptions", "/v1/audio/transcriptions"):
+ self._send_json(404, {"error": "not found"})
+ return
+
+ try:
+ length = int(self.headers.get("Content-Length", "0"))
+ except ValueError:
+ self._send_json(400, {"error": "invalid Content-Length"})
+ return
+ if length <= 0:
+ self._send_json(400, {"error": "empty body"})
+ return
+ if length > MAX_BODY_BYTES:
+ self._send_json(413, {"error": "request body too large"})
+ return
+
+ body = self.rfile.read(length)
+ content_type = self.headers.get("Content-Type", "")
+ try:
+ fields, files = parse_multipart_form(body, content_type)
+ except ValueError as exc:
+ self._send_json(400, {"error": f"bad multipart: {exc}"})
+ return
+
+ if "file" not in files:
+ self._send_json(400, {"error": "missing 'file' field"})
+ return
+
+ filename, file_bytes = files["file"]
+ model = fields.get("model", "")
+ language = fields.get("language") or None
+ prompt = fields.get("prompt") or None
+
+ suffix = os.path.splitext(filename)[1] or ".webm"
+ fd, in_path = tempfile.mkstemp(suffix=suffix)
+ pcm_path = None
+ try:
+ with os.fdopen(fd, "wb") as f:
+ f.write(file_bytes)
+ pcm_path = convert_audio(in_path)
+ text = transcribe(pcm_path, model, language, prompt)
+ self._send_json(200, {"text": text or "", "object": "transcription"})
+ except FileNotFoundError:
+ self._send_json(500, {"error": "ffmpeg not found on PATH"})
+ except subprocess.CalledProcessError:
+ self._send_json(500, {"error": "ffmpeg failed to transcode audio"})
+ except RuntimeError as exc: # network / vendor errors
+ self._send_json(500, {"error": str(exc)})
+ except Exception as exc: # surface, never swallow
+ self._send_json(500, {"error": f"transcription failed: {exc}"})
+ finally:
+ for path in (in_path, pcm_path):
+ if path and os.path.exists(path):
+ os.remove(path)
+
+
+def main() -> None:
+ if not API_KEY:
+ print("error: STEP_API_KEY is not set. Run: export STEP_API_KEY=...", file=sys.stderr)
+ sys.exit(1)
+ server = ThreadingHTTPServer(("127.0.0.1", PORT), ShimHandler)
+ server.daemon_threads = True # let Ctrl+C exit even with a request in flight
+ print(f"StepAudio shim listening on http://localhost:{PORT}")
+ print("Point OpenWhispr at it: Settings -> Transcription -> Self-Hosted")
+ print(f" Server URL: http://localhost:{PORT}")
+ print("Press Ctrl+C to stop.")
+ try:
+ server.serve_forever()
+ except KeyboardInterrupt:
+ print("\nShutting down.")
+ finally:
+ server.server_close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/examples/custom-asr-shim/test_shim.py b/examples/custom-asr-shim/test_shim.py
new file mode 100644
index 000000000..83e75eabd
--- /dev/null
+++ b/examples/custom-asr-shim/test_shim.py
@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""Unit tests for the custom ASR shim example.
+
+Stdlib only (unittest), no network, no ffmpeg: the HTTP tests monkeypatch
+`convert_audio` and `transcribe` so they exercise the request handling,
+multipart parsing, and response shape in isolation.
+
+Run from anywhere:
+ python3 examples/custom-asr-shim/test_shim.py
+or:
+ cd examples/custom-asr-shim && python3 -m unittest
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import sys
+import threading
+import unittest
+from http.server import ThreadingHTTPServer
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import shim_template # noqa: E402
+import stepaudio_shim # noqa: E402
+
+CRLF = b"\r\n"
+
+
+def build_multipart(boundary: bytes, parts) -> bytes:
+ """parts: list of (name, filename|None, content_bytes, content_type|None)."""
+ out = []
+ for name, filename, content, ctype in parts:
+ out.append(b"--" + boundary + CRLF)
+ disp = b'Content-Disposition: form-data; name="' + name.encode() + b'"'
+ if filename is not None:
+ disp += b'; filename="' + filename.encode() + b'"'
+ out.append(disp + CRLF)
+ if ctype is not None:
+ out.append(b"Content-Type: " + ctype + CRLF)
+ out.append(CRLF)
+ out.append(content + CRLF)
+ out.append(b"--" + boundary + b"--" + CRLF)
+ return b"".join(out)
+
+
+class MultipartParserTests(unittest.TestCase):
+ """The parser is duplicated verbatim in both files; test both copies."""
+
+ modules = (shim_template, stepaudio_shim)
+
+ def test_roundtrip_binary_with_embedded_crlf(self):
+ # Binary that starts, ends, and contains CR/LF, to catch over-stripping.
+ file_bytes = b"\r\n\x1aOggS\x00\x02mid\r\ndle\r\nend\r\n"
+ body = build_multipart(
+ b"----WebKitFormBoundaryAbC",
+ [
+ ("file", "audio.webm", file_bytes, b"audio/webm"),
+ ("model", None, b"whisper-1", None),
+ ("language", None, b"en", None),
+ ],
+ )
+ ct = "multipart/form-data; boundary=----WebKitFormBoundaryAbC"
+ for mod in self.modules:
+ with self.subTest(module=mod.__name__):
+ fields, files = mod.parse_multipart_form(body, ct)
+ self.assertEqual(fields.get("model"), "whisper-1")
+ self.assertEqual(fields.get("language"), "en")
+ self.assertIn("file", files)
+ filename, data = files["file"]
+ self.assertEqual(filename, "audio.webm")
+ self.assertEqual(data, file_bytes) # exact byte match, no over-strip
+
+ def test_utf8_text_field(self):
+ body = build_multipart(
+ b"X1",
+ [
+ ("file", "a.webm", b"\x00\x01", b"audio/webm"),
+ ("prompt", None, "caffè, naïve, 日本語".encode("utf-8"), None),
+ ],
+ )
+ for mod in self.modules:
+ with self.subTest(module=mod.__name__):
+ fields, _ = mod.parse_multipart_form(body, "multipart/form-data; boundary=X1")
+ self.assertEqual(fields.get("prompt"), "caffè, naïve, 日本語")
+
+ def test_missing_boundary_raises(self):
+ for mod in self.modules:
+ with self.subTest(module=mod.__name__):
+ with self.assertRaises(ValueError):
+ mod.parse_multipart_form(b"whatever", "application/json")
+
+ def test_trailing_space_boundary(self):
+ # RFC-valid OWS after the boundary token must not break the delimiter.
+ body = build_multipart(b"B9", [("file", "a.webm", b"data", b"audio/webm")])
+ for mod in self.modules:
+ with self.subTest(module=mod.__name__):
+ _, files = mod.parse_multipart_form(
+ body, "multipart/form-data; boundary=B9 "
+ )
+ self.assertIn("file", files)
+ self.assertEqual(files["file"][1], b"data")
+
+ def test_no_file_field(self):
+ body = build_multipart(b"B9", [("model", None, b"x", None)])
+ for mod in self.modules:
+ with self.subTest(module=mod.__name__):
+ _, files = mod.parse_multipart_form(body, "multipart/form-data; boundary=B9")
+ self.assertNotIn("file", files)
+
+
+class SseParserTests(unittest.TestCase):
+ parse = staticmethod(stepaudio_shim.parse_sse_transcript)
+
+ def test_prefers_done_over_deltas(self):
+ raw = (
+ b"event: transcript.text.delta\ndata: {\"delta\": \"par\"}\n\n"
+ b"event: transcript.text.delta\ndata: {\"delta\": \"tial\"}\n\n"
+ b"event: transcript.text.done\ndata: {\"text\": \"full text\"}\n\n"
+ b"data: [DONE]\n\n"
+ )
+ self.assertEqual(self.parse(raw), "full text")
+
+ def test_delta_join_when_no_done(self):
+ raw = (
+ b"event: transcript.text.delta\ndata: {\"delta\": \"foo\"}\n\n"
+ b"event: transcript.text.delta\ndata: {\"delta\": \"bar\"}\n\n"
+ )
+ self.assertEqual(self.parse(raw), "foobar")
+
+ def test_type_field_fallback(self):
+ raw = (
+ b"data: {\"type\": \"transcript.text.delta\", \"delta\": \"x\"}\n\n"
+ b"data: {\"type\": \"transcript.text.done\", \"text\": \"final\"}\n\n"
+ )
+ self.assertEqual(self.parse(raw), "final")
+
+ def test_skips_done_marker_and_malformed_json(self):
+ raw = (
+ b"data: [DONE]\n\n"
+ b"data: not json at all\n\n"
+ b"event: transcript.text.done\ndata: {\"text\": \"ok\"}\n\n"
+ )
+ self.assertEqual(self.parse(raw), "ok")
+
+ def test_empty_stream(self):
+ self.assertEqual(self.parse(b""), "")
+
+
+class _HandlerHarness:
+ """Runs a module's ShimHandler on an ephemeral port with ffmpeg/network
+ stubbed out, and restores the patched globals on stop."""
+
+ def __init__(self, module):
+ self.module = module
+ self.captured = {}
+ self._orig = {}
+
+ def start(self):
+ mod = self.module
+ self._orig["convert_audio"] = mod.convert_audio
+ self._orig["transcribe"] = mod.transcribe
+ # Silence the per-request access log so test output stays readable.
+ self._had_own_log = "log_message" in mod.ShimHandler.__dict__
+ self._orig_log = mod.ShimHandler.__dict__.get("log_message")
+ mod.ShimHandler.log_message = lambda *a, **k: None
+
+ # No ffmpeg: hand the written input file straight through.
+ mod.convert_audio = lambda path: path
+
+ def fake_transcribe(audio_path, model, language, prompt):
+ with open(audio_path, "rb") as f:
+ self.captured["bytes"] = f.read()
+ self.captured["model"] = model
+ self.captured["language"] = language
+ self.captured["prompt"] = prompt
+ return "hello world"
+
+ mod.transcribe = fake_transcribe
+
+ self.server = ThreadingHTTPServer(("127.0.0.1", 0), mod.ShimHandler)
+ self.port = self.server.server_address[1]
+ self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+ self.thread.start()
+
+ def stop(self):
+ self.server.shutdown()
+ self.server.server_close()
+ self.thread.join(timeout=5)
+ self.module.convert_audio = self._orig["convert_audio"]
+ self.module.transcribe = self._orig["transcribe"]
+ if self._had_own_log:
+ self.module.ShimHandler.log_message = self._orig_log
+ else:
+ del self.module.ShimHandler.log_message
+
+ def post(self, path, body, content_type):
+ conn = http.client.HTTPConnection("127.0.0.1", self.port, timeout=5)
+ try:
+ conn.request("POST", path, body, {"Content-Type": content_type})
+ resp = conn.getresponse()
+ return resp.status, resp.read()
+ finally:
+ conn.close()
+
+
+class HttpHandlerTests(unittest.TestCase):
+ modules = (shim_template, stepaudio_shim)
+
+ def _valid_body(self):
+ file_bytes = b"RIFFfake-wav-bytes\r\n\x00"
+ body = build_multipart(
+ b"HB",
+ [
+ ("file", "audio.webm", file_bytes, b"audio/webm"),
+ ("model", None, b"my-model", None),
+ ("language", None, b"en", None),
+ ],
+ )
+ return body, file_bytes, "multipart/form-data; boundary=HB"
+
+ def test_valid_post_returns_text_and_passes_bytes_through(self):
+ body, file_bytes, ct = self._valid_body()
+ for mod in self.modules:
+ with self.subTest(module=mod.__name__):
+ h = _HandlerHarness(mod)
+ h.start()
+ try:
+ for path in ("/audio/transcriptions", "/v1/audio/transcriptions"):
+ status, raw = h.post(path, body, ct)
+ self.assertEqual(status, 200)
+ payload = json.loads(raw)
+ self.assertEqual(payload["text"], "hello world")
+ self.assertEqual(payload["object"], "transcription")
+ # the exact recorded bytes reached transcribe()
+ self.assertEqual(h.captured["bytes"], file_bytes)
+ self.assertEqual(h.captured["model"], "my-model")
+ self.assertEqual(h.captured["language"], "en")
+ finally:
+ h.stop()
+
+ def test_wrong_path_404(self):
+ body, _, ct = self._valid_body()
+ for mod in self.modules:
+ with self.subTest(module=mod.__name__):
+ h = _HandlerHarness(mod)
+ h.start()
+ try:
+ status, _ = h.post("/nope", body, ct)
+ self.assertEqual(status, 404)
+ finally:
+ h.stop()
+
+ def test_missing_file_400(self):
+ body = build_multipart(b"HB", [("model", None, b"x", None)])
+ for mod in self.modules:
+ with self.subTest(module=mod.__name__):
+ h = _HandlerHarness(mod)
+ h.start()
+ try:
+ status, _ = h.post(
+ "/audio/transcriptions", body, "multipart/form-data; boundary=HB"
+ )
+ self.assertEqual(status, 400)
+ finally:
+ h.stop()
+
+ def test_oversize_body_413(self):
+ body, _, ct = self._valid_body()
+ for mod in self.modules:
+ with self.subTest(module=mod.__name__):
+ orig = mod.MAX_BODY_BYTES
+ mod.MAX_BODY_BYTES = 4 # smaller than any real body
+ h = _HandlerHarness(mod)
+ h.start()
+ try:
+ status, _ = h.post("/audio/transcriptions", body, ct)
+ self.assertEqual(status, 413)
+ finally:
+ h.stop()
+ mod.MAX_BODY_BYTES = orig
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)