open-asr-server 0.1.2

OpenAI-compatible ASR server with pluggable local backends.

Open ASR Server

OpenAI-compatible ASR server with pluggable local transcription backends.

Install

Base install includes the API server and shared models/formatters:

uv tool install "open-asr-server"

Add backend extras as needed:

uv tool install "open-asr-server[parakeet]"
uv tool install "open-asr-server[whisper]"
uv tool install "open-asr-server[lightning-whisper]"

Note: the Whisper extras currently require Python 3.11 (tiktoken build constraints on 3.12+).

Whisper troubleshooting

If uv run --extra whisper fails on Python 3.12+, use a 3.11 interpreter for now:

uv run --python 3.11 --extra whisper -- open-asr-server serve --host 127.0.0.1 --port 8000

Run

Install at least one backend extra before running (the default model uses Parakeet MLX):

uv tool install "open-asr-server[parakeet]"

Then start the server:

uv tool run open-asr-server serve --host 127.0.0.1 --port 8000

Environment variables:

• OPEN_ASR_SERVER_DEFAULT_MODEL: default model ID for requests
• OPEN_ASR_SERVER_PRELOAD: comma-separated models to preload at startup
• OPEN_ASR_SERVER_API_KEY: optional shared secret for requests
• OPEN_ASR_SERVER_ALLOWED_MODELS: comma-separated allowed model IDs or patterns
• OPEN_ASR_SERVER_MAX_UPLOAD_BYTES: max upload size in bytes (default: 26214400)
• OPEN_ASR_SERVER_RATE_LIMIT_PER_MINUTE: optional per-client request limit (off by default)
• OPEN_ASR_SERVER_TRANSCRIBE_TIMEOUT_SECONDS: optional transcription timeout (off by default)
• OPEN_ASR_SERVER_TRANSCRIBE_WORKERS: optional thread pool size for transcriptions
• OPEN_ASR_SERVER_MODEL_DIR: override the Hugging Face cache location for this server
• OPEN_ASR_SERVER_HF_TOKEN: optional Hugging Face token for gated/private models

Models default to the Hugging Face cache unless a local path is provided. Use OPEN_ASR_SERVER_MODEL_DIR if you want a dedicated cache without changing your global HF environment. Use OPEN_ASR_SERVER_HF_TOKEN to authenticate downloads without setting global HF environment variables.

Use OPEN_ASR_SERVER_TRANSCRIBE_TIMEOUT_SECONDS to bound long transcriptions. If you set OPEN_ASR_SERVER_TRANSCRIBE_WORKERS, transcriptions run in a background thread pool instead of the event loop.

Sample audio

Two short clips are included in samples/ for quick smoke tests:

• samples/jfk_0_5.flac
• samples/jfk_5_10.flac

They are derived from tests/jfk.flac in the OpenAI Whisper repo (MIT); the original JFK speech is public domain.

uv run --extra parakeet scripts/smoke_parakeet.py samples/jfk_0_5.flac
uv run --python 3.11 --extra whisper scripts/smoke_whisper.py samples/jfk_0_5.flac
uv run --python 3.11 --extra lightning-whisper scripts/smoke_lightning.py samples/jfk_0_5.flac

Backend options

All backends are MLX-based today (Apple Silicon/macOS). Non-MLX backends are planned, but not yet supported.

Model IDs determine which backend is used:

• Parakeet MLX: mlx-community/parakeet-tdt-0.6b-v3 (default) or parakeet-*
• MLX Whisper: whisper-large-v3-turbo or mlx-community/whisper-large-v3-turbo
• Lightning Whisper MLX: lightning-whisper-distil-large-v3

API compatibility

The server implements:

• POST /v1/audio/transcriptions
• GET /v1/models

Example:

curl -s -X POST "http://127.0.0.1:8000/v1/audio/transcriptions" \
  -F "file=@audio.wav" \
  -F "model=whisper-large-v3-turbo"

Security

This server is designed for trusted networks. If you expose it publicly, enable OPEN_ASR_SERVER_API_KEY and front it with a reverse proxy that provides TLS and rate limiting. OPEN_ASR_SERVER_RATE_LIMIT_PER_MINUTE offers a simple in-process limiter for single-instance use, but it is not a substitute for production-grade rate limiting.

API key headers:

• Authorization: Bearer <token>
• X-API-Key: <token>

Use OPEN_ASR_SERVER_ALLOWED_MODELS to limit which model IDs can be loaded and prevent unbounded downloads. Avoid logging request bodies or filenames if those may contain sensitive data, and review reverse-proxy access logs for any retention concerns.

Release

uv version --bump patch
uv run --extra dev pytest
uv build --no-sources
uv publish --index testpypi --token "$UV_PUBLISH_TOKEN"
uv publish --token "$UV_PUBLISH_TOKEN"