OpenAIRealtimeSTTConfig
Configuration options for the OpenAIRealtimeSTT provider.
Defined in: src/providers/stt/openai/OpenAIRealtimeSTT.ts:110
Configuration options for the OpenAIRealtimeSTT provider.
Remarks
Extends STTProviderConfig with OpenAI Realtime-specific settings. You must provide either apiKey (for direct connections) or proxyUrl (for a server-side proxy that injects the API key). If both are provided, proxyUrl takes precedence.
For direct browser connections, mint an ephemeral client secret server-side (POST /v1/realtime/client_secrets) and pass an async factory as apiKey so a fresh secret is fetched on each connection.
Example
// Direct connection with an ephemeral client-secret factory
const config: OpenAIRealtimeSTTConfig = {
apiKey: async () => {
const res = await fetch('/api/openai-client-secret');
const { value } = await res.json();
return value;
},
model: 'gpt-4o-mini-transcribe',
};
// Proxy connection (recommended for production)
const config: OpenAIRealtimeSTTConfig = {
proxyUrl: 'http://localhost:3001/api/proxy/openai-realtime',
language: 'en',
};
See
OpenAIRealtimeSTT for the provider class
Extends
Properties
| Property | Type | Default value | Description | Overrides | Inherited from | Defined in |
|---|---|---|---|---|---|---|
apiKey? | string | () => Promise<string> | undefined | API key or authentication token for the provider. Remarks Can be a static string or an async factory function that returns a fresh token on each call. Use a factory for short-lived tokens (e.g. Deepgram JWTs) so each WebSocket connection gets a valid credential. For client-side usage, consider using a proxy server to keep API keys secure. The SDK provides Express, Next.js, and Node adapters for this purpose. | - | STTProviderConfig.apiKey | src/core/types/providers.ts:71 |
authType? | "token" | "bearer" | Provider-specific (typically 'token' for Deepgram, ignored for REST providers) | Authentication type for providers that support multiple auth mechanisms. Remarks Controls how the apiKey is sent to the provider: - 'token' — WebSocket subprotocol ['token', apiKey] or header Authorization: Token <key>. This is the default for Deepgram providers. - 'bearer' — WebSocket subprotocol ['bearer', token] or header Authorization: Bearer <token>. Use this for OAuth tokens or providers that expect Bearer auth. REST/SDK providers (Anthropic, OpenAI) handle auth through their SDK constructors and ignore this field. | - | STTProviderConfig.authType | src/core/types/providers.ts:115 |
debug? | boolean | false | Whether to enable debug logging for this provider. Remarks When true, the provider emits detailed internal logs. This is separate from the SDK-level LoggingConfig. | - | STTProviderConfig.debug | src/core/types/providers.ts:126 |
endpoint? | string | undefined | Custom endpoint URL to override the provider’s default API endpoint. Remarks Useful for self-hosted instances, proxy servers, or development environments. | - | STTProviderConfig.endpoint | src/core/types/providers.ts:79 |
inputAudioFormat? | "audio/pcm" | "audio/pcmu" | "audio/pcma" | undefined | Input audio encoding for audio appended to the buffer. Remarks - 'audio/pcm' — 16-bit PCM. Only a 24 kHz mono sample rate is supported (configure your input provider accordingly). - 'audio/pcmu' — G.711 mu-law (8 kHz, telephony). - 'audio/pcma' — G.711 A-law (8 kHz, telephony). Default 'audio/pcm' | - | - | src/providers/stt/openai/OpenAIRealtimeSTT.ts:136 |
interimResults? | boolean | undefined | Whether to enable interim (partial) transcription results. Remarks When true, the provider emits results as the user speaks, before the utterance is complete. Only applicable to live/WebSocket providers. | - | STTProviderConfig.interimResults | src/core/types/providers.ts:392 |
keywords? | string[] | undefined | Custom vocabulary or keyword phrases to boost recognition accuracy. Remarks Useful for domain-specific terminology, product names, or proper nouns that the model might not recognize well by default. | - | STTProviderConfig.keywords | src/core/types/providers.ts:406 |
language? | string | undefined | Language code for transcription. Remarks Uses BCP 47 language tags (e.g., 'en-US', 'es-ES', 'fr-FR'). The supported languages depend on the provider and model. | - | STTProviderConfig.language | src/core/types/providers.ts:375 |
model? | string | undefined | The transcription model to use. Remarks Current options are 'gpt-4o-mini-transcribe', 'gpt-4o-transcribe', 'whisper-1', and 'gpt-realtime-whisper' (plus dated snapshots). 'gpt-realtime-whisper' streams natively but does not support server-side turn detection — set turnDetection to null and call OpenAIRealtimeSTT.finalize to commit audio manually. Default 'gpt-4o-mini-transcribe' | STTProviderConfig.model | - | src/providers/stt/openai/OpenAIRealtimeSTT.ts:124 |
noiseReduction? | "near_field" | "far_field" | undefined | Noise reduction applied to input audio before VAD and transcription. Remarks Use 'near_field' for close-talking microphones such as headphones, or 'far_field' for laptop or conference-room microphones. Default undefined (noise reduction off) | - | - | src/providers/stt/openai/OpenAIRealtimeSTT.ts:175 |
organizationId? | string | undefined | OpenAI organization ID, sent as an auth subprotocol in direct mode. Default undefined | - | - | src/providers/stt/openai/OpenAIRealtimeSTT.ts:180 |
projectId? | string | undefined | OpenAI project ID, sent as an auth subprotocol in direct mode. Default undefined | - | - | src/providers/stt/openai/OpenAIRealtimeSTT.ts:185 |
prompt? | string | undefined | Optional text to guide transcription style or spelling of domain terms (e.g. 'Keywords: CompositeVoice, Deepgram, Soniox'). Remarks Not supported by 'gpt-realtime-whisper'. | - | - | src/providers/stt/openai/OpenAIRealtimeSTT.ts:144 |
proxyUrl? | string | undefined | URL of a CompositeVoice proxy server endpoint for this provider. Remarks When set, requests are routed through the proxy which injects the real API key server-side. This keeps API keys out of the browser. For WebSocket providers the HTTP URL is automatically converted to ws(s)://. At least one of apiKey or proxyUrl must be set for providers that require authentication (all except NativeSTT, NativeTTS, and WebLLM). Example proxyUrl: 'http://localhost:3000/api/proxy/deepgram' | - | STTProviderConfig.proxyUrl | src/core/types/providers.ts:97 |
punctuation? | boolean | undefined | Whether to enable automatic punctuation in transcription results. | - | STTProviderConfig.punctuation | src/core/types/providers.ts:397 |
timeout? | number | undefined | Request timeout in milliseconds. Remarks Applies to HTTP requests (REST providers) and connection establishment (WebSocket providers). Set to 0 for no timeout. | - | STTProviderConfig.timeout | src/core/types/providers.ts:135 |
transcriptionDelay? | "low" | "medium" | "high" | "minimal" | "xhigh" | undefined | Latency/accuracy tradeoff for 'gpt-realtime-whisper'. Remarks Lower settings emit partial text earlier; higher settings give the model more audio context and can improve word error rate. | - | - | src/providers/stt/openai/OpenAIRealtimeSTT.ts:152 |
turnDetection? | | OpenAIRealtimeTurnDetection | null | undefined | Voice activity detection used to commit audio at turn boundaries. Remarks Defaults to server VAD, which drives utteranceComplete results for automatic turn-taking in the CompositeVoice pipeline. Set to null to disable VAD and commit audio manually via OpenAIRealtimeSTT.finalize (required for 'gpt-realtime-whisper', which does not support VAD). Default { type: 'server_vad' } | - | - | src/providers/stt/openai/OpenAIRealtimeSTT.ts:165 |