feat: add kokoro plugin

Author: maxkahan

examples/tts_kokoro/README.md

@@ -0,0 +1,51 @@
+# Stream × Kokoro — TTS Bot
+
+Speak into a Stream video call… from Python!
+
+This tiny example spins up a text-to-speech bot that joins a call and greets participants using the open-weight [Kokoro](https://github.com/hexgrad/kokoro) model.
+
+---
+
+## Quick start
+
+```bash
+# clone and move into the repo (if not already there)
+cd examples/tts_kokoro
+
+# install deps (pick one)
+pip install -e .            # classic
+uv venv .venv && source .venv/bin/activate && uv sync   # fast ⚡️
+
+# copy env template and fill in Stream keys
+cp ../stt_deepgram_transcription/env.example .env
+$EDITOR .env                # STREAM_*
+
+# make sure espeak-ng is installed (macOS example)
+brew install espeak-ng
+
+# The example will auto-bootstrap pip if it's missing; this command is a
+# manual fallback in case you want to do it yourself upfront.
+python -m ensurepip --upgrade  # optional
+
+# run it
+python main.py              # or: uv -m python main.py
+```
+
+You'll see the bot join, say a greeting, then wait. Add extra `await tts.send("…")` calls in `main.py` to make it speak more.
+
+---
+
+## How it works (60 sec)
+
+1. Creates two temporary Stream users (human + `tts-bot`).
+2. Opens a browser URL so you can join the call instantly.
+3. Builds an `AudioStreamTrack` at **24 kHz** and connects it to Kokoro.
+4. Joins the call and sends a greeting via `tts.send()`.
+5. `await connection.wait()` keeps the bot alive until **Ctrl-C**.
+6. On shutdown the script deletes the temporary users.
+
+Under 120 lines of code 😀
+
+---
+
+Need help? → [Stream Video docs](https://getstream.io/video/docs/) · [Kokoro README](https://github.com/hexgrad/kokoro/blob/main/README.md) 

examples/tts_kokoro/main.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Example: Text-to-Speech bot with Kokoro
+
+This minimal example shows how to:
+1. Spin up a Stream video call
+2. Attach a Kokoro TTS bot that can speak into the call
+
+Run it, join the call in your browser, and hear the bot greet you 🗣️
+
+Usage::
+    python main.py
+
+The script looks for the following env vars (see `env.example`):
+    STREAM_API_KEY / STREAM_API_SECRET
+
+Kokoro runs fully offline – no extra API key required, but you **must** have
+`espeak-ng` installed and available on the PATH for fallback phoneme
+generation. On macOS: `brew install espeak-ng`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from uuid import uuid4
+import importlib, sys
+
+from dotenv import load_dotenv
+
+from examples.utils import create_user, open_browser
+from getstream.stream import Stream
+from getstream.video import rtc
+from getstream.video.rtc import audio_track
+from getstream_kokoro import KokoroTTS
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+
+os.environ["KOKORO_NO_AUTO_INSTALL"] = "1" # Disable auto-install of kokoro dependencies
+
+# ---------------------------------------------------------------------------
+# Ensure `pip` is present – uv-created virtual-envs omit it for speed and     
+# Kokoro relies on `python -m pip` for optional installs (voices, extras).    
+# Run this *before* we import Kokoro.                                         
+# ---------------------------------------------------------------------------
+try:
+    importlib.import_module("pip")
+except ModuleNotFoundError:  # pragma: no cover – only triggers in uv venvs
+    import ensurepip, subprocess  # noqa: WPS433
+
+    print("Boot-strapping pip (uv venv detected – pip missing)…", file=sys.stderr)
+    ensurepip.bootstrap()
+    subprocess.check_call([sys.executable, "-m", "pip", "install", "--upgrade", "pip"])
+
+async def main() -> None:
+    """Create a video call and let a Kokoro TTS bot greet participants."""
+
+    load_dotenv(os.path.join(os.path.dirname(__file__), "..", ".env"))
+
+    client: Stream = Stream.from_env()
+
+    human_id = f"user-{uuid4()}"
+    bot_id = f"tts-bot-{uuid4()}"
+
+    create_user(client, human_id, "Human")
+    create_user(client, bot_id, "TTS Bot")
+
+    logging.info("Created users: %s (human) / %s (bot)", human_id, bot_id)
+
+    token = client.create_token(human_id, expiration=3600)
+
+    call_id = str(uuid4())
+    call = client.video.call("default", call_id)
+    call.get_or_create(data={"created_by_id": bot_id})
+
+    logging.info("📞 Call ready: %s", call_id)
+
+    open_browser(client.api_key, token, call_id)
+
+    # Kokoro produces 24 kHz mono 16-bit PCM
+    track = audio_track.AudioStreamTrack(framerate=24_000)
+
+    # Build TTS pipeline (defaults to American English / af_heart voice)
+    tts = KokoroTTS()
+    tts.set_output_track(track)
+
+    greeting = (
+        "Hello there! I'm a Kokoro text-to-speech bot speaking inside this call. "
+        "As this is a minimal example, I'll stop speaking now."
+    )
+
+    try:
+        async with await rtc.join(call, bot_id) as connection:
+            await connection.add_tracks(audio=track)
+            logging.info("🤖 Bot joined call: %s", call_id)
+
+            await asyncio.sleep(1)
+            # Send greeting once the track is live
+            await tts.send(greeting)
+            logging.info("Sent greeting via TTS")
+
+            logging.info("🎧 Bot is idle – press Ctrl+C to stop")
+            await connection.wait()
+
+    except (asyncio.CancelledError):
+        logging.info("Stopping TTS bot…")
+    finally:
+        client.delete_users([human_id, bot_id])
+        logging.info("Cleanup completed")
+
+
+if __name__ == "__main__":
+    asyncio.run(main()) 

examples/tts_kokoro/pyproject.toml

@@ -1,29 +1,26 @@
 [project]
-name = "getstream-tts-kokoro-example"
+name = "tts-kokoro-example"
 version = "0.1.0"
-description = "Example project showing how to use Kokoro TTS with GetStream"
+description = "Stream Video + Kokoro TTS demo."
 readme = "README.md"
 requires-python = ">=3.9"
-license = {text = "MIT"}
+license = { text = "MIT" }
 
 dependencies = [
-    "getstream[webrtc]",
     "python-dotenv>=1.0.0",
-    # Add kokoro dependencies as needed
+    "kokoro>=0.9.4",
+    "misaki[en]>=0.1.0",
+    "soundfile>=0.13.0",
+    "aiortc>=1.10.1",
+    "numpy>=2.0.0"
 ]
 
 [project.optional-dependencies]
-dev = [
-    "pytest>=7.0.0",
-    "pytest-asyncio>=0.21.0",
-]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21"]
 
 [build-system]
 requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.uv.sources]
-getstream = { workspace = true }
-getstream-plugins-stt-deepgram = { workspace = true }
-getstream-plugins-tts-elevenlabs = { workspace = true }
-getstream-plugins-vad-silero = { workspace = true }
+getstream = { workspace = true } 

getstream/plugins/deepgram/env-var-api-key

@@ -42,7 +42,7 @@ class DeepgramSTT(STT):
     def __init__(
         self,
         api_key: Optional[str] = None,
-        options: Optional[LiveOptions] = None,
+        options: Optional[LiveOptions] = None, # type: ignore
         sample_rate: int = 48000,
         language: str = "en-US",
         keep_alive_interval: float = 3.0,

getstream/plugins/deepgram/src/getstream_deepgram/stt.py

@@ -0,0 +1,48 @@
+# GetStream Kokoro Plugin
+
+This package integrates the open-weight [Kokoro-82M TTS model](https://github.com/hexgrad/kokoro) with the GetStream audio/video SDK.
+
+It provides a drop-in `KokoroTTS` class that implements the common `getstream_common.tts.TTS` interface, allowing you to stream PCM audio generated by Kokoro directly into a WebRTC `AudioStreamTrack`.
+
+```py
+from getstream_kokoro import KokoroTTS
+from getstream.video.rtc.audio_track import AudioStreamTrack
+
+track = AudioStreamTrack(framerate=24_000)
+
+tts = KokoroTTS(lang_code="a", voice="af_heart")
+tts.set_output_track(track)
+
+await tts.send("Hello from Kokoro!")
+```
+
+## Installation
+
+```bash
+pip install getstream-plugins-kokoro
+```
+
+This will pull in the required `kokoro`, `numpy` and `getstream[webrtc]` dependencies.  You also need `espeak-ng` **at runtime** for pronunciation fallback.  On macOS you can install it with Homebrew:  
+
+```bash
+brew install espeak-ng
+```
+
+## Configuration options
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `lang_code` | `"a"` | Language group passed to `KPipeline` (`"a"` = American English, etc.) |
+| `voice` | `"af_heart"` | Kokoro voice preset.  See the [model card](https://huggingface.co/NeuML/kokoro-int8-onnx#speaker-reference) for available options. |
+| `speed` | `1.0` | Playback speed multiplier. |
+| `sample_rate` | `24000` | Output sample-rate (fixed by Kokoro).  **The attached `AudioStreamTrack` must use the same value.** |
+
+## Development
+
+Run the unit-tests with:
+
+```bash
+pytest -q getstream/plugins/kokoro/tests
+```
+
+No network calls are made – the Kokoro SDK is fully mocked. 

getstream/plugins/kokoro/README.md

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "getstream-plugins-kokoro"
+version = "0.1.0"
+description = "Kokoro TTS plugin for GetStream"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "getstream[webrtc]",
+    "kokoro>=0.9.4",
+    "soundfile>=0.13.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.18.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/getstream_kokoro"]
+
+[tool.uv.sources]
+getstream = { workspace = true } 

getstream/plugins/kokoro/pyproject.toml

@@ -0,0 +1,3 @@
+from .tts import KokoroTTS
+
+__all__ = ["KokoroTTS"]