orbitalsai 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

orbitalsai/streaming/audio/source.py

@@ -0,0 +1,317 @@
+"""
+OrbitalsAI Streaming Audio Sources
+
+Audio source classes for streaming from various inputs.
+"""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import AsyncIterator, Iterator, Optional
+
+from .converter import AudioConverter
+from .buffer import AudioBuffer
+
+logger = logging.getLogger("orbitalsai.streaming")
+
+
+class AudioSource(ABC):
+    """
+    Abstract base class for audio sources.
+    
+    Provides a consistent interface for streaming audio from various sources
+    (files, microphone, etc.).
+    """
+    
+    def __init__(self, sample_rate: int = 16000, chunk_size: int = 8000):
+        """
+        Initialize audio source.
+        
+        Args:
+            sample_rate: Target sample rate in Hz
+            chunk_size: Number of samples per chunk
+        """
+        self.sample_rate = sample_rate
+        self.chunk_size = chunk_size
+    
+    @abstractmethod
+    def __iter__(self) -> Iterator[bytes]:
+        """Iterate over audio chunks synchronously."""
+        pass
+    
+    @abstractmethod
+    def __aiter__(self) -> AsyncIterator[bytes]:
+        """Iterate over audio chunks asynchronously."""
+        pass
+    
+    @property
+    def chunk_duration_ms(self) -> float:
+        """Get chunk duration in milliseconds."""
+        return (self.chunk_size / self.sample_rate) * 1000
+
+
+class FileAudioSource(AudioSource):
+    """
+    Audio source that reads from a file.
+    
+    Supports various audio formats (WAV, MP3, M4A, etc.) and handles
+    conversion to PCM16 format automatically.
+    
+    Example:
+        source = FileAudioSource("speech.mp3")
+        
+        async for chunk in source:
+            await client.send_audio(chunk)
+    """
+    
+    def __init__(
+        self,
+        file_path: str,
+        sample_rate: int = 16000,
+        chunk_size: int = 8000,
+        realtime: bool = False
+    ):
+        """
+        Initialize file audio source.
+        
+        Args:
+            file_path: Path to audio file
+            sample_rate: Target sample rate in Hz
+            chunk_size: Number of samples per chunk
+            realtime: If True, yields chunks at real-time pace
+        """
+        super().__init__(sample_rate, chunk_size)
+        self.file_path = file_path
+        self.realtime = realtime
+        
+        self._audio_bytes: Optional[bytes] = None
+        self._chunks: Optional[list] = None
+    
+    def _load(self) -> None:
+        """Load and convert audio file."""
+        if self._chunks is not None:
+            return
+        
+        path = Path(self.file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Audio file not found: {self.file_path}")
+        
+        logger.debug(f"Loading audio file: {self.file_path}")
+        
+        self._audio_bytes, _ = AudioConverter.from_file(
+            self.file_path,
+            target_sample_rate=self.sample_rate
+        )
+        self._chunks = AudioConverter.split_chunks(
+            self._audio_bytes,
+            chunk_size=self.chunk_size
+        )
+        
+        logger.debug(f"Loaded {len(self._chunks)} chunks")
+    
+    def __iter__(self) -> Iterator[bytes]:
+        """Iterate over audio chunks synchronously."""
+        import time
+        
+        self._load()
+        
+        for chunk in self._chunks:
+            yield chunk
+            if self.realtime:
+                time.sleep(self.chunk_duration_ms / 1000)
+    
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        """Iterate over audio chunks asynchronously."""
+        self._load()
+        
+        for chunk in self._chunks:
+            yield chunk
+            if self.realtime:
+                await asyncio.sleep(self.chunk_duration_ms / 1000)
+    
+    @property
+    def duration_seconds(self) -> float:
+        """Get total audio duration in seconds."""
+        self._load()
+        return len(self._audio_bytes) / (self.sample_rate * 2)
+    
+    @property
+    def num_chunks(self) -> int:
+        """Get total number of chunks."""
+        self._load()
+        return len(self._chunks)
+
+
+class RawPCMFileSource(AudioSource):
+    """
+    Audio source that reads raw PCM16 file.
+    
+    For files that are already in PCM16 mono little-endian format.
+    No conversion is performed.
+    
+    Example:
+        source = RawPCMFileSource("audio.pcm", sample_rate=16000)
+        
+        for chunk in source:
+            client.send_audio(chunk)
+    """
+    
+    def __init__(
+        self,
+        file_path: str,
+        sample_rate: int = 16000,
+        chunk_size: int = 8000,
+        realtime: bool = False
+    ):
+        """
+        Initialize raw PCM file source.
+        
+        Args:
+            file_path: Path to raw PCM16 file
+            sample_rate: Sample rate of the file
+            chunk_size: Number of samples per chunk
+            realtime: If True, yields chunks at real-time pace
+        """
+        super().__init__(sample_rate, chunk_size)
+        self.file_path = file_path
+        self.realtime = realtime
+        self._bytes_per_chunk = chunk_size * 2
+    
+    def __iter__(self) -> Iterator[bytes]:
+        """Iterate over audio chunks synchronously."""
+        import time
+        
+        with open(self.file_path, "rb") as f:
+            while chunk := f.read(self._bytes_per_chunk):
+                yield chunk
+                if self.realtime:
+                    time.sleep(self.chunk_duration_ms / 1000)
+    
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        """Iterate over audio chunks asynchronously."""
+        import aiofiles
+        
+        async with aiofiles.open(self.file_path, "rb") as f:
+            while chunk := await f.read(self._bytes_per_chunk):
+                yield chunk
+                if self.realtime:
+                    await asyncio.sleep(self.chunk_duration_ms / 1000)
+
+
+class MicrophoneSource(AudioSource):
+    """
+    Audio source that captures from microphone.
+    
+    Requires: sounddevice
+    
+    Example:
+        source = MicrophoneSource(duration=30)
+        
+        async for chunk in source:
+            await client.send_audio(chunk)
+    """
+    
+    def __init__(
+        self,
+        sample_rate: int = 16000,
+        chunk_size: int = 8000,
+        device: Optional[int] = None,
+        duration: Optional[float] = None
+    ):
+        """
+        Initialize microphone source.
+        
+        Args:
+            sample_rate: Sample rate in Hz
+            chunk_size: Number of samples per chunk
+            device: Audio input device index (None for default)
+            duration: Recording duration in seconds (None for indefinite)
+        """
+        super().__init__(sample_rate, chunk_size)
+        self.device = device
+        self.duration = duration
+    
+    def __iter__(self) -> Iterator[bytes]:
+        """Iterate over audio chunks synchronously."""
+        try:
+            import sounddevice as sd
+        except ImportError:
+            raise ImportError(
+                "sounddevice is required for microphone input. "
+                "Install it with: pip install sounddevice"
+            )
+        
+        import queue
+        import time
+        
+        audio_queue = queue.Queue()
+        
+        def callback(indata, frames, time_info, status):
+            if status:
+                logger.warning(f"Audio status: {status}")
+            audio_queue.put(indata.copy())
+        
+        start_time = time.time()
+        
+        with sd.InputStream(
+            samplerate=self.sample_rate,
+            channels=1,
+            dtype="int16",
+            blocksize=self.chunk_size,
+            device=self.device,
+            callback=callback
+        ):
+            while True:
+                if self.duration and time.time() - start_time > self.duration:
+                    break
+                
+                try:
+                    audio_data = audio_queue.get(timeout=1.0)
+                    yield audio_data.tobytes()
+                except queue.Empty:
+                    continue
+    
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        """Iterate over audio chunks asynchronously."""
+        try:
+            import sounddevice as sd
+        except ImportError:
+            raise ImportError(
+                "sounddevice is required for microphone input. "
+                "Install it with: pip install sounddevice"
+            )
+        
+        import numpy as np
+        
+        audio_queue = asyncio.Queue()
+        
+        def callback(indata, frames, time_info, status):
+            if status:
+                logger.warning(f"Audio status: {status}")
+            audio_queue.put_nowait(indata.copy())
+        
+        start_time = asyncio.get_event_loop().time()
+        
+        with sd.InputStream(
+            samplerate=self.sample_rate,
+            channels=1,
+            dtype="int16",
+            blocksize=self.chunk_size,
+            device=self.device,
+            callback=callback
+        ):
+            while True:
+                if self.duration:
+                    elapsed = asyncio.get_event_loop().time() - start_time
+                    if elapsed > self.duration:
+                        break
+                
+                try:
+                    audio_data = await asyncio.wait_for(
+                        audio_queue.get(),
+                        timeout=1.0
+                    )
+                    yield audio_data.tobytes()
+                except asyncio.TimeoutError:
+                    continue

orbitalsai/streaming/client.py

@@ -0,0 +1,384 @@
+"""
+OrbitalsAI Sync Streaming Client
+
+Synchronous WebSocket client for real-time streaming transcription.
+"""
+
+import asyncio
+import logging
+import queue
+import threading
+from typing import Optional
+
+from .config import StreamingConfig
+from .events import StreamingEventHandlers
+from .async_client import AsyncStreamingClient
+from .exceptions import SessionClosedError, StreamingError
+
+logger = logging.getLogger("orbitalsai.streaming")
+
+
+class StreamingClient:
+    """
+    Synchronous WebSocket client for streaming transcription.
+    
+    Provides a thread-safe synchronous interface to the async streaming client.
+    Uses a background thread to run the async event loop.
+    
+    Example:
+        from orbitalsai.streaming import StreamingClient, PrintingEventHandlers
+        
+        with StreamingClient(api_key="your_key") as client:
+            client.connect(PrintingEventHandlers())
+            
+            with open("audio.pcm", "rb") as f:
+                while chunk := f.read(16000):
+                    client.send_audio(chunk)
+                    time.sleep(0.5)  # Real-time pacing
+            
+            client.flush()
+    
+    Example with custom handlers:
+        class MyHandlers(StreamingEventHandlers):
+            def on_transcript_final(self, text, metadata):
+                print(f"Transcription: {text}")
+        
+        client = StreamingClient(api_key="your_key")
+        client.connect(MyHandlers())
+        # ... send audio ...
+        client.disconnect()
+    """
+    
+    def __init__(
+        self,
+        api_key: str,
+        config: Optional[StreamingConfig] = None,
+        base_url: str = "wss://api.orbitalsai.com"
+    ):
+        """
+        Initialize the synchronous streaming client.
+        
+        Args:
+            api_key: OrbitalsAI API key or JWT token
+            config: Streaming configuration (optional)
+            base_url: WebSocket base URL (default: wss://api.orbitalsai.com)
+        """
+        self.api_key = api_key
+        self.config = config or StreamingConfig()
+        self.base_url = base_url
+        
+        self._async_client: Optional[AsyncStreamingClient] = None
+        self._thread: Optional[threading.Thread] = None
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._started = threading.Event()
+        self._error: Optional[Exception] = None
+    
+    @property
+    def is_connected(self) -> bool:
+        """Check if WebSocket is connected."""
+        if self._async_client:
+            return self._async_client.is_connected
+        return False
+    
+    @property
+    def session_id(self) -> Optional[str]:
+        """Get current session ID."""
+        if self._async_client:
+            return self._async_client.session_id
+        return None
+    
+    def connect(self, handlers: StreamingEventHandlers, timeout: float = 30.0) -> None:
+        """
+        Start background thread and connect.
+        
+        Args:
+            handlers: Event handlers for callbacks
+            timeout: Connection timeout in seconds
+            
+        Raises:
+            StreamingError: If connection fails
+            TimeoutError: If connection times out
+        """
+        if self._thread is not None and self._thread.is_alive():
+            raise StreamingError("Already connected")
+        
+        # Reset state
+        self._error = None
+        self._started.clear()
+        
+        # Create async client
+        self._async_client = AsyncStreamingClient(
+            api_key=self.api_key,
+            config=self.config,
+            base_url=self.base_url
+        )
+        
+        # Start background thread
+        self._thread = threading.Thread(
+            target=self._run_event_loop,
+            args=(handlers,),
+            daemon=True,
+            name="orbitalsai-streaming"
+        )
+        self._thread.start()
+        
+        # Wait for connection
+        if not self._started.wait(timeout=timeout):
+            self._cleanup()
+            raise TimeoutError("Connection timed out")
+        
+        # Check for errors during connection
+        if self._error:
+            error = self._error
+            self._error = None
+            raise error
+    
+    def _run_event_loop(self, handlers: StreamingEventHandlers) -> None:
+        """
+        Run the async event loop in background thread.
+        
+        Args:
+            handlers: Event handlers for callbacks
+        """
+        try:
+            # Create new event loop for this thread
+            self._loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self._loop)
+            
+            # Connect async client
+            try:
+                self._loop.run_until_complete(
+                    self._async_client.connect(handlers)
+                )
+                self._started.set()
+            except Exception as e:
+                self._error = e
+                self._started.set()
+                return
+            
+            # Run until disconnected
+            try:
+                self._loop.run_forever()
+            except Exception as e:
+                logger.error(f"Event loop error: {e}")
+            
+        finally:
+            # Cleanup
+            if self._loop:
+                try:
+                    self._loop.close()
+                except Exception:
+                    pass
+                self._loop = None
+    
+    def send_audio(self, audio_data: bytes, timeout: float = 10.0) -> None:
+        """
+        Send PCM16 audio chunk (thread-safe).
+        
+        Args:
+            audio_data: Raw PCM16 mono little-endian bytes
+            timeout: Operation timeout in seconds
+            
+        Raises:
+            SessionClosedError: If session is closed
+            TimeoutError: If operation times out
+        """
+        if not self.is_connected or not self._loop:
+            raise SessionClosedError("Session is not connected")
+        
+        future = asyncio.run_coroutine_threadsafe(
+            self._async_client.send_audio(audio_data),
+            self._loop
+        )
+        
+        try:
+            future.result(timeout=timeout)
+        except asyncio.TimeoutError:
+            raise TimeoutError("send_audio timed out")
+    
+    def configure(
+        self,
+        language: Optional[str] = None,
+        sample_rate: Optional[int] = None,
+        timeout: float = 10.0
+    ) -> None:
+        """
+        Update session configuration (thread-safe).
+        
+        Args:
+            language: New transcription language (optional)
+            sample_rate: New sample rate in Hz (optional)
+            timeout: Operation timeout in seconds
+            
+        Raises:
+            SessionClosedError: If session is closed
+            TimeoutError: If operation times out
+        """
+        if not self.is_connected or not self._loop:
+            raise SessionClosedError("Session is not connected")
+        
+        future = asyncio.run_coroutine_threadsafe(
+            self._async_client.configure(language=language, sample_rate=sample_rate),
+            self._loop
+        )
+        
+        try:
+            future.result(timeout=timeout)
+        except asyncio.TimeoutError:
+            raise TimeoutError("configure timed out")
+    
+    def flush(self, timeout: float = 30.0) -> None:
+        """
+        Force transcription of remaining audio buffer (thread-safe).
+        
+        Args:
+            timeout: Operation timeout in seconds
+            
+        Raises:
+            SessionClosedError: If session is closed
+            TimeoutError: If operation times out
+        """
+        if not self.is_connected or not self._loop:
+            raise SessionClosedError("Session is not connected")
+        
+        future = asyncio.run_coroutine_threadsafe(
+            self._async_client.flush(),
+            self._loop
+        )
+        
+        try:
+            future.result(timeout=timeout)
+        except asyncio.TimeoutError:
+            raise TimeoutError("flush timed out")
+    
+    def disconnect(self, timeout: float = 10.0) -> None:
+        """
+        Disconnect and cleanup thread.
+        
+        Args:
+            timeout: Timeout for graceful shutdown
+        """
+        self._cleanup(timeout=timeout)
+    
+    def _cleanup(self, timeout: float = 10.0) -> None:
+        """
+        Internal cleanup method.
+        
+        Args:
+            timeout: Timeout for graceful shutdown
+        """
+        # Disconnect async client
+        if self._async_client and self._loop:
+            try:
+                future = asyncio.run_coroutine_threadsafe(
+                    self._async_client.disconnect(),
+                    self._loop
+                )
+                future.result(timeout=timeout)
+            except Exception as e:
+                logger.debug(f"Error during disconnect: {e}")
+        
+        # Stop event loop
+        if self._loop and self._loop.is_running():
+            self._loop.call_soon_threadsafe(self._loop.stop)
+        
+        # Wait for thread to finish
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=timeout)
+        
+        # Reset state
+        self._async_client = None
+        self._thread = None
+        self._loop = None
+    
+    def __enter__(self) -> 'StreamingClient':
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit."""
+        self.disconnect()
+
+
+class StreamingTranscriptAccumulator(StreamingEventHandlers):
+    """
+    Event handlers that accumulate transcripts.
+    
+    Useful for batch processing where you want to collect all
+    final transcripts and retrieve them at the end.
+    
+    Example:
+        accumulator = StreamingTranscriptAccumulator()
+        
+        with StreamingClient(api_key="...") as client:
+            client.connect(accumulator)
+            # ... send audio ...
+            client.flush()
+        
+        print(accumulator.get_full_transcript())
+        print(f"Total cost: ${accumulator.total_cost:.4f}")
+    """
+    
+    def __init__(self):
+        """Initialize transcript accumulator."""
+        self._transcripts: list = []
+        self._total_cost: float = 0.0
+        self._total_seconds: float = 0.0
+        self._errors: list = []
+        self._lock = threading.Lock()
+    
+    def on_transcript_final(self, transcript: str, metadata: dict) -> None:
+        """Accumulate final transcript."""
+        with self._lock:
+            self._transcripts.append(transcript)
+            self._total_cost += metadata.get("cost", 0)
+            self._total_seconds += metadata.get("audio_seconds", 0)
+    
+    def on_error(self, error: Exception) -> None:
+        """Record error."""
+        with self._lock:
+            self._errors.append(error)
+    
+    def get_transcripts(self) -> list:
+        """Get list of final transcripts."""
+        with self._lock:
+            return list(self._transcripts)
+    
+    def get_full_transcript(self, separator: str = " ") -> str:
+        """
+        Get concatenated transcript.
+        
+        Args:
+            separator: String to join transcripts with
+            
+        Returns:
+            Full transcript string
+        """
+        with self._lock:
+            return separator.join(self._transcripts)
+    
+    @property
+    def total_cost(self) -> float:
+        """Get total cost in dollars."""
+        with self._lock:
+            return self._total_cost
+    
+    @property
+    def total_seconds(self) -> float:
+        """Get total audio duration in seconds."""
+        with self._lock:
+            return self._total_seconds
+    
+    @property
+    def errors(self) -> list:
+        """Get list of errors that occurred."""
+        with self._lock:
+            return list(self._errors)
+    
+    def clear(self) -> None:
+        """Clear accumulated data."""
+        with self._lock:
+            self._transcripts.clear()
+            self._total_cost = 0.0
+            self._total_seconds = 0.0
+            self._errors.clear()