refactor(stt): extract shared helpers and cleanup

Author: chriswritescode-dev

docs/features/stt.md

@@ -69,12 +69,6 @@ Any OpenAI-compatible transcription API works:
 - Self-hosted Whisper servers
 - Local STT servers with OpenAI-compatible API
 
-### Performance
-
-When external voice input is enabled, the browser audio pipeline is warmed up ahead of time so the first and subsequent recordings start faster. The audio context and worklet processor are prepared without requesting microphone access, and are retained between recordings; only the microphone track is stopped after each use. Resources are released entirely when external STT is disabled or the voice input UI unmounts.
-
-This optimization applies only to the external API provider. It does not affect the initial permission prompt — the browser still asks for microphone access on the first recording.
-
 ## Using Voice Input
 
 ### Tap-to-Start / Tap-to-Stop

frontend/src/components/message/VoiceStatusOverlay.tsx

@@ -48,7 +48,7 @@ export function VoiceStatusOverlay({ show, label, state }: VoiceStatusOverlayPro
       className="pointer-events-none absolute inset-x-0 bottom-0 z-10"
     >
       <span className="sr-only">{label}</span>
-      <div className="relative flex h-36 w-full flex-col items-center justify-between overflow-hidden rounded-xl border border-green-300/70 bg-gradient-to-t from-green-700 via-green-500 to-emerald-400 px-1 py-3 text-white shadow-lg shadow-green-500/40">
+      <div className="animate-voice-overlay-in relative flex h-44 w-full flex-col items-center justify-between overflow-hidden rounded-xl border border-green-300/70 bg-gradient-to-t from-green-700 via-green-500 to-emerald-400 px-1 py-4 text-white shadow-lg shadow-green-500/40">
         <div className="absolute inset-x-1 top-1 h-10 rounded-full bg-white/20 blur-sm" />
         <div className="relative flex flex-1 flex-col items-center justify-center gap-1">
           {isLoading ? (

frontend/src/components/settings/STTSettings.tsx

@@ -127,6 +127,9 @@ export function STTSettings() {
       } else if (sttError) {
         setTestResult('failed')
         setIsTesting(false)
+      } else {
+        setTestResult('idle')
+        setIsTesting(false)
       }
     }
   }, [isTesting, isRecording, isProcessing, transcript, sttError])

frontend/src/hooks/useSTT.test.tsx

@@ -30,10 +30,14 @@ vi.mock('@/lib/audioRecorder', () => ({
   AudioRecorder: mocks.AudioRecorder,
 }))
 
-vi.mock('@/lib/webSpeechRecognizer', () => ({
-  getWebSpeechRecognizer: mocks.getWebSpeechRecognizer,
-  isWebRecognitionSupported: mocks.isWebRecognitionSupported,
-}))
+vi.mock('@/lib/webSpeechRecognizer', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/lib/webSpeechRecognizer')>()
+  return {
+    appendTranscriptSegment: actual.appendTranscriptSegment,
+    getWebSpeechRecognizer: mocks.getWebSpeechRecognizer,
+    isWebRecognitionSupported: mocks.isWebRecognitionSupported,
+  }
+})
 
 vi.mock('@/api/stt', () => ({
   sttApi: mocks.sttApi,

frontend/src/hooks/useSTT.ts

@@ -1,6 +1,6 @@
 import { useState, useEffect, useRef, useCallback } from 'react'
 import { useSettings } from '@/hooks/useSettings'
-import { getWebSpeechRecognizer, isWebRecognitionSupported, type SpeechRecognitionOptions, type SpeechRecognitionResult, type RecognitionState } from '@/lib/webSpeechRecognizer'
+import { getWebSpeechRecognizer, isWebRecognitionSupported, appendTranscriptSegment, type SpeechRecognitionOptions, type SpeechRecognitionResult, type RecognitionState } from '@/lib/webSpeechRecognizer'
 import { AudioRecorder } from '@/lib/audioRecorder'
 import { sttApi } from '@/api/stt'
 import { FetchError } from '@/api/fetchWrapper'
@@ -42,6 +42,24 @@ export function useSTT(userId = 'default') {
     ? AudioRecorder.isSupported()
     : isWebRecognitionSupported()
 
+  const flashError = useCallback((message: string) => {
+    setIsError(true)
+    setError(message)
+    if (errorTimeoutRef.current) clearTimeout(errorTimeoutRef.current)
+    errorTimeoutRef.current = setTimeout(() => {
+      setIsError(false)
+      setError(null)
+      errorTimeoutRef.current = null
+    }, 3000)
+  }, [])
+
+  const resetToIdle = useCallback((clearInterim = false) => {
+    setIsRecording(false)
+    setIsProcessing(false)
+    setState('idle')
+    if (clearInterim) setInterimTranscript('')
+  }, [])
+
   useEffect(() => {
     if (!isEnabled || isExternalProvider) {
       return
@@ -55,11 +73,7 @@ export function useSTT(userId = 'default') {
 
     rec.onResult((result: SpeechRecognitionResult) => {
       setIsProcessing(false)
-      setTranscript((prev) => {
-        const prevTrimmed = prev.trim()
-        const next = result.transcript.trim()
-        return prevTrimmed ? `${prevTrimmed} ${next}` : next
-      })
+      setTranscript((prev) => appendTranscriptSegment(prev, result.transcript))
     })
 
     rec.onInterimResult((interim: string) => {
@@ -74,21 +88,11 @@ export function useSTT(userId = 'default') {
     rec.onError((errorMessage: string) => {
       setIsProcessing(false)
       setIsRecording(false)
-      setIsError(true)
-      setError(errorMessage)
-
-      if (errorTimeoutRef.current) clearTimeout(errorTimeoutRef.current)
-      errorTimeoutRef.current = setTimeout(() => {
-        setIsError(false)
-        setError(null)
-        errorTimeoutRef.current = null
-      }, 3000)
+      flashError(errorMessage)
     })
 
     rec.onEnd(() => {
-      setIsRecording(false)
-      setIsProcessing(false)
-      setState('idle')
+      resetToIdle()
     })
 
     rec.onStart(() => {
@@ -105,7 +109,7 @@ export function useSTT(userId = 'default') {
         interimRafRef.current = null
       }
     }
-  }, [isEnabled, isExternalProvider])
+  }, [isEnabled, isExternalProvider, flashError, resetToIdle])
 
   const setupAudioRecorder = useCallback((recorder: AudioRecorder) => {
     recorder.setOnStateChange((recState) => {
@@ -117,9 +121,7 @@ export function useSTT(userId = 'default') {
       } else if (recState === 'stopped') {
         setIsRecording(false)
       } else if (recState === 'error') {
-        setIsRecording(false)
-        setIsProcessing(false)
-        setState('idle')
+        resetToIdle()
       } else if (recState === 'idle') {
         setState('idle')
       }
@@ -128,22 +130,11 @@ export function useSTT(userId = 'default') {
     recorder.setOnError((errorMessage) => {
       setIsProcessing(false)
       setIsRecording(false)
-      setIsError(true)
-      setError(errorMessage)
-
-      if (errorTimeoutRef.current) clearTimeout(errorTimeoutRef.current)
-      errorTimeoutRef.current = setTimeout(() => {
-        setIsError(false)
-        setError(null)
-        errorTimeoutRef.current = null
-      }, 3000)
+      flashError(errorMessage)
     })
 
     recorder.setOnNoSpeech(() => {
-      setIsProcessing(false)
-      setIsRecording(false)
-      setInterimTranscript('')
-      setState('idle')
+      resetToIdle(true)
     })
 
     recorder.setOnDataAvailable(async (blob) => {
@@ -163,11 +154,7 @@ export function useSTT(userId = 'default') {
           abortControllerRef.current.signal
         )
 
-        setTranscript((prev) => {
-          const prevTrimmed = prev.trim()
-          const newText = result.text.trim()
-          return prevTrimmed ? `${prevTrimmed} ${newText}` : newText
-        })
+        setTranscript((prev) => appendTranscriptSegment(prev, result.text))
         setInterimTranscript('')
       } catch (err) {
         if (err instanceof Error && (
@@ -177,23 +164,14 @@ export function useSTT(userId = 'default') {
           return
         }
 
-        setIsError(true)
-        const errorMessage = err instanceof Error ? err.message : 'Transcription failed'
-        setError(errorMessage)
-        
-        if (errorTimeoutRef.current) clearTimeout(errorTimeoutRef.current)
-        errorTimeoutRef.current = setTimeout(() => {
-          setIsError(false)
-          setError(null)
-          errorTimeoutRef.current = null
-        }, 3000)
+        flashError(err instanceof Error ? err.message : 'Transcription failed')
       } finally {
         setIsProcessing(false)
         setState('idle')
         abortControllerRef.current = null
       }
     })
-  }, [])
+  }, [flashError, resetToIdle])
 
   const ensureAudioRecorder = useCallback((): AudioRecorder => {
     if (!audioRecorder.current) {
@@ -233,12 +211,10 @@ export function useSTT(userId = 'default') {
     } else {
       recognizer.current.abort()
     }
-    setIsRecording(false)
-    setIsProcessing(false)
-    setState('idle')
+    resetToIdle()
     setIsError(true)
     setError('Microphone start timed out')
-  }, [isExternalProvider, disposeAudioRecorder])
+  }, [isExternalProvider, disposeAudioRecorder, resetToIdle])
 
   const runStartupWithTimeout = useCallback(
     async (startup: () => Promise<void>, startOpId: number): Promise<boolean> => {
@@ -340,21 +316,15 @@ export function useSTT(userId = 'default') {
     }
 
     setTranscript('')
-    setInterimTranscript('')
-    setIsRecording(false)
-    setIsProcessing(false)
-    setState('idle')
-  }, [isExternalProvider])
+    resetToIdle(true)
+  }, [isExternalProvider, resetToIdle])
 
   const reset = useCallback(() => {
     setTranscript('')
-    setInterimTranscript('')
     setIsError(false)
     setError(null)
-    setIsRecording(false)
-    setIsProcessing(false)
-    setState('idle')
-  }, [])
+    resetToIdle(true)
+  }, [resetToIdle])
 
   const clear = useCallback(() => {
     setTranscript('')

frontend/src/index.css

@@ -128,6 +128,15 @@ body {
   animation: page-slide-in-from-left 300ms cubic-bezier(0.2, 0.9, 0.3, 1) forwards;
 }
 
+@keyframes voice-overlay-in {
+  from { transform: translateY(12px) scale(0.97); opacity: 0; }
+  to { transform: translateY(0) scale(1); opacity: 1; }
+}
+
+.animate-voice-overlay-in {
+  animation: voice-overlay-in 180ms cubic-bezier(0.2, 0.9, 0.3, 1);
+}
+
 @keyframes shine-loading {
   0% {
     background-position: -200% 0;

frontend/src/lib/audioRecorder.test.ts

@@ -1,8 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { AudioRecorder } from './audioRecorder'
 
-// ── Fake MediaRecorder ─────────────────────────────────────────────────────
-
 class FakeMediaRecorder {
   static _instances: FakeMediaRecorder[] = []
   static _supportedTypes = new Set<string>([
@@ -37,8 +35,6 @@ class FakeMediaRecorder {
   }
 }
 
-// ── Helpers ─────────────────────────────────────────────────────────────────
-
 function createMockTrack(): MediaStreamTrack {
   return { stop: vi.fn(), kind: 'audio' } as unknown as MediaStreamTrack
 }
@@ -59,8 +55,6 @@ function createMockStream(tracks: MediaStreamTrack[] = [createMockTrack()]): Med
   } as unknown as MediaStream
 }
 
-// ── describe: AudioRecorder.isSupported ─────────────────────────────────────
-
 describe('AudioRecorder.isSupported', () => {
   afterEach(() => {
     vi.restoreAllMocks()
@@ -109,8 +103,6 @@ describe('AudioRecorder.isSupported', () => {
   })
 })
 
-// ── Describe: AudioRecorder start ───────────────────────────────────────────
-
 describe('AudioRecorder start', () => {
   let mockGetUserMedia: ReturnType<typeof vi.fn>
   let mockTrack: ReturnType<typeof createMockTrack>
@@ -189,15 +181,6 @@ describe('AudioRecorder start', () => {
     expect(mr.mimeType).toBe('')
   })
 
-  it('uses configured mimeTypes when provided', async () => {
-    recorder = new AudioRecorder({ mimeTypes: ['audio/wav', 'audio/ogg'] })
-    recorder.setOnStateChange(onStateChange)
-    FakeMediaRecorder._supportedTypes = new Set(['audio/wav', 'audio/ogg'])
-    await recorder.start()
-    const mr = FakeMediaRecorder._instances[0]
-    expect(mr.mimeType).toBe('audio/wav')
-  })
-
   it('transitions to recording state', async () => {
     await recorder.start()
     expect(recorder.getState()).toBe('recording')
@@ -206,8 +189,6 @@ describe('AudioRecorder start', () => {
 
 })
 
-// ── describe: AudioRecorder stop ────────────────────────────────────────────
-
 describe('AudioRecorder stop', () => {
   let mockGetUserMedia: ReturnType<typeof vi.fn>
   let mockTrack: ReturnType<typeof createMockTrack>
@@ -307,8 +288,6 @@ describe('AudioRecorder stop', () => {
   })
 })
 
-// ── describe: AudioRecorder no-speech ───────────────────────────────────────
-
 describe('AudioRecorder no-speech', () => {
   let mockGetUserMedia: ReturnType<typeof vi.fn>
   let mockTrack: ReturnType<typeof createMockTrack>
@@ -366,8 +345,6 @@ describe('AudioRecorder no-speech', () => {
   })
 })
 
-// ── describe: AudioRecorder abort and dispose ───────────────────────────────
-
 describe('AudioRecorder abort and dispose', () => {
   let mockGetUserMedia: ReturnType<typeof vi.fn>
   let mockTrack: ReturnType<typeof createMockTrack>
@@ -431,8 +408,6 @@ describe('AudioRecorder abort and dispose', () => {
   })
 })
 
-// ── describe: AudioRecorder error handling ──────────────────────────────────
-
 describe('AudioRecorder error handling', () => {
   let recorder: AudioRecorder
   let onError: ReturnType<typeof vi.fn>
@@ -504,41 +479,3 @@ describe('AudioRecorder error handling', () => {
     expect(onStateChange).toHaveBeenCalledWith('error')
   })
 })
-
-// ── describe: AudioRecorder.prepare ─────────────────────────────────────────
-
-describe('AudioRecorder.prepare', () => {
-  afterEach(() => {
-    vi.restoreAllMocks()
-  })
-
-  it('resolves when supported', async () => {
-    Object.defineProperty(navigator, 'mediaDevices', {
-      value: { getUserMedia: vi.fn() },
-      writable: true,
-      configurable: true,
-    })
-    Object.defineProperty(window, 'MediaRecorder', {
-      value: FakeMediaRecorder,
-      writable: true,
-      configurable: true,
-    })
-    const recorder = new AudioRecorder()
-    await expect(recorder.prepare()).resolves.toBeUndefined()
-  })
-
-  it('throws when not supported', async () => {
-    Object.defineProperty(navigator, 'mediaDevices', {
-      value: {},
-      writable: true,
-      configurable: true,
-    })
-    Object.defineProperty(window, 'MediaRecorder', {
-      value: undefined,
-      writable: true,
-      configurable: true,
-    })
-    const recorder = new AudioRecorder()
-    await expect(recorder.prepare()).rejects.toThrow('Audio recording is not supported in this browser')
-  })
-})