@oneciel-ai/ciel-runtime 0.2.12 → 0.2.13

package/ciel_runtime_support/config_repository.py

@@ -37,6 +37,7 @@ def build_default_config(provider_defaults: dict[str, Any]) -> dict[str, Any]:
                 "tts_session": "ciel-tts",
                 "asr_accelerator": "T4",
                 "tts_accelerator": "T4",
+                "tts_backend": "moss",
             },
             "asr": {
                 "enabled": False,
@@ -63,6 +64,8 @@ def build_default_config(provider_defaults: dict[str, Any]) -> dict[str, Any]:
                 "response_format": "wav",
                 "speed": 1.0,
                 "auto_speak": False,
+                "streaming": False,
+                "sample_rate": 48000,
                 "api_key": "",
                 "timeout_seconds": 300,
             },

package/ciel_runtime_support/runtime_constants.py

@@ -93,7 +93,7 @@ OFFICIAL_CHANNEL_PLUGINS = {
 }
 
 APP_NAME = "Ciel Runtime"
-VERSION = "0.2.12"
+VERSION = "0.2.13"
 CREDITS = "Credits: One Ciel LLC"
 PRELAUNCH_CANCEL = 10
 PRELAUNCH_LAUNCH_CODEX = 11

package/ciel_runtime_support/speech_http_controller.py

@@ -204,12 +204,14 @@ class SpeechHttpController:
     def _validated_value(service: str, key: str, value: Any) -> Any:
         allowed = {
             "asr": {"enabled", "base_url", "endpoint", "model", "language", "silence_ms", "min_speech_ms", "vad_threshold", "api_key", "timeout_seconds"},
-            "tts": {"enabled", "base_url", "endpoint", "voices_endpoint", "model", "voice", "language", "ref_audio", "ref_text", "response_format", "speed", "auto_speak", "api_key", "timeout_seconds"},
+            "tts": {"enabled", "base_url", "endpoint", "voices_endpoint", "model", "voice", "language", "ref_audio", "ref_text", "response_format", "speed", "auto_speak", "streaming", "sample_rate", "api_key", "timeout_seconds"},
         }
         if key not in allowed[service]:
             raise ValueError(f"unsupported {service} setting: {key}")
-        if key in {"enabled", "auto_speak"}:
+        if key in {"enabled", "auto_speak", "streaming"}:
             return bool(value)
+        if key == "sample_rate":
+            return max(8000, min(192000, int(value)))
         if key == "timeout_seconds":
             return max(1, min(3600, int(value)))
         if key == "speed":
@@ -256,6 +258,7 @@ class SpeechHttpController:
             "tts_session",
             "asr_accelerator",
             "tts_accelerator",
+            "tts_backend",
         }
         if key not in allowed:
             raise ValueError(f"unsupported colab setting: {key}")
@@ -272,6 +275,11 @@ class SpeechHttpController:
             if accelerator not in {"T4", "L4", "G4", "A100", "H100"}:
                 raise ValueError("unsupported Colab accelerator")
             return accelerator
+        if key == "tts_backend":
+            backend = text.lower()
+            if backend not in {"moss", "cosyvoice3"}:
+                raise ValueError("unsupported Colab TTS backend")
+            return backend
         if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}", text):
             raise ValueError(f"invalid Colab {key}")
         return text
@@ -329,6 +337,7 @@ class SpeechHttpController:
 
     def _proxy_tts(self, handler: BaseHTTPRequestHandler, raw: bytes, content_type: str, *, batch: bool) -> bool:
         config = self._service_config("tts")
+        streaming = False
         if not self._require_enabled(handler, "tts", config):
             return True
         if "application/json" in content_type.lower():
@@ -344,14 +353,17 @@ class SpeechHttpController:
                         body.setdefault("ref_audio", str(config["ref_audio"]))
                     if str(config.get("ref_text") or "").strip():
                         body.setdefault("ref_text", str(config["ref_text"]))
+                    if "CosyVoice3" in str(body.get("model") or "") and (not str(body.get("ref_audio") or "").strip() or not str(body.get("ref_text") or "").strip()):
+                        raise ValueError("CosyVoice 3 requires both ref_audio and its exact ref_text transcript")
                     body.setdefault("response_format", str(config.get("response_format") or "wav"))
                     body.setdefault("speed", float(config.get("speed") or 1.0))
+                    streaming = bool(body.get("stream") and body.get("stream_format") == "audio")
                 raw = json.dumps(body, ensure_ascii=False).encode("utf-8")
             except (ValueError, TypeError, UnicodeError) as exc:
                 self.ports.write_json(handler, {"error": {"type": "invalid_request_error", "message": str(exc)}}, 400)
                 return True
         endpoint = str(config.get("endpoint") or "/v1/audio/speech") + ("/batch" if batch else "")
-        return self._proxy_bytes(handler, "tts", config, endpoint, raw, content_type)
+        return self._proxy_bytes(handler, "tts", config, endpoint, raw, content_type, streaming=streaming)
 
     def _proxy_raw(self, handler: BaseHTTPRequestHandler, service: str, endpoint_key: str, raw: bytes, content_type: str) -> bool:
         config = self._service_config(service)
@@ -359,14 +371,38 @@ class SpeechHttpController:
             return True
         return self._proxy_bytes(handler, service, config, str(config.get(endpoint_key) or ""), raw, content_type)
 
-    def _proxy_bytes(self, handler: BaseHTTPRequestHandler, service: str, config: SpeechConfig, endpoint: str, raw: bytes, content_type: str) -> bool:
+    def _proxy_bytes(self, handler: BaseHTTPRequestHandler, service: str, config: SpeechConfig, endpoint: str, raw: bytes, content_type: str, *, streaming: bool = False) -> bool:
         request = urllib.request.Request(
             self._url(config, endpoint),
             data=raw,
             headers=self._headers(config, content_type or "application/octet-stream"),
             method="POST",
         )
-        return self._open_and_write(handler, service, config, request)
+        return self._open_and_stream(handler, service, config, request) if streaming else self._open_and_write(handler, service, config, request)
+
+    def _open_and_stream(self, handler: BaseHTTPRequestHandler, service: str, config: SpeechConfig, request: urllib.request.Request) -> bool:
+        started = False
+        try:
+            with self.ports.urlopen(request, timeout=self._timeout(config)) as response:
+                handler.send_response(int(getattr(response, "status", 200)))
+                handler.send_header("content-type", str(response.headers.get("content-type") or "audio/pcm"))
+                handler.send_header("cache-control", "no-store")
+                handler.send_header("connection", "close")
+                handler.end_headers()
+                started = True
+                handler.close_connection = True
+                read_chunk = getattr(response, "read1", response.read)
+                while chunk := read_chunk(16 * 1024):
+                    handler.wfile.write(chunk)
+                    handler.wfile.flush()
+        except urllib.error.HTTPError as exc:
+            if not started:
+                self._write_bytes(handler, exc.read(), int(exc.code), str(exc.headers.get("content-type") or "application/json"))
+        except Exception as exc:
+            self.ports.log("ERROR", f"speech_stream_failed service={service} error={type(exc).__name__}: {exc}")
+            if not started:
+                self.ports.write_json(handler, {"error": {"type": "upstream_error", "message": f"{service.upper()} upstream unavailable: {exc}"}}, 502)
+        return True
 
     def _open_and_write(self, handler: BaseHTTPRequestHandler, service: str, config: SpeechConfig, request: urllib.request.Request) -> bool:
         try:

package/ciel_runtime_support/web_ui.py

@@ -238,12 +238,14 @@ def render_web_chat_page(
           <div class="settings-grid">
             <label class="check"><input id="ttsEnabled" type="checkbox"> Enable TTS</label>
             <label class="check"><input id="ttsAutoSpeak" type="checkbox"> Speak replies automatically</label>
+            <label class="check"><input id="ttsStreaming" type="checkbox"> Stream audio while it is generated</label>
             <label class="wide">Tailscale base URL<input id="ttsBaseUrl" placeholder="http://ciel-tts:8091"></label>
             <label>Voice<input id="ttsVoice" placeholder="default"></label>
             <label>Language<input id="ttsLanguage" placeholder="ko"></label>
+            <label>PCM sample rate<input id="ttsSampleRate" type="number" min="8000" max="192000" step="1000"></label>
             <label class="wide">Model<input id="ttsModel" placeholder="OpenMOSS-Team/MOSS-TTS-Nano"></label>
             <label class="wide">Reference voice (required by MOSS-TTS-Nano)<input id="ttsReferenceAudio" type="file" accept="audio/*"><span class="hint" id="ttsReferenceAudioStatus">No reference voice configured</span></label>
-            <label class="wide">Reference transcript (optional)<input id="ttsReferenceText" placeholder="Transcript of the reference clip"></label>
+            <label class="wide">Reference transcript (required by CosyVoice 3)<input id="ttsReferenceText" placeholder="Exact transcript of the reference clip"></label>
             <label class="check wide"><input id="ttsClearReferenceAudio" type="checkbox"> Remove the saved reference voice</label>
             <label class="wide">Remote bearer token<input id="ttsApiKey" type="password" autocomplete="new-password" placeholder="Leave blank to keep current token"></label>
           </div>
@@ -255,6 +257,7 @@ def render_web_chat_page(
             <label>WSL distribution<input id="colabDistribution" placeholder="Ubuntu-26.04"></label>
             <label>Authentication<select id="colabAuth"><option value="adc">ADC</option><option value="oauth2">OAuth2</option></select></label>
             <label>Account profile<input id="colabProfile" placeholder="default"></label>
+            <label>TTS engine<select id="colabTtsBackend"><option value="moss">MOSS-TTS-Nano</option><option value="cosyvoice3">Fun-CosyVoice 3</option></select></label>
             <label>ASR session<input id="colabAsrSession" placeholder="ciel-asr"></label>
             <label>TTS session<input id="colabTtsSession" placeholder="ciel-tts"></label>
             <label>ASR GPU<select id="colabAsrAccelerator"><option>T4</option><option>L4</option><option>G4</option><option>A100</option><option>H100</option></select></label>
@@ -276,7 +279,7 @@ def render_web_chat_page(
           </div>
           <div class="hint">The browser calls Ciel locally. Only the Ciel router connects to these Tailscale services.</div>
         </section>
-        <div class="settings-actions"><button class="ghost" id="speechHealthButton" type="button">Test connections</button><button class="primary" type="submit">Save</button></div>
+        <div class="settings-actions"><button class="ghost" id="speechHealthButton" type="button">Test connections</button><button class="ghost" id="speechPlaybackTestButton" type="button">Test voice</button><button class="primary" type="submit">Save</button></div>
       </div>
     </form>
   </dialog>
@@ -312,6 +315,7 @@ def render_web_chat_page(
     const speechSettingsForm = document.getElementById('speechSettingsForm');
     const speechSettingsClose = document.getElementById('speechSettingsClose');
     const speechHealthButton = document.getElementById('speechHealthButton');
+    const speechPlaybackTestButton = document.getElementById('speechPlaybackTestButton');
     const statePill = document.getElementById('statePill');
     const SESSION_KEY = 'ciel-runtime-web-chat-session';
     const LAST_ID_KEY = 'ciel-runtime-web-chat-last-id';
@@ -357,6 +361,9 @@ def render_web_chat_page(
     let liveUtteranceSerial = 0;
     let activeSpeechAudio = null;
     let activeSpeechUrl = '';
+    let speechPlaybackContext = null;
+    let activeSpeechSource = null;
+    const activeSpeechSources = new Set();
     let speechGenerationController = null;
     let pendingTtsReferenceAudio = '';
     function setState(text, cls = '') {{
@@ -739,10 +746,12 @@ def render_web_chat_page(
       document.getElementById('asrApiKey').placeholder = asr.api_key_set ? 'Token is set; leave blank to keep it' : 'Optional remote bearer token';
       document.getElementById('ttsEnabled').checked = Boolean(tts.enabled);
       document.getElementById('ttsAutoSpeak').checked = Boolean(tts.auto_speak);
+      document.getElementById('ttsStreaming').checked = Boolean(tts.streaming);
       document.getElementById('ttsBaseUrl').value = tts.base_url || '';
       document.getElementById('ttsModel').value = tts.model || '';
       document.getElementById('ttsVoice').value = tts.voice || 'default';
       document.getElementById('ttsLanguage').value = tts.language || 'ko';
+      document.getElementById('ttsSampleRate').value = tts.sample_rate || 48000;
       document.getElementById('ttsReferenceText').value = tts.ref_text || '';
       document.getElementById('ttsReferenceAudioStatus').textContent = tts.ref_audio_set ? 'Reference voice saved securely on this Ciel router' : 'No reference voice configured';
       document.getElementById('ttsClearReferenceAudio').checked = false;
@@ -754,6 +763,7 @@ def render_web_chat_page(
       document.getElementById('colabDistribution').value = colab.distribution || 'Ubuntu-26.04';
       document.getElementById('colabAuth').value = colab.auth || 'adc';
       document.getElementById('colabProfile').value = colab.profile || 'default';
+      document.getElementById('colabTtsBackend').value = colab.tts_backend || (String(tts.model || '').includes('CosyVoice3') ? 'cosyvoice3' : 'moss');
       document.getElementById('colabAsrSession').value = colab.asr_session || 'ciel-asr';
       document.getElementById('colabTtsSession').value = colab.tts_session || 'ciel-tts';
       document.getElementById('colabAsrAccelerator').value = colab.asr_accelerator || 'T4';
@@ -790,10 +800,12 @@ def render_web_chat_page(
         tts: {{
           enabled: document.getElementById('ttsEnabled').checked,
           auto_speak: document.getElementById('ttsAutoSpeak').checked,
+          streaming: document.getElementById('ttsStreaming').checked,
           base_url: document.getElementById('ttsBaseUrl').value,
           model: document.getElementById('ttsModel').value,
           voice: document.getElementById('ttsVoice').value,
           language: document.getElementById('ttsLanguage').value,
+          sample_rate: Number(document.getElementById('ttsSampleRate').value || 48000),
           ref_audio: pendingTtsReferenceAudio,
           ref_text: document.getElementById('ttsReferenceText').value,
           clear_ref_audio: document.getElementById('ttsClearReferenceAudio').checked,
@@ -804,6 +816,7 @@ def render_web_chat_page(
           distribution: document.getElementById('colabDistribution').value,
           auth: document.getElementById('colabAuth').value,
           profile: document.getElementById('colabProfile').value,
+          tts_backend: document.getElementById('colabTtsBackend').value,
           asr_session: document.getElementById('colabAsrSession').value,
           tts_session: document.getElementById('colabTtsSession').value,
           asr_accelerator: document.getElementById('colabAsrAccelerator').value,
@@ -864,9 +877,22 @@ def render_web_chat_page(
       setTimeout(() => pollColabJob().catch(() => {{}}), 1000);
       return data;
     }}
+    function unlockSpeechPlayback() {{
+      const AudioContextClass = window.AudioContext || window.webkitAudioContext;
+      if (!AudioContextClass) return null;
+      if (!speechPlaybackContext || speechPlaybackContext.state === 'closed') speechPlaybackContext = new AudioContextClass();
+      if (speechPlaybackContext.state === 'suspended') speechPlaybackContext.resume().catch(() => {{}});
+      return speechPlaybackContext;
+    }}
     function stopActiveSpeech() {{
       if (speechGenerationController) speechGenerationController.abort();
       speechGenerationController = null;
+      if (activeSpeechSource) {{
+        try {{ activeSpeechSource.stop(); }} catch {{}}
+        activeSpeechSource = null;
+      }}
+      activeSpeechSources.forEach(source => {{ try {{ source.stop(); }} catch {{}} }});
+      activeSpeechSources.clear();
       if (activeSpeechAudio) {{
         activeSpeechAudio.pause();
         activeSpeechAudio.currentTime = 0;
@@ -875,6 +901,87 @@ def render_web_chat_page(
       if (activeSpeechUrl) URL.revokeObjectURL(activeSpeechUrl);
       activeSpeechUrl = '';
     }}
+    async function playSpeechBlob(blob) {{
+      const context = speechPlaybackContext;
+      if (context && context.state === 'running') {{
+        try {{
+          const audioBuffer = await context.decodeAudioData(await blob.arrayBuffer());
+          const source = context.createBufferSource();
+          source.buffer = audioBuffer;
+          source.connect(context.destination);
+          activeSpeechSource = source;
+          activeSpeechSources.add(source);
+          source.addEventListener('ended', () => {{
+            activeSpeechSources.delete(source);
+            if (activeSpeechSource === source) {{
+              activeSpeechSource = null;
+              setState(liveVoiceEnabled ? 'listening' : 'ready', 'ok');
+            }}
+          }}, {{once: true}});
+          source.start();
+          return;
+        }} catch {{}}
+      }}
+      activeSpeechUrl = URL.createObjectURL(blob);
+      activeSpeechAudio = new Audio(activeSpeechUrl);
+      const audio = activeSpeechAudio;
+      audio.preload = 'auto';
+      audio.playsInline = true;
+      const cleanup = () => {{
+        if (activeSpeechAudio === audio) {{
+          activeSpeechAudio = null;
+          if (activeSpeechUrl) URL.revokeObjectURL(activeSpeechUrl);
+          activeSpeechUrl = '';
+          setState(liveVoiceEnabled ? 'listening' : 'ready', 'ok');
+        }}
+      }};
+      audio.addEventListener('ended', cleanup, {{once: true}});
+      audio.addEventListener('error', cleanup, {{once: true}});
+      await audio.play();
+    }}
+    async function playPcmSpeechStream(response, controller, sampleRate) {{
+      const context = unlockSpeechPlayback();
+      if (context && context.state === 'suspended') await context.resume();
+      if (!context || context.state !== 'running' || !response.body) throw new Error('Browser audio is locked; click Test voice once to enable playback');
+      const reader = response.body.getReader();
+      let remainder = new Uint8Array(0);
+      let nextStart = context.currentTime + 0.06;
+      let received = false;
+      while (true) {{
+        const part = await reader.read();
+        if (part.done) break;
+        if (controller.signal.aborted) {{ await reader.cancel(); return; }}
+        let bytes = part.value;
+        if (remainder.length) {{
+          const joined = new Uint8Array(remainder.length + bytes.length);
+          joined.set(remainder);
+          joined.set(bytes, remainder.length);
+          bytes = joined;
+        }}
+        const usable = bytes.length - (bytes.length % 2);
+        remainder = usable < bytes.length ? bytes.slice(usable) : new Uint8Array(0);
+        if (!usable) continue;
+        const samples = usable / 2;
+        const audioBuffer = context.createBuffer(1, samples, sampleRate);
+        const channelData = audioBuffer.getChannelData(0);
+        const view = new DataView(bytes.buffer, bytes.byteOffset, usable);
+        for (let index = 0; index < samples; index += 1) channelData[index] = view.getInt16(index * 2, true) / 32768;
+        const source = context.createBufferSource();
+        source.buffer = audioBuffer;
+        source.connect(context.destination);
+        activeSpeechSources.add(source);
+        source.addEventListener('ended', () => {{
+          activeSpeechSources.delete(source);
+          if (!activeSpeechSources.size && !speechGenerationController) setState(liveVoiceEnabled ? 'listening' : 'ready', 'ok');
+        }}, {{once: true}});
+        const startsAt = Math.max(nextStart, context.currentTime + 0.03);
+        source.start(startsAt);
+        nextStart = startsAt + audioBuffer.duration;
+        if (!received) setState('speaking', 'ok');
+        received = true;
+      }}
+      if (!received) throw new Error('TTS returned an empty PCM stream');
+    }}
     async function speakText(text) {{
       if (!speechConfig.tts || !speechConfig.tts.enabled) {{
         setState('TTS disabled', 'error');
@@ -886,34 +993,28 @@ def render_web_chat_page(
       speechGenerationController = controller;
       try {{
         setState('generating speech');
+        const streamAudio = Boolean(speechConfig.tts.streaming);
+        const requestBody = {{input: String(text || ''), model: speechConfig.tts.model, voice: speechConfig.tts.voice, language: speechConfig.tts.language, response_format: streamAudio ? 'pcm' : (speechConfig.tts.response_format || 'wav')}};
+        if (streamAudio) Object.assign(requestBody, {{stream: true, stream_format: 'audio'}});
         const response = await fetch('/v1/audio/speech', {{
           method: 'POST',
           headers: {{'content-type': 'application/json', 'accept': 'audio/*'}},
-          body: JSON.stringify({{input: String(text || ''), model: speechConfig.tts.model, voice: speechConfig.tts.voice, language: speechConfig.tts.language, response_format: speechConfig.tts.response_format || 'wav'}}),
+          body: JSON.stringify(requestBody),
           signal: controller.signal,
         }});
         if (!response.ok) throw new Error(await response.text() || `HTTP ${{response.status}}`);
+        if (streamAudio) {{
+          await playPcmSpeechStream(response, controller, Number(speechConfig.tts.sample_rate || 24000));
+          speechGenerationController = null;
+          if (!activeSpeechSources.size) setState(liveVoiceEnabled ? 'listening' : 'ready', 'ok');
+          return;
+        }}
         const blob = await response.blob();
         if (!blob.size) throw new Error('TTS returned empty audio');
         if (blob.type && !blob.type.startsWith('audio/')) throw new Error(`TTS returned ${{blob.type}} instead of audio`);
         if (controller.signal.aborted) return;
         speechGenerationController = null;
-        activeSpeechUrl = URL.createObjectURL(blob);
-        activeSpeechAudio = new Audio(activeSpeechUrl);
-        const audio = activeSpeechAudio;
-        audio.preload = 'auto';
-        audio.playsInline = true;
-        const cleanup = () => {{
-          if (activeSpeechAudio === audio) {{
-            activeSpeechAudio = null;
-            if (activeSpeechUrl) URL.revokeObjectURL(activeSpeechUrl);
-            activeSpeechUrl = '';
-            if (liveVoiceEnabled) setState('listening', 'ok');
-          }}
-        }};
-        audio.addEventListener('ended', cleanup, {{once: true}});
-        audio.addEventListener('error', cleanup, {{once: true}});
-        await audio.play();
+        await playSpeechBlob(blob);
         setState('speaking', 'ok');
       }} catch (err) {{
         if (err && err.name === 'AbortError') return;
@@ -1313,6 +1414,8 @@ def render_web_chat_page(
         composer.requestSubmit();
       }}
     }});
+    document.addEventListener('pointerdown', unlockSpeechPlayback, {{capture: true}});
+    document.addEventListener('keydown', unlockSpeechPlayback, {{capture: true}});
     attachButton.addEventListener('click', () => fileInput.click());
     micButton.addEventListener('click', async () => {{
       if (liveVoiceEnabled) {{
@@ -1370,6 +1473,13 @@ def render_web_chat_page(
         addBubble('system', `Speech health — ASR: ${{asr && asr.reachable ? 'reachable' : asr && asr.enabled ? 'unreachable' : 'disabled'}}, TTS: ${{tts && tts.reachable ? 'reachable' : tts && tts.enabled ? 'unreachable' : 'disabled'}}.`);
       }} catch (err) {{ addBubble('system', 'Speech health check failed: ' + String(err && err.message ? err.message : err)); }}
     }});
+    speechPlaybackTestButton.addEventListener('click', async () => {{
+      try {{
+        await saveSpeechConfig();
+        unlockSpeechPlayback();
+        await speakText('음성 재생 테스트입니다.');
+      }} catch (err) {{ addBubble('system', 'Voice playback test failed: ' + String(err && err.message ? err.message : err)); }}
+    }});
     fileInput.addEventListener('change', () => {{
       addSelectedFiles(fileInput.files);
       fileInput.value = '';

package/docs/COLAB_SPEECH.md

@@ -18,7 +18,7 @@ From PowerShell at the repository root:
 
 Set the WSL distribution, authentication mode, ASR/TTS session names, and accelerators in **Web Chat > Speech Settings > Colab CLI connection**. These values are available through `GET|POST /ca/speech/config`; Ciel does not store Colab credentials. The deployment script reads the saved values automatically. Command-line parameters such as `-Distribution`, `-ColabAuth`, `-AsrSession`, and `-AsrAccelerator` override them for one run.
 
-The script reuses matching active sessions when possible, otherwise creates them, installs Qwen3-ASR-0.6B and MOSS-TTS-Nano, starts Tailscale in userspace networking mode, publishes each localhost model server with Tailscale Serve, and saves both returned `base_url` values into Web Chat > Speech Settings automatically.
+The script reuses matching active sessions when possible, otherwise creates them, installs Qwen3-ASR-0.6B plus the selected TTS engine (MOSS-TTS-Nano or Fun-CosyVoice3-0.5B-2512), starts Tailscale in userspace networking mode, publishes each localhost model server with Tailscale Serve, and saves both returned `base_url` values into Web Chat > Speech Settings automatically. Choose the TTS engine in the Colab section before **Recover & deploy**, or pass `-TtsBackend moss|cosyvoice3` to the script.
 
 ### Session recovery and account profiles
 
@@ -40,6 +40,10 @@ Tailscale and speech API keys entered in Web Chat are passed only to the selecte
 
 MOSS-TTS-Nano is a voice-cloning model without built-in speakers. Deployment configures the project's official `zh_1.wav` sample so the first request works immediately. In Web Chat > Speech Settings, upload a reference voice clip (10 MB maximum) to replace it. Ciel stores uploaded audio only in the local protected runtime configuration, omits it from configuration responses, and adds it to TTS requests automatically. API clients can instead pass `ref_audio` as an HTTP(S) URL or base64 audio data URL to `POST /v1/audio/speech`.
 
+CosyVoice 3 deployment configures its official zero-shot reference clip and exact transcript, enables 24 kHz PCM output streaming, and starts browser playback as chunks arrive. For a custom cloned voice, upload the clip and provide its exact transcript; CosyVoice 3 requires both. **Test voice** unlocks browser audio playback and verifies the complete Ciel-to-worker path.
+
+CosyVoice's bi-streaming means incremental text input and incremental audio output. Ciel currently benefits from the audio-output half: lower time to first sound, bounded buffering, and immediate cancellation when the user interrupts. The agent channel still delivers complete `spoken` fields, so using the text-input half later requires forwarding agent tokens or sentence fragments to a persistent streaming TTS connection. It is not by itself a full-duplex conversation protocol.
+
 Colab sessions are ephemeral. Re-run the bootstrap after a runtime reset. The workers are reachable only by devices in the same tailnet unless an administrator separately enables Tailscale Funnel.
 
 ## Live voice

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneciel-ai/ciel-runtime",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Universal AI coding-agent runtime and model-routing layer for Claude, Codex, AGY, and compatible runtimes.",
   "license": "MIT",
   "author": "One Ciel LLC",
@@ -36,7 +36,7 @@
     "ciel-runtime-stop.cmd",
     "ciel-runtime-stop.ps1",
     "npm-bin/",
-    "scripts/colab/",
+    "scripts/colab/*.py",
     "scripts/configure_speech_workers.py",
     "scripts/deploy_colab_speech.ps1",
     "install.sh",

package/scripts/colab/bootstrap_cosyvoice3.py

@@ -0,0 +1,125 @@
+"""Bootstrap Fun-CosyVoice3-0.5B with streaming vLLM-Omni and Tailscale Serve."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import time
+import urllib.request
+
+
+HOSTNAME = os.environ.get("CIEL_TTS_HOSTNAME", "ciel-tts")
+MODEL = "FunAudioLLM/Fun-CosyVoice3-0.5B-2512"
+PORT = 8091
+SOCKET = "/tmp/ciel-tts-tailscaled.sock"
+STATE = "/tmp/ciel-tts-tailscaled.state"
+LOG_DIR = Path("/content/ciel-speech-logs")
+BACKEND_MARKER = Path("/content/ciel-speech-tts-backend")
+
+
+def secret(name: str, *, required: bool = False) -> str:
+    value = str(os.environ.get(name) or "").strip()
+    if not value:
+        try:
+            from google.colab import userdata  # type: ignore
+
+            value = str(userdata.get(name) or "").strip()
+        except Exception:
+            value = ""
+    if required and not value:
+        raise RuntimeError(f"Add {name} to Colab Secrets and allow notebook access, then rerun this script.")
+    return value
+
+
+def run(*args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+    visible: list[str] = []
+    for arg in args:
+        visible.append("--auth-key=<redacted>" if arg.startswith("--auth-key=") else arg)
+    print("+", " ".join(visible))
+    return subprocess.run(args, check=check, text=True, capture_output=False)
+
+
+def install_tailscale() -> None:
+    if not shutil.which("tailscale"):
+        run("bash", "-lc", "curl -fsSL https://tailscale.com/install.sh | sh")
+
+
+def start_tailscale(auth_key: str) -> tuple[str, str]:
+    install_tailscale()
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    tail_log = (LOG_DIR / "tailscale-tts.log").open("ab")
+    if not Path(SOCKET).exists():
+        subprocess.Popen(
+            ["tailscaled", f"--socket={SOCKET}", f"--state={STATE}", "--tun=userspace-networking"],
+            stdout=tail_log,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+    for _ in range(60):
+        if Path(SOCKET).exists():
+            break
+        time.sleep(1)
+    login = run("tailscale", f"--socket={SOCKET}", "up", f"--auth-key={auth_key}", f"--hostname={HOSTNAME}", "--accept-dns=true", "--reset", check=False)
+    if login.returncode:
+        raise RuntimeError("Tailscale authentication failed; use a valid reusable key or a fresh key for this worker")
+    status = subprocess.check_output(["tailscale", f"--socket={SOCKET}", "status", "--json"], text=True)
+    dns_name = str(json.loads(status).get("Self", {}).get("DNSName") or HOSTNAME).rstrip(".")
+    run("tailscale", f"--socket={SOCKET}", "serve", "--bg", "--http=80", f"http://127.0.0.1:{PORT}")
+    return dns_name, f"http://{dns_name}"
+
+
+def server_is_healthy(api_key: str) -> bool:
+    headers = {"authorization": f"Bearer {api_key}"} if api_key else {}
+    try:
+        with urllib.request.urlopen(urllib.request.Request(f"http://127.0.0.1:{PORT}/health", headers=headers), timeout=3) as response:
+            return response.status < 500
+    except Exception:
+        return False
+
+
+def wait_for_server(api_key: str, process: subprocess.Popen[bytes]) -> None:
+    for _ in range(240):
+        if process.poll() is not None:
+            log_path = LOG_DIR / "cosyvoice3.log"
+            log_tail = log_path.read_text(encoding="utf-8", errors="replace")[-12000:] if log_path.exists() else "log unavailable"
+            raise RuntimeError(f"CosyVoice 3 exited with status {process.returncode}:\n{log_tail}")
+        if server_is_healthy(api_key):
+            return
+        time.sleep(2)
+    raise RuntimeError("CosyVoice 3 did not become healthy; inspect /content/ciel-speech-logs/cosyvoice3.log")
+
+
+def prepare_backend() -> None:
+    current = BACKEND_MARKER.read_text(encoding="utf-8", errors="replace").strip() if BACKEND_MARKER.exists() else ""
+    if current != "cosyvoice3":
+        run("bash", "-lc", f"fuser -k {PORT}/tcp >/dev/null 2>&1 || true", check=False)
+        time.sleep(2)
+
+
+def main() -> None:
+    auth_key = secret("TAILSCALE_AUTHKEY", required=True)
+    api_key = secret("CIEL_SPEECH_API_KEY")
+    run(sys.executable, "-m", "pip", "install", "-U", "nvidia-cuda-runtime==13.0.96", "vllm==0.24.0", "vllm-omni==0.24.0")
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    prepare_backend()
+    if not server_is_healthy(api_key):
+        command = [
+            "vllm", "serve", MODEL, "--omni", "--host", "127.0.0.1", "--port", str(PORT),
+            "--trust-remote-code", "--gpu-memory-utilization", "0.72",
+        ]
+        if api_key:
+            command.extend(["--api-key", api_key])
+        server_log = (LOG_DIR / "cosyvoice3.log").open("ab")
+        process = subprocess.Popen(command, stdout=server_log, stderr=subprocess.STDOUT, start_new_session=True)
+        wait_for_server(api_key, process)
+    BACKEND_MARKER.write_text("cosyvoice3", encoding="utf-8")
+    dns_name, base_url = start_tailscale(auth_key)
+    print(json.dumps({"ok": True, "role": "tts", "hostname": dns_name, "base_url": base_url, "model": MODEL, "backend": "cosyvoice3", "streaming": True, "sample_rate": 24000, "api_key_set": bool(api_key)}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/colab/bootstrap_moss_tts.py

@@ -22,6 +22,7 @@ PORT = 8091
 SOCKET = "/tmp/ciel-tts-tailscaled.sock"
 STATE = "/tmp/ciel-tts-tailscaled.state"
 LOG_DIR = Path("/content/ciel-speech-logs")
+BACKEND_MARKER = Path("/content/ciel-speech-tts-backend")
 
 
 def secret(name: str, *, required: bool = False) -> str:
@@ -109,6 +110,13 @@ def server_is_healthy(api_key: str) -> bool:
         return False
 
 
+def prepare_backend() -> None:
+    current = BACKEND_MARKER.read_text(encoding="utf-8", errors="replace").strip() if BACKEND_MARKER.exists() else ""
+    if current and current != "moss":
+        run("bash", "-lc", f"fuser -k {PORT}/tcp >/dev/null 2>&1 || true", check=False)
+        time.sleep(2)
+
+
 def main() -> None:
     auth_key = secret("TAILSCALE_AUTHKEY", required=True)
     api_key = secret("CIEL_SPEECH_API_KEY")
@@ -123,6 +131,7 @@ def main() -> None:
         "vllm-omni==0.24.0",
     )
     LOG_DIR.mkdir(parents=True, exist_ok=True)
+    prepare_backend()
     if not server_is_healthy(api_key):
         command = [
             "vllm-omni", "serve", "OpenMOSS-Team/MOSS-TTS-Nano", "--omni", "--host", "127.0.0.1", "--port", str(PORT),
@@ -142,6 +151,7 @@ def main() -> None:
         server_log = (LOG_DIR / "moss-tts.log").open("ab")
         process = subprocess.Popen(command, stdout=server_log, stderr=subprocess.STDOUT, start_new_session=True, env=server_env)
         wait_for_server(api_key, process)
+    BACKEND_MARKER.write_text("moss", encoding="utf-8")
     dns_name, base_url = start_tailscale(auth_key)
     print(json.dumps({"ok": True, "role": "tts", "hostname": dns_name, "base_url": base_url, "model": "OpenMOSS-Team/MOSS-TTS-Nano", "api_key_set": bool(api_key)}, indent=2))
 

package/scripts/configure_speech_workers.py

@@ -12,6 +12,12 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
 
 DEFAULT_TTS_REFERENCE_AUDIO = "https://raw.githubusercontent.com/OpenMOSS/MOSS-TTS-Nano/main/assets/audio/zh_1.wav"
+DEFAULT_COSYVOICE_REFERENCE_AUDIO = "https://raw.githubusercontent.com/QwenAudio/CosyVoice/main/asset/zero_shot_prompt.wav"
+DEFAULT_COSYVOICE_REFERENCE_TEXT = "希望你以后能够做的比我还好呦。"
+TTS_BACKENDS = {
+    "moss": {"model": "OpenMOSS-Team/MOSS-TTS-Nano", "sample_rate": 48000, "streaming": False},
+    "cosyvoice3": {"model": "FunAudioLLM/Fun-CosyVoice3-0.5B-2512", "sample_rate": 24000, "streaming": True},
+}
 DEFAULT_COLAB_SETTINGS: dict[str, Any] = {
     "enabled": True,
     "distribution": "Ubuntu-26.04",
@@ -21,6 +27,7 @@ DEFAULT_COLAB_SETTINGS: dict[str, Any] = {
     "tts_session": "ciel-tts",
     "asr_accelerator": "T4",
     "tts_accelerator": "T4",
+    "tts_backend": "moss",
 }
 
 
@@ -45,6 +52,7 @@ def configure(
     tts_session: str | None = None,
     asr_accelerator: str | None = None,
     tts_accelerator: str | None = None,
+    tts_backend: str | None = None,
 ) -> dict[str, Any]:
     import ciel_runtime
 
@@ -61,14 +69,24 @@ def configure(
         "tts_session": tts_session,
         "asr_accelerator": asr_accelerator,
         "tts_accelerator": tts_accelerator,
+        "tts_backend": tts_backend,
     }
     colab.update({key: value for key, value in overrides.items() if value is not None})
     colab["enabled"] = True
+    backend = str(colab.get("tts_backend") or "moss").strip().lower()
+    if backend not in TTS_BACKENDS:
+        raise ValueError(f"unsupported TTS backend: {backend}")
+    backend_settings = TTS_BACKENDS[backend]
     speech["colab"] = colab
     asr.update({"enabled": True, "base_url": asr_base_url.rstrip("/"), "model": "Qwen/Qwen3-ASR-0.6B"})
-    tts.update({"enabled": True, "base_url": tts_base_url.rstrip("/"), "model": "OpenMOSS-Team/MOSS-TTS-Nano"})
-    if tts_reference_audio and not str(tts.get("ref_audio") or "").strip():
-        tts["ref_audio"] = tts_reference_audio
+    tts.update({"enabled": True, "base_url": tts_base_url.rstrip("/"), **backend_settings})
+    known_defaults = {DEFAULT_TTS_REFERENCE_AUDIO, DEFAULT_COSYVOICE_REFERENCE_AUDIO, ""}
+    current_reference = str(tts.get("ref_audio") or "").strip()
+    desired_reference = DEFAULT_COSYVOICE_REFERENCE_AUDIO if backend == "cosyvoice3" else tts_reference_audio
+    if desired_reference and current_reference in known_defaults:
+        tts["ref_audio"] = desired_reference
+    if backend == "cosyvoice3" and current_reference in known_defaults and not str(tts.get("ref_text") or "").strip():
+        tts["ref_text"] = DEFAULT_COSYVOICE_REFERENCE_TEXT
     ciel_runtime.save_config(config)
     return {"asr": asr["base_url"], "tts": tts["base_url"], "colab": colab}
 
@@ -85,6 +103,7 @@ def main() -> int:
     parser.add_argument("--tts-session")
     parser.add_argument("--asr-accelerator")
     parser.add_argument("--tts-accelerator")
+    parser.add_argument("--tts-backend", choices=tuple(TTS_BACKENDS))
     parser.add_argument("--print-colab-settings", action="store_true")
     args = parser.parse_args()
     if args.print_colab_settings:
@@ -103,6 +122,7 @@ def main() -> int:
         tts_session=args.tts_session,
         asr_accelerator=args.asr_accelerator,
         tts_accelerator=args.tts_accelerator,
+        tts_backend=args.tts_backend,
     )
     print(f"Configured Ciel speech workers: ASR={result['asr']} TTS={result['tts']}")
     return 0

package/scripts/deploy_colab_speech.ps1

@@ -8,7 +8,8 @@ param(
     [string]$AsrSession,
     [string]$TtsSession,
     [string]$AsrAccelerator,
-    [string]$TtsAccelerator
+    [string]$TtsAccelerator,
+    [string]$TtsBackend
 )
 
 $ErrorActionPreference = "Stop"
@@ -25,6 +26,8 @@ if ([string]::IsNullOrWhiteSpace($AsrSession)) { $AsrSession = [string]$settings
 if ([string]::IsNullOrWhiteSpace($TtsSession)) { $TtsSession = [string]$settings.tts_session }
 if ([string]::IsNullOrWhiteSpace($AsrAccelerator)) { $AsrAccelerator = [string]$settings.asr_accelerator }
 if ([string]::IsNullOrWhiteSpace($TtsAccelerator)) { $TtsAccelerator = [string]$settings.tts_accelerator }
+if ([string]::IsNullOrWhiteSpace($TtsBackend)) { $TtsBackend = [string]$settings.tts_backend }
+if ([string]::IsNullOrWhiteSpace($TtsBackend)) { $TtsBackend = "moss" }
 if ($Distribution -notmatch '^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$') { throw "Invalid WSL distribution name." }
 if ($ColabAuth -notin @('adc', 'oauth2')) { throw "ColabAuth must be adc or oauth2." }
 if ($Profile -notmatch '^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$') { throw "Invalid Colab account profile name." }
@@ -34,6 +37,7 @@ foreach ($session in @($AsrSession, $TtsSession)) {
 foreach ($accelerator in @($AsrAccelerator, $TtsAccelerator)) {
     if ($accelerator -notin @('T4', 'L4', 'G4', 'A100', 'H100')) { throw "Unsupported Colab accelerator: $accelerator" }
 }
+if ($TtsBackend -notin @('moss', 'cosyvoice3')) { throw "TtsBackend must be moss or cosyvoice3." }
 $wslRepo = (& wsl -d $Distribution -- wslpath -a ($repo -replace '\\', '/')).Trim()
 if (-not $wslRepo) { throw "Could not resolve the repository path in WSL." }
 $wslHome = (& wsl -d $Distribution -- bash -lc 'printf %s "$HOME"').Trim()
@@ -122,11 +126,12 @@ $asrArguments += @('--file', "$wslRepo/scripts/colab/bootstrap_qwen_asr.py")
 $asrOutput = (Invoke-Colab $asrArguments 2>&1 | Tee-Object -Variable asrDisplay) -join "`n"
 if ($LASTEXITCODE -ne 0) { throw "ASR bootstrap failed." }
 
-Write-Host "Installing MOSS-TTS-Nano and its Tailscale service..."
+Write-Host "Installing $TtsBackend and its Tailscale service..."
 $ttsArguments = @('exec', '--session', $TtsSession)
 if ($env:TAILSCALE_AUTHKEY) { $ttsArguments += @('--env', "TAILSCALE_AUTHKEY=$($env:TAILSCALE_AUTHKEY)") }
 if ($env:CIEL_SPEECH_API_KEY) { $ttsArguments += @('--env', "CIEL_SPEECH_API_KEY=$($env:CIEL_SPEECH_API_KEY)") }
-$ttsArguments += @('--file', "$wslRepo/scripts/colab/bootstrap_moss_tts.py")
+$ttsBootstrap = if ($TtsBackend -eq 'cosyvoice3') { 'bootstrap_cosyvoice3.py' } else { 'bootstrap_moss_tts.py' }
+$ttsArguments += @('--file', "$wslRepo/scripts/colab/$ttsBootstrap")
 $ttsOutput = (Invoke-Colab $ttsArguments 2>&1 | Tee-Object -Variable ttsDisplay) -join "`n"
 if ($LASTEXITCODE -ne 0) { throw "TTS bootstrap failed." }
 
@@ -140,7 +145,7 @@ function Read-BootstrapResult([string]$Text, [string]$Role) {
 
 $asr = Read-BootstrapResult $asrOutput "asr"
 $tts = Read-BootstrapResult $ttsOutput "tts"
-& python (Join-Path $PSScriptRoot "configure_speech_workers.py") --asr-base-url $asr.base_url --tts-base-url $tts.base_url --distribution $Distribution --auth $ColabAuth --profile $Profile --asr-session $AsrSession --tts-session $TtsSession --asr-accelerator $AsrAccelerator --tts-accelerator $TtsAccelerator
+& python (Join-Path $PSScriptRoot "configure_speech_workers.py") --asr-base-url $asr.base_url --tts-base-url $tts.base_url --distribution $Distribution --auth $ColabAuth --profile $Profile --asr-session $AsrSession --tts-session $TtsSession --asr-accelerator $AsrAccelerator --tts-accelerator $TtsAccelerator --tts-backend $TtsBackend
 if ($LASTEXITCODE -ne 0) { throw "Workers started, but Ciel speech configuration failed." }
 
 Write-Host "Both services are running and connected to Web Chat > Speech Settings."