Metadata-Version: 2.4
Name: haru-speech
Version: 0.1.1
Summary: Haru: a low-latency, multilingual, full-duplex spoken dialogue model
Author: higurashi
License-Expression: Apache-2.0
Project-URL: Homepage, https://higurashi.ai
Project-URL: Repository, https://github.com/higurashi-ai/Haru
Project-URL: Issues, https://github.com/higurashi-ai/Haru/issues
Project-URL: Model, https://huggingface.co/higurashi-ai/Haru-4B
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: torch>=2.6
Requires-Dist: transformers>=5.16
Requires-Dist: tokenizers>=0.21
Requires-Dist: safetensors>=0.4
Requires-Dist: huggingface-hub>=0.26
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.13
Requires-Dist: soundfile>=0.13
Requires-Dist: aiohttp<4,>=3.10
Requires-Dist: sphn<0.3,>=0.2
Provides-Extra: webrtc
Requires-Dist: aiortc==1.15.0; extra == "webrtc"
Requires-Dist: av>=14; extra == "webrtc"
Provides-Extra: triton
Requires-Dist: triton>=3.2; extra == "triton"
Provides-Extra: share
Requires-Dist: gradio>=5; extra == "share"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# haru

<!-- This README is also the project description on PyPI, where relative links do not resolve. Link to other files in the repository with absolute GitHub URLs. -->

The PyTorch implementation of Haru, a full-duplex spoken dialogue model, with
a web demo server and an offline inference command.

```bash
pip install -e .                  # from this directory
pip install -e ".[webrtc]"        # + WebRTC transport for the web demo
pip install -e ".[triton]"        # + faster audio codec on NVIDIA GPUs
pip install -e ".[share]"         # + public link for the web demo (--share)
```

```bash
haru-server --hf-repo higurashi-ai/Haru-4B       # web demo on http://localhost:8998
haru-inference user.wav reply.wav --reference voice.wav --system-prompt "..."
```

Requirements: Python 3.10 or later and a CUDA GPU with about 12 GB of memory.
`ffmpeg` on the `PATH` is needed to use voice clips recorded in the browser
(WebM / MP4); WAV, FLAC and Ogg files work without it.

## Faster audio codec

With the `triton` extra, the codec can run as Triton kernels replayed from
CUDA graphs: about 0.7 ms instead of 6 ms per encoded or decoded frame on a
recent GPU, with the same output up to bfloat16 rounding. It is opt-in:

```python
session = DuplexSession(model, system_prompt=card, reference=voice, config=DuplexConfig(codec_backend="triton"))
```

From the command line: `haru-server --codec-backend triton` (or `auto`: Triton when usable, else PyTorch).

The first use in a new environment compiles the kernels (about 15 seconds).

## Layout

| Module | Contents |
| --- | --- |
| `haru.models.haru` | `HaruModel`: language model, audio projections, audio head, codec |
| `haru.models.meanflow_head` | `MeanFlowHead`: one audio latent from one hidden state |
| `haru.models.vibevoice_codec` | `VibeVoiceCodec`: streaming audio encoder and decoder |
| `haru.codec_triton` | The same codec as Triton kernels replayed from CUDA graphs |
| `haru.session` | `DuplexSession`: a live conversation, one frame at a time |
| `haru.prompt` | Character cards and the prompt layout |
| `haru.sampling` | Text sampling, repetition penalty, incremental detokenization |
| `haru.server`, `haru.webrtc`, `haru.backends` | The web demo |
| `haru.run_inference` | Offline: a recording in, the model's side of the conversation out |

See the [repository README](https://github.com/higurashi-ai/Haru/blob/main/README.md#python) for the Python API.

## Tests

```bash
pip install -e ".[dev]"
pytest                                  # CPU-only tests
HARU_MODEL=/path/to/Haru-4B pytest      # + tests that load the checkpoint on a GPU
```
