dv-pipecat-ai 0.0.74.dev770__py3-none-any.whl → 0.0.82.dev776__py3-none-any.whl

pipecat/audio/vad/silero.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Silero Voice Activity Detection (VAD) implementation for Pipecat.
+
+This module provides a VAD analyzer based on the Silero VAD ONNX model,
+which can detect voice activity in audio streams with high accuracy.
+Supports 8kHz and 16kHz sample rates.
+"""
+
 import time
 from typing import Optional
 
@@ -25,11 +32,20 @@ except ModuleNotFoundError as e:
 
 
 class SileroOnnxModel:
-    def __init__(self, path, force_onnx_cpu=True):
-        import numpy as np
+    """ONNX runtime wrapper for the Silero VAD model.
 
-        global np
+    Provides voice activity detection using the pre-trained Silero VAD model
+    with ONNX runtime for efficient inference. Handles model state management
+    and input validation for audio processing.
+    """
 
+    def __init__(self, path, force_onnx_cpu=True):
+        """Initialize the Silero ONNX model.
+
+        Args:
+            path: Path to the ONNX model file.
+            force_onnx_cpu: Whether to force CPU execution provider.
+        """
         opts = onnxruntime.SessionOptions()
         opts.inter_op_num_threads = 1
         opts.intra_op_num_threads = 1
@@ -45,6 +61,7 @@ class SileroOnnxModel:
         self.sample_rates = [8000, 16000]
 
     def _validate_input(self, x, sr: int):
+        """Validate and preprocess input audio data."""
         if np.ndim(x) == 1:
             x = np.expand_dims(x, 0)
         if np.ndim(x) > 2:
@@ -60,12 +77,18 @@ class SileroOnnxModel:
         return x, sr
 
     def reset_states(self, batch_size=1):
+        """Reset the internal model states.
+
+        Args:
+            batch_size: Batch size for state initialization. Defaults to 1.
+        """
         self._state = np.zeros((2, batch_size, 128), dtype="float32")
         self._context = np.zeros((batch_size, 0), dtype="float32")
         self._last_sr = 0
         self._last_batch_size = 0
 
     def __call__(self, x, sr: int):
+        """Process audio input through the VAD model."""
         x, sr = self._validate_input(x, sr)
         num_samples = 512 if sr == 16000 else 256
 
@@ -105,7 +128,20 @@ class SileroOnnxModel:
 
 
 class SileroVADAnalyzer(VADAnalyzer):
+    """Voice Activity Detection analyzer using the Silero VAD model.
+
+    Implements VAD analysis using the pre-trained Silero ONNX model for
+    accurate voice activity detection. Supports 8kHz and 16kHz sample rates
+    with automatic model state management and periodic resets.
+    """
+
     def __init__(self, *, sample_rate: Optional[int] = None, params: Optional[VADParams] = None):
+        """Initialize the Silero VAD analyzer.
+
+        Args:
+            sample_rate: Audio sample rate (8000 or 16000 Hz). If None, will be set later.
+            params: VAD parameters for detection thresholds and timing.
+        """
         super().__init__(sample_rate=sample_rate, params=params)
 
         logger.debug("Loading Silero VAD model...")
@@ -137,6 +173,14 @@ class SileroVADAnalyzer(VADAnalyzer):
     #
 
     def set_sample_rate(self, sample_rate: int):
+        """Set the sample rate for audio processing.
+
+        Args:
+            sample_rate: Audio sample rate (must be 8000 or 16000 Hz).
+
+        Raises:
+            ValueError: If sample rate is not 8000 or 16000 Hz.
+        """
         if sample_rate != 16000 and sample_rate != 8000:
             raise ValueError(
                 f"Silero VAD sample rate needs to be 16000 or 8000 (sample rate: {sample_rate})"
@@ -145,9 +189,22 @@ class SileroVADAnalyzer(VADAnalyzer):
         super().set_sample_rate(sample_rate)
 
     def num_frames_required(self) -> int:
+        """Get the number of audio frames required for VAD analysis.
+
+        Returns:
+            Number of frames required (512 for 16kHz, 256 for 8kHz).
+        """
         return 512 if self.sample_rate == 16000 else 256
 
     def voice_confidence(self, buffer) -> float:
+        """Calculate voice activity confidence for the given audio buffer.
+
+        Args:
+            buffer: Audio buffer to analyze.
+
+        Returns:
+            Voice confidence score between 0.0 and 1.0.
+        """
         try:
             audio_int16 = np.frombuffer(buffer, np.int16)
             # Divide by 32768 because we have signed 16-bit data.

pipecat/audio/vad/vad_analyzer.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Voice Activity Detection (VAD) analyzer base classes and utilities.
+
+This module provides the abstract base class for VAD analyzers and associated
+data structures for voice activity detection in audio streams. Includes state
+management, parameter configuration, and audio analysis framework.
+"""
+
 from abc import ABC, abstractmethod
 from enum import Enum
 from typing import Optional
@@ -21,6 +28,15 @@ Logger = type(logger)
 
 
 class VADState(Enum):
+    """Voice Activity Detection states.
+
+    Parameters:
+        QUIET: No voice activity detected.
+        STARTING: Voice activity beginning, transitioning from quiet.
+        SPEAKING: Active voice detected and confirmed.
+        STOPPING: Voice activity ending, transitioning to quiet.
+    """
+
     QUIET = 1
     STARTING = 2
     SPEAKING = 3
@@ -28,6 +44,15 @@ class VADState(Enum):
 
 
 class VADParams(BaseModel):
+    """Configuration parameters for Voice Activity Detection.
+
+    Parameters:
+        confidence: Minimum confidence threshold for voice detection.
+        start_secs: Duration to wait before confirming voice start.
+        stop_secs: Duration to wait before confirming voice stop.
+        min_volume: Minimum audio volume threshold for voice detection.
+    """
+
     confidence: float = VAD_CONFIDENCE
     start_secs: float = VAD_START_SECS
     stop_secs: float = VAD_STOP_SECS
@@ -35,7 +60,20 @@ class VADParams(BaseModel):
 
 
 class VADAnalyzer(ABC):
+    """Abstract base class for Voice Activity Detection analyzers.
+
+    Provides the framework for implementing VAD analysis with configurable
+    parameters, state management, and audio processing capabilities.
+    Subclasses must implement the core voice confidence calculation.
+    """
+
     def __init__(self, *, sample_rate: Optional[int] = None, params: Optional[VADParams] = None):
+        """Initialize the VAD analyzer.
+
+        Args:
+            sample_rate: Audio sample rate in Hz. If None, will be set later.
+            params: VAD parameters for detection configuration.
+        """
         self._init_sample_rate = sample_rate
         self._sample_rate = 0
         self._params = params or VADParams()
@@ -49,25 +87,58 @@ class VADAnalyzer(ABC):
 
     @property
     def sample_rate(self) -> int:
+        """Get the current sample rate.
+
+        Returns:
+            Current audio sample rate in Hz.
+        """
         return self._sample_rate
 
     @property
     def num_channels(self) -> int:
+        """Get the number of audio channels.
+
+        Returns:
+            Number of audio channels (always 1 for mono).
+        """
         return self._num_channels
 
     @property
     def params(self) -> VADParams:
+        """Get the current VAD parameters.
+
+        Returns:
+            Current VAD configuration parameters.
+        """
         return self._params
 
     @abstractmethod
     def num_frames_required(self) -> int:
+        """Get the number of audio frames required for analysis.
+
+        Returns:
+            Number of frames needed for VAD processing.
+        """
         pass
 
     @abstractmethod
     def voice_confidence(self, buffer) -> float:
+        """Calculate voice activity confidence for the given audio buffer.
+
+        Args:
+            buffer: Audio buffer to analyze.
+
+        Returns:
+            Voice confidence score between 0.0 and 1.0.
+        """
         pass
 
     def set_sample_rate(self, sample_rate: int):
+        """Set the sample rate for audio processing.
+
+        Args:
+            sample_rate: Audio sample rate in Hz.
+        """
         self._sample_rate = self._init_sample_rate or sample_rate
         self.set_params(self._params)
 
@@ -86,46 +157,59 @@ class VADAnalyzer(ABC):
         self._vad_state: VADState = VADState.QUIET
 
     def _get_smoothed_volume(self, audio: bytes) -> float:
+        """Calculate smoothed audio volume using exponential smoothing."""
         volume = calculate_audio_volume(audio, self.sample_rate)
         return exp_smoothing(volume, self._prev_volume, self._smoothing_factor)
 
     def analyze_audio(self, buffer) -> VADState:
+        """Analyze audio buffer and return current VAD state.
+
+        Processes incoming audio data, maintains internal state, and determines
+        voice activity status based on confidence and volume thresholds.
+
+        Args:
+            buffer: Audio buffer to analyze.
+
+        Returns:
+            Current VAD state after processing the buffer.
+        """
         self._vad_buffer += buffer
 
         num_required_bytes = self._vad_frames_num_bytes
         if len(self._vad_buffer) < num_required_bytes:
             return self._vad_state
 
-        audio_frames = self._vad_buffer[:num_required_bytes]
-        self._vad_buffer = self._vad_buffer[num_required_bytes:]
-
-        confidence = self.voice_confidence(audio_frames)
-
-        volume = self._get_smoothed_volume(audio_frames)
-        self._prev_volume = volume
-
-        speaking = confidence >= self._params.confidence and volume >= self._params.min_volume
-
-        if speaking:
-            match self._vad_state:
-                case VADState.QUIET:
-                    self._vad_state = VADState.STARTING
-                    self._vad_starting_count = 1
-                case VADState.STARTING:
-                    self._vad_starting_count += 1
-                case VADState.STOPPING:
-                    self._vad_state = VADState.SPEAKING
-                    self._vad_stopping_count = 0
-        else:
-            match self._vad_state:
-                case VADState.STARTING:
-                    self._vad_state = VADState.QUIET
-                    self._vad_starting_count = 0
-                case VADState.SPEAKING:
-                    self._vad_state = VADState.STOPPING
-                    self._vad_stopping_count = 1
-                case VADState.STOPPING:
-                    self._vad_stopping_count += 1
+        while len(self._vad_buffer) >= num_required_bytes:
+            audio_frames = self._vad_buffer[:num_required_bytes]
+            self._vad_buffer = self._vad_buffer[num_required_bytes:]
+
+            confidence = self.voice_confidence(audio_frames)
+
+            volume = self._get_smoothed_volume(audio_frames)
+            self._prev_volume = volume
+
+            speaking = confidence >= self._params.confidence and volume >= self._params.min_volume
+
+            if speaking:
+                match self._vad_state:
+                    case VADState.QUIET:
+                        self._vad_state = VADState.STARTING
+                        self._vad_starting_count = 1
+                    case VADState.STARTING:
+                        self._vad_starting_count += 1
+                    case VADState.STOPPING:
+                        self._vad_state = VADState.SPEAKING
+                        self._vad_stopping_count = 0
+            else:
+                match self._vad_state:
+                    case VADState.STARTING:
+                        self._vad_state = VADState.QUIET
+                        self._vad_starting_count = 0
+                    case VADState.SPEAKING:
+                        self._vad_state = VADState.STOPPING
+                        self._vad_stopping_count = 1
+                    case VADState.STOPPING:
+                        self._vad_stopping_count += 1
 
         if (
             self._vad_state == VADState.STARTING

pipecat/clocks/base_clock.py

@@ -4,14 +4,33 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Base clock interface for Pipecat timing operations."""
+
 from abc import ABC, abstractmethod
 
 
 class BaseClock(ABC):
+    """Abstract base class for clock implementations.
+
+    Provides a common interface for timing operations used in Pipecat
+    for synchronization, scheduling, and time-based processing.
+    """
+
     @abstractmethod
     def get_time(self) -> int:
+        """Get the current time value.
+
+        Returns:
+            The current time as an integer value. The specific unit and
+            reference point depend on the concrete implementation.
+        """
         pass
 
     @abstractmethod
     def start(self):
+        """Start or initialize the clock.
+
+        Performs any necessary initialization or starts the timing mechanism.
+        This method should be called before using get_time().
+        """
         pass

pipecat/clocks/system_clock.py

@@ -4,17 +4,42 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""System clock implementation for Pipecat."""
+
 import time
 
 from pipecat.clocks.base_clock import BaseClock
 
 
 class SystemClock(BaseClock):
+    """A monotonic clock implementation using system time.
+
+    Provides high-precision timing using the system's monotonic clock,
+    which is not affected by system clock adjustments and is suitable
+    for measuring elapsed time in real-time applications.
+    """
+
     def __init__(self):
+        """Initialize the system clock.
+
+        The clock starts in an uninitialized state and must be started
+        explicitly using the start() method before time measurement begins.
+        """
         self._time = 0
 
     def get_time(self) -> int:
+        """Get the elapsed time since the clock was started.
+
+        Returns:
+            The elapsed time in nanoseconds since start() was called.
+            Returns 0 if the clock has not been started yet.
+        """
         return time.monotonic_ns() - self._time if self._time > 0 else 0
 
     def start(self):
+        """Start the clock and begin time measurement.
+
+        Records the current monotonic time as the reference point
+        for all subsequent get_time() calls.
+        """
         self._time = time.monotonic_ns()