Phase 1+2 구현: Electron 뼈대 + STT/핫키/오케스트레이터

Phase 1:
- 프로젝트 초기화 (TypeScript strict, electron-vite, ESLint, Prettier)
- shared 타입 (ipc-channels 113채널, types, errors, constants)
- 메인 프로세스 뼈대 (bootstrap, lifecycle, 단일 인스턴스)
- LoggerService, ConfigService (electron-store ESM dynamic import)
- React 19 + MUI 7 Dashboard, 시스템 트레이

Phase 2:
- AudioCaptureService (node-record-lpcm16, PCM16 16kHz mono)
- HotkeyService (uiohook-napi, 더블프레스, holdMode/toggleMode)
- LocalSTTService (faster-whisper Python sidecar, 이중 조건 플러시)
- VoiceModeService 오케스트레이터 (이중 상태머신, Action Queue)
- Python sidecar (FastAPI: health/load/transcribe/shutdown)
- IPC 핸들러 (voice, stt, hotkey) + Preload API 확장
This commit is contained in:
Yun Chan 2026-04-05 02:01:37 +09:00
parent e24bb8378c
commit 1d152d01a1
46 changed files with 10828 additions and 4 deletions

View file

@ -0,0 +1,625 @@
// src/main/services/VoiceModeService.ts
// 전체 음성 파이프라인 오케스트레이터.
// 설계서 01의 IVoiceModeService 구현. Speakly VoiceModeService의
// 상태 머신, 이중 조건 플러시, Action Queue 패턴 적용.
import { EventEmitter } from 'events'
import { randomUUID } from 'crypto'
import { getLogger } from './LoggerService'
import { getAudioCaptureService } from './AudioCaptureService'
import { getLocalSTTService } from './LocalSTTService'
import type { TranscriptionResult } from './LocalSTTService'
import { getHotkeyService } from './HotkeyService'
import type { HotkeyConfig } from './HotkeyService'
import { configGet } from './ConfigService'
import { D3ROError, ErrorCode } from '@shared/errors'
import { TIMING } from '@shared/constants'
import { RecognitionState, AudioState } from '@shared/types'
import type { VoiceMode, VoiceState } from '@shared/types'
const logger = getLogger('VoiceModeService')
// ============================================================
// 내부 타입
// ============================================================
interface VoiceSession {
id: string
mode: VoiceMode
startedAt: number
recognitionState: RecognitionState
audioState: AudioState
audioBufferDurationMs: number
transcription: string
processedText: string | null
accidentalPress: boolean
}
interface VoiceAction {
type: 'press' | 'release' | 'escape'
timestamp: number
mode: VoiceMode
hotkeyId: string
}
interface VoiceModeEvents {
'session-started': (payload: { session: VoiceSession }) => void
'recognition-state-changed': (payload: {
previous: RecognitionState
current: RecognitionState
}) => void
'audio-state-changed': (payload: {
previous: AudioState
current: AudioState
}) => void
'transcription-update': (payload: { text: string; isFinal: boolean }) => void
'session-completed': (payload: { session: VoiceSession; finalText: string }) => void
'session-cancelled': (payload: {
session: VoiceSession
reason: 'user' | 'timeout' | 'too-short'
}) => void
'audio-level': (payload: { level: number }) => void
error: (payload: { error: D3ROError; session: VoiceSession | null }) => void
}
// ============================================================
// 터미널 상태 헬퍼
// ============================================================
const TERMINAL_STATES = new Set<RecognitionState>([
RecognitionState.COMPLETED,
RecognitionState.CANCELLED,
RecognitionState.ERROR,
RecognitionState.DESTROYED
])
// ============================================================
// VoiceModeService
// ============================================================
class VoiceModeService extends EventEmitter {
private _session: VoiceSession | null = null
private _recognitionState = RecognitionState.IDLE
private _audioState = AudioState.IDLE
// 이중 조건 플러시
private _sttReady = false
private _audioStarted = false
private _audioBuffer: Buffer[] = []
private _audioBufferBytes = 0
// 에러 가드
private _errorEmitted = false
// Action Queue (이벤트 직렬화)
private _actionQueue: VoiceAction[] = []
private _isProcessingQueue = false
// 리스너 해제용 참조
private _audioDataHandler: ((payload: { buffer: Buffer }) => void) | null = null
private _audioLevelHandler: ((payload: { level: number }) => void) | null = null
private _hotkeyPressHandler: ((payload: { config: HotkeyConfig; timestamp: number }) => void) | null = null
private _hotkeyReleaseHandler: ((payload: { config: HotkeyConfig; durationMs: number; timestamp: number }) => void) | null = null
private _doublePressHandler: ((payload: { config: HotkeyConfig }) => void) | null = null
private _disposed = false
get currentSession(): VoiceSession | null {
return this._session
}
get isActive(): boolean {
return this._session !== null && !this._isInTerminalState()
}
getState(): VoiceState {
return {
recognitionState: this._recognitionState,
audioState: this._audioState,
mode: configGet('defaultLLMAction') === 'translate' ? 'hands-free' : 'dictation',
sessionId: this._session?.id ?? null,
recordingStartedAt: this._session?.startedAt ?? null
}
}
// ── 초기화 ──────────────────────────────────────────────
/**
* HotkeyService .
* bootstrap에서 .
*/
connectHotkey(): void {
const hotkey = getHotkeyService()
this._hotkeyPressHandler = (payload) => {
const mode = this._resolveMode(payload.config)
this._enqueueAction({ type: 'press', timestamp: payload.timestamp, mode, hotkeyId: payload.config.id })
}
this._hotkeyReleaseHandler = (payload) => {
const mode = this._resolveMode(payload.config)
this._enqueueAction({ type: 'release', timestamp: payload.timestamp, mode, hotkeyId: payload.config.id })
}
this._doublePressHandler = (payload) => {
// 더블프레스 → hands-free 모드 토글
this._enqueueAction({ type: 'press', timestamp: Date.now(), mode: 'hands-free', hotkeyId: payload.config.id })
}
hotkey.on('hotkey-pressed', this._hotkeyPressHandler)
hotkey.on('hotkey-released', this._hotkeyReleaseHandler)
hotkey.on('double-press', this._doublePressHandler)
logger.info('Hotkey events connected')
}
// ── 세션 제어 ──────────────────────────────────────────
async startSession(mode: VoiceMode): Promise<void> {
if (this._disposed) return
if (this._session && !this._isInTerminalState()) {
logger.warn('Session already active, ignoring startSession')
return
}
// 세션 생성
this._session = {
id: randomUUID(),
mode,
startedAt: Date.now(),
recognitionState: RecognitionState.PREPARING,
audioState: AudioState.IDLE,
audioBufferDurationMs: 0,
transcription: '',
processedText: null,
accidentalPress: false
}
this._errorEmitted = false
this._sttReady = false
this._audioStarted = false
this._audioBuffer = []
this._audioBufferBytes = 0
this._setRecognitionState(RecognitionState.PREPARING)
this.emit('session-started', { session: this._session })
logger.info(`Session started: ${this._session.id} (mode: ${mode})`)
// 이중 조건 플러시: STT 초기화 + 오디오 캡처를 병렬 시작
const sttPromise = this._initSTT()
const audioPromise = this._startAudio()
// 둘 다 에러여도 개별 처리하므로 allSettled
await Promise.allSettled([sttPromise, audioPromise])
}
async stopSession(): Promise<void> {
if (!this._session || this._isInTerminalState()) return
const session = this._session
const duration = Date.now() - session.startedAt
// accidentalPress 체크 (700ms 미만)
if (duration < TIMING.MIN_AUDIO_DURATION) {
session.accidentalPress = true
logger.info(`Accidental press detected (${duration}ms < ${TIMING.MIN_AUDIO_DURATION}ms)`)
this._cancelSession('too-short')
return
}
// 오디오 캡처 중지
await this._stopAudio()
// 버퍼가 있으면 STT에 전달
if (this._audioBuffer.length > 0 && this._sttReady) {
await this._transcribe()
} else if (this._audioBuffer.length > 0 && !this._sttReady) {
// STT 아직 준비 안 됨 → tryFlushAll이 처리
logger.info('Waiting for STT to be ready before transcribing')
// 타임아웃 설정
setTimeout(() => {
if (this._session?.id === session.id && !this._isInTerminalState()) {
logger.warn('STT readiness timeout, cancelling session')
this._cancelSession('timeout')
}
}, TIMING.POST_RECORDING_WAIT_BUFFERED)
} else {
// 오디오 없음
logger.warn('No audio buffer, cancelling session')
this._cancelSession('too-short')
}
}
cancelSession(): void {
this._cancelSession('user')
}
// ── 상태 머신 ──────────────────────────────────────────
private _isInTerminalState(): boolean {
return TERMINAL_STATES.has(this._recognitionState)
}
private _setRecognitionState(state: RecognitionState): void {
if (this._recognitionState === state) return
if (this._isInTerminalState() && state !== RecognitionState.IDLE) return
const previous = this._recognitionState
this._recognitionState = state
if (this._session) {
this._session.recognitionState = state
}
this.emit('recognition-state-changed', { previous, current: state })
logger.debug(`RecognitionState: ${previous}${state}`)
}
private _setAudioState(state: AudioState): void {
if (this._audioState === state) return
const previous = this._audioState
this._audioState = state
if (this._session) {
this._session.audioState = state
}
this.emit('audio-state-changed', { previous, current: state })
logger.debug(`AudioState: ${previous}${state}`)
}
// ── STT 초기화 ─────────────────────────────────────────
private async _initSTT(): Promise<void> {
try {
this._setRecognitionState(RecognitionState.CONNECTING)
const stt = getLocalSTTService()
const modelId = configGet('sttModelId')
await stt.initialize(modelId)
if (this._isInTerminalState()) return
this._sttReady = true
this._setRecognitionState(RecognitionState.READY)
logger.info('STT ready')
this._tryFlushAll()
} catch (error) {
if (this._isInTerminalState()) return
this._handleError(
new D3ROError(
ErrorCode.STTModelLoadFailed,
`STT initialization failed: ${error instanceof Error ? error.message : String(error)}`
)
)
}
}
// ── 오디오 캡처 ────────────────────────────────────────
private async _startAudio(): Promise<void> {
try {
this._setAudioState(AudioState.INITIALIZING)
const audio = getAudioCaptureService()
// 오디오 데이터 수신
this._audioDataHandler = (payload) => {
if (this._isInTerminalState()) return
this._audioBuffer.push(payload.buffer)
this._audioBufferBytes += payload.buffer.length
// 버퍼 duration 업데이트 (16kHz, 16bit, mono)
const durationMs = (this._audioBufferBytes / 2 / 16000) * 1000
if (this._session) {
this._session.audioBufferDurationMs = durationMs
}
this._tryFlushAll()
}
this._audioLevelHandler = (payload) => {
this.emit('audio-level', { level: payload.level })
}
audio.on('audio-data', this._audioDataHandler)
audio.on('audio-level', this._audioLevelHandler)
await audio.start()
if (this._isInTerminalState()) return
this._audioStarted = true
this._setAudioState(AudioState.STREAMING)
logger.info('Audio capture started')
this._tryFlushAll()
} catch (error) {
if (this._isInTerminalState()) return
this._setAudioState(AudioState.STOPPED)
this._handleError(
new D3ROError(
ErrorCode.AudioCaptureStartFailed,
`Audio capture failed: ${error instanceof Error ? error.message : String(error)}`
)
)
}
}
private async _stopAudio(): Promise<void> {
this._setAudioState(AudioState.STOPPED)
const audio = getAudioCaptureService()
if (this._audioDataHandler) {
audio.off('audio-data', this._audioDataHandler)
this._audioDataHandler = null
}
if (this._audioLevelHandler) {
audio.off('audio-level', this._audioLevelHandler)
this._audioLevelHandler = null
}
try {
await audio.stop()
} catch (error) {
logger.warn(`Audio stop error: ${error instanceof Error ? error.message : String(error)}`)
}
}
// ── 이중 조건 플러시 ───────────────────────────────────
private _tryFlushAll(): void {
if (!this._sttReady || !this._audioStarted) return
if (this._audioBuffer.length === 0) return
if (this._isInTerminalState()) return
// 아직 녹음 중이면 flush 하지 않음 (stopSession에서 처리)
if (this._audioState === AudioState.STREAMING) return
this._transcribe()
}
// ── 전사 ───────────────────────────────────────────────
private async _transcribe(): Promise<void> {
if (this._audioBuffer.length === 0) return
if (this._isInTerminalState()) return
this._setRecognitionState(RecognitionState.RECOGNIZING)
const merged = Buffer.concat(this._audioBuffer)
this._audioBuffer = []
this._audioBufferBytes = 0
try {
const stt = getLocalSTTService()
const language = configGet('sttLanguage')
const result: TranscriptionResult = await stt.transcribe(merged, {
language: language === 'auto' ? undefined : language
})
if (this._isInTerminalState()) return
if (this._session) {
this._session.transcription = result.text
}
this.emit('transcription-update', { text: result.text, isFinal: true })
// Phase 2: LLM 후처리 없이 바로 완료
this._completeSession(result.text)
} catch (error) {
if (this._isInTerminalState()) return
this._handleError(
new D3ROError(
ErrorCode.STTTranscriptionFailed,
`Transcription failed: ${error instanceof Error ? error.message : String(error)}`
)
)
}
}
// ── 세션 완료/취소 ─────────────────────────────────────
private _completeSession(finalText: string): void {
if (!this._session) return
this._setRecognitionState(RecognitionState.COMPLETED)
this._setAudioState(AudioState.STOPPED)
const session = { ...this._session }
logger.info(`Session completed: "${finalText.substring(0, 50)}${finalText.length > 50 ? '...' : ''}"`)
this.emit('session-completed', { session, finalText })
// IDLE로 복귀
this._resetToIdle()
}
private _cancelSession(reason: 'user' | 'timeout' | 'too-short'): void {
if (!this._session) return
this._setRecognitionState(RecognitionState.CANCELLED)
this._setAudioState(AudioState.STOPPED)
const session = { ...this._session }
logger.info(`Session cancelled: ${reason}`)
// 오디오 정리
this._stopAudio()
this.emit('session-cancelled', { session, reason })
this._resetToIdle()
}
private _resetToIdle(): void {
this._session = null
this._audioBuffer = []
this._audioBufferBytes = 0
this._sttReady = false
this._audioStarted = false
this._errorEmitted = false
// 약간의 딜레이 후 IDLE로 전이 (UI 애니메이션용)
setTimeout(() => {
if (!this._session) {
this._setRecognitionState(RecognitionState.IDLE)
this._setAudioState(AudioState.IDLE)
}
}, 200)
}
// ── 에러 처리 ──────────────────────────────────────────
private _handleError(error: D3ROError): void {
if (this._errorEmitted) return
this._errorEmitted = true
logger.error(`VoiceMode error [${error.code}]: ${error.message}`)
this._setRecognitionState(RecognitionState.ERROR)
this._stopAudio()
this.emit('error', { error, session: this._session ? { ...this._session } : null })
this._resetToIdle()
}
// ── Action Queue (이벤트 직렬화) ───────────────────────
private _enqueueAction(action: VoiceAction): void {
this._actionQueue.push(action)
this._processQueue()
}
private async _processQueue(): Promise<void> {
if (this._isProcessingQueue) return
this._isProcessingQueue = true
try {
while (this._actionQueue.length > 0) {
const action = this._actionQueue.shift()!
await this._processAction(action)
}
} finally {
this._isProcessingQueue = false
}
}
private async _processAction(action: VoiceAction): Promise<void> {
try {
switch (action.type) {
case 'press':
await this._handlePress(action)
break
case 'release':
await this._handleRelease(action)
break
case 'escape':
this.cancelSession()
break
}
} catch (error) {
logger.error(`Action processing error: ${error instanceof Error ? error.message : String(error)}`)
}
}
private async _handlePress(action: VoiceAction): Promise<void> {
if (action.mode === 'dictation') {
// Dictation: hold-to-talk — press로 시작
if (!this.isActive) {
await this.startSession('dictation')
}
} else if (action.mode === 'hands-free') {
// HandsFree: toggle
if (this.isActive) {
await this.stopSession()
} else {
await this.startSession('hands-free')
}
}
}
private async _handleRelease(action: VoiceAction): Promise<void> {
if (action.mode === 'dictation' && this.isActive) {
// Dictation: hold-to-talk — release로 종료 (200ms 딜레이)
await new Promise<void>((resolve) => setTimeout(resolve, 200))
await this.stopSession()
}
// HandsFree: release 무시
}
// ── 유틸리티 ───────────────────────────────────────────
private _resolveMode(config: HotkeyConfig): VoiceMode {
if (config.id === 'voice-handsfree' || config.doublePressEnabled) {
return 'hands-free'
}
return 'dictation'
}
// ── 종료 ───────────────────────────────────────────────
dispose(): void {
this._disposed = true
this._actionQueue = []
// 진행 중 세션 취소
if (this._session && !this._isInTerminalState()) {
this._cancelSession('user')
}
// 핫키 리스너 해제
const hotkey = getHotkeyService()
if (this._hotkeyPressHandler) {
hotkey.off('hotkey-pressed', this._hotkeyPressHandler)
}
if (this._hotkeyReleaseHandler) {
hotkey.off('hotkey-released', this._hotkeyReleaseHandler)
}
if (this._doublePressHandler) {
hotkey.off('double-press', this._doublePressHandler)
}
// 오디오 리스너 해제
this._stopAudio()
this._setRecognitionState(RecognitionState.DESTROYED)
this.removeAllListeners()
logger.info('VoiceModeService disposed')
}
// ── EventEmitter 타입 오버라이드 ───────────────────────
override on<K extends keyof VoiceModeEvents>(
event: K,
listener: VoiceModeEvents[K]
): this {
return super.on(event, listener)
}
override off<K extends keyof VoiceModeEvents>(
event: K,
listener: VoiceModeEvents[K]
): this {
return super.off(event, listener)
}
override emit<K extends keyof VoiceModeEvents>(
event: K,
...args: Parameters<VoiceModeEvents[K]>
): boolean {
return super.emit(event, ...args)
}
}
// ── 싱글톤 ─────────────────────────────────────────────
let instance: VoiceModeService | null = null
export function getVoiceModeService(): VoiceModeService {
if (!instance) {
instance = new VoiceModeService()
}
return instance
}