Skip to content

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

PropertyTypeDefault valueDescriptionOverridesInherited fromDefined in
apiKey?string | () => Promise<string>undefinedAPI 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.apiKeysrc/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.authTypesrc/core/types/providers.ts:115
debug?booleanfalseWhether 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.debugsrc/core/types/providers.ts:126
endpoint?stringundefinedCustom endpoint URL to override the provider’s default API endpoint. Remarks Useful for self-hosted instances, proxy servers, or development environments.-STTProviderConfig.endpointsrc/core/types/providers.ts:79
inputAudioFormat?"audio/pcm" | "audio/pcmu" | "audio/pcma"undefinedInput 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?booleanundefinedWhether 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.interimResultssrc/core/types/providers.ts:392
keywords?string[]undefinedCustom 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.keywordssrc/core/types/providers.ts:406
language?stringundefinedLanguage 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.languagesrc/core/types/providers.ts:375
model?stringundefinedThe 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"undefinedNoise 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?stringundefinedOpenAI organization ID, sent as an auth subprotocol in direct mode. Default undefined--src/providers/stt/openai/OpenAIRealtimeSTT.ts:180
projectId?stringundefinedOpenAI project ID, sent as an auth subprotocol in direct mode. Default undefined--src/providers/stt/openai/OpenAIRealtimeSTT.ts:185
prompt?stringundefinedOptional 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?stringundefinedURL 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.proxyUrlsrc/core/types/providers.ts:97
punctuation?booleanundefinedWhether to enable automatic punctuation in transcription results.-STTProviderConfig.punctuationsrc/core/types/providers.ts:397
timeout?numberundefinedRequest timeout in milliseconds. Remarks Applies to HTTP requests (REST providers) and connection establishment (WebSocket providers). Set to 0 for no timeout.-STTProviderConfig.timeoutsrc/core/types/providers.ts:135
transcriptionDelay?"low" | "medium" | "high" | "minimal" | "xhigh"undefinedLatency/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 | nullundefinedVoice 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

© 2026 CompositeVoice. All rights reserved.

Font size
Contrast
Motion
Transparency