atom-audio-engine 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

tts/base.py

@@ -1,155 +0,0 @@
-"""Abstract base class for TTS (Text-to-Speech) providers."""
-
-from abc import ABC, abstractmethod
-from typing import AsyncIterator, Optional
-
-from core.types import AudioChunk, AudioFormat
-
-
-class BaseTTS(ABC):
-    """
-    Abstract base class for Text-to-Speech providers.
-
-    All TTS implementations must inherit from this class and implement
-    the required methods for both batch and streaming audio synthesis.
-    """
-
-    def __init__(
-        self,
-        api_key: Optional[str] = None,
-        voice_id: Optional[str] = None,
-        model: Optional[str] = None,
-        speed: float = 1.0,
-        output_format: AudioFormat = AudioFormat.PCM_24K,
-        **kwargs
-    ):
-        """
-        Initialize the TTS provider.
-
-        Args:
-            api_key: API key for the provider
-            voice_id: Voice identifier to use
-            model: Model identifier (if applicable)
-            speed: Speech speed multiplier (1.0 = normal)
-            output_format: Desired audio output format
-            **kwargs: Additional provider-specific configuration
-        """
-        self.api_key = api_key
-        self.voice_id = voice_id
-        self.model = model
-        self.speed = speed
-        self.output_format = output_format
-        self.config = kwargs
-
-    @abstractmethod
-    async def synthesize(self, text: str) -> bytes:
-        """
-        Synthesize complete audio from text.
-
-        Args:
-            text: Text to convert to speech
-
-        Returns:
-            Complete audio as bytes
-        """
-        pass
-
-    @abstractmethod
-    async def synthesize_stream(self, text: str) -> AsyncIterator[AudioChunk]:
-        """
-        Synthesize streaming audio from text.
-
-        Args:
-            text: Text to convert to speech
-
-        Yields:
-            AudioChunk objects with audio data
-        """
-        pass
-
-    async def synthesize_stream_text(
-        self, text_stream: AsyncIterator[str]
-    ) -> AsyncIterator[AudioChunk]:
-        """
-        Synthesize streaming audio from streaming text input.
-
-        This enables sentence-by-sentence TTS as the LLM generates text.
-        Default implementation buffers until punctuation. Override for
-        providers with native text streaming support.
-
-        Args:
-            text_stream: Async iterator yielding text chunks
-
-        Yields:
-            AudioChunk objects with audio data
-        """
-        buffer = ""
-        sentence_enders = ".!?;"
-
-        async for text_chunk in text_stream:
-            buffer += text_chunk
-
-            # Check if we have a complete sentence
-            for ender in sentence_enders:
-                if ender in buffer:
-                    # Split at the sentence boundary
-                    parts = buffer.split(ender, 1)
-                    sentence = parts[0] + ender
-
-                    if sentence.strip():
-                        async for audio_chunk in self.synthesize_stream(
-                            sentence.strip()
-                        ):
-                            yield audio_chunk
-
-                    buffer = parts[1] if len(parts) > 1 else ""
-                    break
-
-        # Handle remaining text
-        if buffer.strip():
-            async for audio_chunk in self.synthesize_stream(buffer.strip()):
-                yield audio_chunk
-
-    async def __aenter__(self):
-        """Async context manager entry."""
-        await self.connect()
-        return self
-
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
-        """Async context manager exit."""
-        await self.disconnect()
-
-    async def connect(self):
-        """
-        Establish connection to the TTS service.
-        Override in subclasses if needed.
-        """
-        pass
-
-    async def disconnect(self):
-        """
-        Close connection to the TTS service.
-        Override in subclasses if needed.
-        """
-        pass
-
-    @property
-    @abstractmethod
-    def name(self) -> str:
-        """Return the name of this TTS provider."""
-        pass
-
-    @property
-    def supports_streaming(self) -> bool:
-        """Whether this provider supports streaming audio output."""
-        return True
-
-    @property
-    def sample_rate(self) -> int:
-        """Return the sample rate for this provider's output."""
-        format_rates = {
-            AudioFormat.PCM_16K: 16000,
-            AudioFormat.PCM_24K: 24000,
-            AudioFormat.PCM_44K: 44100,
-        }
-        return format_rates.get(self.output_format, 24000)

tts/cartesia.py

@@ -1,392 +0,0 @@
-"""Cartesia API implementation for TTS (Text-to-Speech)."""
-
-import asyncio
-import base64
-import json
-import logging
-from typing import AsyncIterator, Optional
-
-import websockets
-
-
-from core.types import AudioChunk, AudioFormat
-from .base import BaseTTS
-
-logger = logging.getLogger(__name__)
-
-
-class CartesiaTTS(BaseTTS):
-    """
-    Cartesia API client for text-to-speech synthesis.
-
-    Supports streaming synthesis with per-chunk latency < 200ms.
-    Uses WebSocket connections for real-time streaming with continuations.
-    Outputs 16kHz PCM by default (can be configured).
-
-    Example:
-        tts = CartesiaTTS(api_key="...", voice_id="sonic")
-
-        # Streaming text input (from LLM)
-        async for chunk in tts.synthesize_stream_text(llm_text_stream):
-            play_audio(chunk)
-    """
-
-    CARTESIA_VERSION = "2025-04-16"
-    DEFAULT_VOICE_ID = "c8605446-247c-4d39-acd4-8f4c28aa363c"  # Edith voice
-    WS_URL = "wss://api.cartesia.ai/tts/websocket"
-
-    def __init__(
-        self,
-        api_key: Optional[str] = None,
-        voice_id: Optional[str] = None,
-        model: Optional[str] = "sonic-3",
-        speed: float = 1.0,
-        output_format: AudioFormat = AudioFormat.PCM_16K,
-        sample_rate: int = 16000,
-        max_buffer_delay_ms: int = 1500,
-        **kwargs,
-    ):
-        """
-        Initialize Cartesia TTS provider.
-
-        Args:
-            api_key: Cartesia API key (or None to use CARTESIA_API_KEY env var)
-            voice_id: Voice identifier (UUID or default Edith)
-            model: Model to use (default: sonic-3)
-            speed: Speech speed multiplier (1.0 = normal)
-            output_format: Desired audio output format (default 16kHz PCM)
-            sample_rate: Output sample rate in Hz (default: 16000)
-            max_buffer_delay_ms: Buffering delay for streaming (0-5000ms)
-            **kwargs: Additional config
-        """
-        # Fallback to environment variable if not provided
-        if not api_key:
-            import os
-
-            api_key = os.getenv("CARTESIA_API_KEY")
-
-        super().__init__(
-            api_key=api_key,
-            voice_id=voice_id or self.DEFAULT_VOICE_ID,
-            model=model,
-            speed=speed,
-            output_format=output_format,
-            **kwargs,
-        )
-        self._sample_rate = sample_rate
-        self.max_buffer_delay_ms = max_buffer_delay_ms
-
-    @property
-    def name(self) -> str:
-        """Return provider name."""
-        return "cartesia"
-
-    @property
-    def sample_rate(self) -> int:
-        """Return the sample rate for this provider's output."""
-        return self._sample_rate
-
-    async def connect(self):
-        """Cartesia uses WebSocket connections - no persistent client needed."""
-        pass
-
-    async def disconnect(self):
-        """Cartesia uses WebSocket connections - no persistent client needed."""
-        pass
-
-    async def synthesize(self, text: str) -> bytes:
-        """
-        Synthesize complete audio from text (non-streaming).
-
-        Args:
-            text: Text to convert to speech
-
-        Returns:
-            Complete audio as bytes (PCM)
-        """
-        audio_data = bytearray()
-        async for chunk in self.synthesize_stream_text(self._text_to_async_iter(text)):
-            if chunk.data and not chunk.is_final:
-                audio_data.extend(chunk.data)
-        return bytes(audio_data)
-
-    async def synthesize_stream(self, text: str) -> AsyncIterator[AudioChunk]:
-        """
-        Synthesize streaming audio from text.
-
-        Args:
-            text: Text to convert to speech
-
-        Yields:
-            AudioChunk objects with audio data
-        """
-        async for chunk in self.synthesize_stream_text(self._text_to_async_iter(text)):
-            yield chunk
-
-    async def synthesize_stream_text(
-        self, text_stream: AsyncIterator[str]
-    ) -> AsyncIterator[AudioChunk]:
-        """
-        Synthesize streaming audio from streaming text input via WebSocket.
-
-        Uses continuations to maintain natural prosody across streamed text chunks.
-
-        Args:
-            text_stream: Async iterator yielding text tokens
-
-        Yields:
-            AudioChunk objects with audio data
-        """
-        if websockets is None:
-            raise ImportError(
-                "websockets package required. Install: pip install websockets"
-            )
-
-        if not self.api_key:
-            raise ValueError("api_key required for Cartesia TTS")
-
-        # Use unique context ID for this synthesis session
-        import uuid
-
-        context_id = str(uuid.uuid4())
-
-        ws_url = (
-            f"{self.WS_URL}"
-            f"?api_key={self.api_key}"
-            f"&cartesia_version={self.CARTESIA_VERSION}"
-        )
-
-        try:
-            async with websockets.connect(ws_url) as websocket:
-                logger.debug(
-                    f"Cartesia TTS WebSocket connected | Context: {context_id}"
-                )
-
-                # Task to receive audio from WebSocket
-                async def receive_audio():
-                    """Receive audio chunks from TTS WebSocket."""
-                    logger.debug("Cartesia: receive_audio started")
-                    try:
-                        async for message in websocket:
-                            if isinstance(message, str):
-                                try:
-                                    response = json.loads(message)
-                                    logger.debug(
-                                        f"Cartesia: received response type={response.get('type')}"
-                                    )
-                                    # Handle audio chunk (base64 in "data" field)
-                                    if response.get("type") == "chunk" and response.get(
-                                        "data"
-                                    ):
-                                        audio_bytes = base64.b64decode(response["data"])
-                                        yield audio_bytes
-                                        logger.debug(
-                                            f"Cartesia: received audio chunk {len(audio_bytes)} bytes"
-                                        )
-                                    # Handle buffer flush
-                                    elif response.get("type") == "flush_done":
-                                        logger.debug("Cartesia: buffer flushed")
-                                    # Handle completion
-                                    elif response.get("type") == "done":
-                                        logger.info("Cartesia: TTS generation complete")
-                                        break
-                                    # Handle error
-                                    elif response.get("type") == "error":
-                                        error_msg = (
-                                            response.get("error")
-                                            or response.get("error_message")
-                                            or response.get("message")
-                                            or str(response)
-                                        )
-                                        logger.error(f"Cartesia TTS error: {error_msg}")
-                                        raise RuntimeError(
-                                            f"Cartesia API error: {error_msg}"
-                                        )
-                                    else:
-                                        logger.debug(
-                                            f"Cartesia: response type {response.get('type')}"
-                                        )
-                                except json.JSONDecodeError:
-                                    logger.warning(
-                                        f"Failed to parse Cartesia response: {message}"
-                                    )
-                    except Exception as e:
-                        logger.error(f"Cartesia receive error: {e}", exc_info=True)
-                        raise
-
-                # Task to send text to WebSocket
-                async def send_text():
-                    """Send text tokens to TTS WebSocket."""
-                    logger.debug("Cartesia: send_text started")
-                    accumulated_text = ""
-                    first_token_timeout = 30.0
-                    subsequent_token_timeout = 2.0
-                    first_token_received = False
-
-                    try:
-                        while True:
-                            try:
-                                # Wait for token with appropriate timeout
-                                timeout = (
-                                    first_token_timeout
-                                    if not first_token_received
-                                    else subsequent_token_timeout
-                                )
-                                token = await asyncio.wait_for(
-                                    self._get_next_token(text_stream),
-                                    timeout=timeout,
-                                )
-                                first_token_received = True
-                            except asyncio.TimeoutError:
-                                logger.debug(
-                                    f"Cartesia: token timeout (first_token={first_token_received})"
-                                )
-                                # Send accumulated text even on timeout
-                                if accumulated_text.strip():
-                                    request = {
-                                        "model_id": self.model,
-                                        "transcript": accumulated_text,
-                                        "context_id": context_id,
-                                        "continue": True,
-                                        "max_buffer_delay_ms": self.max_buffer_delay_ms,
-                                        "voice": {
-                                            "mode": "id",
-                                            "id": self.voice_id,
-                                        },
-                                        "output_format": {
-                                            "container": "raw",
-                                            "encoding": "pcm_s16le",
-                                            "sample_rate": self.sample_rate,
-                                        },
-                                    }
-                                    await websocket.send(json.dumps(request))
-                                    logger.debug(
-                                        f"Cartesia: sent text on timeout (continue=true)"
-                                    )
-                                    accumulated_text = ""
-                                continue
-
-                            # None signals end of text stream
-                            if token is None:
-                                # Send remaining text with continue=false
-                                if accumulated_text.strip():
-                                    request = {
-                                        "model_id": self.model,
-                                        "transcript": accumulated_text,
-                                        "context_id": context_id,
-                                        "continue": False,
-                                        "max_buffer_delay_ms": self.max_buffer_delay_ms,
-                                        "voice": {
-                                            "mode": "id",
-                                            "id": self.voice_id,
-                                        },
-                                        "output_format": {
-                                            "container": "raw",
-                                            "encoding": "pcm_s16le",
-                                            "sample_rate": self.sample_rate,
-                                        },
-                                    }
-                                    await websocket.send(json.dumps(request))
-                                    logger.debug(
-                                        f"Cartesia: sent final text (continue=false)"
-                                    )
-                                else:
-                                    # Send empty transcript to signal end
-                                    request = {
-                                        "model_id": self.model,
-                                        "transcript": "",
-                                        "context_id": context_id,
-                                        "continue": False,
-                                        "max_buffer_delay_ms": self.max_buffer_delay_ms,
-                                        "voice": {
-                                            "mode": "id",
-                                            "id": self.voice_id,
-                                        },
-                                        "output_format": {
-                                            "container": "raw",
-                                            "encoding": "pcm_s16le",
-                                            "sample_rate": self.sample_rate,
-                                        },
-                                    }
-                                    await websocket.send(json.dumps(request))
-                                    logger.debug(
-                                        "Cartesia: sent empty transcript to signal end"
-                                    )
-                                logger.info("Cartesia: all text sent")
-                                break
-
-                            # Accumulate token
-                            accumulated_text += token
-                            logger.debug(
-                                f"Cartesia: buffered token {len(accumulated_text)} chars total"
-                            )
-
-                            # Send when buffer is large enough or ends with punctuation
-                            if len(accumulated_text) > 30 or token.endswith(
-                                (".", "!", "?")
-                            ):
-                                request = {
-                                    "model_id": self.model,
-                                    "transcript": accumulated_text,
-                                    "context_id": context_id,
-                                    "continue": True,
-                                    "max_buffer_delay_ms": self.max_buffer_delay_ms,
-                                    "voice": {
-                                        "mode": "id",
-                                        "id": self.voice_id,
-                                    },
-                                    "output_format": {
-                                        "container": "raw",
-                                        "encoding": "pcm_s16le",
-                                        "sample_rate": self.sample_rate,
-                                    },
-                                }
-                                await websocket.send(json.dumps(request))
-                                logger.debug(
-                                    f"Cartesia: sent buffered text (continue=true)"
-                                )
-                                accumulated_text = ""
-
-                    except Exception as e:
-                        logger.error(f"Cartesia send error: {e}")
-
-                # Run send and receive concurrently
-                send_task = asyncio.create_task(send_text())
-
-                async for audio_bytes in receive_audio():
-                    yield AudioChunk(
-                        data=audio_bytes,
-                        sample_rate=self.sample_rate,
-                        channels=1,
-                        format=self.output_format,
-                        is_final=False,
-                    )
-
-                # Wait for send task to complete
-                await send_task
-
-                # Yield final marker
-                yield AudioChunk(
-                    data=b"",
-                    sample_rate=self.sample_rate,
-                    channels=1,
-                    format=self.output_format,
-                    is_final=True,
-                )
-
-                logger.info("Cartesia: stream complete")
-
-        except Exception as e:
-            logger.error(f"Cartesia streaming text error: {e}")
-            raise
-
-    async def _get_next_token(self, text_stream: AsyncIterator[str]) -> Optional[str]:
-        """Get next token from async iterator."""
-        try:
-            return await text_stream.__anext__()
-        except StopAsyncIteration:
-            return None
-
-    async def _text_to_async_iter(self, text: str) -> AsyncIterator[str]:
-        """Convert plain text to async iterator."""
-        yield text

utils/__init__.py

@@ -1,15 +0,0 @@
-"""Utility functions for the audio engine."""
-
-from utils.audio import (
-    resample_audio,
-    pcm_to_wav,
-    wav_to_pcm,
-    get_audio_duration,
-)
-
-__all__ = [
-    "resample_audio",
-    "pcm_to_wav",
-    "wav_to_pcm",
-    "get_audio_duration",
-]