Skip to content

feat: mirror voice packs for robots without internet access - #259

Closed
jipjan wants to merge 4 commits into
Python-roborock:mainfrom
jipjan:feat/voice-pack-mirror
Closed

jipjan wants to merge 4 commits into
Python-roborock:mainfrom
jipjan:feat/voice-pack-mirror

Conversation

@jipjan

@jipjan jipjan commented Nov 14, 2026

Copy link
Copy Markdown

What

Changing the robot's voice sends dnld_install_sound with a URL from Roborock's voice-pack list. A robot whose internet access is blocked, as it usually is with this server, cannot download from Roborock, so voice changes fail.

This adds a small mirror:

  • GET /voice-pkg/<bucket>/info returns Roborock's list for a product (e.g. vida for the Saros 20 Neo, a295/a296) with every pack, picture and preview URL pointing at this server.
  • GET /voice-pkg/<bucket>/{package,pic,wav}/<file> serves a file: fetched from Roborock the first time, checked against the storage ETag (an MD5), and kept under <data_dir>/voice_packs/. The first list request also downloads the whole bucket in the background, so later changes need no internet.
  • New [voice_packs] mode: mirror (default), offline (serve stored copies only, never contact Roborock) or disabled (routes return 404). The Home Assistant add-on gets the same choice as voice_packs_mode.
  • Docs: docs/voice_packs.md, linked from the README, docs index and the example config.

Like the cloud import and plugin proxy, mirror mode talks to Roborock's servers; offline and disabled are there for anyone who doesn't want that.

The official app still reads the list from Roborock directly, so it keeps sending Roborock's URLs; a client has to use this list for the robot to download locally. (LocalRock does.)

Abuse limits

The routes are public, like Roborock's own copies, because the robot downloads without credentials. To keep them from being used to make the server fetch arbitrary things:

  • Bucket and file names are validated, and the upstream host is fixed by region.
  • Only files named in a stored list are fetched.
  • At most 8 buckets are mirrored.
  • Downloads are read in chunks and capped (64 MB per file, 2 MB per list).
  • Refusals and failed list refreshes are not retried for 10 minutes.
  • Republished packs (new md5/version in the list) are downloaded again.
  • The prefetch task is tracked, logged, and cancelled on stop.

Testing

  • tests/test_voice_packs.py: URL rewriting, name validation, fetch-once, offline mode, port handling, disabled mode, back-off, cap, corrupt list, republished package. Plus config and add-on tests.
  • Full suite passes.
  • On a Saros 20 Neo (a296) whose WAN is blocked: switched voices to English (UK) and Danish and back to Dutch through the mirror; the robot downloaded each pack from the local server and spoke it.

🤖 Generated with Claude Code

jipjan and others added 4 commits November 14, 2026 22:40
The official app installs a voice pack by sending the robot a Roborock URL
(dnld_install_sound), which a robot cut off from the internet cannot reach.
The server now serves /voice-pkg/<bucket>/info, Roborock's list with every
URL pointing at this server, and /voice-pkg/<bucket>/<package|pic|wav>/<file>,
fetched from Roborock once, checked against the list's MD5 and kept under
<data_dir>/voice_packs. The first request for a list also stores every pack.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The list's voice_pkg_md5 is not the MD5 of the file Roborock serves (an a296
nl.pkg hashes to its ETag, 75bcab..., the list says 71737e...); the robot
checks it after unpacking. It is passed on untouched, and the download is
checked against Roborock's ETag instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- [voice_packs] mode = mirror (default) | offline | disabled, also as the
  Home Assistant add-on option voice_packs_mode. offline serves only stored
  copies and never contacts Roborock; disabled answers 404.
- Rewritten list URLs carry the advertised HTTPS port when it is not 443.
- docs/voice_packs.md: how the mirror works, buckets, how a client uses it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Every file, not only packages, must be in the stored list before it is
  fetched; at most 8 buckets are mirrored.
- Downloads are read in chunks and refused past 64 MB (lists 2 MB); lists
  use a 15 s timeout.
- Refused files and failed list refreshes are not retried for 10 minutes,
  so a down Roborock no longer stalls every list request.
- A corrupt stored list is replaced; disk errors answer 507 instead of 500.
- A package is fetched again when the list shows a new md5/version for it.
- The prefetch task is kept, logged, retried after a failure and cancelled
  on stop. An unknown region is logged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jipjan jipjan closed this Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant