---
title: "Echo canceller worker"
description: "lvq-worker runs LocalVQE v1.3 (s2s.cpp's ggml/Metal port) for the gateway's [wake] lvq_shadow lane. The gateway feeds it the session's 16 kHz mic, with the TTS it is playing as the far end, and runs a second wake worker on its output."
type: "living"
source: "runtime/localvqe-worker/README.md"
verified: "2026-11-14"
group: "The voice path"
---

> **Living doc**, checked against the code 2026-11-14

localvqe-worker — the shadow echo canceller for the wake fan-out

That worker's wakes are `wake_lvq` trace rows and never arm anything.


The stdin/stdout contract does not name the canceller, so another one (DTLN) can stand in:

- stdout, once: one JSON status line with `hop` and `sample_rate` (16000);
- per hop: the gateway writes `hop` f32le mic samples, then `hop` f32le far-end samples, and reads `hop` f32le
  enhanced samples.

Nothing third-party is in git. `fetch.sh` takes s2s.cpp's `src/localvqe.cpp` and the headers it includes (MIT) from a
zip (`S2S_ZIP=…`) or a clone (`S2S_GIT_REF=…`), checks each against `sources.sha256`, and clones ggml at a pinned
commit. `fetch.sh --weights` also downloads `Serveurperso/LocalVQE-GGUF` `localvqe-v1.3-F32.gguf` (Apache-2.0, 19 MB,
sha256 pinned). Everything lands in `LVQ_HOME` (`~/.local/share/fox9/localvqe-worker` by default).

```
S2S_ZIP=<s2s.cpp-master.zip> runtime/localvqe-worker/fetch.sh --weights
runtime/localvqe-worker/build.sh        # niced cmake; prints the binary path
```

Then, in the gateway config:

```
[wake]
lvq_shadow = true
lvq_worker_bin = "<LVQ_HOME>/build/lvq-worker"
lvq_worker_args = ["--model", "<LVQ_HOME>/models/localvqe-v1.3-F32.gguf"]
# lvq_gate_source = "raw"   # default; "enhanced" lets the canceller's output decide its own silence;
#                           # "hybrid": the canceller's output opens/closes, only raw silence resets;
#                           # "hybrid_reset": hybrid, plus a reset after the gate was closed >= 4 s
```

`lvq_gate_source` picks the stream whose level opens, closes and resets the second worker's fan-out gate; the gate
admits the canceller's output in every mode. `raw` makes the same decisions as the live gate on the same samples.
`enhanced` can cut the first consonant of a barge's alias, because LocalVQE holds a TTS-only stretch near silence and
the gate resets there. `hybrid` keeps the alias onset but can lose full-session windows.

For the offline replay, the spike's `wake_replay.py` takes `--gate-wav <raw mic wav>` for the `raw` rule,
`--gate-wav <raw> --gate-rule hybrid`, or `--gate-wav <raw> --gate-rule hybrid_reset --reset-cap-ms 4000`.


On a MacBook Air's GPU the worker takes 5.1 ms per 16 ms hop (3.1 times realtime) and 113 MB peak, LocalVQE and
Silero together (`benchmarks/results/localvqe-replay-20261003.md`). No gateway host is measured yet.
