Bundle mission speech with an admin mute option and fix live audio downloads

docs/welcome-voice-test.md

@@ -1,6 +1,6 @@
 # Welcome briefing
 
-The optional welcome plays once per authenticated account in the running server
+The bundled welcome plays once per authenticated account in the running server
 game session, after a controlled character exists, loading releases audio and
 the player closes the menus. The server records permission before the client
 downloads the greeting, so a crash, reconnect or return through the main menu
@@ -16,7 +16,27 @@ Requests are skipped while the engine HTTP service is disabled (including native
 `-noBackend` diagnostics).
 An empty URL disables downloading instead of requesting an empty address.
 
-The dynamic briefing names the **loaded terrain**, not a saved next-round choice,
+The default welcome is a bundled generic recording and contains no terrain or
+weather claims. The addon includes 37 prerecorded messages: the welcome, ten
+extraction-radio lines, and 26 soldier lines. They need no speech service,
+credentials, HTTP downloads, or PCM reconstruction during play. Recordings use
+the existing Algenib voice, with their scripts and hashes in
+[`bundled-speech.json`](bundled-speech.json) and
+[`bundled-speech-assets.json`](bundled-speech-assets.json). Their combined PCM
+source size is about 6.9 MB. Event-specific wording still requires the appropriate
+gameplay event; the bank does not manufacture contact, rescue, or weather facts.
+
+An administrator can explicitly opt into a live welcome using **TTS → Test &
+enable**. **Disable live TTS** restores the bundled welcome source.
+**TTS → Prerecorded speech → On / Off** controls all bundled welcome, soldier,
+and extraction recordings for everyone. It defaults to On, saves immediately as
+`voice.recordingsEnabled`, survives restarts, and stops bundled audio already
+playing when switched Off. Text announcements remain visible. The optional live
+welcome has its own setting. The `voice.bundledSpeech`
+preference defaults to true, including for existing configurations without that
+field. Live bridge credentials alone do not disable the bundled default.
+
+The optional dynamic briefing names the **loaded terrain**, not a saved next-round choice,
 and says the escape was generated for it. It reports the game's current weather
 and its next known weather state when different. It gives no invented time or
 forecast for an unknown custom weather state. The server checks for changes once
@@ -83,6 +103,26 @@ The existing `/welcome.b64` and `/welcome.wav` endpoints remain supported.
 recording to the new voice, regenerate it once. Dynamic cache entries include
 the text, voice, model, prompt and endpoint in their identity.
 
+Speech downloads use sequential `?part=N` requests on the `.b64` URL. Each
+response contains at most 256 KiB of encoded audio plus a small JSON envelope
+(`offset`, `total`, `data`), below the engine's REST response limit. The client
+checks part order, exact sizes and a consistent total, then runs the existing
+bounded WAV preparation. Audio bytes, quality and duration are unchanged; old
+cached clips need no regeneration. At most eleven parts can form a 2 MiB WAV.
+An invalid part or failed request cancels the transfer without playing partial
+audio. The original full-download URLs remain available for older clients.
+
+Deploy the updated helper before the addon containing the chunked downloader.
+Restart only the speech helper to activate its new endpoint. The addon update
+is still required on the mission and clients; updating the helper alone does not
+fix an older client's oversized downloads. Existing external speech helpers must
+implement the same part response protocol.
+
+The opt-in native `speech-download` fixture uses an explicit loopback
+`--speech-probe-url`, real REST callbacks, queued decoding and a native playback
+handle. Compare its `speech-downloaded.wav` with the served clip for exact byte
+integrity. It does not prove audible multiplayer playback.
+
 ## Enable the dynamic briefing
 
 Log in as administrator, open the mission menu from Escape, and select **TTS**.
@@ -127,20 +167,16 @@ Alternatively, edit only the `voice` section of the dedicated server's
 }
 ```
 
-The saved service is verified at mission startup before replacing `welcomeUrl`.
-Restart after installing the
-updated mod and speech helper. Merely republishing the mod does not upgrade an
-already-running external helper or give it Google credentials. If the bridge
-fails, the game keeps the original `welcomeUrl` recording, if configured, and
-shows the failure in the TTS page. With no original recording it remains silent.
-An unavailable service does not block gameplay. Startup verification may delay
-the optional welcome while the request is pending (up to 100 seconds).
+Bundled playback starts immediately once the normal welcome readiness checks
+pass. A saved explicit live preference (`bundledSpeech: false`) verifies its
+service at startup; unavailable live speech falls back to the generic bundled
+welcome. The admin test saves the live preference only after verification.
+Disable keeps the bridge address/token but saves the bundled preference.
 
-For the old fixed recording, leave the bridge fields absent/empty and keep
-`welcomeUrl` pointing at a public `.b64` clip. It gains the connection-scoped
-playback fix, but its spoken terrain/weather cannot change. Unconfigured TTS makes
-no requests and leaves this behavior unchanged. For compatibility, existing
-complete bridge settings without `ttsEnabled` are treated as enabled.
+Installing the addon supplies the recordings to every player. The external
+helper is needed only for optional live speech and its admin preview. Legacy
+`welcomeUrl` settings are preserved in the profile; the generic bundled welcome
+is now the default and failure fallback.
 
 Mission code can use the server-only `mode.ERR_Speech().Request(text, receiver)`
 entry point after verification. It returns false when unavailable, busy, or
@@ -269,31 +305,25 @@ contact/engaging events with a confirmed visible count or observed approach.
 Other detailed orders and radio transmissions stay native. There are no generic
 HQ announcements. Calm groups can now have the short exchanges described below.
 
-A supported callout near a living player prepares its TTS line if the verified
-bridge is idle. New preparations are spaced at least 65 seconds apart to respect
-the bridge's synthesis limit. The first occurrences therefore remain native;
-the generated vocabulary fills gradually as those events occur. Server and
-bridge caches reuse repeated text. Subsequent calls advertise the prepared
-clip to nearby clients, which download, validate and prepare a spatial graph.
+A supported callout near a living player selects its bundled recording. Nearby
+clients initialize its native spatial graph without synthesis or downloading.
 The server replaces a call only after **every nearby living player** has
 acknowledged readiness for that exact clip in the current mission. Otherwise
-the entire allowed native call uses normal native audio. Covert calls are silent
-including their stock fallback; added conversations wait for prepared clips.
-No player request can start synthesis.
+the allowed call uses native audio. Covert calls remain silent, including their
+stock fallback; conversations still require both sides to be ready. Unknown
+callout types and radio transmissions remain native.
 
-Generated direct speech uses `AudioSystem.PlayEvent` with a runtime audio graph
-and the soldier's transform. Playback follows the soldier near head height,
-stops on death or loss of a nearby living listener, and has an 80 metre delivery
-limit and twelve second lifetime. Up to eight actors can speak concurrently.
-Generated clips are not transmitted as native VoN audio, and this version does
-not reproduce native radio filtering or all environmental occlusion. It must
-not be described as full native voice replacement. TTS credentials remain on
-the server; clients receive only public clip URLs and speaker replication IDs.
-Unconfigured/disabled TTS leaves native soldier speech and the welcome unchanged.
+Direct speech uses `AudioSystem.PlayEvent` at the soldier's transform. Playback
+follows the soldier near head height, stops on death or loss of a nearby living
+listener, and keeps the existing 80 metre delivery limit, twelve second lifetime
+and eight simultaneous actor limit. These are local audio graphs, not native
+VoN transmission, and are not a full replacement for native radio filtering or
+all environmental occlusion. Disabling the optional live TTS service does not
+disable bundled speech.
 
 Verification: production policy tests cover all-client readiness, fallback,
 actual-event mapping, radio exclusion, range, unavailable service, changed URL
-and preparation failure. A hidden client using a null audio sink prepared the
+and preparation failure. Earlier live-download validation: a hidden client using a null audio sink prepared the
 production runtime graph and recorded the existing Google WAV with strong left
 and right separation at five metres. Playback at 500 metres returned an invalid
 handle and the recording was silent after the preceding clip finished. The
@@ -307,14 +337,14 @@ historical. It proves radio recipient routing, not native soldier voice playback
 
 ## Context and conversations (5 October follow-up)
 
-When optional TTS is verified and enabled, the comms handler suppresses direct
+The comms handler suppresses direct
 and radio callouts while an alerted group has not opened fire or come under
 fire. This is a conservative proxy for being discovered, not a claim to know
 what a player has noticed. Own projectile events and incoming bullet impacts
 or flybys permit combat calls for 20 seconds; mere sightings, aiming and distant
 gunshots do not. Recent perceived enemies keep casual chatter suppressed for
 at least 60 seconds after the last threat observation. Disabling/unconfiguring
-TTS preserves native speech; this feature does not change combat decisions.
+Missing bundled clips preserve allowed native speech; this feature does not change combat decisions.
 
 Reports count distinct currently visible, living enemy characters in the
 speaker's own native perception, without enumerating players or inspecting
@@ -336,7 +366,7 @@ can take several eligible encounters to become audible. This is contextual
 scripted dialogue voiced by Google TTS, not an LLM generating conversations.
 
 Validation for this follow-up: production-method regression harnesses cover
-stealth fallback, disabled settings, count/motion sampling, two-clip readiness,
+stealth fallback, offline bundled playback, count/motion sampling, two-clip readiness,
 reply cancellation and cooldowns. The complete mod compiled and loaded in the
 isolated Nogova dedicated fixture without script errors. No live server restart,
 Workshop publication or end-to-end multiplayer conversation test was performed.