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

reachy_mini/media/media_manager.py

@@ -1,6 +1,37 @@
 """Media Manager.
 
-Provides camera and audio access based on the selected backedn
+Provides camera and audio access based on the selected backend.
+
+This module offers a unified interface for managing both camera and audio
+devices with support for multiple backends. It simplifies the process of
+initializing, configuring, and using media devices across different
+platforms and use cases.
+
+Available backends:
+- NO_MEDIA: No media devices (useful for headless operation)
+- DEFAULT: OpenCV + SoundDevice (cross-platform default)
+- DEFAULT_NO_VIDEO: SoundDevice only (audio without video)
+- GSTREAMER: GStreamer-based media (advanced features)
+- GSTREAMER_NO_VIDEO: GStreamer audio only
+- WEBRTC: WebRTC-based media for real-time communication
+
+Example usage:
+    >>> from reachy_mini.media.media_manager import MediaManager, MediaBackend
+    >>>
+    >>> # Initialize with default backend
+    >>> media = MediaManager(backend=MediaBackend.DEFAULT)
+    >>>
+    >>> # Capture a frame
+    >>> frame = media.get_frame()
+    >>> if frame is not None:
+    ...     cv2.imshow("Frame", frame)
+    ...     cv2.waitKey(1)
+    >>>
+    >>> # Play a sound
+    >>> media.play_sound("/path/to/sound.wav")
+    >>>
+    >>> # Clean up
+    >>> media.close()
 """
 
 import logging
@@ -17,7 +48,25 @@ from reachy_mini.media.camera_base import CameraBase
 
 
 class MediaBackend(Enum):
-    """Media backends."""
+    """Media backends.
+
+    Enumeration of available media backends that can be used with MediaManager.
+    Each backend provides different capabilities and performance characteristics.
+
+    Attributes:
+        NO_MEDIA: No media devices - useful for headless operation or when
+                 media devices are not needed.
+        DEFAULT: Default backend using OpenCV for video and SoundDevice for audio.
+                Cross-platform and widely compatible.
+        DEFAULT_NO_VIDEO: SoundDevice audio only - for audio processing without video.
+        GSTREAMER: GStreamer-based media backend with advanced video and audio
+                  processing capabilities.
+        GSTREAMER_NO_VIDEO: GStreamer audio only - for advanced audio processing
+                           without video.
+        WEBRTC: WebRTC-based media backend for real-time communication and
+               streaming applications.
+
+    """
 
     NO_MEDIA = "no_media"
     DEFAULT = "default"
@@ -28,7 +77,19 @@ class MediaBackend(Enum):
 
 
 class MediaManager:
-    """Abstract class for opening and managing audio devices."""
+    """Media Manager for handling camera and audio devices.
+
+        This class provides a unified interface for managing both camera and audio
+    devices across different backends. It handles initialization, configuration,
+    and cleanup of media resources.
+
+    Attributes:
+            logger (logging.Logger): Logger instance for media-related messages.
+            backend (MediaBackend): The selected media backend.
+            camera (Optional[CameraBase]): Camera device instance.
+            audio (Optional[AudioBase]): Audio device instance.
+
+    """
 
     def __init__(
         self,
@@ -37,7 +98,28 @@ class MediaManager:
         use_sim: bool = False,
         signalling_host: str = "localhost",
     ) -> None:
-        """Initialize the audio device."""
+        """Initialize the media manager.
+
+        Args:
+            backend (MediaBackend): The media backend to use. Default is DEFAULT.
+            log_level (str): Logging level for media operations.
+                          Options: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'.
+                          Default: 'INFO'.
+            use_sim (bool): Whether to use simulation mode (for testing).
+                          Default: False.
+            signalling_host (str): Host address for WebRTC signalling server.
+                                 Only used with WEBRTC backend.
+                                 Default: 'localhost'.
+
+        Note:
+            The constructor initializes the selected media backend and sets up
+            the appropriate camera and audio devices based on the backend choice.
+
+        Example:
+            >>> media = MediaManager(backend=MediaBackend.DEFAULT)
+            >>> media = MediaManager(backend=MediaBackend.GSTREAMER, log_level="DEBUG")
+
+        """
         self.logger = logging.getLogger(__name__)
         self.logger.setLevel(log_level)
         self.backend = backend
@@ -69,7 +151,26 @@ class MediaManager:
                 raise NotImplementedError(f"Media backend {backend} not implemented.")
 
     def close(self) -> None:
-        """Close the media manager and release resources."""
+        """Close the media manager and release resources.
+
+        This method should be called when the media manager is no longer needed
+        to properly clean up and release all media resources. It stops any ongoing
+        audio recording/playback and closes the camera device.
+
+        Note:
+            After calling this method, the media manager can be reused by calling
+            the appropriate initialization methods again, but it's generally
+            recommended to create a new MediaManager instance if needed.
+
+        Example:
+            >>> media = MediaManager()
+            >>> try:
+            ...     # Use media devices
+            ...     frame = media.get_frame()
+            ... finally:
+            ...     media.close()
+
+        """
         if self.camera is not None:
             self.camera.close()
         if self.audio is not None:
@@ -111,7 +212,27 @@ class MediaManager:
         """Get a frame from the camera.
 
         Returns:
-            Optional[npt.NDArray[np.uint8]]: The captured BGR frame, or None if the camera is not available.
+            Optional[npt.NDArray[np.uint8]]: The captured BGR frame as a numpy array
+            with shape (height, width, 3), or None if the camera is not available
+            or an error occurred.
+
+            The image is in BGR format (OpenCV convention) and can be directly
+            used with OpenCV functions or converted to RGB if needed.
+
+        Note:
+            This method returns None if the camera is not initialized or if
+            there's an error capturing the frame. Always check the return value
+            before using the frame.
+
+        Example:
+            >>> frame = media.get_frame()
+            >>> if frame is not None:
+            ...     # Process the frame
+            ...     cv2.imshow("Camera", frame)
+            ...     cv2.waitKey(1)
+            ...
+            ...     # Convert to RGB if needed
+            ...     rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
 
         """
         if self.camera is None:
@@ -279,3 +400,15 @@ class MediaManager:
             self.logger.warning("Audio system is not initialized.")
             return
         self.audio.stop_playing()
+
+    def get_DoA(self) -> tuple[float, bool] | None:
+        """Get the Direction of Arrival (DoA) from the microphone array.
+
+        Returns:
+            tuple[float, bool] | None: A tuple (angle_radians, speech_detected),
+            or None if the audio system is not available.
+
+        """
+        if self.audio is None:
+            return None
+        return self.audio.get_DoA()

reachy_mini/media/webrtc_client_gstreamer.py

@@ -1,10 +1,45 @@
 """GStreamer WebRTC client implementation.
 
 The class is a client for the webrtc server hosted on the Reachy Mini Wireless robot.
+
+This module provides a GStreamer-based WebRTC client that implements both CameraBase
+and AudioBase interfaces, allowing it to be used as a drop-in replacement for
+traditional camera and audio devices in the media system.
+
+The WebRTC client supports real-time audio and video streaming over WebRTC protocol,
+making it suitable for remote operation and telepresence applications.
+
+Note:
+    This class is typically used internally by the MediaManager when the WEBRTC
+    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 WebRTC backend
+    >>> media = MediaManager(
+    ...     backend=MediaBackend.WEBRTC,
+    ...     signalling_host="192.168.1.100",
+    ...     log_level="INFO"
+    ... )
+    >>>
+    >>> # Use camera functionality
+    >>> frame = media.get_frame()
+    >>> if frame is not None:
+    ...     cv2.imshow("WebRTC Stream", frame)
+    ...     cv2.waitKey(1)
+    >>>
+    >>> # Use audio functionality
+    >>> media.start_recording()
+    >>> audio_samples = media.get_audio_sample()
+    >>>
+    >>> # Clean up
+    >>> media.close()
+
 """
 
 from threading import Thread
-from typing import Optional, cast
+from typing import Iterator, Optional, cast
 
 import gi
 import numpy as np
@@ -24,7 +59,18 @@ from gi.repository import GLib, Gst, GstApp  # noqa: E402, F401
 
 
 class GstWebRTCClient(CameraBase, AudioBase):
-    """GStreamer WebRTC client implementation."""
+    """GStreamer WebRTC client implementation.
+
+    This class implements a WebRTC client using GStreamer that can connect to
+    a WebRTC server (such as the one hosted on Reachy Mini Wireless) to stream
+    audio and video in real-time. It implements both CameraBase and AudioBase
+    interfaces, allowing seamless integration with the media system.
+
+    Attributes:
+        Inherits all attributes from CameraBase and AudioBase.
+        Additionally manages GStreamer pipelines for WebRTC communication.
+
+    """
 
     def __init__(
         self,
@@ -33,7 +79,30 @@ class GstWebRTCClient(CameraBase, AudioBase):
         signaling_host: str = "",
         signaling_port: int = 8443,
     ):
-        """Initialize the GStreamer WebRTC client."""
+        """Initialize the GStreamer WebRTC client.
+
+        Args:
+            log_level (str): Logging level for WebRTC operations.
+                          Default: 'INFO'.
+            peer_id (str): WebRTC peer ID to connect to. Default: ''.
+            signaling_host (str): Host address of the WebRTC signaling server.
+                               Default: ''.
+            signaling_port (int): Port of the WebRTC signaling server.
+                               Default: 8443.
+
+        Note:
+            This constructor initializes the GStreamer environment and sets up
+            the necessary pipelines for WebRTC communication. The WebRTC connection
+            is established when open() is called.
+
+        Example:
+            >>> client = GstWebRTCClient(
+            ...     peer_id="reachymini",
+            ...     signaling_host="192.168.1.100",
+            ...     signaling_port=8443
+            ... )
+
+        """
         super().__init__(log_level=log_level)
         Gst.init(None)
         self._loop = GLib.MainLoop()
@@ -56,7 +125,7 @@ class GstWebRTCClient(CameraBase, AudioBase):
         self._pipeline_record.add(self._appsink_audio)
 
         self.camera_specs = cast(CameraSpecs, ReachyMiniWirelessCamSpecs)
-        self.set_resolution(CameraResolution.R1920x1080at30fps)
+        self.set_resolution(self.camera_specs.default_resolution)
 
         self._appsink_video = Gst.ElementFactory.make("appsink")
         caps_video = Gst.Caps.from_string("video/x-raw,format=BGR")
@@ -104,11 +173,32 @@ class GstWebRTCClient(CameraBase, AudioBase):
         signaller.set_property("uri", f"ws://{signaling_host}:{signaling_port}")
         return source
 
+    def _iterate_gst(self, iterator: Gst.Iterator) -> Iterator[Gst.Element]:
+        """Iterate over GStreamer iterators."""
+        while True:
+            result, elem = iterator.next()
+            if result == Gst.IteratorResult.DONE:
+                break
+            if result == Gst.IteratorResult.OK:
+                yield elem
+            elif result == Gst.IteratorResult.RESYNC:
+                iterator.resync()
+
     def _configure_webrtcbin(self, webrtcsrc: Gst.Element) -> None:
         if isinstance(webrtcsrc, Gst.Bin):
-            webrtcbin_name = "webrtcbin0"
-            webrtcbin = webrtcsrc.get_by_name(webrtcbin_name)
-            assert webrtcbin is not None
+            # Try to find by standard name first (fast path)
+            webrtcbin = webrtcsrc.get_by_name("webrtcbin0")
+            
+            if webrtcbin is None:
+                # If not found by name (e.g. re-init scenarios), fallback to recursive search by factory type
+                self.logger.debug(f"webrtcbin0 not found, scanning elements in {webrtcsrc.get_name()} recursively...")
+                for elem in self._iterate_gst(webrtcsrc.iterate_recurse()):
+                    if elem.get_factory().get_name() == "webrtcbin":
+                        webrtcbin = elem
+                        self.logger.debug(f"Found webrtcbin by factory search: {elem.get_name()}")
+                        break
+
+            assert webrtcbin is not None, "Could not find webrtcbin element in webrtcsrc"
             # jitterbuffer has a default 200 ms buffer. Should be ok to lower this in localnetwork config
             webrtcbin.set_property("latency", 100)
 
@@ -166,7 +256,10 @@ class GstWebRTCClient(CameraBase, AudioBase):
         return True
 
     def open(self) -> None:
-        """Open the video stream."""
+        """Open the video stream.
+
+        See CameraBase.open() for complete documentation.
+        """
         self._pipeline_record.set_state(Gst.State.PLAYING)
 
     def _get_sample(self, appsink: GstApp.AppSink) -> Optional[bytes]:
@@ -185,6 +278,8 @@ class GstWebRTCClient(CameraBase, 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.
 
@@ -197,6 +292,8 @@ class GstWebRTCClient(CameraBase, AudioBase):
     def read(self) -> Optional[npt.NDArray[np.uint8]]:
         """Read a frame from the camera. Returns the frame or None if error.
 
+        See CameraBase.read() for complete documentation.
+
         Returns:
             Optional[npt.NDArray[np.uint8]]: The captured frame in BGR format, or None if error.
 
@@ -211,16 +308,25 @@ class GstWebRTCClient(CameraBase, AudioBase):
         return arr
 
     def close(self) -> None:
-        """Stop the pipeline."""
+        """Stop the pipeline.
+
+        See CameraBase.close() for complete documentation.
+        """
         # self._loop.quit()
         self._pipeline_record.set_state(Gst.State.NULL)
 
     def start_recording(self) -> None:
-        """Open the audio card using GStreamer."""
+        """Open the audio card using GStreamer.
+
+        See AudioBase.start_recording() for complete documentation.
+        """
         pass  # already started in open()
 
     def stop_recording(self) -> None:
-        """Release the camera resource."""
+        """Release the camera resource.
+
+        See AudioBase.stop_recording() for complete documentation.
+        """
         pass  # managed in close()
 
     def _init_pipeline_playback(
@@ -259,12 +365,33 @@ class GstWebRTCClient(CameraBase, AudioBase):
         queue.link(rtpopuspay)
         rtpopuspay.link(udpsink)
 
+    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 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:
@@ -281,6 +408,8 @@ class GstWebRTCClient(CameraBase, 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.
 

reachy_mini/media/webrtc_daemon.py

@@ -1,14 +1,41 @@
 """WebRTC daemon.
 
 Starts a gstreamer webrtc pipeline to stream video and audio.
+
+This module provides a WebRTC server implementation using GStreamer that can
+stream video and audio from the Reachy Mini robot to WebRTC clients. It's
+designed to run as a daemon process on the robot and handle multiple client
+connections for telepresence and remote monitoring applications.
+
+The WebRTC daemon supports:
+- Real-time video streaming from the robot's camera
+- Real-time audio streaming from the robot's microphone
+- Multiple client connections
+- Automatic camera detection and configuration
+
+Example usage:
+    >>> from reachy_mini.media.webrtc_daemon import GstWebRTC
+    >>>
+    >>> # Create and start WebRTC daemon
+    >>> webrtc_daemon = GstWebRTC(log_level="INFO")
+    >>> # The daemon will automatically start streaming when initialized
+    >>>
+    >>> # Run until interrupted
+    >>> try:
+    ...     while True:
+    ...         pass  # Keep the daemon running
+    ... except KeyboardInterrupt:
+    ...     pass  # Cleanup would be handled automatically
 """
 
 import logging
+import os
 from threading import Thread
 from typing import Optional, Tuple, cast
 
 import gi
 
+from reachy_mini.daemon.utils import CAMERA_SOCKET_PATH, is_local_camera_available
 from reachy_mini.media.camera_constants import (
     ArducamSpecs,
     CameraSpecs,
@@ -23,18 +50,50 @@ from gi.repository import GLib, Gst  # noqa: E402
 
 
 class GstWebRTC:
-    """WebRTC pipeline using GStreamer."""
+    """WebRTC pipeline using GStreamer.
+
+    This class implements a WebRTC server using GStreamer that streams video
+    and audio from the Reachy Mini robot to connected WebRTC clients. It's
+    designed to run as a daemon process and handle the complete WebRTC
+    signaling and media streaming pipeline.
+
+    Attributes:
+        _logger (logging.Logger): Logger instance for WebRTC daemon operations.
+        _loop (GLib.MainLoop): GLib main loop for handling GStreamer events.
+        camera_specs (CameraSpecs): Specifications of the detected camera.
+        _resolution (CameraResolution): Current streaming resolution.
+        resized_K (npt.NDArray[np.float64]): Camera intrinsic matrix for current resolution.
+
+    """
 
     def __init__(
         self,
         log_level: str = "INFO",
     ) -> None:
-        """Initialize the GStreamer WebRTC pipeline."""
+        """Initialize the GStreamer WebRTC pipeline.
+
+        Args:
+            log_level (str): Logging level for WebRTC daemon operations.
+                          Default: 'INFO'.
+
+        Note:
+            This constructor initializes the GStreamer environment, detects the
+            available camera, and sets up the WebRTC streaming pipeline. The
+            pipeline automatically starts streaming when initialized.
+
+        Raises:
+            RuntimeError: If no camera is detected or camera specifications cannot
+                        be determined.
+
+        Example:
+            >>> # Initialize WebRTC daemon with debug logging
+            >>> webrtc_daemon = GstWebRTC(log_level="DEBUG")
+            >>> # The daemon is now streaming and ready to accept client connections
+
+        """
         self._logger = logging.getLogger(__name__)
         self._logger.setLevel(log_level)
 
-        # self._id_audio_card = get_respeaker_card_number()
-
         Gst.init(None)
         self._loop = GLib.MainLoop()
         self._thread_bus_calls = Thread(target=lambda: self._loop.run(), daemon=True)
@@ -70,6 +129,7 @@ class GstWebRTC:
 
     def __del__(self) -> None:
         """Destructor to ensure gstreamer resources are released."""
+        self._logger.debug("Cleaning up GstWebRTC")
         self._loop.quit()
         self._bus_sender.remove_watch()
         self._bus_receiver.remove_watch()
@@ -156,7 +216,10 @@ class GstWebRTC:
         tee = Gst.ElementFactory.make("tee")
         # make camera accessible to other applications via unixfdsrc/sink
         unixfdsink = Gst.ElementFactory.make("unixfdsink")
-        unixfdsink.set_property("socket-path", "/tmp/reachymini_camera_socket")
+        if is_local_camera_available():
+            # prevent crash if socket already exists
+            os.remove(CAMERA_SOCKET_PATH)
+        unixfdsink.set_property("socket-path", CAMERA_SOCKET_PATH)
         queue_unixfd = Gst.ElementFactory.make("queue", "queue_unixfd")
         queue_encoder = Gst.ElementFactory.make("queue", "queue_encoder")
         v4l2h264enc = Gst.ElementFactory.make("v4l2h264enc")
@@ -164,8 +227,10 @@ class GstWebRTC:
         extra_controls_structure.set_value("repeat_sequence_header", 1)
         extra_controls_structure.set_value("video_bitrate", 5_000_000)
         v4l2h264enc.set_property("extra-controls", extra_controls_structure)
+        # Use H264 Level 3.1 + Constrained Baseline for Safari/WebKit compatibility
         caps_h264 = Gst.Caps.from_string(
-            "video/x-h264,stream-format=byte-stream,alignment=au,level=(string)4"
+            "video/x-h264,stream-format=byte-stream,alignment=au,"
+            "level=(string)3.1,profile=(string)constrained-baseline"
         )
         capsfilter_h264 = Gst.ElementFactory.make("capsfilter")
         capsfilter_h264.set_property("caps", caps_h264)
@@ -215,7 +280,7 @@ class GstWebRTC:
         alsasrc.link(webrtcsink)
 
     def _get_audio_input_device(self) -> Optional[str]:
-        """Use Gst.DeviceMonitor to find the pipeire audio card.
+        """Use Gst.DeviceMonitor to find the pipewire audio card.
 
         Returns the device ID of the found audio card, None if not.
         """

reachy_mini/motion/recorded_move.py

@@ -1,5 +1,6 @@
 import bisect  # noqa: D100
 import json
+import logging
 import os
 from glob import glob
 from pathlib import Path
@@ -8,10 +9,58 @@ from typing import Any, Dict, List, Optional
 import numpy as np
 import numpy.typing as npt
 from huggingface_hub import snapshot_download
+from huggingface_hub.errors import LocalEntryNotFoundError
 
 from reachy_mini.motion.move import Move
 from reachy_mini.utils.interpolation import linear_pose_interpolation
 
+logger = logging.getLogger(__name__)
+
+# Default datasets to preload at daemon startup
+DEFAULT_DATASETS = [
+    "pollen-robotics/reachy-mini-emotions-library",
+    "pollen-robotics/reachy-mini-dances-library",
+]
+
+
+def preload_dataset(dataset_name: str) -> str | None:
+    """Pre-download a HuggingFace dataset to local cache.
+
+    This function downloads the dataset with network access, so it should be
+    called during daemon startup (not during playback) to avoid blocking.
+
+    Args:
+        dataset_name: The HuggingFace dataset name (e.g., "pollen-robotics/reachy-mini-emotions-library")
+
+    Returns:
+        The local path to the cached dataset, or None if download failed.
+
+    """
+    try:
+        logger.info(f"Pre-downloading dataset: {dataset_name}")
+        local_path: str = snapshot_download(dataset_name, repo_type="dataset")
+        logger.info(f"Dataset {dataset_name} cached at: {local_path}")
+        return local_path
+    except Exception as e:
+        logger.warning(f"Failed to pre-download dataset {dataset_name}: {e}")
+        return None
+
+
+def preload_default_datasets() -> dict[str, str | None]:
+    """Pre-download all default recorded move datasets.
+
+    Should be called during daemon startup to ensure datasets are cached
+    before any playback requests.
+
+    Returns:
+        A dict mapping dataset names to their local paths (or None if failed).
+
+    """
+    results = {}
+    for dataset in DEFAULT_DATASETS:
+        results[dataset] = preload_dataset(dataset)
+    return results
+
 
 def lerp(v0: float, v1: float, alpha: float) -> float:
     """Linear interpolation between two values."""
@@ -105,12 +154,33 @@ class RecordedMove(Move):
 
 
 class RecordedMoves:
-    """Load a library of recorded moves from a HuggingFace dataset."""
+    """Load a library of recorded moves from a HuggingFace dataset.
+
+    Uses local cache only to avoid blocking network calls during playback.
+    The dataset should be pre-downloaded at daemon startup via preload_default_datasets().
+    If not cached, falls back to network download (which may cause delays).
+    """
 
     def __init__(self, hf_dataset_name: str):
         """Initialize RecordedMoves."""
         self.hf_dataset_name = hf_dataset_name
-        self.local_path = snapshot_download(self.hf_dataset_name, repo_type="dataset")
+        # Try local cache first (instant, no network)
+        try:
+            self.local_path = snapshot_download(
+                self.hf_dataset_name,
+                repo_type="dataset",
+                local_files_only=True,
+            )
+        except LocalEntryNotFoundError:
+            # Fallback: download from network (slow, but ensures it works)
+            logger.warning(
+                f"Dataset {hf_dataset_name} not in cache, downloading from HuggingFace. "
+                "This may take a moment. Consider pre-loading datasets at daemon startup."
+            )
+            self.local_path = snapshot_download(
+                self.hf_dataset_name,
+                repo_type="dataset",
+            )
         self.moves: Dict[str, Any] = {}
         self.sounds: Dict[str, Optional[Path]] = {}
 
@@ -119,6 +189,10 @@ class RecordedMoves:
     def process(self) -> None:
         """Populate recorded moves and sounds."""
         move_paths_tmp = glob(f"{self.local_path}/*.json")
+        data_dir = os.path.join(self.local_path, "data")
+        if os.path.isdir(data_dir):
+            # Newer datasets keep their moves inside data/; look there as well.
+            move_paths_tmp.extend(glob(f"{data_dir}/*.json"))
         move_paths = [Path(move_path) for move_path in move_paths_tmp]
         for move_path in move_paths:
             move_name = move_path.stem