GoogleSTT

Defined in: src/providers/stt/google/GoogleSTT.ts:247

Google Cloud STT provider using native fetch for batch (per-utterance) speech-to-text.

Remarks

This is a REST/batch provider, not a live streaming one: each transcribe(blob) call uploads a complete recording (base64-encoded) to Google’s synchronous POST /v1/speech:recognize endpoint, which accepts up to 60 seconds (~10 MB) of audio per request. The top alternative of the response is emitted as a single final result with utteranceComplete: true, which is the flag CompositeVoice checks to trigger LLM processing.

There is deliberately no GoogleLiveSTT: Google’s streaming recognition (StreamingRecognize) is exposed only over gRPC in both the v1 and v2 APIs. There is no public WebSocket endpoint, so real-time browser streaming would require gRPC/protobuf dependencies that conflict with this SDK’s zero-dependency design. For live streaming STT, use a WebSocket provider such as DeepgramSTT, AssemblyAISTT, or SonioxSTT.

Audio flow: Complete audio Blob -> transcribe() -> Google STT REST API -> emitTranscription (final)

Example

import { GoogleSTT } from 'composite-voice';

const stt = new GoogleSTT({
  apiKey: 'AIza...',
  language: 'en-US',
  encoding: 'WEBM_OPUS',
  sampleRate: 48000,
  model: 'latest_short',
});

await stt.initialize();
stt.onTranscription((result) => console.log(result.text, result.confidence));

// Record an utterance (e.g. via MediaRecorder), then:
await stt.transcribe(recordedBlob);

See

• RestSTTProvider - The base class this provider extends.
• GoogleSTTConfig - Configuration options for this provider.

Extends

• RestSTTProvider

Constructors

Constructor

new GoogleSTT(config, logger?): GoogleSTT;

Defined in: src/providers/stt/google/GoogleSTT.ts:257

Creates a new GoogleSTT provider instance.

Parameters

Returns

GoogleSTT

Overrides

RestSTTProvider.constructor

Properties

Accessors

isProxyMode

Get Signature

get protected isProxyMode(): boolean;

Defined in: src/providers/base/BaseProvider.ts:286

Whether the provider is in proxy mode.

Returns

boolean

true when proxyUrl is set.

Inherited from

RestSTTProvider.isProxyMode

Methods

assertAuth()

protected assertAuth(): void;

Defined in: src/providers/base/BaseProvider.ts:272

Validate that auth is configured (either apiKey or proxyUrl).

Returns

void

Remarks

Call this in onInitialize() for any provider that requires external authentication. Native providers (NativeSTT, NativeTTS) and in-browser providers (WebLLM) should NOT call this method.

Throws

ProviderInitializationError Thrown when neither apiKey nor proxyUrl is set.

Inherited from

RestSTTProvider.assertAuth

assertReady()

protected assertReady(): void;

Defined in: src/providers/base/BaseProvider.ts:255

Guard that throws if the provider has not been initialized.

Returns

void

Remarks

Call at the start of any method that requires the provider to be ready.

Throws

Error Thrown with a descriptive message when initialized is false.

Inherited from

RestSTTProvider.assertReady

dispose()

dispose(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:154

Clean up resources and dispose of the provider.

Returns

Promise<void>

Remarks

Delegates to the subclass hook onDispose and resets the initialized flag. If the provider is not initialized, the call is a no-op.

Throws

Re-throws any error raised by onDispose.

Inherited from

RestSTTProvider.dispose

emitTranscription()

protected emitTranscription(result): void;

Defined in: src/providers/base/BaseSTTProvider.ts:206

Emit a transcription result to the registered callback.

Parameters

Returns

void

Remarks

Subclasses call this method whenever transcribed text is available. If no callback has been registered via onTranscription, the result is logged as a warning and dropped.

Inherited from

RestSTTProvider.emitTranscription

getConfig()

getConfig(): STTProviderConfig;

Defined in: src/providers/base/BaseSTTProvider.ts:225

Get a shallow copy of the current STT configuration.

Returns

STTProviderConfig

A new STTProviderConfig object.

Inherited from

RestSTTProvider.getConfig

initialize()

initialize(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:127

Initialize the provider, making it ready for use.

Returns

Promise<void>

Remarks

Calls the subclass hook onInitialize. If the provider has already been initialized the call is a no-op.

Throws

ProviderInitializationError Thrown when onInitialize rejects. The original error is wrapped with the provider class name for diagnostics.

Inherited from

RestSTTProvider.initialize

isFinal()

isFinal(result): boolean;

Defined in: src/providers/base/BaseSTTProvider.ts:174

Is this a final segment (but not necessarily utterance-complete)?

Parameters

Returns

boolean

true when this is a final segment.

Remarks

A final segment represents committed text, but multi-segment providers (e.g., Deepgram) may emit several final segments for a single utterance. Only the last one will have isUtteranceComplete return true.

Inherited from

RestSTTProvider.isFinal

isInterim()

isInterim(result): boolean;

Defined in: src/providers/base/BaseSTTProvider.ts:159

Is this an interim (partial, non-final) result?

Parameters

Returns

boolean

true when this is an interim result.

Remarks

Interim results update as the user speaks and are replaced by subsequent results. Useful for display but not for triggering downstream processing.

Inherited from

RestSTTProvider.isInterim

isPreflight()

isPreflight(result): boolean;

Defined in: src/providers/base/BaseSTTProvider.ts:144

Is this a preflight/eager end-of-turn signal?

Parameters

Returns

boolean

true when this is a preflight signal.

Remarks

Used by the eager LLM pipeline for speculative generation. Only providers with preflight support (e.g., Deepgram Flux) need to override this.

Inherited from

RestSTTProvider.isPreflight

isReady()

isReady(): boolean;

Defined in: src/providers/base/BaseProvider.ts:178

Check whether the provider has been initialized and is ready.

Returns

boolean

true when initialize has completed successfully and dispose has not yet been called.

Inherited from

RestSTTProvider.isReady

isUtteranceComplete()

isUtteranceComplete(result): boolean;

Defined in: src/providers/base/BaseSTTProvider.ts:129

Is this result a complete utterance ready for LLM processing?

Parameters

Returns

boolean

true when the utterance is complete.

Remarks

The orchestrator calls this to decide when to send transcribed text to the LLM. Concrete providers override this when they have domain- specific endpointing logic (e.g., DeepgramSTT checks speech_final).

Inherited from

RestSTTProvider.isUtteranceComplete

onConfigUpdate()

protected onConfigUpdate(_config): void;

Defined in: src/providers/base/BaseProvider.ts:242

Hook called after updateConfig merges new values.

Parameters

Returns

void

Remarks

The default implementation is a no-op. Override in subclasses to react to runtime configuration changes (e.g. reconnect with a new API key).

Inherited from

RestSTTProvider.onConfigUpdate

onDispose()

protected onDispose(): Promise<void>;

Defined in: src/providers/stt/google/GoogleSTT.ts:303

Disposes the provider and releases the HTTP client.

Returns

Promise<void>

Overrides

RestSTTProvider.onDispose

onInitialize()

protected onInitialize(): Promise<void>;

Defined in: src/providers/stt/google/GoogleSTT.ts:266

Initializes the HTTP client for the Google Cloud STT API.

Returns

Promise<void>

Throws

ProviderInitializationError if neither apiKey nor proxyUrl is configured.

Overrides

RestSTTProvider.onInitialize

onTranscription()

onTranscription(callback): void;

Defined in: src/providers/base/BaseSTTProvider.ts:191

Register a callback to receive transcription results.

Parameters

Returns

void

Remarks

All STT providers — regardless of transport — deliver text through this callback. CompositeVoice registers it during pipeline setup so that transcription results flow into the conversation manager and, ultimately, the LLM provider.

Inherited from

RestSTTProvider.onTranscription

processAudio()

processAudio(_chunk): void;

Defined in: src/providers/base/RestSTTProvider.ts:100

Process a raw audio chunk (no-op for REST providers).

Parameters

Returns

void

Remarks

REST STT providers do not process streaming audio. Use transcribe for batch processing instead. This method exists to satisfy the BaseSTTProvider contract.

Inherited from

RestSTTProvider.processAudio

resolveApiKey()

protected resolveApiKey(): Promise<string>;

Defined in: src/providers/base/BaseProvider.ts:321

Resolve the API key, calling the factory if apiKey is a function.

Returns

Promise<string>

The resolved API key string, or 'proxy' in proxy mode.

Inherited from

RestSTTProvider.resolveApiKey

resolveAuthHeader()

protected resolveAuthHeader(defaultAuthType?): Promise<string | undefined>;

Defined in: src/providers/base/BaseProvider.ts:366

Resolve Authorization header value for the configured auth type.

Parameters

Returns

Promise<string | undefined>

The Authorization header value, or undefined in proxy mode.

Remarks

If apiKey is a factory function it is called to get a fresh token. Returns the header value for REST or server-side WebSocket connections:

• 'token' → 'Token <apiKey>'
• 'bearer' → 'Bearer <apiKey>'

Returns undefined in proxy mode.

Inherited from

RestSTTProvider.resolveAuthHeader

resolveBaseUrl()

protected resolveBaseUrl(defaultUrl?): string | undefined;

Defined in: src/providers/base/BaseProvider.ts:307

Resolve the base URL for this provider.

Parameters

Returns

string | undefined

The resolved URL, or undefined when all sources are unset.

Remarks

Priority: proxyUrl > endpoint > defaultUrl.

For WebSocket providers (this.type === 'websocket'), the proxy URL’s http(s) scheme is automatically converted to ws(s).

When no URL is configured and defaultUrl is undefined, the return value is undefined — this lets SDK-based providers (Anthropic, OpenAI) fall back to their own built-in defaults.

Inherited from

RestSTTProvider.resolveBaseUrl

resolveWsProtocols()

protected resolveWsProtocols(defaultAuthType?): Promise<string[] | undefined>;

Defined in: src/providers/base/BaseProvider.ts:342

Resolve WebSocket subprotocol for authentication.

Parameters

Returns

Promise<string[] | undefined>

Subprotocol array for new WebSocket(url, protocols), or undefined.

Remarks

If apiKey is a factory function it is called to get a fresh token. Returns the subprotocol array for direct mode based on authType:

• 'token' → ['token', apiKey] (Deepgram default)
• 'bearer' → ['bearer', apiKey] (OAuth/Bearer tokens)

Returns undefined in proxy mode (no client-side auth needed).

Inherited from

RestSTTProvider.resolveWsProtocols

transcribe()

transcribe(audio): Promise<void>;

Defined in: src/providers/stt/google/GoogleSTT.ts:328

Transcribes a complete audio recording using the Google Cloud STT synchronous REST API.

Parameters

Returns

Promise<void>

Remarks

The audio is base64-encoded and sent inline (audio.content), so it is limited to 60 seconds / ~10 MB per request — one utterance at a time, not long-form transcription. The transcripts of all returned result segments are concatenated and emitted as a single final TranscriptionResult with utteranceComplete: true. When enableWordTimeOffsets is enabled, word timings are exposed in metadata.words.

If Google detects no speech in the audio, no result is emitted.

Throws

Error if the provider is not initialized.

Throws

ProviderResponseError if the Google Cloud STT API request fails.

Overrides

RestSTTProvider.transcribe

updateConfig()

updateConfig(config): void;

Defined in: src/providers/base/BaseProvider.ts:201

Merge partial configuration updates into the current config.

Parameters

Returns

void

Remarks

After merging, the subclass hook onConfigUpdate is called so providers can react to changed values at runtime.

Inherited from

RestSTTProvider.updateConfig