"""Splainer's local voice: Kokoro-82M (Apache-2.0) behind OpenAI's speech API on 127.0.0.1, so Splainer narrates with a natural voice without the cloud. Runs on the processor (ONNX Runtime), leaving the graphics card to the drawing model. python kokoro_server.py --models --token-file [--port 8880] Every request must carry "Authorization: Bearer " (Splainer creates it per install). Browser requests (any Origin header) and other Host names are refused, so web pages can't use the voice; input is capped at 4096 characters. POST /v1/audio/speech {"model":"kokoro","input":"...","voice":"female"|"male"|,"response_format":"wav"|"pcm","speed":1.0} -> 24 kHz mono 16-bit WAV, or raw PCM streamed sentence by sentence. POST /v1/audio/transcriptions (multipart: file=, language, prompt) -> {"text": "..."} Whisper (faster-whisper): large-v3-turbo on the graphics card (~0.2 s per question), else "small" on the processor. The installed app runs this file as a packaged program (tools/voice/build.ps1) and puts the models in the --models folder: kokoro-v1.0.onnx, voices-v1.0.bin, whisper-small/, and with an NVIDIA card whisper-large-v3-turbo/ and gpu/ (CUDA libraries). GET /v1/models, /v1/audio/voices """ import argparse, glob, hmac, io, json, os, re, site, struct, sys, threading, time, wave from email.parser import BytesParser from email.policy import HTTP from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer import numpy as np from kokoro_onnx import Kokoro # The two choices Splainer offers; any Kokoro voice name also works. ALIASES = {"female": "af_heart", "male": "am_michael", "default": "af_heart"} RATE = 24000 kokoro: Kokoro lock = threading.Lock() TOKEN = "" HOSTS: set = set() MAX_INPUT = 4096 MAX_AUDIO = 25 * 1024 * 1024 FOLDER = "." whisper = None whisper_ready = threading.Event() whisper_lock = threading.Lock() def gpu_folders(folder): """Where the CUDA libraries for Whisper live: the GPU pack Splainer downloads (/gpu), or the nvidia-* wheels of a developer's Python environment.""" found = [os.path.join(folder, "gpu")] if os.path.isdir(os.path.join(folder, "gpu")) else [] if not getattr(sys, "frozen", False): try: found += glob.glob(os.path.join(site.getsitepackages()[-1], "nvidia", "*", "bin")) except Exception: pass return found def whisper_source(folder, name): """A model folder Splainer downloaded (/whisper-, holding model.bin), else the model's name so a developer's environment fetches it into /whisper.""" local = os.path.join(folder, "whisper-" + name) return local if os.path.exists(os.path.join(local, "model.bin")) else name def load_whisper(folder): """Loads Whisper in the background so speech is available at once: large-v3-turbo on the graphics card when the CUDA libraries are there, else "small" on the processor. The installed app never downloads here: it only loads what is on disk.""" global whisper try: from faster_whisper import WhisperModel frozen = getattr(sys, "frozen", False); model = None dirs = gpu_folders(folder) for d in dirs: os.add_dll_directory(d); os.environ["PATH"] = d + os.pathsep + os.environ["PATH"] turbo = whisper_source(folder, "large-v3-turbo") if dirs and (not frozen or os.path.isdir(turbo)): try: model = WhisperModel(turbo, device="cuda", compute_type="float16", download_root=os.path.join(folder, "whisper")) list(model.transcribe(np.zeros(16000, np.float32), beam_size=1)[0]) # warm up; fails here when CUDA is unusable log("whisper: large-v3-turbo on the graphics card") except Exception as e: model = None; log(f"whisper: the graphics card could not be used ({str(e)[:160]}); using the processor") if model is None: small = whisper_source(folder, "small") if frozen and not os.path.isdir(small): raise RuntimeError("no speech recognition model is installed") model = WhisperModel(small, device="cpu", compute_type="int8", download_root=os.path.join(folder, "whisper")) list(model.transcribe(np.zeros(16000, np.float32), beam_size=1)[0]) log("whisper: small on the processor") whisper = model except Exception as e: log(f"whisper unavailable: {str(e)[:200]}") finally: whisper_ready.set() def pcm_from_wav(data): w = wave.open(io.BytesIO(data)); rate, channels = w.getframerate(), w.getnchannels() if w.getsampwidth() != 2: raise ValueError("send 16-bit PCM WAV") a = np.frombuffer(w.readframes(w.getnframes()), dtype=" 1: a = a.reshape(-1, channels).mean(1) if rate != 16000: a = np.interp(np.arange(0, len(a), rate / 16000), np.arange(len(a)), a).astype(np.float32) return a def transcribe(data, language, prompt): whisper_ready.wait(120) if whisper is None: raise RuntimeError("speech recognition is not available") lang = (language or "").split("-")[0].lower() or None audio = pcm_from_wav(data) level = f"{len(audio) / 16000:.1f} s, peak {np.abs(audio).max(initial=0):.3f}, rms {float(np.sqrt(np.mean(audio ** 2))) if len(audio) else 0:.4f}" if os.path.exists(os.path.join(FOLDER, "debug")): open(os.path.join(FOLDER, "last-recording.wav"), "wb").write(data) with whisper_lock: segments, _ = whisper.transcribe(audio, language=lang if lang not in ("default", "auto") else None, initial_prompt=prompt or None, beam_size=1, vad_filter=True) text = " ".join(s.text.strip() for s in segments).strip() log(f"heard {len(text)} chars from {level}") return text def log(line): with open(os.path.join(FOLDER, "server.log"), "a", encoding="utf-8") as f: f.write(time.strftime("%H:%M:%S ") + line + "\n") def resolve(voice): name = ALIASES.get((voice or "default").lower(), voice) return name if name in kokoro.get_voices() else ALIASES["default"] def lang_for(voice): return "en-gb" if voice[:1] == "b" else "en-us" def sentences(text): # Short pieces start playback sooner; very short ones are joined so the voice keeps its flow. parts, cur = [], "" for s in re.split(r"(?<=[.!?…])\s+", text.strip()): cur = f"{cur} {s}".strip() if len(cur) >= 60: parts.append(cur); cur = "" if cur: parts.append(cur) return parts or [text] def pcm16(samples): return (np.clip(samples, -1, 1) * 32767).astype(" limit: raise ValueError("request too large") length = int(self.headers.get("Content-Length", 0)) if length > limit: raise ValueError("request too large") return self.rfile.read(length) def transcription(self): kind = self.headers.get("Content-Type", "") if not kind.lower().startswith("multipart/form-data"): return self.send(415, b'{"error":"send multipart/form-data"}') message = BytesParser(policy=HTTP).parsebytes(b"Content-Type: " + kind.encode() + b"\r\n\r\n" + self.body(MAX_AUDIO + 65536)) fields = {p.get_param("name", header="content-disposition"): p.get_payload(decode=True) for p in message.iter_parts()} if not fields.get("file"): return self.send(400, b'{"error":"file is missing"}') text = transcribe(fields["file"], (fields.get("language") or b"").decode(), (fields.get("prompt") or b"").decode()[:500]) self.send(200, json.dumps({"text": text}).encode()) def do_POST(self): if not self.allowed(): return if self.path.rstrip("/") == "/v1/audio/transcriptions": try: return self.transcription() except Exception as e: return self.send(500, json.dumps({"error": str(e)}).encode()) if self.path.rstrip("/") != "/v1/audio/speech": return self.send(404, b"{}") if not self.headers.get("Content-Type", "").lower().startswith("application/json"): return self.send(415, b'{"error":"send JSON"}') try: req = json.loads(self.body() or b"{}") text = (req.get("input") or "").strip() if not text: return self.send(400, b'{"error":"input is empty"}') if len(text) > MAX_INPUT: return self.send(413, b'{"error":"input is longer than 4096 characters"}') voice, speed = resolve(req.get("voice")), float(req.get("speed") or 1.0) speed = min(2.0, max(0.5, speed)) if req.get("response_format") == "pcm": # Stream: each sentence is sent as soon as it is spoken, so the first words play within a fraction of a second. self.send_response(200); self.send_header("Content-Type", "audio/pcm"); self.send_header("Transfer-Encoding", "chunked"); self.end_headers() for piece in sentences(text): data = synth(piece, voice, speed) self.wfile.write(f"{len(data):X}\r\n".encode() + data + b"\r\n"); self.wfile.flush() self.wfile.write(b"0\r\n\r\n"); return self.send(200, wav(b"".join(synth(p, voice, speed) for p in sentences(text))), "audio/wav") except (BrokenPipeError, ConnectionResetError): pass except Exception as e: self.send(500, json.dumps({"error": str(e)}).encode()) def main(): global kokoro, TOKEN, FOLDER ap = argparse.ArgumentParser(); ap.add_argument("--models", required=True); ap.add_argument("--port", type=int, default=8880); ap.add_argument("--token-file", required=True) a = ap.parse_args() TOKEN = open(a.token_file, encoding="utf-8").read().strip() if len(TOKEN) < 32: sys.exit("the token file must hold a secret of at least 32 characters") FOLDER = a.models HOSTS.update({f"127.0.0.1:{a.port}", f"localhost:{a.port}"}) full_speed() kokoro = Kokoro(os.path.join(a.models, "kokoro-v1.0.onnx"), os.path.join(a.models, "voices-v1.0.bin")) synth("Ready.", ALIASES["default"], 1.0) # warm up so the first answer is quick threading.Thread(target=load_whisper, args=(a.models,), daemon=True).start() print(f"Splainer voice ready on http://127.0.0.1:{a.port}/v1", flush=True) ThreadingHTTPServer(("127.0.0.1", a.port), Handler).serve_forever() if __name__ == "__main__": main()