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

orbitalsai/streaming/audio/converter.py

@@ -0,0 +1,327 @@
+"""
+OrbitalsAI Streaming Audio Converter
+
+Audio format conversion utilities for streaming.
+"""
+
+import logging
+from pathlib import Path
+from typing import List, Optional, Tuple, Union
+
+logger = logging.getLogger("orbitalsai.streaming")
+
+# Lazy imports for optional dependencies
+_numpy = None
+_librosa = None
+_soundfile = None
+
+
+def _get_numpy():
+    """Lazy import numpy."""
+    global _numpy
+    if _numpy is None:
+        try:
+            import numpy as np
+            _numpy = np
+        except ImportError:
+            raise ImportError(
+                "numpy is required for audio conversion. "
+                "Install it with: pip install numpy"
+            )
+    return _numpy
+
+
+def _get_librosa():
+    """Lazy import librosa."""
+    global _librosa
+    if _librosa is None:
+        try:
+            import librosa
+            _librosa = librosa
+        except ImportError:
+            raise ImportError(
+                "librosa is required for audio file loading. "
+                "Install it with: pip install librosa"
+            )
+    return _librosa
+
+
+def _get_soundfile():
+    """Lazy import soundfile."""
+    global _soundfile
+    if _soundfile is None:
+        try:
+            import soundfile as sf
+            _soundfile = sf
+        except ImportError:
+            raise ImportError(
+                "soundfile is required for audio file loading. "
+                "Install it with: pip install soundfile"
+            )
+    return _soundfile
+
+
+class AudioConverter:
+    """
+    Convert various audio formats to PCM16.
+    
+    Provides utilities for loading audio files, converting numpy arrays,
+    and splitting audio into chunks for streaming.
+    
+    Example:
+        # Load and convert an audio file
+        audio_bytes, sample_rate = AudioConverter.from_file("speech.mp3")
+        
+        # Split into chunks for streaming
+        chunks = AudioConverter.split_chunks(audio_bytes, chunk_size=16000)
+        for chunk in chunks:
+            await client.send_audio(chunk)
+    """
+    
+    @staticmethod
+    def from_file(
+        file_path: str,
+        target_sample_rate: int = 16000
+    ) -> Tuple[bytes, int]:
+        """
+        Load audio file and convert to PCM16.
+        
+        Supports: WAV, MP3, M4A, FLAC, OGG, etc.
+        Uses librosa for decoding and resampling.
+        
+        Args:
+            file_path: Path to audio file
+            target_sample_rate: Target sample rate in Hz (default: 16000)
+            
+        Returns:
+            Tuple of (PCM16 bytes, actual sample rate used)
+            
+        Raises:
+            ImportError: If required libraries not installed
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file format is unsupported
+        """
+        librosa = _get_librosa()
+        np = _get_numpy()
+        
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Audio file not found: {file_path}")
+        
+        logger.debug(f"Loading audio file: {file_path}")
+        
+        # Load audio with librosa (handles resampling automatically)
+        try:
+            audio, sr = librosa.load(
+                file_path,
+                sr=target_sample_rate,
+                mono=True
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to load audio file: {e}")
+        
+        # Convert float32 [-1, 1] to int16 bytes
+        audio_bytes = AudioConverter._float32_to_pcm16_bytes(audio)
+        
+        logger.debug(
+            f"Loaded {len(audio_bytes)} bytes "
+            f"({len(audio_bytes) / (target_sample_rate * 2):.2f}s) "
+            f"at {target_sample_rate}Hz"
+        )
+        
+        return audio_bytes, target_sample_rate
+    
+    @staticmethod
+    def from_wav_file(
+        file_path: str,
+        target_sample_rate: int = 16000
+    ) -> Tuple[bytes, int]:
+        """
+        Load WAV file using soundfile (faster than librosa for WAV).
+        
+        Args:
+            file_path: Path to WAV file
+            target_sample_rate: Target sample rate in Hz (default: 16000)
+            
+        Returns:
+            Tuple of (PCM16 bytes, actual sample rate used)
+        """
+        sf = _get_soundfile()
+        librosa = _get_librosa()
+        np = _get_numpy()
+        
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Audio file not found: {file_path}")
+        
+        # Read audio file
+        audio, sr = sf.read(file_path)
+        
+        # Convert to mono if stereo
+        if len(audio.shape) > 1:
+            audio = audio.mean(axis=1)
+        
+        # Resample if needed
+        if sr != target_sample_rate:
+            audio = librosa.resample(audio, orig_sr=sr, target_sr=target_sample_rate)
+        
+        # Ensure float32 type
+        audio = audio.astype(np.float32)
+        
+        # Convert to PCM16 bytes
+        audio_bytes = AudioConverter._float32_to_pcm16_bytes(audio)
+        
+        return audio_bytes, target_sample_rate
+    
+    @staticmethod
+    def from_numpy(
+        audio: 'np.ndarray',
+        source_sample_rate: int,
+        target_sample_rate: int = 16000
+    ) -> bytes:
+        """
+        Convert numpy array to PCM16 bytes.
+        
+        Args:
+            audio: Numpy array of audio samples (float32 [-1, 1] or int16)
+            source_sample_rate: Sample rate of input audio
+            target_sample_rate: Target sample rate in Hz (default: 16000)
+            
+        Returns:
+            PCM16 bytes (mono, little-endian)
+        """
+        np = _get_numpy()
+        librosa = _get_librosa()
+        
+        # Handle different input types
+        if audio.dtype == np.int16:
+            audio = audio.astype(np.float32) / 32768.0
+        elif audio.dtype != np.float32:
+            audio = audio.astype(np.float32)
+        
+        # Normalize to [-1, 1] if needed
+        max_val = np.abs(audio).max()
+        if max_val > 1.0:
+            audio = audio / max_val
+        
+        # Convert to mono if stereo
+        if len(audio.shape) > 1:
+            audio = audio.mean(axis=1)
+        
+        # Resample if needed
+        if source_sample_rate != target_sample_rate:
+            audio = librosa.resample(
+                audio, 
+                orig_sr=source_sample_rate, 
+                target_sr=target_sample_rate
+            )
+        
+        return AudioConverter._float32_to_pcm16_bytes(audio)
+    
+    @staticmethod
+    def split_chunks(audio_bytes: bytes, chunk_size: int) -> List[bytes]:
+        """
+        Split audio bytes into chunks.
+        
+        Args:
+            audio_bytes: PCM16 bytes to split
+            chunk_size: Number of samples per chunk
+            
+        Returns:
+            List of chunk bytes (last chunk may be smaller)
+        """
+        bytes_per_chunk = chunk_size * 2  # 2 bytes per int16 sample
+        
+        chunks = []
+        for i in range(0, len(audio_bytes), bytes_per_chunk):
+            chunk = audio_bytes[i:i + bytes_per_chunk]
+            chunks.append(chunk)
+        
+        return chunks
+    
+    @staticmethod
+    def _float32_to_pcm16_bytes(audio: 'np.ndarray') -> bytes:
+        """
+        Convert float32 audio to PCM16 bytes.
+        
+        Args:
+            audio: Float32 numpy array in range [-1, 1]
+            
+        Returns:
+            PCM16 bytes (little-endian)
+        """
+        np = _get_numpy()
+        
+        # Clip to [-1, 1] to prevent overflow
+        audio = np.clip(audio, -1.0, 1.0)
+        
+        # Convert to int16
+        audio_int16 = (audio * 32767).astype(np.int16)
+        
+        # Convert to bytes (little-endian)
+        return audio_int16.tobytes()
+    
+    @staticmethod
+    def _int16_to_float32(audio: 'np.ndarray') -> 'np.ndarray':
+        """
+        Convert int16 audio to float32.
+        
+        Args:
+            audio: Int16 numpy array
+            
+        Returns:
+            Float32 numpy array in range [-1, 1]
+        """
+        np = _get_numpy()
+        return audio.astype(np.float32) / 32768.0
+    
+    @staticmethod
+    def pcm16_bytes_to_float32(audio_bytes: bytes) -> 'np.ndarray':
+        """
+        Convert PCM16 bytes to float32 numpy array.
+        
+        Args:
+            audio_bytes: PCM16 bytes (little-endian)
+            
+        Returns:
+            Float32 numpy array in range [-1, 1]
+        """
+        np = _get_numpy()
+        audio_int16 = np.frombuffer(audio_bytes, dtype='<i2')
+        return audio_int16.astype(np.float32) / 32768.0
+    
+    @staticmethod
+    def get_duration_seconds(audio_bytes: bytes, sample_rate: int = 16000) -> float:
+        """
+        Calculate duration of PCM16 audio in seconds.
+        
+        Args:
+            audio_bytes: PCM16 bytes
+            sample_rate: Sample rate in Hz
+            
+        Returns:
+            Duration in seconds
+        """
+        num_samples = len(audio_bytes) // 2
+        return num_samples / sample_rate
+    
+    @staticmethod
+    def validate_pcm16(audio_bytes: bytes) -> bool:
+        """
+        Validate that audio bytes are valid PCM16 format.
+        
+        Args:
+            audio_bytes: Bytes to validate
+            
+        Returns:
+            True if valid PCM16, False otherwise
+        """
+        # PCM16 must have even length (2 bytes per sample)
+        if len(audio_bytes) % 2 != 0:
+            return False
+        
+        # Must have at least some data
+        if len(audio_bytes) == 0:
+            return False
+        
+        return True

orbitalsai/streaming/audio/formats.py

@@ -0,0 +1,112 @@
+"""
+OrbitalsAI Streaming Audio Formats
+
+Audio format definitions and utilities.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AudioFormat:
+    """
+    Audio format specification.
+    
+    Attributes:
+        encoding: Audio encoding (e.g., "pcm_s16le")
+        sample_rate: Sample rate in Hz
+        channels: Number of audio channels
+        sample_width: Bytes per sample
+        byte_order: Byte order ("little" or "big")
+    """
+    encoding: str
+    sample_rate: int
+    channels: int
+    sample_width: int
+    byte_order: str = "little"
+    
+    @property
+    def bytes_per_second(self) -> int:
+        """Calculate bytes per second for this format."""
+        return self.sample_rate * self.channels * self.sample_width
+    
+    @property
+    def frame_size(self) -> int:
+        """Calculate bytes per frame (all channels)."""
+        return self.channels * self.sample_width
+
+
+# Standard PCM16 mono format used by the streaming API
+PCM16_MONO = AudioFormat(
+    encoding="pcm_s16le",
+    sample_rate=16000,
+    channels=1,
+    sample_width=2,
+    byte_order="little"
+)
+
+
+# Supported audio file extensions
+SUPPORTED_AUDIO_EXTENSIONS = {
+    ".wav", ".wave",
+    ".mp3",
+    ".m4a", ".aac",
+    ".ogg", ".oga", ".opus",
+    ".flac",
+    ".wma",
+    ".amr",
+    ".3gp", ".3gpp",
+    ".webm",
+}
+
+
+def get_format_for_file(file_path: str) -> Optional[str]:
+    """
+    Determine audio format from file extension.
+    
+    Args:
+        file_path: Path to audio file
+        
+    Returns:
+        Format string (e.g., "wav", "mp3") or None if unsupported
+    """
+    ext = Path(file_path).suffix.lower()
+    
+    if ext in (".wav", ".wave"):
+        return "wav"
+    elif ext == ".mp3":
+        return "mp3"
+    elif ext in (".m4a", ".aac"):
+        return "m4a"
+    elif ext in (".ogg", ".oga"):
+        return "ogg"
+    elif ext == ".opus":
+        return "opus"
+    elif ext == ".flac":
+        return "flac"
+    elif ext == ".wma":
+        return "wma"
+    elif ext == ".amr":
+        return "amr"
+    elif ext in (".3gp", ".3gpp"):
+        return "3gp"
+    elif ext == ".webm":
+        return "webm"
+    
+    return None
+
+
+def is_supported_audio_file(file_path: str) -> bool:
+    """
+    Check if file is a supported audio format.
+    
+    Args:
+        file_path: Path to audio file
+        
+    Returns:
+        True if supported, False otherwise
+    """
+    ext = Path(file_path).suffix.lower()
+    return ext in SUPPORTED_AUDIO_EXTENSIONS