737 lines
29 KiB
Python
737 lines
29 KiB
Python
"""음성 캐스케이드 — OpenAI STT + OpenAI/Higgs TTS 어댑터.
|
||
|
||
MASTERPLAN '음성 필수'(한신대 요구) / DESIGN_CONCEPT §5.2(음성 오브 4상태) / §4.3(립싱크 RMS):
|
||
STT : OpenAI /v1/audio/transcriptions (gpt-4o-transcribe | whisper-1). 학습자 음성 → 텍스트.
|
||
TTS : OpenAI /v1/audio/speech 또는 로컬 Higgs v3. 내담자 텍스트 → 음성.
|
||
|
||
설계 원칙(이 모듈의 경계):
|
||
- 순수 어댑터: httpx 로 OpenAI 음성 엔드포인트만 호출한다. 상담 로직(orchestrator)·상태머신은
|
||
호출부(routes/voice.py)가 조립한다. 여기는 "오디오↔텍스트" 변환 + voice preset 매핑만.
|
||
- API 키 없으면 명확히 degraded: is_available()=False, 호출 시 VoiceUnavailable.
|
||
절대 크래시·무한대기 금지(라우트가 503/close 로 변환).
|
||
- 립싱크 힌트: TTS 오디오 청크를 흘리며 RMS(진폭) 힌트를 같이 산출(설계 §4.3 — viseme 정밀
|
||
매칭 안 함, RMS 1채널). PCM 디코딩 의존성 없이 바이트 에너지 근사로 임시 RMS 추정.
|
||
|
||
페르소나 voice preset(persona/*.json voice.preset, 설계 §4.6) → OpenAI voice 매핑은
|
||
PRESET_TO_OPENAI_VOICE 테이블이 흡수. 새 preset 추가는 이 테이블만 손대면 된다.
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import re
|
||
from dataclasses import dataclass, field
|
||
from pathlib import Path
|
||
from typing import Any, AsyncIterator, Mapping, Optional
|
||
|
||
import httpx
|
||
|
||
from ..config import settings
|
||
from ..paths import repo_root, repo_path
|
||
|
||
# ════════════════════════════════════════════════════════════════════════════
|
||
# OpenAI 음성 엔드포인트/모델 상수
|
||
# ════════════════════════════════════════════════════════════════════════════
|
||
OPENAI_BASE_URL = "https://api.openai.com/v1"
|
||
STT_ENDPOINT = "/audio/transcriptions"
|
||
TTS_ENDPOINT = "/audio/speech"
|
||
HIGGS_TTS_ENDPOINT = "/tts"
|
||
|
||
# STT 모델: gpt-4o-transcribe(고품질) — 미가용 폴백은 whisper-1.
|
||
STT_MODEL = "gpt-4o-transcribe"
|
||
STT_MODEL_FALLBACK = "whisper-1"
|
||
# TTS 모델: gpt-4o-mini-tts(저지연·표현력) — 폴백 tts-1.
|
||
TTS_MODEL = "gpt-4o-mini-tts"
|
||
TTS_MODEL_FALLBACK = "tts-1"
|
||
HIGGS_TTS_MODEL = "higgs-audio-v3-tts-4b"
|
||
|
||
# 전사 언어 힌트(상담은 한국어). OpenAI 는 ISO-639-1.
|
||
STT_LANGUAGE = "ko"
|
||
|
||
# TTS 출력 포맷: 브라우저 MediaSource/<audio> 친화. 스트리밍은 mp3/opus 청크.
|
||
TTS_RESPONSE_FORMAT = "mp3"
|
||
|
||
# End-of-turn readiness default for cascaded STT providers.
|
||
EOT_SILENCE_THRESHOLD_MS = 1200
|
||
|
||
POC_SAMPLE_TTS_PRESET = "soft-young-fem"
|
||
POC_SAMPLE_TTS_DEFAULT_DIR = (
|
||
repo_path("docs", "voice-art", "p1-seoyeon-higgs-v3-20260627")
|
||
)
|
||
POC_SAMPLE_TTS_CHUNK_SIZE = 4096
|
||
_POC_SAMPLE_TTS_DEFAULT_SAMPLE = "p1_seoyeon_01_depressed_slow"
|
||
_POC_SAMPLE_TTS_KEYWORDS: tuple[tuple[str, tuple[str, ...]], ...] = (
|
||
(
|
||
"p1_seoyeon_03_anxious_guarded",
|
||
("엄마", "비밀", "말하지", "불안", "무서", "걱정", "들키", "싫", "갈래"),
|
||
),
|
||
(
|
||
"p1_seoyeon_02_tired_flat",
|
||
("잠", "피곤", "무거", "아무것도", "지쳐", "힘들", "에너지"),
|
||
),
|
||
(
|
||
"p1_seoyeon_05_recovered_lively",
|
||
("오늘은", "친구", "웃", "괜찮았", "좋았", "해냈"),
|
||
),
|
||
(
|
||
"p1_seoyeon_04_rapport_relief",
|
||
("괜찮", "들어", "고마", "선생님", "편해", "조금", "말해"),
|
||
),
|
||
)
|
||
|
||
_HIGGS_DELIVERY_TAGS: tuple[tuple[tuple[str, ...], str], ...] = (
|
||
(
|
||
("엄마", "비밀", "말하지", "불안", "무서", "걱정", "들키", "갈래"),
|
||
"<|emotion:fear|><|prosody:speed_fast|><|prosody:pitch_high|>",
|
||
),
|
||
(
|
||
("잠", "피곤", "무거", "아무것도", "지쳐", "힘들", "에너지"),
|
||
"<|emotion:sadness|><|prosody:speed_slow|><|prosody:expressive_low|>",
|
||
),
|
||
(
|
||
("오늘은", "친구", "웃", "괜찮았", "좋았", "해냈"),
|
||
"<|emotion:contentment|><|prosody:speed_fast|>",
|
||
),
|
||
(
|
||
("괜찮", "들어", "고마", "선생님", "편해", "조금", "말해"),
|
||
"<|emotion:relief|><|prosody:speed_slow|>",
|
||
),
|
||
)
|
||
|
||
# OpenAI 공식 voice 풀(2026 기준): alloy, ash, ballad, coral, echo, fable,
|
||
# nova, onyx, sage, shimmer, verse. 페르소나 톤별로 골라 매핑한다.
|
||
_OPENAI_VOICES = {
|
||
"alloy", "ash", "ballad", "coral", "echo", "fable",
|
||
"nova", "onyx", "sage", "shimmer", "verse",
|
||
}
|
||
DEFAULT_OPENAI_VOICE = "sage"
|
||
|
||
# ── 페르소나 voice preset(설계 §4.6) → OpenAI voice ──────────────────────────
|
||
# preset 명명: <톤><연령><성별> 조합(soft-young-fem 등). 새 페르소나는 여기에만 추가.
|
||
PRESET_TO_OPENAI_VOICE: dict[str, str] = {
|
||
# 청소년 여성(P1 서연) — 부드럽고 톤 높은
|
||
"soft-young-fem": "coral",
|
||
# 성인 남성(P2 민재) — 차분·안정·약간 긴장
|
||
"calm-adult-male": "ash",
|
||
# 성인 여성(P3 지우) — 따뜻하지만 지친
|
||
"warm-adult-fem": "shimmer",
|
||
# 범용 폴백 프리셋
|
||
"neutral": "sage",
|
||
}
|
||
|
||
# ── 페르소나 code(P1/P2/P3) → 기본 preset (persona 카드에 voice 필드 없을 때) ──
|
||
# persona.py 시드는 voice 필드를 갖지 않으므로 code 로 기본 preset 을 정한다.
|
||
# DB/JSON 페르소나가 voice.preset 을 직접 주면 그걸 우선한다(resolve_voice 참조).
|
||
PERSONA_CODE_TO_PRESET: dict[str, str] = {
|
||
"P1": "soft-young-fem",
|
||
"P2": "calm-adult-male",
|
||
"P3": "warm-adult-fem",
|
||
}
|
||
|
||
# TTS rate(말 속도) 페르소나 기본값(설계 §4.6 voice.rate). 1.0=표준.
|
||
PRESET_RATE: dict[str, float] = {
|
||
"soft-young-fem": 0.96,
|
||
"calm-adult-male": 1.0,
|
||
"warm-adult-fem": 0.98,
|
||
"neutral": 1.0,
|
||
}
|
||
|
||
|
||
class VoiceUnavailable(RuntimeError):
|
||
"""음성 미설정/장애. 라우트가 503/WS close(degraded) 로 변환."""
|
||
|
||
|
||
@dataclass(slots=True)
|
||
class VoicePreset:
|
||
"""해석된 음성 프리셋(페르소나 → OpenAI 파라미터)."""
|
||
|
||
preset: str # 논리 preset 명(soft-young-fem 등)
|
||
openai_voice: str # OpenAI voice 파라미터
|
||
rate: float = 1.0 # 말 속도(speed)
|
||
instructions: Optional[str] = None # gpt-4o-mini-tts 표현 지시(선택)
|
||
|
||
|
||
@dataclass(slots=True)
|
||
class TranscriptResult:
|
||
"""STT 결과."""
|
||
|
||
text: str
|
||
language: Optional[str] = None
|
||
model: str = STT_MODEL
|
||
duration: Optional[float] = None
|
||
provider_events: list[dict[str, object]] = field(default_factory=list)
|
||
|
||
|
||
@dataclass(frozen=True, slots=True)
|
||
class EndOfTurnDecision:
|
||
"""Provider-neutral readiness signal for a completed learner utterance."""
|
||
|
||
ready: bool
|
||
transcript_ready: bool
|
||
silence_ready: bool
|
||
silence_ms: int
|
||
threshold_ms: int
|
||
reason: str
|
||
|
||
|
||
@dataclass(slots=True)
|
||
class TTSChunk:
|
||
"""TTS 스트림 1청크(오디오 바이트). 립싱크는 프론트 Web Audio AnalyserNode가 자체 산출."""
|
||
|
||
audio: bytes
|
||
|
||
|
||
# ════════════════════════════════════════════════════════════════════════════
|
||
# voice preset 해석 (페르소나 → OpenAI 파라미터)
|
||
# ════════════════════════════════════════════════════════════════════════════
|
||
def resolve_voice(
|
||
*,
|
||
persona_code: Optional[str] = None,
|
||
preset: Optional[str] = None,
|
||
instructions: Optional[str] = None,
|
||
) -> VoicePreset:
|
||
"""페르소나 code 또는 명시 preset → OpenAI voice 파라미터로 해석.
|
||
|
||
우선순위: 명시 preset > persona_code 기본 preset > 'neutral'.
|
||
알 수 없는 preset 은 DEFAULT_OPENAI_VOICE 로 안전 폴백(크래시 없음).
|
||
"""
|
||
chosen = preset
|
||
if not chosen and persona_code:
|
||
chosen = PERSONA_CODE_TO_PRESET.get(persona_code.upper())
|
||
if not chosen:
|
||
chosen = "neutral"
|
||
|
||
openai_voice = PRESET_TO_OPENAI_VOICE.get(chosen, DEFAULT_OPENAI_VOICE)
|
||
if openai_voice not in _OPENAI_VOICES:
|
||
openai_voice = DEFAULT_OPENAI_VOICE
|
||
rate = PRESET_RATE.get(chosen, 1.0)
|
||
return VoicePreset(
|
||
preset=chosen,
|
||
openai_voice=openai_voice,
|
||
rate=rate,
|
||
instructions=instructions,
|
||
)
|
||
|
||
|
||
def resolve_voice_from_map(
|
||
*,
|
||
provider: str,
|
||
voice_id: str,
|
||
base_params: Mapping[str, Any] | None,
|
||
persona_code: Optional[str] = None,
|
||
) -> VoicePreset | None:
|
||
"""DB persona_voice_map row -> live OpenAI VoicePreset.
|
||
|
||
provider-agnostic rows are allowed in the catalog, but this service only
|
||
knows how to send OpenAI TTS. Unsupported providers return None so callers
|
||
can fall back to the existing preset resolver.
|
||
"""
|
||
if provider.strip().lower() != "openai":
|
||
return None
|
||
|
||
fallback = resolve_voice(persona_code=persona_code)
|
||
params = dict(base_params or {})
|
||
preset = _clean_optional_text(params.get("preset")) or fallback.preset
|
||
mapped_voice = _clean_optional_text(params.get("openai_voice"))
|
||
voice_id_value = _clean_optional_text(voice_id)
|
||
if not mapped_voice and voice_id_value in _OPENAI_VOICES:
|
||
mapped_voice = voice_id_value
|
||
if not mapped_voice:
|
||
mapped_voice = PRESET_TO_OPENAI_VOICE.get(preset, fallback.openai_voice)
|
||
if mapped_voice not in _OPENAI_VOICES:
|
||
mapped_voice = fallback.openai_voice
|
||
if mapped_voice not in _OPENAI_VOICES:
|
||
mapped_voice = DEFAULT_OPENAI_VOICE
|
||
|
||
rate = PRESET_RATE.get(preset, fallback.rate)
|
||
if "rate" in params:
|
||
try:
|
||
rate = float(params["rate"])
|
||
except (TypeError, ValueError):
|
||
rate = fallback.rate
|
||
|
||
return VoicePreset(
|
||
preset=preset,
|
||
openai_voice=mapped_voice,
|
||
rate=rate,
|
||
instructions=_clean_optional_text(params.get("instructions")),
|
||
)
|
||
|
||
|
||
def build_higgs_prompt(text: str, voice: VoicePreset) -> str:
|
||
"""합성 seed의 화자 정체성을 지키면서 감정·속도 태그를 첫 단어 뒤에 넣는다."""
|
||
normalized = text.casefold()
|
||
tags = ""
|
||
if voice.preset == POC_SAMPLE_TTS_PRESET:
|
||
for keywords, candidate in _HIGGS_DELIVERY_TAGS:
|
||
if any(keyword.casefold() in normalized for keyword in keywords):
|
||
tags = candidate
|
||
break
|
||
if not tags:
|
||
tags = (
|
||
"<|emotion:helplessness|><|prosody:speed_slow|>"
|
||
"<|prosody:expressive_low|>"
|
||
)
|
||
elif voice.rate <= 0.85:
|
||
tags = "<|prosody:speed_slow|>"
|
||
elif voice.rate >= 1.15:
|
||
tags = "<|prosody:speed_fast|>"
|
||
if not tags:
|
||
return text
|
||
|
||
# Higgs 강한 감정 태그를 맨 앞에 두면 reference 화자가 흔들릴 수 있다. 첫 단어로
|
||
# 화자를 먼저 고정한 뒤 태그 다음 단어를 공백 없이 이어 붙인다.
|
||
match = re.match(r"^(\S+\s+)(.+)$", text, flags=re.DOTALL)
|
||
if match:
|
||
return f"{match.group(1)}{tags}{match.group(2).lstrip()}"
|
||
return tags + text
|
||
|
||
|
||
# 비언어 지문 패턴: (…)·（…）·[…]·【…】. 내담자 발화의 무대지시(고개 끄덕/한숨/침묵 등).
|
||
_STAGE_DIRECTION_RE = re.compile(r"[\(（\[【][^\)）\]】]*[\)）\]】]")
|
||
|
||
|
||
def speakable_text(text: str) -> str:
|
||
"""TTS로 읽을 텍스트만 남긴다 — 비언어 지문((고개 살짝 끄덕)·（한숨）·[침묵])을 제거.
|
||
|
||
지문은 자막/회기리뷰에 남고 아바타 애니메이션이 표현하며, 음성으로는 읽지 않는다.
|
||
지문만으로 이뤄진 발화(예: "(침묵)")는 빈 문자열을 반환 → 합성 생략.
|
||
"""
|
||
if not text:
|
||
return ""
|
||
stripped = _STAGE_DIRECTION_RE.sub(" ", text)
|
||
# 말줄임표/중복 공백 정리 + 고아 구두점 앞 공백 제거
|
||
stripped = re.sub(r"\s+", " ", stripped)
|
||
stripped = re.sub(r"\s+([,.!?…」』】)])", r"\1", stripped)
|
||
return stripped.strip()
|
||
|
||
|
||
def build_tts_payload(
|
||
text: str,
|
||
voice: VoicePreset,
|
||
*,
|
||
model: str = TTS_MODEL,
|
||
response_format: str = TTS_RESPONSE_FORMAT,
|
||
) -> dict[str, object]:
|
||
"""Build the deterministic OpenAI TTS payload for a resolved voice preset."""
|
||
payload: dict[str, object] = {
|
||
"model": model,
|
||
"voice": voice.openai_voice,
|
||
"input": text,
|
||
"response_format": response_format,
|
||
"speed": _clamp_speed(voice.rate),
|
||
}
|
||
if voice.instructions and model.startswith("gpt-4o"):
|
||
payload["instructions"] = voice.instructions
|
||
return payload
|
||
|
||
|
||
def assess_end_of_turn(
|
||
*,
|
||
transcript_text: Optional[str],
|
||
transcript_final: bool,
|
||
silence_ms: Optional[int],
|
||
silence_threshold_ms: int = EOT_SILENCE_THRESHOLD_MS,
|
||
) -> EndOfTurnDecision:
|
||
"""Return whether final STT text plus observed silence is enough to run a turn."""
|
||
observed_silence = _nonnegative_int(silence_ms)
|
||
threshold = max(0, _nonnegative_int(silence_threshold_ms))
|
||
has_text = bool((transcript_text or "").strip())
|
||
transcript_ready = bool(transcript_final and has_text)
|
||
silence_ready = observed_silence >= threshold
|
||
ready = transcript_ready and silence_ready
|
||
if ready:
|
||
reason = "ready"
|
||
elif not has_text:
|
||
reason = "empty_transcript"
|
||
elif not transcript_final:
|
||
reason = "final_transcript_pending"
|
||
else:
|
||
reason = "silence_threshold_pending"
|
||
return EndOfTurnDecision(
|
||
ready=ready,
|
||
transcript_ready=transcript_ready,
|
||
silence_ready=silence_ready,
|
||
silence_ms=observed_silence,
|
||
threshold_ms=threshold,
|
||
reason=reason,
|
||
)
|
||
|
||
|
||
# ════════════════════════════════════════════════════════════════════════════
|
||
# OpenAI 음성 서비스
|
||
# ════════════════════════════════════════════════════════════════════════════
|
||
class VoiceService:
|
||
"""OpenAI STT와 선택형 OpenAI/Higgs TTS 어댑터(httpx 풀 공유)."""
|
||
|
||
def __init__(
|
||
self,
|
||
api_key: Optional[str] = None,
|
||
base_url: Optional[str] = None,
|
||
*,
|
||
poc_sample_tts_enabled: Optional[bool] = None,
|
||
environment: Optional[str] = None,
|
||
poc_sample_tts_dir: Optional[str | Path] = None,
|
||
tts_provider: Optional[str] = None,
|
||
higgs_base_url: Optional[str] = None,
|
||
higgs_timeout_seconds: Optional[float] = None,
|
||
) -> None:
|
||
self._api_key = (api_key if api_key is not None else settings.openai_api_key) or ""
|
||
self._base_url = (base_url or settings.openai_base_url or OPENAI_BASE_URL).rstrip("/")
|
||
self._environment = environment if environment is not None else settings.environment
|
||
self._tts_provider = (
|
||
tts_provider if tts_provider is not None else settings.voice_tts_provider
|
||
).strip().lower()
|
||
self._higgs_base_url = (
|
||
higgs_base_url if higgs_base_url is not None else settings.higgs_tts_url
|
||
).rstrip("/")
|
||
self._higgs_timeout_seconds = max(
|
||
1.0,
|
||
float(
|
||
higgs_timeout_seconds
|
||
if higgs_timeout_seconds is not None
|
||
else settings.higgs_tts_timeout_seconds
|
||
),
|
||
)
|
||
self._poc_sample_tts_enabled = (
|
||
bool(settings.voice_poc_sample_tts_enabled)
|
||
if poc_sample_tts_enabled is None
|
||
else bool(poc_sample_tts_enabled)
|
||
)
|
||
sample_dir_value: str | Path = (
|
||
poc_sample_tts_dir
|
||
if poc_sample_tts_dir is not None
|
||
else (settings.voice_poc_sample_tts_dir or POC_SAMPLE_TTS_DEFAULT_DIR)
|
||
)
|
||
sample_dir = Path(sample_dir_value)
|
||
if not sample_dir.is_absolute():
|
||
sample_dir = repo_root() / sample_dir
|
||
self._poc_sample_tts_dir = sample_dir
|
||
self._client: Optional[httpx.AsyncClient] = None
|
||
self._higgs_client: Optional[httpx.AsyncClient] = None
|
||
|
||
# ── 수명주기 ──────────────────────────────────────────
|
||
async def startup(self) -> None:
|
||
if self._api_key:
|
||
self._client = httpx.AsyncClient(
|
||
base_url=self._base_url,
|
||
headers={"Authorization": f"Bearer {self._api_key}"},
|
||
timeout=httpx.Timeout(60.0, connect=10.0),
|
||
)
|
||
if self._higgs_enabled():
|
||
self._higgs_client = httpx.AsyncClient(
|
||
base_url=self._higgs_base_url,
|
||
timeout=httpx.Timeout(self._higgs_timeout_seconds, connect=3.0),
|
||
)
|
||
|
||
async def shutdown(self) -> None:
|
||
if self._client is not None:
|
||
await self._client.aclose()
|
||
self._client = None
|
||
if self._higgs_client is not None:
|
||
await self._higgs_client.aclose()
|
||
self._higgs_client = None
|
||
|
||
def is_available(self) -> bool:
|
||
"""마이크 캐스케이드(STT+TTS) 전체 가용 여부."""
|
||
return self.stt_available() and self.tts_available()
|
||
|
||
def stt_available(self) -> bool:
|
||
return bool(self._api_key)
|
||
|
||
def tts_available(self, voice: VoicePreset | None = None) -> bool:
|
||
if self._higgs_enabled() and (voice is None or self._should_use_higgs_tts(voice)):
|
||
return True
|
||
if self._poc_sample_tts_available():
|
||
return True
|
||
return bool(self._api_key)
|
||
|
||
def tts_provider(self) -> str:
|
||
if self._higgs_enabled():
|
||
return "higgs"
|
||
if self._poc_sample_tts_available():
|
||
return "p1-sample-poc"
|
||
if self._tts_provider == "higgs" and self._environment != "dev":
|
||
return "disabled-non-dev"
|
||
if self._api_key:
|
||
return "openai"
|
||
if self._poc_sample_tts_enabled and self._environment != "dev":
|
||
return "disabled-non-dev"
|
||
return "unavailable"
|
||
|
||
def tts_provider_for_voice(self, voice: VoicePreset) -> str:
|
||
if self._should_use_higgs_tts(voice):
|
||
return "higgs"
|
||
if self._should_use_poc_sample_tts(voice):
|
||
return "p1-sample-poc"
|
||
return "openai" if self._api_key else "unavailable"
|
||
|
||
def tts_model_for_voice(self, voice: VoicePreset) -> str:
|
||
return HIGGS_TTS_MODEL if self._should_use_higgs_tts(voice) else TTS_MODEL
|
||
|
||
def tts_media_type_for_voice(self, voice: VoicePreset) -> str:
|
||
return "audio/wav" if self._should_use_higgs_tts(voice) else "audio/mpeg"
|
||
|
||
def _higgs_enabled(self) -> bool:
|
||
return self._tts_provider == "higgs" and self._environment == "dev"
|
||
|
||
def _should_use_higgs_tts(self, voice: VoicePreset) -> bool:
|
||
# 현재 권리 안전한 synthetic reference는 P1 서연 프리셋만 보유한다.
|
||
return self._higgs_enabled() and voice.preset == POC_SAMPLE_TTS_PRESET
|
||
|
||
def poc_sample_tts_available(self) -> bool:
|
||
return self._poc_sample_tts_available()
|
||
|
||
def _poc_sample_tts_available(self) -> bool:
|
||
return (
|
||
self._poc_sample_tts_enabled
|
||
and self._environment == "dev"
|
||
and self._poc_sample_path(_POC_SAMPLE_TTS_DEFAULT_SAMPLE).is_file()
|
||
)
|
||
|
||
def _should_use_poc_sample_tts(self, voice: VoicePreset) -> bool:
|
||
return (
|
||
self._poc_sample_tts_enabled
|
||
and self._environment == "dev"
|
||
and voice.preset == POC_SAMPLE_TTS_PRESET
|
||
)
|
||
|
||
def _poc_sample_path(self, sample_id: str) -> Path:
|
||
return self._poc_sample_tts_dir / f"{sample_id}.mp3"
|
||
|
||
@property
|
||
def _http(self) -> httpx.AsyncClient:
|
||
if not self._api_key:
|
||
raise VoiceUnavailable("OPENAI_API_KEY 미설정 — 음성 기능 degraded")
|
||
if self._client is None:
|
||
# lazy 보강(테스트/지연 startup 대비)
|
||
self._client = httpx.AsyncClient(
|
||
base_url=self._base_url,
|
||
headers={"Authorization": f"Bearer {self._api_key}"},
|
||
timeout=httpx.Timeout(60.0, connect=10.0),
|
||
)
|
||
return self._client
|
||
|
||
@property
|
||
def _higgs_http(self) -> httpx.AsyncClient:
|
||
if not self._higgs_enabled():
|
||
raise VoiceUnavailable("Higgs TTS는 로컬 dev 환경에서만 사용할 수 있습니다.")
|
||
if self._higgs_client is None:
|
||
self._higgs_client = httpx.AsyncClient(
|
||
base_url=self._higgs_base_url,
|
||
timeout=httpx.Timeout(self._higgs_timeout_seconds, connect=3.0),
|
||
)
|
||
return self._higgs_client
|
||
|
||
# ── STT (transcriptions) ─────────────────────────────
|
||
async def transcribe(
|
||
self,
|
||
audio: bytes,
|
||
*,
|
||
filename: str = "audio.webm",
|
||
content_type: str = "audio/webm",
|
||
language: str = STT_LANGUAGE,
|
||
model: str = STT_MODEL,
|
||
) -> TranscriptResult:
|
||
"""오디오 바이트 → 텍스트 전사(OpenAI /audio/transcriptions).
|
||
|
||
클라가 보낸 webm/opus(또는 wav/mp3) 청크를 multipart 로 OpenAI 에 올린다.
|
||
키 없으면 VoiceUnavailable, OpenAI 오류는 그대로 RuntimeError 로 전파(라우트가 처리).
|
||
"""
|
||
if not audio:
|
||
return TranscriptResult(text="", model=model)
|
||
files = {"file": (filename, audio, content_type)}
|
||
data = {
|
||
"model": model,
|
||
"language": language,
|
||
"response_format": "json",
|
||
}
|
||
try:
|
||
r = await self._http.post(STT_ENDPOINT, files=files, data=data)
|
||
if r.status_code == 404 and model != STT_MODEL_FALLBACK:
|
||
# 모델 미가용(계정 권한) → whisper-1 폴백 1회
|
||
data["model"] = STT_MODEL_FALLBACK
|
||
r = await self._http.post(STT_ENDPOINT, files=files, data=data)
|
||
r.raise_for_status()
|
||
except VoiceUnavailable:
|
||
raise
|
||
except httpx.HTTPStatusError as e:
|
||
raise RuntimeError(f"STT {e.response.status_code}: {e.response.text[:200]}") from e
|
||
except httpx.HTTPError as e:
|
||
raise RuntimeError(f"STT transport error: {e}") from e
|
||
|
||
body = r.json()
|
||
return TranscriptResult(
|
||
text=(body.get("text") or "").strip(),
|
||
language=body.get("language"),
|
||
model=str(data["model"]),
|
||
duration=body.get("duration"),
|
||
)
|
||
|
||
# ── TTS (speech) — 스트리밍 ──────────────────────────
|
||
async def synthesize_stream(
|
||
self,
|
||
text: str,
|
||
voice: VoicePreset,
|
||
*,
|
||
model: str = TTS_MODEL,
|
||
response_format: str = TTS_RESPONSE_FORMAT,
|
||
) -> AsyncIterator[TTSChunk]:
|
||
"""텍스트 → 음성 스트리밍(OpenAI 또는 로컬 Higgs). 오디오 청크를 yield한다.
|
||
|
||
설계 §5.2 'speaking' 상태: 오디오 청크를 흘리며 진폭 힌트(립싱크)를 같이 보낸다.
|
||
선택 provider가 준비되지 않으면 VoiceUnavailable, 전송 오류는 RuntimeError로 전파한다.
|
||
"""
|
||
# 비언어 지문((고개 끄덕)·（한숨）·[침묵])은 음성으로 읽지 않는다. 자막엔 남고
|
||
# 아바타 애니메이션이 표현한다. 지문만 있는 발화는 합성 생략(빈 오디오).
|
||
text = speakable_text(text)
|
||
if not text:
|
||
return
|
||
if self._should_use_higgs_tts(voice):
|
||
async for chunk in self._synthesize_higgs_tts(text, voice):
|
||
yield chunk
|
||
return
|
||
if self._should_use_poc_sample_tts(voice):
|
||
async for chunk in self._synthesize_poc_sample_tts(text):
|
||
yield chunk
|
||
return
|
||
payload = build_tts_payload(
|
||
text,
|
||
voice,
|
||
model=model,
|
||
response_format=response_format,
|
||
)
|
||
|
||
try:
|
||
async with self._http.stream("POST", TTS_ENDPOINT, json=payload) as r:
|
||
if r.status_code == 404 and model != TTS_MODEL_FALLBACK:
|
||
# 모델 미가용 → tts-1 폴백(비스트림 재시도). instructions 제거.
|
||
payload["model"] = TTS_MODEL_FALLBACK
|
||
payload.pop("instructions", None)
|
||
await r.aclose()
|
||
async for c in self._synthesize_fallback(payload):
|
||
yield c
|
||
return
|
||
r.raise_for_status()
|
||
async for chunk in r.aiter_bytes(chunk_size=4096):
|
||
if not chunk:
|
||
continue
|
||
yield TTSChunk(audio=chunk)
|
||
except VoiceUnavailable:
|
||
raise
|
||
except httpx.HTTPStatusError as e:
|
||
text_body = ""
|
||
try:
|
||
text_body = (await e.response.aread()).decode("utf-8", "ignore")[:200]
|
||
except Exception:
|
||
pass
|
||
raise RuntimeError(f"TTS {e.response.status_code}: {text_body}") from e
|
||
except httpx.HTTPError as e:
|
||
raise RuntimeError(f"TTS transport error: {e}") from e
|
||
|
||
async def _synthesize_poc_sample_tts(self, text: str) -> AsyncIterator[TTSChunk]:
|
||
sample_id = self._select_poc_sample_id(text)
|
||
sample_path = self._poc_sample_path(sample_id)
|
||
try:
|
||
data = sample_path.read_bytes()
|
||
except OSError as e:
|
||
raise VoiceUnavailable(f"P1 sample TTS asset is missing: {sample_path}") from e
|
||
for i in range(0, len(data), POC_SAMPLE_TTS_CHUNK_SIZE):
|
||
chunk = data[i : i + POC_SAMPLE_TTS_CHUNK_SIZE]
|
||
if chunk:
|
||
yield TTSChunk(audio=chunk)
|
||
|
||
async def _synthesize_higgs_tts(
|
||
self, text: str, voice: VoicePreset
|
||
) -> AsyncIterator[TTSChunk]:
|
||
payload = {
|
||
"text": build_higgs_prompt(text, voice),
|
||
"preset": voice.preset,
|
||
}
|
||
try:
|
||
async with self._higgs_http.stream(
|
||
"POST", HIGGS_TTS_ENDPOINT, json=payload
|
||
) as response:
|
||
response.raise_for_status()
|
||
async for chunk in response.aiter_bytes(chunk_size=POC_SAMPLE_TTS_CHUNK_SIZE):
|
||
if chunk:
|
||
yield TTSChunk(audio=chunk)
|
||
except httpx.HTTPStatusError as exc:
|
||
body = ""
|
||
try:
|
||
body = (await exc.response.aread()).decode("utf-8", "ignore")[:200]
|
||
except Exception:
|
||
pass
|
||
raise RuntimeError(f"Higgs TTS {exc.response.status_code}: {body}") from exc
|
||
except httpx.HTTPError as exc:
|
||
raise RuntimeError(f"Higgs TTS transport error: {exc}") from exc
|
||
|
||
def _select_poc_sample_id(self, text: str) -> str:
|
||
normalized = text.casefold()
|
||
for sample_id, keywords in _POC_SAMPLE_TTS_KEYWORDS:
|
||
if any(keyword.casefold() in normalized for keyword in keywords):
|
||
return sample_id
|
||
return _POC_SAMPLE_TTS_DEFAULT_SAMPLE
|
||
|
||
async def _synthesize_fallback(self, payload: dict[str, object]) -> AsyncIterator[TTSChunk]:
|
||
"""tts-1 폴백(비스트림 POST → 전체 바이트를 청크로 분할)."""
|
||
try:
|
||
r = await self._http.post(TTS_ENDPOINT, json=payload)
|
||
r.raise_for_status()
|
||
except httpx.HTTPStatusError as e:
|
||
raise RuntimeError(f"TTS(fallback) {e.response.status_code}: {e.response.text[:200]}") from e
|
||
except httpx.HTTPError as e:
|
||
raise RuntimeError(f"TTS(fallback) transport error: {e}") from e
|
||
data = r.content
|
||
for i in range(0, len(data), 4096):
|
||
chunk = data[i : i + 4096]
|
||
yield TTSChunk(audio=chunk)
|
||
|
||
|
||
def _clamp_speed(rate: float) -> float:
|
||
"""OpenAI speed 허용범위 [0.25, 4.0] 클램프."""
|
||
try:
|
||
return max(0.25, min(4.0, float(rate)))
|
||
except (TypeError, ValueError):
|
||
return 1.0
|
||
|
||
|
||
def _nonnegative_int(value: object) -> int:
|
||
try:
|
||
return max(0, int(value)) # type: ignore[arg-type]
|
||
except (TypeError, ValueError):
|
||
return 0
|
||
|
||
|
||
def _clean_optional_text(value: object) -> str | None:
|
||
if value is None:
|
||
return None
|
||
text = str(value).strip()
|
||
return text or None
|
||
|
||
|
||
# 앱 전역 싱글톤 (main lifespan 이 startup/shutdown — Foundation 이 관리하거나
|
||
# 라우트가 lazy 사용). engine_client 패턴과 동일.
|
||
voice_service = VoiceService()
|
||
|
||
|
||
__all__ = [
|
||
"VoiceUnavailable",
|
||
"VoicePreset",
|
||
"TranscriptResult",
|
||
"EndOfTurnDecision",
|
||
"TTSChunk",
|
||
"VoiceService",
|
||
"voice_service",
|
||
"resolve_voice",
|
||
"resolve_voice_from_map",
|
||
"build_tts_payload",
|
||
"build_higgs_prompt",
|
||
"assess_end_of_turn",
|
||
"EOT_SILENCE_THRESHOLD_MS",
|
||
"PRESET_TO_OPENAI_VOICE",
|
||
"PERSONA_CODE_TO_PRESET",
|
||
"DEFAULT_OPENAI_VOICE",
|
||
"STT_MODEL",
|
||
"TTS_MODEL",
|
||
"HIGGS_TTS_MODEL",
|
||
]
|