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

audio_engine/pipelines/personaplex/types.py

@@ -0,0 +1,173 @@
+"""Data types for PersonaPlex speech-to-speech pipeline."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+from enum import Enum
+from datetime import UTC, datetime
+
+
+class MessageType(Enum):
+    """WebSocket message types for PersonaPlex protocol."""
+
+    HANDSHAKE = 0x00
+    AUDIO = 0x01
+    TEXT = 0x02
+    CONTROL = 0x03
+    METADATA = 0x04
+    ERROR = 0x05
+    PING = 0x06
+
+
+@dataclass
+class PersonaPlexMessage:
+    """
+    A message in the PersonaPlex WebSocket protocol.
+
+    Attributes:
+        type: Message type (audio, text, handshake, etc.)
+        data: Message payload (bytes for audio, str for text)
+        timestamp_ms: Optional timestamp in milliseconds
+    """
+
+    type: MessageType
+    data: bytes | str
+    timestamp_ms: Optional[int] = None
+
+    def encode(self) -> bytes:
+        """Encode message to binary format for transmission."""
+        type_byte = bytes([self.type.value])
+        if isinstance(self.data, bytes):
+            return type_byte + self.data
+        else:
+            return type_byte + self.data.encode("utf-8")
+
+    @classmethod
+    def decode(cls, data: bytes) -> "PersonaPlexMessage":
+        """Decode binary message from WebSocket."""
+        if len(data) < 1:
+            raise ValueError("Message too short")
+
+        msg_type = MessageType(data[0])
+        payload = data[1:]
+
+        # Text messages are UTF-8 decoded
+        if msg_type == MessageType.TEXT:
+            text_data = payload.decode("utf-8")
+            return cls(type=msg_type, data=text_data)
+        else:
+            return cls(type=msg_type, data=payload)
+
+
+@dataclass
+class TranscriptMessage:
+    """
+    A single message in the conversation transcript.
+
+    Attributes:
+        role: "user" or "assistant"
+        text: The message content
+        timestamp: ISO 8601 timestamp when message was generated
+    """
+
+    role: str
+    text: str
+    timestamp: str
+
+
+@dataclass
+class SessionData:
+    """
+    Metadata and transcript for a PersonaPlex session.
+
+    Attributes:
+        session_id: Unique session identifier (UUID)
+        timestamp: Session start time (ISO 8601)
+        system_prompt: System prompt used for the session
+        voice_prompt: Voice preset used (e.g., "NATF0.pt")
+        messages: List of transcript messages (user + assistant)
+    """
+
+    session_id: str
+    timestamp: str
+    system_prompt: str
+    voice_prompt: str
+    messages: list[TranscriptMessage] = field(default_factory=list)
+
+    def add_message(self, role: str, text: str) -> None:
+        """Add a message to the transcript."""
+        msg = TranscriptMessage(
+            role=role,
+            text=text,
+            timestamp=datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+        )
+        self.messages.append(msg)
+
+    def to_dict(self) -> dict:
+        """Convert session data to dictionary for JSON serialization."""
+        return {
+            "session_id": self.session_id,
+            "timestamp": self.timestamp,
+            "system_prompt": self.system_prompt,
+            "voice_prompt": self.voice_prompt,
+            "messages": [
+                {
+                    "role": msg.role,
+                    "text": msg.text,
+                    "timestamp": msg.timestamp,
+                }
+                for msg in self.messages
+            ],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SessionData":
+        """Create SessionData from dictionary."""
+        messages = [
+            TranscriptMessage(
+                role=msg["role"],
+                text=msg["text"],
+                timestamp=msg.get("timestamp", ""),
+            )
+            for msg in data.get("messages", [])
+        ]
+        return cls(
+            session_id=data["session_id"],
+            timestamp=data["timestamp"],
+            system_prompt=data["system_prompt"],
+            voice_prompt=data["voice_prompt"],
+            messages=messages,
+        )
+
+
+@dataclass
+class AudioChunk:
+    """
+    A chunk of audio data from PersonaPlex.
+
+    Attributes:
+        data: Raw Opus-encoded audio bytes
+        sample_rate: Sample rate in Hz (typically 48000)
+        timestamp_ms: When this chunk was generated
+        is_final: Whether this is the last chunk in a sequence
+    """
+
+    data: bytes
+    sample_rate: int = 48000
+    timestamp_ms: Optional[int] = None
+    is_final: bool = False
+
+
+@dataclass
+class TextChunk:
+    """
+    A text token from PersonaPlex LLM output.
+
+    Attributes:
+        text: Text content (partial or complete word)
+        timestamp_ms: When this token was generated
+        is_final: Whether this is the last token in a sequence
+    """
+
+    text: str
+    timestamp_ms: Optional[int] = None
+    is_final: bool = False

audio_engine/pipelines/personaplex/utils.py

@@ -0,0 +1,192 @@
+"""Utility functions for PersonaPlex pipeline."""
+
+import json
+import logging
+import uuid
+from pathlib import Path
+from datetime import datetime, UTC
+from typing import Optional
+
+from .types import SessionData
+
+logger = logging.getLogger(__name__)
+
+
+def generate_session_id() -> str:
+    """
+    Generate a unique session identifier.
+
+    Returns:
+        UUID4 string for this session
+    """
+    return str(uuid.uuid4())
+
+
+def get_timestamp_iso() -> str:
+    """
+    Get current timestamp in ISO 8601 format with Z suffix.
+
+    Returns:
+        Timestamp string (e.g., "2026-02-03T10:30:45.123456Z")
+    """
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+
+
+def save_transcript(
+    session_data: SessionData,
+    output_path: Optional[str] = None,
+) -> Path:
+    """
+    Save session transcript to JSON file.
+
+    Approach:
+    1. Convert SessionData to dictionary
+    2. Write as formatted JSON
+    3. Return path for verification
+
+    Args:
+        session_data: SessionData object with transcript
+        output_path: Directory to save transcript (default: ./transcripts/)
+
+    Returns:
+        Path to saved JSON file
+
+    Raises:
+        IOError: If file write fails
+    """
+    if output_path is None:
+        output_path = "./transcripts/"
+
+    output_dir = Path(output_path)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Filename: session_id_YYYY-MM-DD.json
+    timestamp_str = session_data.timestamp.split("T")[0]  # Extract date
+    filename = f"{session_data.session_id}_{timestamp_str}.json"
+    filepath = output_dir / filename
+
+    try:
+        with open(filepath, "w") as f:
+            json.dump(session_data.to_dict(), f, indent=2)
+        logger.info(f"Transcript saved to {filepath}")
+        return filepath
+    except IOError as e:
+        logger.error(f"Failed to save transcript: {e}")
+        raise
+
+
+def load_transcript(filepath: str | Path) -> SessionData:
+    """
+    Load session transcript from JSON file.
+
+    Args:
+        filepath: Path to transcript JSON file
+
+    Returns:
+        SessionData object
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        json.JSONDecodeError: If JSON is invalid
+    """
+    filepath = Path(filepath)
+
+    try:
+        with open(filepath, "r") as f:
+            data = json.load(f)
+        logger.info(f"Loaded transcript from {filepath}")
+        return SessionData.from_dict(data)
+    except FileNotFoundError:
+        logger.error(f"Transcript file not found: {filepath}")
+        raise
+    except json.JSONDecodeError as e:
+        logger.error(f"Invalid JSON in transcript file: {e}")
+        raise
+
+
+def list_transcripts(directory: str | Path = "./transcripts/") -> list[Path]:
+    """
+    List all transcript files in a directory.
+
+    Args:
+        directory: Path to transcripts directory
+
+    Returns:
+        List of Path objects for .json files, sorted by modification time (newest first)
+    """
+    dir_path = Path(directory)
+    if not dir_path.exists():
+        logger.warning(f"Transcripts directory does not exist: {directory}")
+        return []
+
+    transcripts = sorted(
+        dir_path.glob("*.json"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    return transcripts
+
+
+def format_transcript_for_display(session_data: SessionData) -> str:
+    """
+    Format transcript as human-readable text.
+
+    Args:
+        session_data: SessionData object
+
+    Returns:
+        Formatted text with speaker labels and messages
+    """
+    lines = [
+        f"=== PersonaPlex Session ===",
+        f"Session ID: {session_data.session_id}",
+        f"Started: {session_data.timestamp}",
+        f"Voice: {session_data.voice_prompt}",
+        f"Prompt: {session_data.system_prompt}",
+        f"",
+        "--- Transcript ---",
+    ]
+
+    for msg in session_data.messages:
+        speaker = msg.role.upper()
+        lines.append(f"{speaker}: {msg.text}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def cleanup_old_transcripts(
+    directory: str | Path = "./transcripts/",
+    max_age_days: int = 30,
+) -> int:
+    """
+    Delete transcripts older than specified number of days.
+
+    Args:
+        directory: Path to transcripts directory
+        max_age_days: Delete files older than this many days
+
+    Returns:
+        Number of files deleted
+    """
+    from datetime import timedelta
+    import time
+
+    dir_path = Path(directory)
+    if not dir_path.exists():
+        return 0
+
+    cutoff_time = time.time() - (max_age_days * 24 * 60 * 60)
+    deleted_count = 0
+
+    for transcript_file in dir_path.glob("*.json"):
+        if transcript_file.stat().st_mtime < cutoff_time:
+            try:
+                transcript_file.unlink()
+                logger.info(f"Deleted old transcript: {transcript_file}")
+                deleted_count += 1
+            except OSError as e:
+                logger.error(f"Failed to delete {transcript_file}: {e}")
+
+    logger.info(f"Cleaned up {deleted_count} old transcripts")
+    return deleted_count

audio_engine/scripts/debug_pipeline.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""
+Debug the exact pipeline flow
+"""
+
+import asyncio
+import sys
+import logging
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+logging.basicConfig(
+    level=logging.DEBUG, format="%(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+from core.config import AudioEngineConfig
+
+
+async def main():
+    logger.info("\n" + "=" * 70)
+    logger.info("DEBUG: Full Pipeline Flow")
+    logger.info("=" * 70)
+
+    # Load config exactly like the example does
+    config = AudioEngineConfig.from_env()
+    logger.info(f"✓ Config loaded")
+    logger.info(f"  ASR: {config.asr.provider}")
+    logger.info(f"  LLM: {config.llm.provider}")
+    logger.info(f"  TTS: {config.tts.provider}")
+
+    # Create pipeline exactly like the example does
+    pipeline = config.create_pipeline(
+        system_prompt="You are a helpful assistant. Keep responses brief."
+    )
+    logger.info(f"✓ Pipeline created")
+
+    # Log TTS config
+    logger.info(f"\n  TTS Details:")
+    logger.info(
+        f"    api_key: {pipeline.tts.api_key[:10]}..."
+        if pipeline.tts.api_key
+        else "    api_key: None"
+    )
+    logger.info(f"    voice_id: {pipeline.tts.voice_id}")
+    logger.info(f"    model: {pipeline.tts.model}")
+    logger.info(f"    sample_rate: {pipeline.tts.sample_rate}")
+
+    # Test with simple text
+    logger.info(f"\n✓ Testing with simple text...")
+    user_text = "Hello world"
+
+    try:
+        chunk_count = 0
+        total_bytes = 0
+        async for audio_chunk in pipeline.stream_text_input(user_text):
+            chunk_count += 1
+            total_bytes += len(audio_chunk.data) if audio_chunk.data else 0
+            is_final_str = "final" if audio_chunk.is_final else "chunk"
+            logger.info(
+                f"  • Audio {is_final_str} {chunk_count}: {len(audio_chunk.data) if audio_chunk.data else 0} bytes"
+            )
+
+        logger.info(f"\n✓ SUCCESS: Got {chunk_count} chunks, {total_bytes} bytes")
+    except Exception as e:
+        logger.error(f"✗ FAILED: {type(e).__name__}: {e}", exc_info=True)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    exit_code = asyncio.run(main())
+    sys.exit(exit_code)

audio_engine/scripts/debug_tts.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+Debug script: Test CartesiaTTS in isolation
+"""
+
+import asyncio
+import sys
+import logging
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from dotenv import load_dotenv
+from tts.cartesia import CartesiaTTS
+
+# Load env variables
+load_dotenv()
+
+# Setup logging
+logging.basicConfig(
+    level=logging.DEBUG, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+async def test_simple_text():
+    """Test simple text-to-speech."""
+    logger.info("=" * 70)
+    logger.info("TEST: Simple Text-to-Speech")
+    logger.info("=" * 70)
+
+    tts = CartesiaTTS(
+        api_key=None,  # Will use env var
+        voice_id=None,  # Will use default
+        model="sonic-3",
+        sample_rate=16000,
+    )
+
+    logger.info(f"TTS Config:")
+    logger.info(f"  API Key: {tts.api_key}")
+    logger.info(f"  Voice ID: {tts.voice_id}")
+    logger.info(f"  Model: {tts.model}")
+    logger.info(f"  Sample Rate: {tts.sample_rate}")
+
+    try:
+        logger.info("\nCalling synthesize_stream_text with simple text...")
+
+        async def text_gen():
+            yield "Hello "
+            yield "world"
+
+        chunk_count = 0
+        total_bytes = 0
+
+        async for chunk in tts.synthesize_stream_text(text_gen()):
+            chunk_count += 1
+            if chunk.data:
+                total_bytes += len(chunk.data)
+                logger.info(
+                    f"✓ Got audio chunk {chunk_count}: {len(chunk.data)} bytes, is_final={chunk.is_final}"
+                )
+            else:
+                logger.info(f"✓ Got final marker: is_final={chunk.is_final}")
+
+        logger.info(f"\n✓ SUCCESS: Got {chunk_count} chunks, {total_bytes} bytes total")
+
+    except Exception as e:
+        logger.error(f"✗ FAILED: {type(e).__name__}: {e}", exc_info=True)
+        return False
+
+    return True
+
+
+async def test_with_queue():
+    """Test using asyncio.Queue like the original example."""
+    logger.info("\n" + "=" * 70)
+    logger.info("TEST: With asyncio.Queue (like StreamingService)")
+    logger.info("=" * 70)
+
+    tts = CartesiaTTS(
+        api_key=None,
+        voice_id=None,
+        model="sonic-3",
+        sample_rate=16000,
+    )
+
+    queue = asyncio.Queue()
+
+    async def text_producer():
+        """Simulate LLM producing text tokens."""
+        tokens = ["Hello ", "world", "!"]
+        for token in tokens:
+            logger.info(f"📤 Producing: {token!r}")
+            await queue.put(token)
+        logger.info("📤 Putting None to signal end")
+        await queue.put(None)
+
+    async def queue_to_async_iter():
+        """Convert queue to async iterator."""
+        while True:
+            token = await queue.get()
+            if token is None:
+                break
+            yield token
+
+    try:
+        logger.info("\nStarting text producer and TTS consumer...")
+
+        producer_task = asyncio.create_task(text_producer())
+
+        chunk_count = 0
+        total_bytes = 0
+
+        async for chunk in tts.synthesize_stream_text(queue_to_async_iter()):
+            chunk_count += 1
+            if chunk.data:
+                total_bytes += len(chunk.data)
+                logger.info(f"✓ Got audio chunk {chunk_count}: {len(chunk.data)} bytes")
+            else:
+                logger.info(f"✓ Got final marker")
+
+        await producer_task
+
+        logger.info(f"\n✓ SUCCESS: Got {chunk_count} chunks, {total_bytes} bytes total")
+        return True
+
+    except Exception as e:
+        logger.error(f"✗ FAILED: {type(e).__name__}: {e}", exc_info=True)
+        return False
+
+
+async def main():
+    logger.info("\n")
+    logger.info("╔" + "=" * 68 + "╗")
+    logger.info("║" + " " * 15 + "CARTESIA TTS DEBUG TEST" + " " * 31 + "║")
+    logger.info("╚" + "=" * 68 + "╝")
+
+    results = []
+
+    # Test 1: Simple text
+    results.append(("Simple text-to-speech", await test_simple_text()))
+
+    # Test 2: Queue-based
+    results.append(("Queue-based streaming", await test_with_queue()))
+
+    # Summary
+    logger.info("\n" + "=" * 70)
+    logger.info("SUMMARY")
+    logger.info("=" * 70)
+    for test_name, passed in results:
+        status = "✓ PASS" if passed else "✗ FAIL"
+        logger.info(f"{status}: {test_name}")
+
+    all_passed = all(result for _, result in results)
+    logger.info("=" * 70)
+
+    return 0 if all_passed else 1
+
+
+if __name__ == "__main__":
+    exit_code = asyncio.run(main())
+    sys.exit(exit_code)

audio_engine/scripts/test_cartesia_connect.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Test Cartesia WebSocket connection and capture error message."""
+
+import asyncio
+import logging
+from pathlib import Path
+from urllib.parse import quote
+
+import websockets
+from websockets.exceptions import InvalidStatus
+
+# Setup logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Load env
+from dotenv import load_dotenv
+import os
+
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+CARTESIA_API_KEY = os.getenv("CARTESIA_API_KEY")
+
+
+async def test_connection():
+    """Test Cartesia WebSocket connection."""
+    url = (
+        f"wss://api.cartesia.ai/stt/websocket?"
+        f"model={quote('ink-whisper')}"
+        f"&language={quote('en')}"
+        f"&encoding={quote('pcm_s16le')}"
+        f"&sample_rate={quote('16000')}"
+        f"&min_volume={quote('0.0')}"
+        f"&max_silence_duration_secs={quote('30.0')}"
+        f"&api_key={quote(CARTESIA_API_KEY)}"
+    )
+
+    print(f"Connecting to: {url}\n")
+
+    try:
+        async with websockets.connect(url, open_timeout=30) as ws:
+            print("✓ Connected!")
+    except InvalidStatus as e:
+        print(f"✗ Invalid Status Error")
+        print(f"  Response object: {e.response}")
+        print(
+            f"  Response dir: {[attr for attr in dir(e.response) if not attr.startswith('_')]}"
+        )
+        print(f"  Exception str: {str(e)}")
+    except Exception as e:
+        print(f"✗ Connection failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(test_connection())

audio_engine/streaming/__init__.py

@@ -0,0 +1,5 @@
+"""Streaming and WebSocket server components."""
+
+from streaming.websocket_server import WebSocketServer
+
+__all__ = ["WebSocketServer"]