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

reachy_mini/media/audio_base.py

@@ -1,7 +1,15 @@
 """Base classes for audio implementations.
 
 The audio implementations support various backends and provide a unified
-interface for audio input/output.
+interface for audio input/output. This module defines the abstract base class
+that all audio implementations should inherit from, ensuring consistent
+API across different audio backends.
+
+Available backends include:
+- SoundDevice: Cross-platform audio backend using sounddevice library
+- GStreamer: GStreamer-based audio backend for advanced audio processing
+- WebRTC: WebRTC-based audio for real-time communication
+
 """
 
 import logging
@@ -15,13 +23,36 @@ from reachy_mini.media.audio_control_utils import ReSpeaker, init_respeaker_usb
 
 
 class AudioBase(ABC):
-    """Abstract class for opening and managing audio devices."""
+    """Abstract class for opening and managing audio devices.
+
+    This class defines the interface that all audio implementations must follow.
+    It provides common audio parameters and methods for managing audio devices,
+    including microphone input and speaker output functionality.
+
+    Attributes:
+        SAMPLE_RATE (int): Default sample rate for audio operations (16000 Hz).
+        CHANNELS (int): Default number of audio channels (2 for stereo).
+        logger (logging.Logger): Logger instance for audio-related messages.
+        _respeaker (Optional[ReSpeaker]): ReSpeaker microphone array device handler.
+
+    """
 
     SAMPLE_RATE = 16000  # respeaker samplerate
     CHANNELS = 2  # respeaker channels
 
     def __init__(self, log_level: str = "INFO") -> None:
-        """Initialize the audio device."""
+        """Initialize the audio device.
+
+        Args:
+            log_level (str): Logging level for audio operations.
+                          Options: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'.
+                          Default: 'INFO'.
+
+        Note:
+            This constructor initializes the logging system and attempts to detect
+            and initialize the ReSpeaker microphone array if available.
+
+        """
         self.logger = logging.getLogger(__name__)
         self.logger.setLevel(log_level)
         self._respeaker: Optional[ReSpeaker] = init_respeaker_usb()
@@ -33,48 +64,179 @@ class AudioBase(ABC):
 
     @abstractmethod
     def start_recording(self) -> None:
-        """Start recording audio."""
+        """Start recording audio.
+
+        This method should initialize the audio recording system and prepare
+        it to capture audio data. After calling this method, get_audio_sample()
+        should be able to retrieve recorded audio data.
+
+        Note:
+            Implementations should handle any necessary resource allocation and
+            error checking. If recording cannot be started, implementations should
+            log appropriate error messages.
+
+        Raises:
+            RuntimeError: If audio recording cannot be started due to hardware
+                        or configuration issues.
+
+        """
         pass
 
     @abstractmethod
     def get_audio_sample(self) -> Optional[npt.NDArray[np.float32]]:
-        """Read audio data from the device. Returns the data or None if error."""
+        """Read audio data from the device. Returns the data or None if error.
+
+        Returns:
+            Optional[npt.NDArray[np.float32]]: A numpy array containing audio samples
+            in float32 format, or None if no data is available or an error occurred.
+
+            The array shape is typically (num_samples,) for mono or
+            (num_samples, num_channels) for multi-channel audio.
+
+        Note:
+            This method should be called after start_recording() has been called.
+            The sample rate and number of channels can be obtained via
+            get_input_audio_samplerate() and get_input_channels() respectively.
+
+        Example:
+            >>> audio.start_recording()
+            >>> samples = audio.get_audio_sample()
+            >>> if samples is not None:
+            ...     print(f"Got {len(samples)} audio samples")
+
+        """
         pass
 
     def get_input_audio_samplerate(self) -> int:
-        """Get the input samplerate of the audio device."""
+        """Get the input samplerate of the audio device.
+
+        Returns:
+            int: The sample rate in Hz at which audio is being captured.
+                Default is 16000 Hz.
+
+        Note:
+            This value represents the number of audio samples captured per second
+            for each channel.
+
+        """
         return self.SAMPLE_RATE
 
     def get_output_audio_samplerate(self) -> int:
-        """Get the outputsamplerate of the audio device."""
+        """Get the output samplerate of the audio device.
+
+        Returns:
+            int: The sample rate in Hz at which audio is being played back.
+                Default is 16000 Hz.
+
+        Note:
+            This value represents the number of audio samples played per second
+            for each channel.
+
+        """
         return self.SAMPLE_RATE
 
     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.
+
+        Returns:
+            int: The number of audio input channels (e.g., 1 for mono, 2 for stereo).
+                Default is 2 channels.
+
+        Note:
+            For the ReSpeaker microphone array, this typically returns 2 channels
+            representing the stereo microphone configuration.
+
+        """
         return self.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.
+
+        Returns:
+            int: The number of audio output channels (e.g., 1 for mono, 2 for stereo).
+                Default is 2 channels.
+
+        Note:
+            This determines how audio data should be formatted when passed to
+            push_audio_sample() method.
+
+        """
         return self.CHANNELS
 
     @abstractmethod
     def stop_recording(self) -> None:
-        """Close the audio device and release resources."""
+        """Close the audio device and release resources.
+
+        This method should stop any ongoing audio recording and release
+        all associated resources. After calling this method, get_audio_sample()
+        should return None until start_recording() is called again.
+
+        Note:
+            Implementations should ensure proper cleanup to prevent resource leaks.
+
+        """
         pass
 
     @abstractmethod
     def start_playing(self) -> None:
-        """Start playing audio."""
+        """Start playing audio.
+
+        This method should initialize the audio playback system and prepare
+        it to receive audio data via push_audio_sample().
+
+        Note:
+            Implementations should handle any necessary resource allocation and
+            error checking. If playback cannot be started, implementations should
+            log appropriate error messages.
+
+        Raises:
+            RuntimeError: If audio playback cannot be started due to hardware
+                        or configuration issues.
+
+        """
+        pass
+
+    @abstractmethod
+    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.
+
+        """
         pass
 
     @abstractmethod
     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.
+
+        Args:
+            data (npt.NDArray[np.float32]): Audio samples to be played.
+                The array should contain float32 values typically in the range [-1.0, 1.0].
+
+                For mono audio: shape should be (num_samples,)
+                For stereo audio: shape should be (num_samples, 2)
+
+        Note:
+            This method should be called after start_playing() has been called.
+            The audio data will be played at the sample rate returned by
+            get_output_audio_samplerate().
+
+        """
         pass
 
     @abstractmethod
     def stop_playing(self) -> None:
-        """Stop playing audio and release resources."""
+        """Stop playing audio and release resources.
+
+        This method should stop any ongoing audio playback and release
+        all associated resources. After calling this method, push_audio_sample()
+        calls will have no effect until start_playing() is called again.
+
+        Note:
+            Implementations should ensure proper cleanup to prevent resource leaks.
+
+        """
         pass
 
     @abstractmethod
@@ -83,6 +245,16 @@ class AudioBase(ABC):
 
         Args:
             sound_file (str): Path to the sound file to play.
+                Supported formats depend on the specific implementation.
+
+        Note:
+            This is a convenience method that handles the complete playback
+            of a sound file from start to finish. For more control over
+            audio playback, use start_playing(), push_audio_sample(),
+            and stop_playing() methods.
+
+        Example:
+            >>> audio.play_sound("/path/to/sound.wav")
 
         """
         pass

reachy_mini/media/audio_control_utils.py

@@ -1,15 +1,15 @@
-"""Allows tuning of the XMOS XVF3800 chip.
+"""Allows tuning of the XMOS XVF3800 chip integrated in the Reachy Mini Audio card.
 
 Example usage:
 
     # Read a parameter
-    python reachy_host.py AUDIO_MGR_OP_L
+    python audio_control_utils.py AUDIO_MGR_OP_L
     # Output:
     # ReadCMD: cmdid: 143, resid: 35, response: array('B', [0, 8, 0])
     # AUDIO_MGR_OP_L: [0, 8, 0]
 
     # Write a parameter
-    python reachy_host.py AUDIO_MGR_OP_L --values 3 0
+    python audio_control_utils.py AUDIO_MGR_OP_L --values 3 0
     # Output:
     # Writing to AUDIO_MGR_OP_L with values: [3, 0]
     # WriteCMD: cmdid: 15, resid: 35, payload: [3, 0]
@@ -320,7 +320,34 @@ class ReSpeaker:
 
 
 def find(vid: int = 0x2886, pid: int = 0x001A) -> ReSpeaker | None:
-    """Find and return the ReSpeaker USB device with the given Vendor ID and Product ID."""
+    """Find and return the ReSpeaker USB device with the given Vendor ID and Product ID.
+
+    Args:
+        vid (int): USB Vendor ID to search for. Default: 0x2886 (XMOS).
+        pid (int): USB Product ID to search for. Default: 0x001A (XMOS XVF3800).
+
+    Returns:
+        ReSpeaker | None: A ReSpeaker object if the device is found,
+                         None otherwise.
+
+    Note:
+        This function searches for USB devices with the specified Vendor ID
+        and Product ID using libusb backend. The default values target
+        XMOS XVF3800 devices used in ReSpeaker microphone arrays.
+
+    Example:
+        >>> from reachy_mini.media.audio_control_utils import find
+        >>>
+        >>> # Find default ReSpeaker device
+        >>> respeaker = find()
+        >>> if respeaker is not None:
+        ...     print("Found ReSpeaker device")
+        ...     respeaker.close()
+        >>>
+        >>> # Find specific device
+        >>> custom_device = find(vid=0x1234, pid=0x5678)
+
+    """
     dev = usb.core.find(idVendor=vid, idProduct=pid, backend=get_libusb1_backend())
     if not dev:
         return None
@@ -329,7 +356,35 @@ def find(vid: int = 0x2886, pid: int = 0x001A) -> ReSpeaker | None:
 
 
 def init_respeaker_usb() -> Optional[ReSpeaker]:
-    """Initialize the ReSpeaker USB device. Looks for both new and beta device IDs."""
+    """Initialize the ReSpeaker USB device. Looks for both new and beta device IDs.
+
+    Returns:
+        Optional[ReSpeaker]: A ReSpeaker object if a compatible device is found,
+                           None otherwise.
+
+    Note:
+        This function attempts to initialize a ReSpeaker microphone array by
+        searching for USB devices with known Vendor and Product IDs. It tries:
+        1. New Reachy Mini Audio firmware (0x38FB:0x1001) - preferred
+        2. Old ReSpeaker firmware (0x2886:0x001A) - with warning to update
+
+        The function handles USB backend errors gracefully and returns
+        None if no compatible device is found or if initialization fails.
+
+    Example:
+        >>> from reachy_mini.media.audio_control_utils import init_respeaker_usb
+        >>>
+        >>> # Initialize ReSpeaker device
+        >>> respeaker = init_respeaker_usb()
+        >>> if respeaker is not None:
+        ...     print("ReSpeaker initialized successfully")
+        ...     # Use the device...
+        ...     doa = respeaker.read("DOA_VALUE_RADIANS")
+        ...     respeaker.close()
+        ... else:
+        ...     print("No ReSpeaker device found")
+
+    """
     try:
         # Try new firmware first
         dev = usb.core.find(

reachy_mini/media/audio_gstreamer.py

@@ -1,7 +1,45 @@
-"""GStreamer camera backend.
+"""GStreamer audio backend.
+
+This module provides an implementation of the AudioBase class using GStreamer.
+It offers advanced audio processing capabilities including microphone input,
+speaker output, and integration with the ReSpeaker microphone array for
+Direction of Arrival (DoA) estimation.
+
+The GStreamer audio backend supports:
+- High-quality audio capture and playback
+- ReSpeaker microphone array integration
+- Direction of Arrival (DoA) estimation
+- Advanced audio processing pipelines
+- Multiple audio formats and sample rates
+
+Note:
+    This class is typically used internally by the MediaManager when the GSTREAMER
+    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 GStreamer backend
+    >>> media = MediaManager(backend=MediaBackend.GSTREAMER, 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")
+    >>>
+    >>> # Get Direction of Arrival
+    >>> doa = media.get_DoA()
+    >>> if doa is not None:
+    ...     angle, speech_detected = doa
+    ...     print(f"Sound direction: {angle} radians, speech detected: {speech_detected}")
+    >>>
+    >>> # Clean up
+    >>> media.stop_recording()
+    >>> media.close()
 
-This module provides an implementation of the CameraBase class using GStreamer.
-By default the module directly returns JPEG images as output by the camera.
 """
 
 import os
@@ -108,6 +146,21 @@ class GStreamerAudio(AudioBase):
         self._bus_record.remove_watch()
         self._bus_playback.remove_watch()
 
+    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.
+
+        """
+        if self._appsrc is not None:
+            self._appsrc.set_property("max-buffers", max_buffers)
+            self._appsrc.set_property("leaky-type", 2)  # drop old buffers
+        else:
+            self.logger.warning(
+                "AppSrc is not initialized. Call start_playing() first."
+            )
+
     def _init_pipeline_playback(self, pipeline: Gst.Pipeline) -> None:
         self._appsrc = Gst.ElementFactory.make("appsrc")
         self._appsrc.set_property("format", Gst.Format.TIME)
@@ -120,7 +173,6 @@ class GStreamerAudio(AudioBase):
         audioconvert = Gst.ElementFactory.make("audioconvert")
         audioresample = Gst.ElementFactory.make("audioresample")
 
-        queue = Gst.ElementFactory.make("queue")
         audiosink: Optional[Gst.Element] = None
         if self._id_audio_card == -1:
             audiosink = Gst.ElementFactory.make("autoaudiosink")  # use default speaker
@@ -132,14 +184,12 @@ class GStreamerAudio(AudioBase):
             audiosink = Gst.ElementFactory.make("alsasink")
             audiosink.set_property("device", f"hw:{self._id_audio_card},0")
 
-        pipeline.add(queue)
         pipeline.add(audiosink)
         pipeline.add(self._appsrc)
         pipeline.add(audioconvert)
         pipeline.add(audioresample)
 
-        self._appsrc.link(queue)
-        queue.link(audioconvert)
+        self._appsrc.link(audioconvert)
         audioconvert.link(audioresample)
         audioresample.link(audiosink)
 
@@ -157,7 +207,10 @@ class GStreamerAudio(AudioBase):
         return True
 
     def start_recording(self) -> None:
-        """Open the audio card using GStreamer."""
+        """Open the audio card using GStreamer.
+
+        See AudioBase.start_recording() for complete documentation.
+        """
         self._pipeline_record.set_state(Gst.State.PLAYING)
 
     def _get_sample(self, appsink: GstApp.AppSink) -> Optional[bytes]:
@@ -176,6 +229,8 @@ class GStreamerAudio(AudioBase):
     def get_audio_sample(self) -> Optional[npt.NDArray[np.float32]]:
         """Read a sample from the audio card. Returns the sample or None if error.
 
+        See AudioBase.get_audio_sample() for complete documentation.
+
         Returns:
             Optional[npt.NDArray[np.float32]]: The captured sample in raw format, or None if error.
 
@@ -186,35 +241,59 @@ class GStreamerAudio(AudioBase):
         return np.frombuffer(sample, dtype=np.float32).reshape(-1, 2)
 
     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 self.SAMPLE_RATE
 
     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 self.SAMPLE_RATE
 
     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 self.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 self.CHANNELS
 
     def stop_recording(self) -> None:
-        """Release the camera resource."""
+        """Release the camera resource.
+
+        See AudioBase.stop_recording() for complete documentation.
+        """
         self._pipeline_record.set_state(Gst.State.NULL)
 
     def start_playing(self) -> None:
-        """Open the audio output using GStreamer."""
+        """Open the audio output using GStreamer.
+
+        See AudioBase.start_playing() for complete documentation.
+        """
         self._pipeline_playback.set_state(Gst.State.PLAYING)
 
     def stop_playing(self) -> None:
-        """Stop playing audio and release resources."""
+        """Stop playing audio and release resources.
+
+        See AudioBase.stop_playing() for complete documentation.
+        """
         self._pipeline_playback.set_state(Gst.State.NULL)
 
     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._appsrc is not None:
             buf = Gst.Buffer.new_wrapped(data.tobytes())
             self._appsrc.push_buffer(buf)
@@ -226,6 +305,8 @@ class GStreamerAudio(AudioBase):
     def play_sound(self, sound_file: str) -> None:
         """Play a sound file.
 
+        See AudioBase.play_sound() for complete documentation.
+
         Todo: for now this function is mean to be used on the wireless version.
 
         Args: