Liu-zhongxian/zongzhu-bot

A round-screen desk companion with animated eyes, local speech recognition, subtitles and spoken replies. The interesting part is not the hardware: it is the split between local media control, a PC backend and a bot with file-write access.

The problem

You want to say a request out loud and have something useful happen without opening a laptop or typing into a chat window. The usual path is: pick up your phone, open the bot, type or dictate, read the reply, and if it is music, switch apps and search manually. Here, the board listens, the PC backend recognizes speech, and the sentence is routed: playback commands run on the PC within about a second and a half, while other requests go to your Grok bot and the reply is spoken back with the full text scrolling on screen. The board shows a countdown while waiting and re-sends replies that arrived while disconnected.

What's different

The mechanism is a routing backend, not a cloud voice product. The firmware is built on the xiaozhi ESP32 base, the backend on xiaozhi-esp32-server, and the project's own code sits in a small set of handler and board directories. That keeps upstream merges possible: the baseline upstream commit is recorded and most code is untouched. Locally, X-ASR does offline recognition with hot-word correction so "你好中主" becomes the wake word. Optional local music uses go-music-dl and mpv, searching NetEase first and then QQ, Kugou, Kuwo and Migu, skipping covers and live versions and preferring higher bitrate.

The trade-off is that the interesting behavior depends on your own computer and your own bot. Music search hits unofficial platform interfaces, and the project limits that to personal use. The bot path is more consequential: the board passes speech to your bot unchanged, so whatever the bot can do with its permissions, voice can trigger. The README asks you to keep the backend on the LAN, with a separate guide for server deployment that binds to localhost and enables a device allowlist. Notably, go-music-dl listens on all interfaces on port 18080, so other LAN devices can search and download while the backend runs.

Who should try it

Good fit: a developer or tinkerer who already has an always-on Mac, a Grok bot with a webhook that can write files to that machine, and a Waveshare 1.75C or LCKFB ESP32-S3 board. The animated eyes and touch/tilt reactions are a reason to pick this over a plain speaker, and you should be comfortable running a local backend and accepting that voice inherits the bot's permissions.

Poor fit: anyone without an always-on computer, or anyone expecting a self-contained appliance. The board alone cannot complete the loop. A bot without webhook and file-write support will not deliver replies back. The M5Stack StopWatch target compiles but has not been run on hardware according to the README.

Requirements and limitations

You need a supported board, a 2.4GHz LAN, and an always-on computer (Apple silicon Mac is the verified setup) or a public server configured per the deployment guide. The first-time backend install downloads roughly 200MB of speech models and asks for the bot webhook address. Flashing is done through a browser-based installer, with a manual build path for those who skip the web flow.

Ongoing upkeep matters. Replies depend on the bot writing to the PC, so the webhook address and token must be kept in private/ and handled carefully. If you enable local music, you maintain go-music-dl and mpv under local-music/, and NetEase member tracks need a scanned login whose cookie lives outside Git. The project also depends on upstreams that move; the recorded baseline helps, but you will be resolving merges yourself.

HotRepo's take

HotRepo first tracked this repository at 8 days old and recorded it on the NEW-REPOSITORY board (cpp) at #25 with 220 total stars on 2026-10-25. That is a snapshot from a two-day sample, not a daily growth series, so persistence cannot be judged. Before committing, read the project's usage guide and confirm your bot can write replies to the backend machine.