reachy-mini 1.2.5rc1__py3-none-any.whl → 1.2.11__py3-none-any.whl

reachy_mini/media/audio_sounddevice.py

@@ -1,4 +1,43 @@
-"""Audio implementation using sounddevice backend."""
+"""Audio implementation using sounddevice backend.
+
+This module provides a cross-platform audio implementation using the sounddevice
+library. It supports microphone input, speaker output, and sound file playback
+across different operating systems (Windows, macOS, Linux).
+
+The sounddevice backend features:
+- Cross-platform compatibility
+- Low-latency audio processing
+- Support for multiple audio devices
+- Sound file playback (WAV, OGG, FLAC, etc.)
+- Automatic sample rate and channel conversion
+- Thread-safe audio buffer management
+
+Note:
+    This class is typically used internally by the MediaManager when the DEFAULT
+    backend is selected. Direct usage is possible but usually not necessary.
+
+Example usage via MediaManager:
+    >>> from reachy_mini.media.media_manager import MediaManager, MediaBackend
+    >>>
+    >>> # Create media manager with sounddevice backend (default)
+    >>> media = MediaManager(backend=MediaBackend.DEFAULT, log_level="INFO")
+    >>>
+    >>> # Start audio recording
+    >>> media.start_recording()
+    >>>
+    >>> # Get audio samples
+    >>> samples = media.get_audio_sample()
+    >>> if samples is not None:
+    ...     print(f"Captured {len(samples)} audio samples")
+    >>>
+    >>> # Play a sound file
+    >>> media.play_sound("/path/to/sound.wav")
+    >>>
+    >>> # Clean up
+    >>> media.stop_recording()
+    >>> media.close()
+
+"""
 
 import os
 import threading
@@ -20,13 +59,32 @@ MAX_INPUT_QUEUE_SECONDS = 60.0
 
 
 class SoundDeviceAudio(AudioBase):
-    """Audio device implementation using sounddevice."""
+    """Audio device implementation using sounddevice.
+
+    This class implements the AudioBase interface using the sounddevice library,
+    providing cross-platform audio capture and playback capabilities.
+
+    Attributes:
+        Inherits all attributes from AudioBase.
+        Additionally manages sounddevice streams and audio buffers.
+
+    """
 
     def __init__(
         self,
         log_level: str = "INFO",
     ) -> None:
-        """Initialize the SoundDevice audio device."""
+        """Initialize the SoundDevice audio device.
+
+        Args:
+            log_level (str): Logging level for audio operations.
+                          Default: 'INFO'.
+
+        Note:
+            This constructor initializes the sounddevice audio system and sets up
+            the necessary audio streams for recording and playback.
+
+        """
         super().__init__(log_level=log_level)
         self._input_stream = None
         self._output_stream = None
@@ -58,7 +116,10 @@ class SoundDeviceAudio(AudioBase):
         return self._input_stream is not None and self._input_stream.active
 
     def start_recording(self) -> None:
-        """Open the audio input stream, using ReSpeaker card if available."""
+        """Open the audio input stream, using ReSpeaker card if available.
+
+        See AudioBase.start_recording() for complete documentation.
+        """
         if self._is_recording:
             self.stop_recording()
 
@@ -109,7 +170,10 @@ class SoundDeviceAudio(AudioBase):
             self._input_queued_samples += indata.shape[0]
 
     def get_audio_sample(self) -> Optional[npt.NDArray[np.float32]]:
-        """Read audio data from the buffer. Returns numpy array or None if empty."""
+        """Read audio data from the buffer. Returns numpy array or None if empty.
+
+        See AudioBase.get_audio_sample() for complete documentation.
+        """
         with self._input_lock:
             if self._input_buffer and len(self._input_buffer) > 0:
                 data: npt.NDArray[np.float32] = np.concatenate(
@@ -122,32 +186,47 @@ class SoundDeviceAudio(AudioBase):
         return None
 
     def get_input_audio_samplerate(self) -> int:
-        """Get the input samplerate of the audio device."""
+        """Get the input samplerate of the audio device.
+
+        See AudioBase.get_input_audio_samplerate() for complete documentation.
+        """
         return int(
             sd.query_devices(self._input_device_id, "input")["default_samplerate"]
         )
 
     def get_output_audio_samplerate(self) -> int:
-        """Get the output samplerate of the audio device."""
+        """Get the output samplerate of the audio device.
+
+        See AudioBase.get_output_audio_samplerate() for complete documentation.
+        """
         return int(
             sd.query_devices(self._output_device_id, "output")["default_samplerate"]
         )
 
     def get_input_channels(self) -> int:
-        """Get the number of input channels of the audio device."""
+        """Get the number of input channels of the audio device.
+
+        See AudioBase.get_input_channels() for complete documentation.
+        """
         return min(
             int(sd.query_devices(self._input_device_id, "input")["max_input_channels"]),
             MAX_INPUT_CHANNELS,
         )
 
     def get_output_channels(self) -> int:
-        """Get the number of output channels of the audio device."""
+        """Get the number of output channels of the audio device.
+
+        See AudioBase.get_output_channels() for complete documentation.
+        """
         return int(
             sd.query_devices(self._output_device_id, "output")["max_output_channels"]
         )
 
     def stop_recording(self) -> None:
-        """Close the audio stream and release resources."""
+        """Close the audio stream and release resources.
+
+        See AudioBase.stop_recording() for complete documentation.
+        """
         if self._is_recording:
             self._input_stream.stop()  # type: ignore[attr-defined]
             self._input_stream.close()  # type: ignore[attr-defined]
@@ -155,7 +234,10 @@ class SoundDeviceAudio(AudioBase):
             self.logger.info("SoundDevice audio stream closed.")
 
     def push_audio_sample(self, data: npt.NDArray[np.float32]) -> None:
-        """Push audio data to the output device."""
+        """Push audio data to the output device.
+
+        See AudioBase.push_audio_sample() for complete documentation.
+        """
         if self._output_stream is not None:
             with self._output_lock:
                 self._output_buffer.append(data.copy())
@@ -169,8 +251,22 @@ class SoundDeviceAudio(AudioBase):
         with self._output_lock:
             self._output_buffer.clear()
 
+    def set_max_output_buffers(self, max_buffers: int) -> None:
+        """Set the maximum number of output buffers to queue in the player.
+
+        Args:
+            max_buffers (int): Maximum number of buffers to queue.
+
+        """
+        self.logger.warning(
+            "set_max_output_buffers is not implemented for SoundDeviceAudio."
+        )
+
     def start_playing(self) -> None:
-        """Open the audio output stream."""
+        """Open the audio output stream.
+
+        See AudioBase.start_playing() for complete documentation.
+        """
         self.clear_output_buffer()
 
         if self._output_stream is not None:
@@ -195,26 +291,26 @@ class SoundDeviceAudio(AudioBase):
         """Handle audio output stream callback."""
         if status:
             self.logger.warning(f"SoundDevice output status: {status}")
-        
+
         with self._output_lock:
             filled = 0
             while filled < frames and self._output_buffer:
                 chunk = self._output_buffer[0]
-                
+
                 needed = frames - filled
                 available = len(chunk)
                 take = min(needed, available)
-                
-                outdata[filled:filled + take] = chunk[:take]
+
+                outdata[filled : filled + take] = chunk[:take]
                 filled += take
-                
+
                 if take < available:
                     # Partial consumption, keep remainder
                     self._output_buffer[0] = chunk[take:]
                 else:
                     # Fully consumed this chunk
                     self._output_buffer.pop(0)
-            
+
             # Only pad with zeros if buffer is truly empty
             if filled < frames:
                 outdata[filled:] = 0
@@ -237,7 +333,10 @@ class SoundDeviceAudio(AudioBase):
         return chunk
 
     def stop_playing(self) -> None:
-        """Close the audio output stream."""
+        """Close the audio output stream.
+
+        See AudioBase.stop_playing() for complete documentation.
+        """
         if self._output_stream is not None:
             self._output_stream.stop()
             self._output_stream.close()
@@ -248,6 +347,8 @@ class SoundDeviceAudio(AudioBase):
     def play_sound(self, sound_file: str) -> None:
         """Play a sound file.
 
+        See AudioBase.play_sound() for complete documentation.
+
         Args:
             sound_file (str): Path to the sound file to play. May be given relative to the assets directory or as an absolute path.
 

reachy_mini/media/audio_utils.py

@@ -1,4 +1,22 @@
-"""Utility functions for audio handling, specifically for detecting the ReSpeaker sound card."""
+"""Utility functions for audio handling, specifically for detecting the ReSpeaker sound card.
+
+This module provides helper functions for working with the ReSpeaker microphone array
+and managing audio device configuration on Linux systems. It includes functions for
+detecting sound cards, checking configuration files, and managing ALSA configuration.
+
+Example usage:
+    >>> from reachy_mini.media.audio_utils import get_respeaker_card_number, has_reachymini_asoundrc
+    >>>
+    >>> # Get the ReSpeaker card number
+    >>> card_num = get_respeaker_card_number()
+    >>> print(f"ReSpeaker card number: {card_num}")
+    >>>
+    >>> # Check if .asoundrc is properly configured
+    >>> if has_reachymini_asoundrc():
+    ...     print("Reachy Mini audio configuration is properly set up")
+    ... else:
+    ...     print("Need to configure audio devices")
+"""
 
 import logging
 import subprocess
@@ -6,7 +24,27 @@ from pathlib import Path
 
 
 def _process_card_number_output(output: str) -> int:
-    """Process the output of 'arecord -l' to find the ReSpeaker or Reachy Mini Audio card number."""
+    """Process the output of 'arecord -l' to find the ReSpeaker or Reachy Mini Audio card number.
+
+    Args:
+        output (str): The output string from the 'arecord -l' command containing
+                     information about available audio devices.
+
+    Returns:
+        int: The card number of the detected Reachy Mini Audio or ReSpeaker device,
+             or 0 if neither is found (default sound card).
+
+    Note:
+        This function parses the output of 'arecord -l' to identify Reachy Mini
+        Audio or ReSpeaker devices. It prefers Reachy Mini Audio devices and
+        warns if only a ReSpeaker device is found (indicating firmware update needed).
+
+    Example:
+        >>> output = "card 1: ReachyMiniAudio [reachy mini audio], device 0: USB Audio [USB Audio]"
+        >>> card_num = _process_card_number_output(output)
+        >>> print(f"Detected card: {card_num}")
+
+    """
     lines = output.split("\n")
     for line in lines:
         if "reachy mini audio" in line.lower():
@@ -25,7 +63,33 @@ def _process_card_number_output(output: str) -> int:
 
 
 def get_respeaker_card_number() -> int:
-    """Return the card number of the ReSpeaker sound card, or 0 if not found."""
+    """Return the card number of the ReSpeaker sound card, or 0 if not found.
+
+    Returns:
+        int: The card number of the detected ReSpeaker/Reachy Mini Audio device.
+             Returns 0 if no specific device is found (uses default sound card),
+             or -1 if there's an error running the detection command.
+
+    Note:
+        This function runs 'arecord -l' to list available audio capture devices
+        and processes the output to find Reachy Mini Audio or ReSpeaker devices.
+        It's primarily used on Linux systems with ALSA audio configuration.
+
+        The function returns:
+        - Positive integer: Card number of detected Reachy Mini Audio device
+        - 0: No Reachy Mini Audio device found, using default sound card
+        - -1: Error occurred while trying to detect audio devices
+
+    Example:
+        >>> card_num = get_respeaker_card_number()
+        >>> if card_num > 0:
+        ...     print(f"Using Reachy Mini Audio card {card_num}")
+        ... elif card_num == 0:
+        ...     print("Using default sound card")
+        ... else:
+        ...     print("Error detecting audio devices")
+
+    """
     try:
         result = subprocess.run(
             ["arecord", "-l"], capture_output=True, text=True, check=True
@@ -40,7 +104,27 @@ def get_respeaker_card_number() -> int:
 
 
 def has_reachymini_asoundrc() -> bool:
-    """Check if ~/.asoundrc exists and contains both reachymini_audio_sink and reachymini_audio_src."""
+    """Check if ~/.asoundrc exists and contains both reachymini_audio_sink and reachymini_audio_src.
+
+    Returns:
+        bool: True if ~/.asoundrc exists and contains the required Reachy Mini
+             audio configuration entries, False otherwise.
+
+    Note:
+        This function checks for the presence of the ALSA configuration file
+        ~/.asoundrc and verifies that it contains the necessary configuration
+        entries for Reachy Mini audio devices (reachymini_audio_sink and
+        reachymini_audio_src). These entries are required for proper audio
+        routing and device management.
+
+    Example:
+        >>> if has_reachymini_asoundrc():
+        ...     print("Reachy Mini audio configuration is properly set up")
+        ... else:
+        ...     print("Need to configure Reachy Mini audio devices")
+        ...     write_asoundrc_to_home()  # Create the configuration
+
+    """
     asoundrc_path = Path.home().joinpath(".asoundrc")
     if not asoundrc_path.exists():
         return False
@@ -68,7 +152,28 @@ def check_reachymini_asoundrc() -> bool:
 
 
 def write_asoundrc_to_home() -> None:
-    """Write the .asoundrc file with Reachy Mini audio configuration to the user's home directory."""
+    """Write the .asoundrc file with Reachy Mini audio configuration to the user's home directory.
+
+    This function creates an ALSA configuration file (.asoundrc) in the user's home directory
+    that configures the ReSpeaker sound card for proper audio routing and multi-client support.
+    The configuration enables simultaneous audio input and output access, which is essential
+    for the Reachy Mini Wireless version's audio functionality.
+
+    The generated configuration includes:
+        - Default audio device settings pointing to the ReSpeaker sound card
+        - dmix plugin for multi-client audio output (reachymini_audio_sink)
+        - dsnoop plugin for multi-client audio input (reachymini_audio_src)
+        - Proper buffer and sample rate settings for optimal performance
+
+    Note:
+    This function automatically detects the ReSpeaker card number and creates a configuration
+    tailored to the detected hardware. It is primarily used for the Reachy Mini Wireless version.
+
+    The configuration file will be created at ~/.asoundrc and will overwrite any existing file
+    with the same name. Existing audio configurations should be backed up before calling this function.
+
+
+    """
     card_id = get_respeaker_card_number()
     asoundrc_content = f"""
 pcm.!default {{

reachy_mini/media/camera_base.py

@@ -1,7 +1,24 @@
 """Base classes for camera implementations.
 
 The camera implementations support various backends and provide a unified
-interface for capturing images.
+interface for capturing images. This module defines the abstract base class
+that all camera implementations should inherit from, ensuring consistent
+API across different camera backends.
+
+Available backends include:
+- OpenCV: Cross-platform camera backend using OpenCV library
+- GStreamer: GStreamer-based camera backend for advanced video processing
+- WebRTC: WebRTC-based camera for real-time video communication
+
+Example usage:
+    >>> from reachy_mini.media.camera_base import CameraBase
+    >>> class MyCamera(CameraBase):
+    ...     def open(self) -> None:
+    ...         pass
+    ...     def read(self) -> Optional[npt.NDArray[np.uint8]]:
+    ...         pass
+    ...     def close(self) -> None:
+    ...         pass
 """
 
 import logging
@@ -19,13 +36,38 @@ from reachy_mini.media.camera_constants import (
 
 
 class CameraBase(ABC):
-    """Abstract class for opening and managing a camera."""
+    """Abstract class for opening and managing a camera.
+
+    This class defines the interface that all camera implementations must follow.
+    It provides common camera parameters and methods for managing camera devices,
+    including image capture, resolution management, and camera calibration.
+
+    Attributes:
+        logger (logging.Logger): Logger instance for camera-related messages.
+        _resolution (Optional[CameraResolution]): Current camera resolution setting.
+        camera_specs (Optional[CameraSpecs]): Camera specifications including
+            supported resolutions and calibration parameters.
+        resized_K (Optional[npt.NDArray[np.float64]]): Camera intrinsic matrix
+            resized to match the current resolution.
+
+    """
 
     def __init__(
         self,
         log_level: str = "INFO",
     ) -> None:
-        """Initialize the camera."""
+        """Initialize the camera.
+
+        Args:
+            log_level (str): Logging level for camera operations.
+                          Options: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'.
+                          Default: 'INFO'.
+
+        Note:
+            This constructor initializes the logging system. Camera specifications
+            and resolution should be set before calling open().
+
+        """
         self.logger = logging.getLogger(__name__)
         self.logger.setLevel(log_level)
         self._resolution: Optional[CameraResolution] = None
@@ -34,32 +76,116 @@ class CameraBase(ABC):
 
     @property
     def resolution(self) -> tuple[int, int]:
-        """Get the current camera resolution as a tuple (width, height)."""
+        """Get the current camera resolution as a tuple (width, height).
+
+        Returns:
+            tuple[int, int]: A tuple containing (width, height) in pixels.
+
+        Raises:
+            RuntimeError: If camera resolution has not been set.
+
+        Example:
+            >>> width, height = camera.resolution
+            >>> print(f"Camera resolution: {width}x{height}")
+
+        """
         if self._resolution is None:
             raise RuntimeError("Camera resolution is not set.")
         return (self._resolution.value[0], self._resolution.value[1])
 
     @property
     def framerate(self) -> int:
-        """Get the current camera frames per second."""
+        """Get the current camera frames per second.
+
+        Returns:
+            int: The current frame rate in frames per second (fps).
+
+        Raises:
+            RuntimeError: If camera resolution has not been set.
+
+        Example:
+            >>> fps = camera.framerate
+            >>> print(f"Camera frame rate: {fps} fps")
+
+        """
         if self._resolution is None:
             raise RuntimeError("Camera resolution is not set.")
         return int(self._resolution.value[2])
 
     @property
     def K(self) -> Optional[npt.NDArray[np.float64]]:
-        """Get the camera intrinsic matrix for the current resolution."""
+        """Get the camera intrinsic matrix for the current resolution.
+
+        Returns:
+            Optional[npt.NDArray[np.float64]]: The 3x3 camera intrinsic matrix
+            in the format:
+
+            [[fx,  0, cx],
+             [ 0, fy, cy],
+             [ 0,  0,  1]]
+
+            Where fx, fy are focal lengths in pixels, and cx, cy are the
+            principal point coordinates. Returns None if not available.
+
+        Note:
+            The intrinsic matrix is automatically resized to match the current
+            camera resolution when set_resolution() is called.
+
+        Example:
+            >>> K = camera.K
+            >>> if K is not None:
+            ...     fx, fy = K[0, 0], K[1, 1]
+            ...     cx, cy = K[0, 2], K[1, 2]
+
+        """
         return self.resized_K
 
     @property
     def D(self) -> Optional[npt.NDArray[np.float64]]:
-        """Get the camera distortion coefficients."""
+        """Get the camera distortion coefficients.
+
+        Returns:
+            Optional[npt.NDArray[np.float64]]: The distortion coefficients
+            as a 5-element array [k1, k2, p1, p2, k3] representing radial
+            and tangential distortion parameters, or None if not available.
+
+        Note:
+            These coefficients can be used with OpenCV's distortion correction
+            functions to undistort captured images.
+
+        Example:
+            >>> D = camera.D
+            >>> if D is not None:
+            ...     print(f"Distortion coefficients: {D}")
+
+        """
         if self.camera_specs is not None:
             return self.camera_specs.D
         return None
 
     def set_resolution(self, resolution: CameraResolution) -> None:
-        """Set the camera resolution."""
+        """Set the camera resolution.
+
+        Args:
+            resolution (CameraResolution): The desired camera resolution from
+                the CameraResolution enum.
+
+        Raises:
+            RuntimeError: If camera specs are not set or if trying to change
+                        resolution of a Mujoco simulated camera.
+            ValueError: If the requested resolution is not supported by the camera.
+
+        Note:
+            This method updates the camera's resolution and automatically rescales
+            the camera intrinsic matrix (K) to match the new resolution. The
+            rescaling preserves the camera's field of view and principal point
+            position relative to the image dimensions.
+
+        Example:
+            >>> from reachy_mini.media.camera_constants import CameraResolution
+            >>> camera.set_resolution(CameraResolution.R1280x720at30fps)
+
+        """
         if self.camera_specs is None:
             raise RuntimeError(
                 "Camera specs not set. Open the camera before setting the resolution."
@@ -86,15 +212,60 @@ class CameraBase(ABC):
 
     @abstractmethod
     def open(self) -> None:
-        """Open the camera."""
+        """Open the camera.
+
+        This method should initialize the camera device and prepare it for
+        capturing images. After calling this method, read() should be able
+        to retrieve camera frames.
+
+        Note:
+            Implementations should handle any necessary resource allocation,
+            camera configuration, and error checking. If the camera cannot
+            be opened, implementations should log appropriate error messages.
+
+        Raises:
+            RuntimeError: If the camera cannot be opened due to hardware
+                        or configuration issues.
+
+        """
         pass
 
     @abstractmethod
     def read(self) -> Optional[npt.NDArray[np.uint8]]:
-        """Read an image from the camera. Returns the image or None if error."""
+        """Read an image from the camera. Returns the image or None if error.
+
+        Returns:
+            Optional[npt.NDArray[np.uint8]]: A numpy array containing the
+            captured image in BGR format (OpenCV convention), or None if
+            no image is available or an error occurred.
+
+            The array shape is (height, width, 3) where the last dimension
+            represents the BGR color channels.
+
+        Note:
+            This method should be called after open() has been called.
+            The image resolution can be obtained via the resolution property.
+
+        Example:
+            >>> camera.open()
+            >>> frame = camera.read()
+            >>> if frame is not None:
+            ...     cv2.imshow("Camera Frame", frame)
+            ...     cv2.waitKey(1)
+
+        """
         pass
 
     @abstractmethod
     def close(self) -> None:
-        """Close the camera and release resources."""
+        """Close the camera and release resources.
+
+        This method should stop any ongoing image capture and release
+        all associated resources. After calling this method, read() should
+        return None until open() is called again.
+
+        Note:
+            Implementations should ensure proper cleanup to prevent resource leaks.
+
+        """
         pass