huri-module-vad 0.1.0.dev0__tar.gz

huri_module_vad-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: huri-module-vad
+Version: 0.1.0.dev0
+Summary: HuRI module: Voice activity detection (WebRTC VAD): microphone frames in, speech segments out
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: huri-core[server]<0.5,>=0.4.0.dev0
+Requires-Dist: huri-events<0.2,>=0.1.0.dev0
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: webrtcvad==2.0.10
+Requires-Dist: setuptools<82
+
+# huri-module-vad
+
+Voice activity detection (WebRTC VAD): microphone frames in, speech segments out.
+
+| Module | Topics | What it does |
+|---|---|---|
+| `vad` | `huri.audio.in` → `huri.voice` | Detects speech in microphone frames (WebRTC VAD) |
+
+```sh
+pip install -e packages/huri-module-vad     # from a huri-modules checkout, next to huri-core and huri-events
+HURI_MODULES=vad ...   # enable it on the server
+```
+
+A distribution of
+[huri-modules](https://github.com/Lucy-Robotics/huri-modules), versioned in its
+`pyproject.toml` (see RELEASING.md there). It depends on `huri-core` and
+`huri-events`, which are not on PyPI: without a checkout, install them from git
+in the same pip command, so pip never looks them up on an index:
+
+```sh
+ref=0.1.0   # a huri-modules release tag
+core=0.4.0  # HURI_CORE_REF in that release's versions.env
+pip install \
+  "huri-core[server] @ git+https://github.com/Lucy-Robotics/huri-core.git@$core" \
+  "huri-events @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-events" \
+  "huri-module-vad @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-module-vad"
+```

huri_module_vad-0.1.0.dev0/README.md

@@ -0,0 +1,27 @@
+# huri-module-vad
+
+Voice activity detection (WebRTC VAD): microphone frames in, speech segments out.
+
+| Module | Topics | What it does |
+|---|---|---|
+| `vad` | `huri.audio.in` → `huri.voice` | Detects speech in microphone frames (WebRTC VAD) |
+
+```sh
+pip install -e packages/huri-module-vad     # from a huri-modules checkout, next to huri-core and huri-events
+HURI_MODULES=vad ...   # enable it on the server
+```
+
+A distribution of
+[huri-modules](https://github.com/Lucy-Robotics/huri-modules), versioned in its
+`pyproject.toml` (see RELEASING.md there). It depends on `huri-core` and
+`huri-events`, which are not on PyPI: without a checkout, install them from git
+in the same pip command, so pip never looks them up on an index:
+
+```sh
+ref=0.1.0   # a huri-modules release tag
+core=0.4.0  # HURI_CORE_REF in that release's versions.env
+pip install \
+  "huri-core[server] @ git+https://github.com/Lucy-Robotics/huri-core.git@$core" \
+  "huri-events @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-events" \
+  "huri-module-vad @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-module-vad"
+```

huri_module_vad-0.1.0.dev0/huri_module_vad.egg-info/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: huri-module-vad
+Version: 0.1.0.dev0
+Summary: HuRI module: Voice activity detection (WebRTC VAD): microphone frames in, speech segments out
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: huri-core[server]<0.5,>=0.4.0.dev0
+Requires-Dist: huri-events<0.2,>=0.1.0.dev0
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: webrtcvad==2.0.10
+Requires-Dist: setuptools<82
+
+# huri-module-vad
+
+Voice activity detection (WebRTC VAD): microphone frames in, speech segments out.
+
+| Module | Topics | What it does |
+|---|---|---|
+| `vad` | `huri.audio.in` → `huri.voice` | Detects speech in microphone frames (WebRTC VAD) |
+
+```sh
+pip install -e packages/huri-module-vad     # from a huri-modules checkout, next to huri-core and huri-events
+HURI_MODULES=vad ...   # enable it on the server
+```
+
+A distribution of
+[huri-modules](https://github.com/Lucy-Robotics/huri-modules), versioned in its
+`pyproject.toml` (see RELEASING.md there). It depends on `huri-core` and
+`huri-events`, which are not on PyPI: without a checkout, install them from git
+in the same pip command, so pip never looks them up on an index:
+
+```sh
+ref=0.1.0   # a huri-modules release tag
+core=0.4.0  # HURI_CORE_REF in that release's versions.env
+pip install \
+  "huri-core[server] @ git+https://github.com/Lucy-Robotics/huri-core.git@$core" \
+  "huri-events @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-events" \
+  "huri-module-vad @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-module-vad"
+```

huri_module_vad-0.1.0.dev0/huri_module_vad.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+huri_module_vad.egg-info/PKG-INFO
+huri_module_vad.egg-info/SOURCES.txt
+huri_module_vad.egg-info/dependency_links.txt
+huri_module_vad.egg-info/entry_points.txt
+huri_module_vad.egg-info/requires.txt
+huri_module_vad.egg-info/top_level.txt
+huri_vad/__init__.py
+huri_vad/huri_module.toml
+huri_vad/module.py
+tests/test_vad.py

huri_module_vad-0.1.0.dev0/huri_module_vad.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

huri_module_vad-0.1.0.dev0/huri_module_vad.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[huri.modules]
+vad = huri_vad.module:VAD

huri_module_vad-0.1.0.dev0/huri_module_vad.egg-info/requires.txt

@@ -0,0 +1,5 @@
+huri-core[server]<0.5,>=0.4.0.dev0
+huri-events<0.2,>=0.1.0.dev0
+numpy<2,>=1.26
+webrtcvad==2.0.10
+setuptools<82

huri_module_vad-0.1.0.dev0/huri_module_vad.egg-info/top_level.txt

@@ -0,0 +1 @@
+huri_vad

huri_module_vad-0.1.0.dev0/huri_vad/huri_module.toml

@@ -0,0 +1,7 @@
+name = "vad"
+summary = "Detects speech in microphone frames (WebRTC VAD)"
+input = { topic = "huri.audio.in", event = "huri_core.core.events:BytesEvent" }
+output = { topic = "huri.voice", event = "huri_events.speech:Voice" }
+events = ["huri-events>=0.1,<0.2"]
+requires = { gpu = false, actuation = false }
+huri_core = ">=0.4.0.dev0,<0.5"

huri_module_vad-0.1.0.dev0/huri_vad/module.py

@@ -0,0 +1,69 @@
+from typing import Optional
+
+import numpy as np
+import webrtcvad
+from huri_events.speech import Voice
+
+from huri_core.core.events import BytesEvent
+from huri_core.core.module import Module
+
+
+class VAD(Module):
+    """VAD Module
+
+    Detect voice and silence using WebRTC VAD.
+
+    input: huri.audio.in,
+    output: huri.voice
+
+    :vad_agressiveness: from 0 (low) to 3 (high, can distord audio).
+    :silence_duration: how many seconds will a no voice be considered a silence.
+    :sample_rate: size of received chunk of audio. Usually 8000, 16000 or 48000.
+    :block_duration: size of received chunk of audio (in s).
+        Can only be 0.010, 0.020 and 0.030.
+    """
+
+    # Inbound microphone frames travel on their own topic so the TTS-output
+    # "audio" topic (consumed by MOV and the client Sender) never collides
+    # with mic input — otherwise raw mic bytes get echoed back to the client.
+    input_type = "huri.audio.in"
+    output_type = "huri.voice"
+    input_event = BytesEvent
+    output_event = Voice
+
+    def __init__(
+        self,
+        vad_agressiveness: int = 3,
+        silence_duration: float = 3,  # s
+        sample_rate: int = 16000,
+        block_duration: float = 0.020,  # s
+    ):
+        super().__init__()
+
+        if block_duration not in [0.010, 0.020, 0.030]:
+            raise RuntimeError("block duration must be 0.010, 0.020 or 0.030 s")
+
+        self.sample_rate: int = sample_rate
+        self.block_size: int = int(block_duration * sample_rate)  # ms
+
+        self.silence_frames_size: int = int(silence_duration * sample_rate)
+        self.silence_frames_count: int = -1
+
+        self.vad = webrtcvad.Vad(vad_agressiveness)
+
+    async def process(self, data: BytesEvent) -> Optional[Voice]:
+        if self.vad.is_speech(data.data, self.sample_rate) is True:
+            self.silence_frames_count = 0
+
+            audio_array = np.frombuffer(data.data, dtype=np.int16)
+            audio_array_float = audio_array.astype(np.float32) / 32768.0
+
+            return Voice(audio_array_float)
+        else:
+            if self.silence_frames_count != -1:
+                self.silence_frames_count += self.block_size
+            if self.silence_frames_count > self.silence_frames_size:
+                self.silence_frames_count = -1  # sent only once
+
+                return Voice(None)
+            return None

huri_module_vad-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=64,<82"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "huri-module-vad"
+version = "0.1.0.dev0"
+description = "HuRI module: Voice activity detection (WebRTC VAD): microphone frames in, speech segments out"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "huri-core[server]>=0.4.0.dev0,<0.5",
+  "huri-events>=0.1.0.dev0,<0.2",
+  "numpy>=1.26,<2",
+  "webrtcvad==2.0.10",
+  # webrtcvad imports pkg_resources, removed in setuptools 82
+  "setuptools<82",
+]
+
+[project.entry-points."huri.modules"]
+vad = "huri_vad.module:VAD"
+
+[tool.setuptools.packages.find]
+include = ["huri_vad*"]
+
+[tool.setuptools.package-data]
+huri_vad = ["huri_module.toml", "manifests/*/huri_module.toml"]

huri_module_vad-0.1.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

huri_module_vad-0.1.0.dev0/tests/test_vad.py

@@ -0,0 +1,51 @@
+"""VAD's speech/silence logic, with WebRTC's detector scripted."""
+
+import numpy as np
+import pytest
+from huri_events.speech import Voice
+from huri_vad.module import VAD
+
+from huri_core.core.events import BytesEvent
+from huri_core.testing import ModuleHarness
+
+FRAME = (np.full(320, 16384, dtype=np.int16)).tobytes()  # 20 ms at 16 kHz
+
+
+class Scripted:
+    def __init__(self, decisions):
+        self.decisions = list(decisions)
+
+    def is_speech(self, frame, sample_rate):
+        return self.decisions.pop(0)
+
+
+def vad(decisions, silence_duration=0.05):
+    harness = ModuleHarness(VAD, silence_duration=silence_duration)
+    harness.module.vad = Scripted(decisions)
+    return harness
+
+
+def test_speech_frames_become_normalized_voice():
+    (voice,) = vad([True]).run(BytesEvent(FRAME))
+    assert voice.data.dtype == np.float32 and voice.data.size == 320
+    assert voice.data[0] == pytest.approx(0.5)
+
+
+def test_end_of_utterance_is_sent_once_after_enough_silence():
+    # 0.05 s of silence = more than 2 frames of 20 ms.
+    out = vad([True] + [False] * 6).run(*[BytesEvent(FRAME)] * 7)
+    assert [v.data is None for v in out] == [False, True]
+
+
+def test_silence_before_any_speech_sends_nothing():
+    assert vad([False] * 5).run(*[BytesEvent(FRAME)] * 5) == []
+
+
+def test_block_duration_must_be_one_webrtc_accepts():
+    with pytest.raises(RuntimeError, match="block duration"):
+        ModuleHarness(VAD, block_duration=0.025)
+
+
+def test_real_detector_runs_on_a_frame():
+    out = ModuleHarness(VAD).run(BytesEvent(bytes(640)))  # digital silence
+    assert out == [] or isinstance(out[0], Voice)