tts_provider.py 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114
  1. """Text-to-Speech Provider ABC.
  2. Providers register via ``PluginContext.register_tts_provider()`` and service
  3. ``text_to_speech`` only when ``tts.provider`` names neither a built-in
  4. (``BUILTIN_TTS_PROVIDERS`` in :mod:`tools.tts_tool`; the registry rejects
  5. colliding names) nor a ``tts.providers.<name>: type: command`` entry (config is
  6. more local than a plugin install, so it wins). :meth:`TTSProvider.synthesize`
  7. should raise on failure — the dispatcher builds the ``{success: False}`` envelope.
  8. """
  9. from __future__ import annotations
  10. import abc
  11. import logging
  12. from typing import Any, Dict, Iterator, List, Optional
  13. from agent.provider_base import CatalogProviderBase
  14. logger = logging.getLogger(__name__)
  15. DEFAULT_OUTPUT_FORMAT = "mp3"
  16. VALID_OUTPUT_FORMATS = frozenset({"mp3", "wav", "ogg", "opus", "flac"})
  17. class TTSProvider(CatalogProviderBase):
  18. """Abstract base class for a text-to-speech backend.
  19. Subclasses must implement :attr:`name` (rejected at registration if it
  20. collides with a built-in TTS provider name) and :meth:`synthesize`.
  21. Opting into the streaming voice path (CLI/TUI speaker, desktop speak-stream,
  22. gateway streaming audio): set :attr:`streams_pcm` and :attr:`stream_sample_rate`
  23. and make ``stream(text, format="pcm", ...)`` yield raw int16 little-endian mono
  24. PCM at that rate. Both are read (with :meth:`is_available`) each time a reply
  25. resolves its streamer, so they may be properties reflecting live state; a
  26. missing rate falls back to per-sentence :meth:`synthesize`. Unlike
  27. :meth:`synthesize`, ``stream()`` may run concurrently for consecutive
  28. sentences of one reply (the speaker prefetches up to 3), so it must be
  29. thread-safe.
  30. """
  31. streams_pcm: bool = False
  32. stream_sample_rate: Optional[int] = None
  33. def list_voices(self) -> list[dict[str, Any]]:
  34. """Voice catalog entries: ``{"id"}`` required; ``display`` / ``language``
  35. / ``gender`` / ``preview_url`` optional. Default: empty."""
  36. return []
  37. def default_voice(self) -> Optional[str]:
  38. """Id of the first voice entry, or None if not applicable."""
  39. voices = self.list_voices()
  40. return voices[0].get("id") if voices else None
  41. @abc.abstractmethod
  42. def synthesize(
  43. self, text: str, output_path: str, *, voice: Optional[str]=None, model: Optional[str]=None,
  44. speed: Optional[float]=None, format: str=DEFAULT_OUTPUT_FORMAT, ** extra: Any,
  45. ) -> str:
  46. """Synthesize ``text`` into ``output_path`` and return the written path.
  47. ``text`` is already truncated to the provider's max length and the
  48. parent directory exists. ``voice`` / ``model`` fall back to
  49. :meth:`default_voice` / :meth:`default_model` when None; ``speed`` is a
  50. rate multiplier providers may ignore. If ``format`` is unsupported, pick
  51. the closest equivalent and make ``output_path`` carry the right
  52. extension. Unknown ``extra`` keys must be ignored. Raise on failure.
  53. """
  54. def stream(
  55. self, text: str, *, voice: Optional[str] = None, model: Optional[str] = None,
  56. format: str = "opus", **extra: Any,
  57. ) -> Iterator[bytes]:
  58. """Stream synthesized audio bytes (optional).
  59. Default raises :class:`NotImplementedError`; the dispatcher then falls
  60. back to :meth:`synthesize` + read-whole-file. ``format`` defaults to
  61. ``opus`` because the primary streaming consumer is voice-bubble
  62. delivery (Telegram et al.), which requires Opus.
  63. """
  64. raise NotImplementedError(
  65. f"TTS provider {self.name!r} does not implement streaming "
  66. "synthesis. Use synthesize() instead, or implement stream() "
  67. "if your backend supports it."
  68. )
  69. def warm(self) -> None:
  70. """Speech output was just turned on; pre-load so the first reply is hot.
  71. Called from the TTS lease path when this is the configured provider.
  72. Best-effort; default no-op."""
  73. def release(self) -> None:
  74. """Last speech-output lease released; free resident resources (counterpart
  75. of :meth:`warm`). Best-effort; default no-op."""
  76. @property
  77. def voice_compatible(self) -> bool:
  78. """Whether output suits voice-bubble delivery (mirrors
  79. ``tts.providers.<name>.voice_compatible``): True → the gateway converts
  80. to Opus via ffmpeg if needed; False → regular audio attachment. Default
  81. False (opt in).
  82. See #17843.
  83. """
  84. return False
  85. def resolve_output_format(value: Optional[str]) -> str:
  86. """Clamp an output_format to :data:`VALID_OUTPUT_FORMATS`; invalid values
  87. coerce to :data:`DEFAULT_OUTPUT_FORMAT` so the tool surface forgives agent
  88. mistakes instead of rejecting them."""
  89. v = value.strip().lower() if isinstance(value, str) else None
  90. return v if v in VALID_OUTPUT_FORMATS else DEFAULT_OUTPUT_FORMAT