Custom OpenAI-compatible provider (#79)

* Add an openai_custom backend.
* Add sample dump.

Author: bgrozev

.gitignore

@@ -172,7 +172,7 @@ dist/
 # WebSocket and transcript dumps
 media.jsonl
 transcript.jsonl
-*.jsonl
+#*.jsonl
 
 tmp/
 

BACKENDS.md

@@ -10,6 +10,42 @@ opus-transcriber-proxy uses an abstract backend system that allows you to choose
 ### OpenAI (Default)
 Uses OpenAI's Realtime API for low-latency streaming transcription.
 
+### OpenAI Custom
+Re-uses the OpenAI Realtime API backend but connects to a custom WebSocket URL with per-request credentials. Useful for proxies, self-hosted compatible endpoints, or when different sessions need different API keys.
+
+**How it works:**
+- Identical to the `openai` backend in all respects (same protocol, same audio format, same session configuration)
+- The WebSocket URL and API key are supplied per-request rather than from environment variables
+
+**Per-request configuration:**
+| Source | Parameter | Description |
+|--------|-----------|-------------|
+| URL query param | `openaiCustomUrl` | WebSocket URL to connect to (e.g. `wss://your-proxy/v1/realtime?intent=transcription`) |
+| HTTP header | `X-Custom-Openai-Api-Key` | API key for authentication |
+
+Both values are required; if either is missing the backend connection will fail.
+
+**Configuration:**
+```bash
+# Enable the openai_custom provider (required)
+ENABLE_OPENAI_CUSTOM_PROVIDER=true
+
+# Require wss:// scheme for the openaiCustomUrl parameter (default: true)
+# Set to false to allow unencrypted ws:// connections (not recommended in production)
+OPENAI_CUSTOM_REQUIRE_WSS=false
+
+# Optionally set openai_custom as the default provider
+PROVIDERS_PRIORITY=openai_custom,openai,deepgram,gemini
+```
+
+**Usage (per-session via URL):**
+```
+ws://host/transcribe?sendBack=true&provider=openai_custom&openaiCustomUrl=wss://...
+# Also pass the X-Custom-Openai-Api-Key HTTP header on the WebSocket upgrade request
+```
+
+The global `OPENAI_MODEL` and `OPENAI_TRANSCRIPTION_PROMPT` environment variables are used as defaults for model and prompt, same as for the `openai` provider.
+
 **Features:**
 - WebSocket-based streaming
 - Interim and final transcriptions

CLAUDE.md

@@ -373,6 +373,8 @@ See README.md for complete list. Key ones:
 
 - `PROVIDERS_PRIORITY` - Provider priority order (default: openai,deepgram,gemini)
 - `OPENAI_API_KEY`, `DEEPGRAM_API_KEY`, `GEMINI_API_KEY` - API keys
+- `ENABLE_OPENAI_CUSTOM_PROVIDER` - Enable the openai_custom provider (default: false)
+- `OPENAI_CUSTOM_REQUIRE_WSS` - Require wss:// for openaiCustomUrl (default: true; set false to allow ws://)
 - `PORT`, `HOST` - Server listen config
 - `FORCE_COMMIT_TIMEOUT` - Seconds before finalizing pending audio (default: 2)
 - `SESSION_RESUME_ENABLED` - Enable session resumption (default: true)
@@ -398,6 +400,7 @@ Do not leave stale descriptions. If a note says "only X happens" and you change
 - Each participant creates its own `OutgoingConnection` and backend connection to the provider.
 - The `tag` field identifies a participant within a session. Format can be `{id}-{ssrc}` or just `{id}`.
 - Deepgram is the only backend that supports raw Opus/Ogg pass-through (controlled by `DEEPGRAM_ENCODING`, default `opus`). It returns the input encoding unchanged from `getDesiredAudioFormat()` when pass-through is active. The old `wantsRawOpus()` method has been replaced by `getDesiredAudioFormat()`.
+- `openai_custom` is a provider that reuses `OpenAIBackend` but with a per-request WebSocket URL (from the `openaiCustomUrl` URL query parameter) and API key (from the `X-Custom-Openai-Api-Key` HTTP header). It is gated by `ENABLE_OPENAI_CUSTOM_PROVIDER=true` (similar to `ENABLE_DUMMY_PROVIDER`). The URL and key are stored in `TranscriberProxyOptions` (`openaiCustomUrl`, `openaiCustomApiKey`) and passed to `BackendFactory.createBackend` via `OpenAICustomOptions`. `BackendFactory` instantiates `OpenAIBackend(tag, participantInfo, wsUrl, apiKey)` for this provider.
 - `DecodedAudio.audioData` is a `Uint8Array` of raw bytes (PCM for decoded audio, raw frames for pass-through). The old `pcmData: Int16Array` field no longer exists.
 - When adding a new backend, implement `getDesiredAudioFormat(inputFormat): AudioFormat`. Return `{ encoding: 'l16', sampleRate: 24000 }` for PCM or `{ ...inputFormat }` (shallow copy) for raw pass-through. Do not return the `inputFormat` reference directly. This method is called on every `reinitializeDecoder` call (not just once at construction), so it must be a pure function of `inputFormat` for a given backend configuration. If the method has connect-time side effects (like `DeepgramBackend` storing `negotiatedFormat`), it will also be called on any new backend instance before `connect()`, so those side effects will be applied correctly.
 - `AudioFormat.encoding` is a lowercase union type: `'opus' | 'ogg' | 'l16'`. The client-facing `'ogg-opus'` value is normalised to `'ogg'` by `validateAudioFormat()`, and all incoming encodings are lowercased before validation so case-insensitive client values are accepted.