tjbot-ce 3.0.1

package/dist/stt/backends/azure-stt.js

@@ -0,0 +1,227 @@
+/**
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import * as sdk from 'microsoft-cognitiveservices-speech-sdk';
+import { loadAzureCredentials } from '../../utils/credentials.js';
+import { TJBotError } from '../../utils/index.js';
+import { getLogger } from '../../utils/logging.js';
+import { STTEngine } from '../stt-engine.js';
+import { isTimeoutLikeStreamEndReason, resolveTranscriptForStreamEnd } from '../stt-utils.js';
+const logger = getLogger(import.meta.url);
+/**
+ * Azure Cognitive Services Speech-to-Text Engine
+ *
+ * Cloud-based speech recognition using Microsoft Azure Speech Services.
+ * Requires Azure subscription key and region to be configured.
+ * @public
+ */
+export class AzureSTTEngine extends STTEngine {
+    microphoneRate = 44100;
+    microphoneChannels = 2;
+    subscriptionKey;
+    region;
+    async initialize(microphoneRate, microphoneChannels) {
+        const config = this.config;
+        const credentials = loadAzureCredentials(config?.credentialsPath);
+        this.subscriptionKey = credentials.speechKey;
+        this.region = credentials.speechRegion;
+        if (!config?.language) {
+            throw new TJBotError('Azure STT language not specified. Provide language in listen.backend.azure-stt config.');
+        }
+        if (!this.subscriptionKey || !this.region) {
+            throw new TJBotError('Azure Speech subscription key and region are required.');
+        }
+        this.microphoneRate = microphoneRate;
+        this.microphoneChannels = microphoneChannels;
+        logger.info('Azure STT engine initialized');
+        logger.debug(`Initialized AzureSTTEngine with config:
+            language: ${config?.language},
+            region: ${config?.region},
+            microphoneRate: ${this.microphoneRate},
+            microphoneChannels: ${this.microphoneChannels},
+            subscriptionKey: ${this.subscriptionKey ? '***' : 'not set'}
+        `);
+    }
+    async transcribe(micStream, options) {
+        const config = this.config;
+        if (!this.subscriptionKey || !this.region) {
+            throw new TJBotError('Azure STT not initialized. Call initialize() first.');
+        }
+        const interimResults = config?.interimResults ?? false;
+        logger.verbose(`Transcribing speech with Azure STT (language=${config?.language})`);
+        // Create speech config
+        const speechConfig = sdk.SpeechConfig.fromSubscription(this.subscriptionKey, this.region);
+        speechConfig.speechRecognitionLanguage = config?.language;
+        // Create audio config from stream
+        const audioFormat = sdk.AudioStreamFormat.getWaveFormatPCM(this.microphoneRate, 16, this.microphoneChannels);
+        const pushStream = sdk.AudioInputStream.createPushStream(audioFormat);
+        // Pipe microphone data to push stream
+        this.ensureStream(micStream).on('data', (chunk) => {
+            // Azure SDK expects an ArrayBuffer, convert Buffer while preserving view
+            const arrayBuffer = chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength);
+            pushStream.write(arrayBuffer);
+            logger.silly(`piped ${chunk.length} bytes from microphone to Azure STT push stream`);
+        });
+        this.ensureStream(micStream).on('end', () => {
+            pushStream.close();
+            logger.silly('microphone stream ended, closed Azure STT push stream');
+        });
+        const audioConfig = sdk.AudioConfig.fromStreamInput(pushStream);
+        // Create recognizer
+        const recognizer = new sdk.SpeechRecognizer(speechConfig, audioConfig);
+        if (!interimResults) {
+            return new Promise((resolve, reject) => {
+                recognizer.recognizeOnceAsync((result) => {
+                    recognizer.close();
+                    if (result.reason === sdk.ResultReason.RecognizedSpeech) {
+                        logger.debug(`Azure STT recognized: ${result.text}`);
+                        resolve(result.text.trim());
+                    }
+                    else if (result.reason === sdk.ResultReason.NoMatch) {
+                        reject(new TJBotError('Azure STT: No speech could be recognized', {
+                            code: 'stt.no-speech',
+                        }));
+                    }
+                    else if (result.reason === sdk.ResultReason.Canceled) {
+                        const cancellation = sdk.CancellationDetails.fromResult(result);
+                        reject(new TJBotError(`Azure STT canceled: ${cancellation.reason} - ${cancellation.errorDetails}`));
+                    }
+                    else {
+                        reject(new TJBotError(`Azure STT recognition failed with reason: ${result.reason}`));
+                    }
+                }, (error) => {
+                    recognizer.close();
+                    reject(new TJBotError('Azure STT recognition error', { cause: new Error(error) }));
+                });
+            });
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let latestPartialTranscript = '';
+            let latestFinalTranscript = '';
+            const cleanup = () => {
+                recognizer.recognizing = () => {
+                    // no-op after cleanup
+                };
+                recognizer.recognized = () => {
+                    // no-op after cleanup
+                };
+                recognizer.canceled = () => {
+                    // no-op after cleanup
+                };
+                recognizer.sessionStopped = () => {
+                    // no-op after cleanup
+                };
+                recognizer.close();
+            };
+            const settleResolve = (text) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                recognizer.stopContinuousRecognitionAsync(() => {
+                    cleanup();
+                    resolve(text);
+                }, (error) => {
+                    cleanup();
+                    reject(new TJBotError('Azure STT stop recognition error', { cause: new Error(error) }));
+                });
+            };
+            const settleReject = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                recognizer.stopContinuousRecognitionAsync(() => {
+                    cleanup();
+                    reject(error);
+                }, () => {
+                    cleanup();
+                    reject(error);
+                });
+            };
+            recognizer.recognizing = (_sender, event) => {
+                const text = event.result?.text?.trim();
+                if (text) {
+                    latestPartialTranscript = text;
+                    options.onPartialResult?.(text);
+                }
+            };
+            recognizer.recognized = (_sender, event) => {
+                if (event.result.reason === sdk.ResultReason.RecognizedSpeech) {
+                    const text = event.result.text?.trim();
+                    if (text) {
+                        latestFinalTranscript = text;
+                        logger.debug(`Azure STT recognized: ${text}`);
+                        options.onFinalResult?.(text);
+                        settleResolve(text);
+                    }
+                    return;
+                }
+                if (event.result.reason === sdk.ResultReason.NoMatch) {
+                    settleReject(new TJBotError('Azure STT: No speech could be recognized', {
+                        code: 'stt.no-speech',
+                    }));
+                }
+            };
+            recognizer.canceled = (_sender, event) => {
+                const cancelReason = `${event.reason} - ${event.errorDetails || ''}`;
+                const timeoutLikeEnd = isTimeoutLikeStreamEndReason(cancelReason);
+                const fallbackTranscript = resolveTranscriptForStreamEnd({
+                    finalTranscript: latestFinalTranscript,
+                    partialTranscript: latestPartialTranscript,
+                    allowPartialOnTimeoutLikeEnd: true,
+                    timeoutLikeEnd,
+                });
+                if (fallbackTranscript) {
+                    logger.debug('Azure STT finalized using partial transcript after cancel event');
+                    options.onFinalResult?.(fallbackTranscript);
+                    settleResolve(fallbackTranscript);
+                    return;
+                }
+                if (timeoutLikeEnd) {
+                    settleReject(new TJBotError('Azure STT: No speech could be recognized', {
+                        code: 'stt.no-speech',
+                    }));
+                    return;
+                }
+                settleReject(new TJBotError(`Azure STT canceled: ${event.reason} - ${event.errorDetails}`));
+            };
+            recognizer.sessionStopped = () => {
+                const fallbackTranscript = resolveTranscriptForStreamEnd({
+                    finalTranscript: latestFinalTranscript,
+                    partialTranscript: latestPartialTranscript,
+                    allowPartialOnTimeoutLikeEnd: true,
+                    timeoutLikeEnd: true,
+                });
+                if (fallbackTranscript) {
+                    logger.debug('Azure STT finalized using partial transcript after session stop');
+                    options.onFinalResult?.(fallbackTranscript);
+                    settleResolve(fallbackTranscript);
+                    return;
+                }
+                settleReject(new TJBotError('Azure STT: No speech could be recognized', {
+                    code: 'stt.no-speech',
+                }));
+            };
+            recognizer.startContinuousRecognitionAsync(() => {
+                logger.silly('Azure STT continuous recognition started');
+            }, (error) => {
+                settleReject(new TJBotError('Azure STT start recognition error', { cause: new Error(error) }));
+            });
+        });
+    }
+}
+//# sourceMappingURL=azure-stt.js.map

package/dist/stt/backends/azure-stt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"azure-stt.js","sourceRoot":"","sources":["../../../src/stt/backends/azure-stt.ts"],"names":[],"mappings":"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"}

package/dist/stt/backends/google-cloud-stt.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { STTEngine, STTRequestOptions } from '../stt-engine.js';
+/**
+ * Google Cloud Speech-to-Text Engine
+ *
+ * Cloud-based speech recognition using Google Cloud Speech-to-Text API.
+ * Requires Google Cloud credentials JSON file to be configured.
+ * @public
+ */
+export declare class GoogleCloudSTTEngine extends STTEngine {
+    private microphoneRate;
+    private microphoneChannels;
+    private client;
+    initialize(microphoneRate: number, microphoneChannels: number): Promise<void>;
+    transcribe(micStream: NodeJS.ReadableStream, options: STTRequestOptions): Promise<string>;
+}
+//# sourceMappingURL=google-cloud-stt.d.ts.map

package/dist/stt/backends/google-cloud-stt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-cloud-stt.d.ts","sourceRoot":"","sources":["../../../src/stt/backends/google-cloud-stt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAqFhE;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAC/C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,kBAAkB,CAAa;IACvC,OAAO,CAAC,MAAM,CAAoC;IAE5C,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+C7E,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;CA0SlG"}

package/dist/stt/backends/google-cloud-stt.js

@@ -0,0 +1,371 @@
+/**
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { protos as speechProtos, v2 as speechV2 } from '@google-cloud/speech';
+import { isTimeoutLikeStreamEndReason, resolveTranscriptForStreamEnd } from '../stt-utils.js';
+import { loadGoogleCloudCredentials } from '../../utils/credentials.js';
+import { TJBotError } from '../../utils/index.js';
+import { getLogger } from '../../utils/logging.js';
+import { STTEngine } from '../stt-engine.js';
+const logger = getLogger(import.meta.url);
+const SUPPORTED_GOOGLE_STT_MODEL_REGIONS = {
+    chirp_3: ['us', 'eu'],
+    chirp_2: ['us-central1', 'europe-west4', 'asia-southeast1'],
+};
+const MAX_GOOGLE_STT_AUDIO_CHUNK_BYTES = 25600;
+function assertSupportedGoogleSTTModelAndRegion(model, region) {
+    if (!(model in SUPPORTED_GOOGLE_STT_MODEL_REGIONS)) {
+        throw new TJBotError(`Google Cloud STT model "${model}" is not supported. Supported models: ${Object.keys(SUPPORTED_GOOGLE_STT_MODEL_REGIONS).join(', ')}`);
+    }
+    const supportedRegions = [...SUPPORTED_GOOGLE_STT_MODEL_REGIONS[model]];
+    if (!supportedRegions.includes(region)) {
+        throw new TJBotError(`Google Cloud STT region "${region}" is not supported for model "${model}". Supported regions: ${supportedRegions.join(', ')}`);
+    }
+}
+function toGoogleCloudRecognitionError(error, recognizerPath) {
+    const googleError = error;
+    const permission = googleError.errorInfoMetadata?.permission;
+    const details = googleError.details ?? googleError.message;
+    const isPermissionDenied = googleError.code === 7 ||
+        googleError.reason === 'IAM_PERMISSION_DENIED' ||
+        permission === 'speech.recognizers.recognize';
+    const isAudioChunkTooLarge = googleError.code === 3 && /maximum of 25600 bytes/i.test(details);
+    if (isAudioChunkTooLarge) {
+        return new TJBotError(`Google Cloud STT rejected an audio chunk over ${MAX_GOOGLE_STT_AUDIO_CHUNK_BYTES} bytes. Audio must be streamed in smaller chunks.`, {
+            code: 'stt.google-cloud.chunk-too-large',
+            cause: error,
+            context: {
+                recognizer: recognizerPath,
+                details,
+            },
+        });
+    }
+    if (isPermissionDenied) {
+        return new TJBotError(`Google Cloud STT permission denied for recognizer ${recognizerPath}. Ensure the credentials have the permission speech.recognizers.recognize on that recognizer resource and that the selected region matches the recognizer location.`, {
+            code: 'stt.google-cloud.permission-denied',
+            cause: error,
+            context: {
+                recognizer: recognizerPath,
+                permission: permission ?? 'speech.recognizers.recognize',
+                details,
+            },
+        });
+    }
+    return new TJBotError('Google Cloud STT recognition failed', {
+        cause: error,
+        context: {
+            recognizer: recognizerPath,
+            details,
+        },
+    });
+}
+/**
+ * Google Cloud Speech-to-Text Engine
+ *
+ * Cloud-based speech recognition using Google Cloud Speech-to-Text API.
+ * Requires Google Cloud credentials JSON file to be configured.
+ * @public
+ */
+export class GoogleCloudSTTEngine extends STTEngine {
+    microphoneRate = 44100;
+    microphoneChannels = 2;
+    client;
+    async initialize(microphoneRate, microphoneChannels) {
+        const config = this.config;
+        const credentials = loadGoogleCloudCredentials(config?.credentialsPath);
+        const model = config?.model?.trim();
+        const languageCode = config?.languageCode?.trim();
+        const region = config?.region?.trim();
+        const endpoint = `${region}-speech.googleapis.com`;
+        const enableAutomaticPunctuation = config?.enableAutomaticPunctuation ?? true;
+        const profanityFilter = config?.profanityFilter ?? true;
+        const interimResults = config?.interimResults ?? true;
+        if (!model) {
+            throw new TJBotError('Google Cloud STT model not specified. Provide model in listen.backend.google-cloud-stt config.');
+        }
+        if (!languageCode) {
+            throw new TJBotError('Google Cloud STT languageCode not specified. Provide languageCode in listen.backend.google-cloud-stt config.');
+        }
+        if (!region) {
+            throw new TJBotError('Google Cloud STT region not specified. Provide region in listen.backend.google-cloud-stt config.');
+        }
+        assertSupportedGoogleSTTModelAndRegion(model, region);
+        this.microphoneRate = microphoneRate;
+        this.microphoneChannels = microphoneChannels;
+        this.client = new speechV2.SpeechClient({ apiEndpoint: endpoint });
+        logger.info('Google Cloud STT engine initialized');
+        logger.debug(`Initialized GoogleCloudSTTEngine with config:
+            model: ${model},
+            languageCode: ${languageCode},
+            region: ${region},
+            endpoint: ${endpoint},
+            enableAutomaticPunctuation: ${enableAutomaticPunctuation},
+            profanityFilter: ${profanityFilter},
+            interimResults: ${interimResults},
+            microphoneRate: ${this.microphoneRate},
+            microphoneChannels: ${this.microphoneChannels},
+            credentialsPath: ${credentials.credentialsPath}`);
+    }
+    async transcribe(micStream, options) {
+        const config = this.config;
+        const model = config?.model?.trim();
+        const languageCode = config?.languageCode?.trim();
+        const region = config?.region?.trim();
+        const enableAutomaticPunctuation = config?.enableAutomaticPunctuation ?? true;
+        const profanityFilter = config?.profanityFilter ?? true;
+        const interimResults = config?.interimResults ?? true;
+        if (!this.client) {
+            throw new TJBotError('Google Cloud STT client not initialized. Call initialize() first.');
+        }
+        const client = this.client;
+        if (!model) {
+            throw new TJBotError('Google Cloud STT model not specified. Provide model in listen.backend.google-cloud-stt config.');
+        }
+        if (!languageCode) {
+            throw new TJBotError('Google Cloud STT languageCode not specified. Provide languageCode in listen.backend.google-cloud-stt config.');
+        }
+        if (!region) {
+            throw new TJBotError('Google Cloud STT region not specified. Provide region in listen.backend.google-cloud-stt config.');
+        }
+        assertSupportedGoogleSTTModelAndRegion(model, region);
+        const projectId = await client.getProjectId();
+        const recognizerPath = `projects/${projectId}/locations/${region}/recognizers/_`;
+        logger.verbose(`Transcribing speech with Google Cloud STT v2 (model=${model}, languageCode=${languageCode}, recognizer=${recognizerPath})`);
+        const request = {
+            config: {
+                explicitDecodingConfig: {
+                    encoding: speechProtos.google.cloud.speech.v2.ExplicitDecodingConfig.AudioEncoding.LINEAR16,
+                    sampleRateHertz: this.microphoneRate,
+                    audioChannelCount: this.microphoneChannels,
+                },
+                model,
+                languageCodes: [languageCode],
+                features: {
+                    profanityFilter,
+                    enableAutomaticPunctuation,
+                },
+            },
+            streamingFeatures: {
+                interimResults,
+            },
+        };
+        logger.silly('Google Cloud STT params:', JSON.stringify(request, null, 2));
+        const sourceStream = this.ensureStream(micStream);
+        return new Promise((resolve, reject) => {
+            const recognizeStream = client._streamingRecognize();
+            let settled = false;
+            let timeoutLikeStreamEnd = false;
+            let latestPartialTranscript = '';
+            let latestFinalTranscript = '';
+            const settleResolve = (transcript) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                resolve(transcript);
+            };
+            const settleReject = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            const handleData = (data) => {
+                if (data.results && data.results.length > 0) {
+                    const result = data.results[0];
+                    if (!result.alternatives || result.alternatives.length === 0) {
+                        return;
+                    }
+                    const transcript = result.alternatives[0].transcript?.trim();
+                    if (!transcript) {
+                        return;
+                    }
+                    if (!result.isFinal) {
+                        // Always retain latest non-final transcript so timeout endings can still return best effort text.
+                        latestPartialTranscript = transcript;
+                    }
+                    if (interimResults && !result.isFinal) {
+                        options.onPartialResult?.(transcript);
+                        return;
+                    }
+                    if (result.isFinal) {
+                        latestFinalTranscript = transcript;
+                        logger.debug(`Google Cloud STT recognized: ${transcript}`);
+                        if (interimResults) {
+                            options.onFinalResult?.(transcript);
+                        }
+                        settleResolve(transcript);
+                    }
+                }
+            };
+            const handleMicData = (chunk) => {
+                if (settled) {
+                    return;
+                }
+                let audioChunk;
+                if (typeof chunk === 'string') {
+                    audioChunk = Buffer.from(chunk);
+                }
+                else if (Buffer.isBuffer(chunk)) {
+                    audioChunk = chunk;
+                }
+                else {
+                    audioChunk = Buffer.from(chunk);
+                }
+                try {
+                    for (let offset = 0; offset < audioChunk.length; offset += MAX_GOOGLE_STT_AUDIO_CHUNK_BYTES) {
+                        const chunkSlice = audioChunk.subarray(offset, offset + MAX_GOOGLE_STT_AUDIO_CHUNK_BYTES);
+                        recognizeStream.write({
+                            audio: chunkSlice,
+                        });
+                    }
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    settleReject(toGoogleCloudRecognitionError(error, recognizerPath));
+                }
+            };
+            const handleMicEnd = () => {
+                if (!settled) {
+                    recognizeStream.end();
+                }
+            };
+            const handleMicError = (err) => {
+                logger.error('Google Cloud STT microphone stream error:', err);
+                settleReject(new TJBotError('Google Cloud STT microphone stream failed', { cause: err }));
+            };
+            const handleError = (err) => {
+                const timeoutLikeReason = isTimeoutLikeStreamEndReason(err.message);
+                timeoutLikeStreamEnd = timeoutLikeStreamEnd || timeoutLikeReason;
+                if (timeoutLikeReason) {
+                    logger.warn(`Google Cloud STT stream reached timeout-like ending: ${err.message}`);
+                }
+                else {
+                    logger.error('Google Cloud STT stream error:', err);
+                }
+                const fallbackTranscript = resolveTranscriptForStreamEnd({
+                    finalTranscript: latestFinalTranscript,
+                    partialTranscript: latestPartialTranscript,
+                    allowPartialOnTimeoutLikeEnd: true,
+                    timeoutLikeEnd: timeoutLikeStreamEnd,
+                });
+                if (fallbackTranscript) {
+                    logger.debug('Google Cloud STT finalized using partial transcript after stream timeout');
+                    if (interimResults) {
+                        options.onFinalResult?.(fallbackTranscript);
+                    }
+                    settleResolve(fallbackTranscript);
+                    return;
+                }
+                if (timeoutLikeStreamEnd) {
+                    settleReject(new TJBotError('Google Cloud STT: No speech could be recognized', {
+                        code: 'stt.no-speech',
+                    }));
+                    return;
+                }
+                settleReject(toGoogleCloudRecognitionError(err, recognizerPath));
+            };
+            const handleEndWithoutTranscript = () => {
+                const fallbackTranscript = resolveTranscriptForStreamEnd({
+                    finalTranscript: latestFinalTranscript,
+                    partialTranscript: latestPartialTranscript,
+                    allowPartialOnTimeoutLikeEnd: true,
+                    timeoutLikeEnd: timeoutLikeStreamEnd,
+                });
+                if (fallbackTranscript) {
+                    logger.debug('Google Cloud STT finalized using partial transcript after stream end');
+                    if (interimResults) {
+                        options.onFinalResult?.(fallbackTranscript);
+                    }
+                    settleResolve(fallbackTranscript);
+                    return;
+                }
+                settleReject(new TJBotError('Google Cloud STT: No speech could be recognized', {
+                    code: 'stt.no-speech',
+                }));
+            };
+            const handleStatus = (status) => {
+                if (status.code === 0 || status.code === undefined) {
+                    return;
+                }
+                timeoutLikeStreamEnd = timeoutLikeStreamEnd || isTimeoutLikeStreamEndReason(status.details);
+                const fallbackTranscript = resolveTranscriptForStreamEnd({
+                    finalTranscript: latestFinalTranscript,
+                    partialTranscript: latestPartialTranscript,
+                    allowPartialOnTimeoutLikeEnd: true,
+                    timeoutLikeEnd: timeoutLikeStreamEnd,
+                });
+                if (fallbackTranscript) {
+                    logger.debug('Google Cloud STT finalized using partial transcript from gRPC status');
+                    if (interimResults) {
+                        options.onFinalResult?.(fallbackTranscript);
+                    }
+                    settleResolve(fallbackTranscript);
+                    return;
+                }
+                if (timeoutLikeStreamEnd) {
+                    settleReject(new TJBotError('Google Cloud STT: No speech could be recognized', {
+                        code: 'stt.no-speech',
+                    }));
+                    return;
+                }
+                settleReject(new TJBotError(`Google Cloud STT recognition failed: ${status.details || 'unknown error'}`, {
+                    cause: new Error(`gRPC status ${String(status.code)}: ${status.details || 'unknown error'}`),
+                }));
+            };
+            const cleanup = () => {
+                sourceStream.removeListener('data', handleMicData);
+                sourceStream.removeListener('end', handleMicEnd);
+                sourceStream.removeListener('error', handleMicError);
+                recognizeStream.removeListener('data', handleData);
+                recognizeStream.removeListener('close', handleEndWithoutTranscript);
+                recognizeStream.removeListener('end', handleEndWithoutTranscript);
+                recognizeStream.removeListener('status', handleStatus);
+                try {
+                    if (!recognizeStream.destroyed) {
+                        recognizeStream.end();
+                    }
+                }
+                catch (err) {
+                    logger.debug('recognize stream end failed (likely already closed)', err);
+                }
+                recognizeStream.destroy();
+            };
+            recognizeStream.on('data', handleData);
+            recognizeStream.on('error', handleError);
+            recognizeStream.once('close', handleEndWithoutTranscript);
+            recognizeStream.once('end', handleEndWithoutTranscript);
+            recognizeStream.on('status', handleStatus);
+            try {
+                recognizeStream.write({
+                    recognizer: recognizerPath,
+                    streamingConfig: request,
+                });
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                settleReject(toGoogleCloudRecognitionError(error, recognizerPath));
+                return;
+            }
+            sourceStream.on('data', handleMicData);
+            sourceStream.once('end', handleMicEnd);
+            sourceStream.once('error', handleMicError);
+        });
+    }
+}
+//# sourceMappingURL=google-cloud-stt.js.map