[tronikos]

2.5.2 stopped excluding *.onnx from backups because the new web interface can upload custom voices into /data, and an uploaded voice exists nowhere else. That is right for uploads, but it also put catalog voices back into every backup: a single model is 20–110 MB, and the app downloads it again from HuggingFace whenever it is missing.

By default, wyoming-piper uses --download-dir both for downloading catalog voices (wyoming_piper.download.ensure_voice_exists) and for saving custom voices uploaded through the web UI (wyoming_piper.web_server.make_web_server). To separate the two without losing uploads or keeping newly downloaded catalog voices in backups until the next restart:

1. Store catalog voices in /data/catalog_voices, which config.yaml excludes from backups and which is passed to wyoming-piper as an additional --data-dir (after /data, so a custom voice in /data with a catalog name still takes precedence).
2. Wrap wyoming_piper.download.ensure_voice_exists when launching wyoming-piper so catalog voices downloaded at startup or on demand while the app runs are written directly to /data/catalog_voices, while --download-dir remains /data for web UI uploads, voices.json, and HF_HOME.
3. At startup, move any catalog voices already in /data (e.g. from 2.5.2, or uploaded unmodified through the web UI) to /data/catalog_voices when both .onnx and .onnx.json match the md5 digests in the catalog. Custom voices—including fine-tunes that reuse a catalog voice name—stay in /data and stay in backups.

Supersedes home-assistant/apps#4829.

[Copilot]

🔵 Needs a closer look

Voice lookup still selects an existing zero-byte uploaded model over the healthy downloaded pair, causing synthesis to fail.

No open issues 🎉

What changed in this PR

This PR separates re-downloadable Piper catalog voices from custom uploads to reduce backup size while preserving uploaded voices.

Changes:

• Redirect catalog downloads to /data/catalog_voices and exclude that directory from backups.
• Move existing voice pairs only when both files match catalog hashes.
• Preserve /data for uploads and document backup and restore behavior.

File	Description
piper/​rootfs/​usr/​local/​bin/​sort_catalog_voices.py	Adds hash-based migration and catalog download redirection.
piper/​rootfs/​etc/​s6-overlay/​s6-rc.d/​piper/​run	Runs migration and launches Piper with the separate catalog directory.
piper/​DOCS.md	Explains backup exclusions and custom voice preservation.
piper/​config.yaml	Excludes the catalog voice directory from backups.

_{Review effort: Balanced}