hackerbot 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

hackerbot/base/__init__.py

@@ -16,8 +16,12 @@
 
 
 from hackerbot.utils.hackerbot_helper import HackerbotHelper
+from hackerbot.utils.tts_helper import TTSHelper
 from .maps import Maps
 import time
+import sounddevice as sd
+from piper.voice import PiperVoice
+import numpy as np
 
 class Base():    
     def __init__(self, controller: HackerbotHelper):
@@ -220,4 +224,67 @@ class Base():
         if auto_dock:
             time.sleep(3.0)
             self.dock(block=False)
-        self._controller.destroy()
+        self._controller.destroy()
+
+    def speak(self, model_src, text, speaker_id=None):
+        """
+        Synthesize and play speech audio based on the given text and voice model.
+
+        This function attempts to load a voice model, initialize an audio stream,
+        synthesize the given text into audio, and play it through the audio output
+        stream. If any step fails, an error is logged, and the process is aborted.
+
+        Args:
+            model_src: The source of the voice model to load for speech synthesis.
+            text: The text content to be synthesized into speech.
+            speaker_id (optional): The ID of the speaker to use, if applicable.
+
+        Returns:
+            None
+        """
+        try:
+            try:
+                tts_helper = TTSHelper()
+                model_path = tts_helper.get_or_download_model(model_src)
+            except Exception as e:
+                self._controller.log_error(f"Failed to get or download model: {e}")
+                return
+
+            try:
+                voice = PiperVoice.load(model_path)
+            except Exception as e:
+                self._controller.log_error(f"Failed to load voice model: {e}")
+                return
+
+            try:
+                stream = sd.OutputStream(
+                    samplerate=voice.config.sample_rate,
+                    channels=1,
+                    dtype='int16',
+                    blocksize=0  # Let sounddevice choose blocksize automatically
+                )
+            except Exception as e:
+                self._controller.log_error(f"Failed to initialize audio stream: {e}")
+                return
+
+            try:
+                with stream:
+                    for audio_bytes in voice.synthesize_stream_raw(text, speaker_id=speaker_id):
+                        try:
+                            int_data = np.frombuffer(audio_bytes, dtype=np.int16)
+                            stream.write(int_data)
+                        except Exception as e:
+                            self._controller.log_error(f"Error writing audio data to stream: {e}")
+                            break
+
+                    try:
+                        stream.stop()
+                    except Exception as e:
+                        self._controller.log_error(f"Failed to stop audio stream cleanly: {e}")
+
+                print("Finished speaking.")
+
+            except Exception as e:
+                self._controller.log_error(f"Error during audio streaming: {e}")
+        except Exception as e:
+            self._controller.log_error(f"Error in base:speak: {e}")

hackerbot/head/__init__.py

@@ -17,9 +17,6 @@
 
 from hackerbot.utils.hackerbot_helper import HackerbotHelper
 from .eyes import Eyes
-import sounddevice as sd
-from piper.voice import PiperVoice
-import numpy as np
 
 class Head():
     def __init__(self, controller: HackerbotHelper):
@@ -62,26 +59,3 @@ class Head():
         except Exception as e:
             self._controller.log_error(f"Error in head:set_idle_mode: {e}")
             return False
-        
-    def speak(self, model_src, text, speaker_id = None):
-        model = model_src
-        voice = PiperVoice.load(model)
-
-        # Setup a sounddevice OutputStream with appropriate parameters
-        # The sample rate and channels should match the properties of the PCM data
-        stream = sd.OutputStream(
-            samplerate=voice.config.sample_rate,
-            channels=1,
-            dtype='int16',
-            blocksize=0  # Let sounddevice choose blocksize automatically
-        )
-
-        with stream:  # This automatically handles start/stop/close
-            for audio_bytes in voice.synthesize_stream_raw(text, speaker_id=speaker_id):
-                int_data = np.frombuffer(audio_bytes, dtype=np.int16)
-                stream.write(int_data)
-
-            # At this point, all data has been written,
-            # but we need to wait for any remaining buffered audio to play out.
-            stream.stop()  # Ensure stream stops cleanly
-            print("Finished speaking.")  # <-- You now know it's done

hackerbot/utils/tts_helper.py

@@ -0,0 +1,101 @@
+################################################################################
+# Copyright (c) 2025 Hackerbot Industries LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+# Created By: Allen Chien
+# Created:    April 2025
+# Updated:    2025.05.13
+#
+# This module contains the TTSHelper class that gets or downloads a Piper voice 
+# model from HuggingFace
+#
+# Special thanks to the following for their code contributions to this codebase:
+# Allen Chien - https://github.com/AllenChienXXX
+# Saad Elbeleidy - https://github.com/sbeleidy
+#
+# Credits:
+# This project makes use of functionality inspired by or adapted from:
+# Dimits - https://github.com/Reqeique/Dimits
+################################################################################
+
+
+import os
+from huggingface_hub import hf_hub_url
+import requests
+
+class TTSHelper:
+    """
+    Downloads a Piper voice model (.onnx + .json) from HuggingFace
+    and stores it in a local directory for future use.
+    """
+
+    def __init__(self, cache_dir: str = os.path.expanduser("~/piper_models")):
+        """
+        Args:
+            cache_dir (str): Directory where downloaded models will be stored. Defaults to "~/piper_models".
+        """
+        self.cache_dir = cache_dir
+        os.makedirs(self.cache_dir, exist_ok=True)
+
+    def get_or_download_model(self, model_src: str) -> str:
+        """
+        If model_src is a valid file path, returns it.
+        Otherwise treats it as a HuggingFace voice model name and downloads it.
+
+        Args:
+            model_src (str): Either local .onnx path or voice name (e.g., "en_US-amy-low").
+
+        Returns:
+            str: Path to ONNX model file.
+        """
+        if os.path.isfile(model_src):
+            return model_src
+        return self._download_model_from_huggingface(model_src)
+
+    def _download_model_from_huggingface(self, voice: str) -> str:
+        """
+        Downloads a Piper voice model (.onnx and .json) from HuggingFace.
+
+        Args:
+            voice (str): Voice model name, e.g., "en_US-amy-low".
+
+        Returns:
+            str: Path to downloaded .onnx model.
+
+        Raises:
+            RuntimeError: If the download fails.
+        """
+        try:
+            locale, person, pitch = voice.split('-')
+            lang, country = locale.split('_')
+        except ValueError:
+            raise RuntimeError(f"Invalid voice model name: {voice}")
+
+        base_path = f"{lang}/{locale}/{person}/{pitch}"
+        filename_onnx = f"{voice}.onnx"
+        filename_json = f"{voice}.onnx.json"
+
+        url_onnx = hf_hub_url(repo_id="rhasspy/piper-voices", filename=f"{base_path}/{filename_onnx}")
+        url_json = hf_hub_url(repo_id="rhasspy/piper-voices", filename=f"{base_path}/{filename_json}")
+
+        path_onnx = os.path.join(self.cache_dir, filename_onnx)
+        path_json = os.path.join(self.cache_dir, filename_json)
+
+        if not os.path.exists(path_onnx):
+            self._download_file(url_onnx, path_onnx)
+        if not os.path.exists(path_json):
+            self._download_file(url_json, path_json)
+
+        return path_onnx
+
+    def _download_file(self, url: str, dest_path: str):
+        try:
+            response = requests.get(url, stream=True)
+            response.raise_for_status()
+            with open(dest_path, 'wb') as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    f.write(chunk)
+        except Exception as e:
+            raise RuntimeError(f"Failed to download {url}: {e}")

hackerbot-0.6.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: hackerbot
+Version: 0.6.0
+Summary: This module contains the setup for the hackerbot python package.
+Author-email: Allen Chien <allen@hackerbot.co>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hackerbotindustries/hackerbot-python-package
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial
+Requires-Dist: pytest
+Requires-Dist: piper-tts
+Requires-Dist: sounddevice
+Requires-Dist: pyaudio
+Requires-Dist: huggingface_hub
+Requires-Dist: requests
+Dynamic: license-file
+
+![HackerBot](images/transparent_hb_horizontal_industries_.png)
+# Hackerbot Python Package
+
+The `hackerbot` Python package provides modules for controlling and managing the Hackerbot robotics system.
+
+## Installation
+
+You can now install the package directly from PyPI:
+
+```bash
+pip install hackerbot
+```
+
+This will automatically install all required dependencies and make the `hackerbot` package available in your Python environment.
+
+### (Optional) Installing from Source
+
+If you prefer to install from source for development purposes:
+
+1. **Clone the Repository**
+
+   ```bash
+   git clone https://github.com/hackerbotindustries/hackerbot-python-package.git
+   cd hackerbot-python-package/
+   ```
+
+2. **Install Locally**
+
+   ```bash
+   pip install .
+   ```
+
+## Quick Start
+
+SSH into the Raspberry Pi or open a VNC viewer, then install the official Python package:
+
+```bash
+pip install hackerbot
+```
+
+Or upgrade the existing package:
+
+```bash
+pip install --upgrade hackerbot
+```
+
+Then, run `python3` to open up the Python interactive shell and copy and paste the following:
+
+```python
+from hackerbot import Hackerbot
+
+bot = Hackerbot()
+
+bot.base.drive(0, 65)
+bot.base.drive(200, 0)
+```
+
+You should see your Hackerbot leave the charger and move in the opposite direction.
+
+```python
+bot.head.look(180, 250, 70)
+```
+
+Now your robot should move its head and look up at you!
+
+```python
+bot.arm.move_joints(0, 0, 0, 0, 0, 0, 10)
+```
+
+You should see your elephant arm moving to a straight-up position.
+
+```python
+bot.base.destroy(auto_dock=True)
+```
+
+Safely clean up, and your Hackerbot will return to the charger. Once `destroy` is called, you need to create a new Hackerbot instance to perform new actions.
+
+## Usage
+
+After installation, you can import and use the package in your Python scripts:
+
+```python
+import hackerbot
+```
+
+## Testing
+
+To run the unit tests:
+
+```bash
+cd tests/unit_tests
+pytest
+```
+
+## Troubleshooting
+
+If you run into issues during installation or usage, try the following:
+
+* Use a virtual environment:
+
+  ```bash
+  python3 -m venv venv
+  source venv/bin/activate
+  ```
+
+* Upgrade `pip`:
+
+  ```bash
+  pip install --upgrade pip
+  ```

{hackerbot-0.5.0.dist-info → hackerbot-0.6.0.dist-info}/RECORD

@@ -2,14 +2,15 @@ hackerbot/__init__.py,sha256=fjzBB_VsqCuKJ3yeLdqLSvAQIz9bAMI-KXrUC6ZrscY,1248
 hackerbot/core.py,sha256=oZKQEUaMn19MnaWNTDFqTZ7lziBEZeSk5CdLXLSLvr0,5521
 hackerbot/arm/__init__.py,sha256=JdCmTDQ2qk3W8-Alc4mjaQYxHnmH26r0nSy0JFg6J4A,3400
 hackerbot/arm/gripper.py,sha256=xZux0PZL4vvrJTTKHL7dDsRBfJr4zbmgMaA0uBR1u4s,1986
-hackerbot/base/__init__.py,sha256=PG2Ykn2MLfobAWClGFnp-AZfh1xVsnbc1nQ8E6Yy6eA,8698
+hackerbot/base/__init__.py,sha256=7OtK29R8G9JYkg_hYWJbZ4DhX0PtldYCneyrZE31qCQ,11387
 hackerbot/base/maps.py,sha256=I_4NdvOMnkHX6-mW43QpDPJ-eVc6npgcBXq99tU7D1g,5916
-hackerbot/head/__init__.py,sha256=w4mhnz70miLaChxxF-8bGntDRo8GFLTFICxtTWJX2Iw,3581
+hackerbot/head/__init__.py,sha256=uBJ4gTst_QuCdveeNnuYZLIwsS8ANK9hxKMsLJVpI74,2467
 hackerbot/head/eyes.py,sha256=xqeKMxL12iaa8KQzDlbgbNy3LzcmWm8aXkebztYJ4P8,1370
 hackerbot/utils/hackerbot_helper.py,sha256=egQPVBBUo52ywsO6jGAGVqhyGLpMPz-b2fgLBb39WSM,4998
 hackerbot/utils/serial_helper.py,sha256=qo-mpbE_sb23_IAIfDuRT8sCDtW8d8A8qyav-b9e5Kw,6567
-hackerbot-0.5.0.dist-info/licenses/LICENSE,sha256=SCcXH0bf35ISRu_Ks8xEKySHXiqclANLWhBUbVU8VvA,1081
-hackerbot-0.5.0.dist-info/METADATA,sha256=TjRFtJ_ZSFGW50WkBhwEHlQfNkOXSJWd5wXZgasXoJ0,1786
-hackerbot-0.5.0.dist-info/WHEEL,sha256=ck4Vq1_RXyvS4Jt6SI0Vz6fyVs4GWg7AINwpsaGEgPE,91
-hackerbot-0.5.0.dist-info/top_level.txt,sha256=2n_FStAr1SiI3BV67x7KJHYIOmEwxjUD59zedw2hLkU,10
-hackerbot-0.5.0.dist-info/RECORD,,
+hackerbot/utils/tts_helper.py,sha256=X-3G2hhq94i9z3MdLzD-pFSwnIW707pI7Leu1h8EO60,3575
+hackerbot-0.6.0.dist-info/licenses/LICENSE,sha256=SCcXH0bf35ISRu_Ks8xEKySHXiqclANLWhBUbVU8VvA,1081
+hackerbot-0.6.0.dist-info/METADATA,sha256=V95jUbd4OUR80K9xnCg2uIjeCmMpAC2NmgSW4PHx8GM,2724
+hackerbot-0.6.0.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+hackerbot-0.6.0.dist-info/top_level.txt,sha256=2n_FStAr1SiI3BV67x7KJHYIOmEwxjUD59zedw2hLkU,10
+hackerbot-0.6.0.dist-info/RECORD,,

{hackerbot-0.5.0.dist-info → hackerbot-0.6.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.0.0)
+Generator: setuptools (80.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

hackerbot-0.5.0.dist-info/METADATA

@@ -1,69 +0,0 @@
-Metadata-Version: 2.4
-Name: hackerbot
-Version: 0.5.0
-Summary: This module contains the setup for the hackerbot python package.
-Author-email: Allen Chien <allen@hackerbot.co>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/hackerbotindustries/hackerbot-python-package
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pyserial
-Requires-Dist: pytest
-Requires-Dist: piper-tts
-Requires-Dist: sounddevice
-Requires-Dist: pyaudio
-Dynamic: license-file
-
-# Hackerbot Python Package
-
-Hackerbot python package (`hackerbot-python-package`) is a project that includes modules for controlling and managing the Hackerbot system.
-
-## Installation
-
-Follow these steps to clone the repository and set up the required dependencies.
-
-### 1. Clone the Repository
-Use SSH to clone the repository:
-```bash
-https://github.com/hackerbotindustries/hackerbot-python-package.git
-```
-This will create a directory named `hackerbot-python-package` and download all necessary files.
-
-### 2. Navigate to the Modules Directory
-Move into the `hackerbot_modules` directory:
-```bash
-cd hackerbot-python-package/
-```
-
-### 3. Install Dependencies
-Install the `hackerbot` package using `pip`:
-```bash
-pip install .
-```
-This will install the package locally for your Python environment.
-
-## Usage
-Once installed, you can import `hackerbot` in your Python scripts:
-```python
-import hackerbot
-```
-
-### 4. Testing
-To run the unit tests run:
-```bash
-cd tests/unit_tests
-pytest
-```
-
-## Troubleshooting
-If you run into issues with the installation, try the following:
-- Ensure you're using a virtual environment:  
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
-- Upgrade `pip` before installation:  
-  ```bash
-  pip install --upgrade pip
-  ```