Support local-only mode

Author: thespad

README.md

@@ -84,6 +84,7 @@ services:
       - PGID=1000
       - TZ=Etc/UTC
       - PIPER_VOICE=en_US-lessac-medium
+      - LOCAL_ONLY= #optional
       - PIPER_LENGTH=1.0 #optional
       - PIPER_NOISE=0.667 #optional
       - PIPER_NOISEW=0.333 #optional
@@ -106,6 +107,7 @@ docker run -d \
   -e PGID=1000 \
   -e TZ=Etc/UTC \
   -e PIPER_VOICE=en_US-lessac-medium \
+  -e LOCAL_ONLY= `#optional` \
   -e PIPER_LENGTH=1.0 `#optional` \
   -e PIPER_NOISE=0.667 `#optional` \
   -e PIPER_NOISEW=0.333 `#optional` \
@@ -129,6 +131,7 @@ Containers are configured using parameters passed at runtime (such as those abov
 | `-e PGID=1000` | for GroupID - see below for explanation |
 | `-e TZ=Etc/UTC` | specify a timezone to use, see this [list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). |
 | `-e PIPER_VOICE=en_US-lessac-medium` | The [Piper voice](https://huggingface.co/rhasspy/piper-voices/tree/main) to use, in the format `<language>-<name>-<quality>` |
+| `-e LOCAL_ONLY=` | If set to `true`, or any other value, the container will not attempt to download models from HuggingFace and will only use locally-provided models. |
 | `-e PIPER_LENGTH=1.0` | Voice speaking rate, 1.0 is default with < 1.0 being faster and > 1.0 being slower. |
 | `-e PIPER_NOISE=0.667` | Controls the variability of the voice by adding noise. Values above 1 will start to degrade audio. |
 | `-e PIPER_NOISEW=0.333` | Controls the variability of speaking cadence. Values above 1 produce extreme stutters and pauses. |
@@ -300,6 +303,7 @@ Once registered you can define the dockerfile to use with `-f Dockerfile.aarch64
 
 ## Versions
 
+* **29.08.25:** - Add support for local only mode.
 * **10.08.25:** - Add streaming support.
 * **18.07.24:** - Rebase to Ubuntu Noble.
 * **25.11.23:** - Initial Release.

readme-vars.yml

@@ -30,6 +30,7 @@ param_ports:
 # optional container parameters
 opt_param_usage_include_env: true
 opt_param_env_vars:
+  - {env_var: "LOCAL_ONLY", env_value: "", desc: "If set to `true`, or any other value, the container will not attempt to download models from HuggingFace and will only use locally-provided models."}
   - {env_var: "PIPER_LENGTH", env_value: "1.0", desc: "Voice speaking rate, 1.0 is default with < 1.0 being faster and > 1.0 being slower."}
   - {env_var: "PIPER_NOISE", env_value: "0.667", desc: "Controls the variability of the voice by adding noise. Values above 1 will start to degrade audio."}
   - {env_var: "PIPER_NOISEW", env_value: "0.333", desc: "Controls the variability of speaking cadence. Values above 1 produce extreme stutters and pauses."}
@@ -86,6 +87,7 @@ init_diagram: |
   "piper:latest" <- Base Images
 # changelog
 changelogs:
+  - {date: "29.08.25:", desc: "Add support for local only mode."}
   - {date: "10.08.25:", desc: "Add streaming support."}
   - {date: "18.07.24:", desc: "Rebase to Ubuntu Noble."}
   - {date: "25.11.23:", desc: "Initial Release."}

root/etc/s6-overlay/s6-rc.d/svc-piper/run

@@ -1,6 +1,12 @@
 #!/command/with-contenv bash
 # shellcheck shell=bash
 
+unset UPDATE_MODELS
+
+if [[ -z ${LOCAL_ONLY} ]]; then
+    UPDATE_MODELS=true
+fi
+
 exec \
     s6-notifyoncheck -d -n 300 -w 1000 -c "nc -z localhost 10200" \
         s6-setuidgid abc python3 -m wyoming_piper \
@@ -13,5 +19,6 @@ exec \
         --voice "${PIPER_VOICE}" \
         --max-piper-procs "${PIPER_PROCS:-1}" \
         --data-dir /config \
-        --download-dir /config --update-voices \
+        --download-dir /config \
+        ${UPDATE_MODELS:+--update-voices} \
         ${STREAMING:+--streaming}