livekit-plugins-duplexjev 0.1.0__tar.gz

livekit_plugins_duplexjev-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 (2026-10-10)
+
+- First release: `duplexjev.TurnDetector`, an audio (streaming) turn detector for LiveKit Agents that asks a
+  DuplexJev gateway for the turn state of the current user turn.
+- Extra questions (emotion, non-verbal sound, barge-in, or your own) answered in the same request; see
+  `last_answers` / `on_answers`.
+- Optional backchannel opportunity from "What should the assistant do now?" (`backchannel_threshold`).
+- Tested with livekit-agents 1.8.6.

livekit_plugins_duplexjev-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Adventists.ai (AI降临派)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

livekit_plugins_duplexjev-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: livekit-plugins-duplexjev
+Version: 0.1.0
+Summary: Audio end-of-turn detection for LiveKit Agents with DuplexJev: turn state, emotion and non-verbal sounds from one request, no transcript needed.
+Project-URL: Homepage, https://github.com/adventists-ai/duplexjev/tree/main/integrations/livekit
+Project-URL: Models, https://huggingface.co/adventists-ai/DuplexJev-4B-Para
+Project-URL: Paper, https://arxiv.org/abs/2610.02638
+Author-email: Jie Jin <jiejin@adventists.ai>
+License: BSD-2-Clause
+License-File: LICENSE
+Keywords: duplexjev,end-of-turn,livekit,livekit-agents,speech-llm,turn-detection,voice-agent
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: aiohttp
+Requires-Dist: livekit-agents<2,>=1.8
+Requires-Dist: numpy
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# livekit-plugins-duplexjev
+
+**Audio end-of-turn detection for [LiveKit Agents](https://github.com/livekit/agents), powered by
+[DuplexJev](https://github.com/adventists-ai/duplexjev).** It listens to *how* the user speaks, not only what they
+say, and tells your agent whether the user is **finished**, **still talking**, **just backchanneling** ("mm-hmm") or
+**asking you to wait**. The same request can also return **emotion**, **laughter / breathing / coughs / sighs** and
+**barge-in**.
+
+- **Reads the audio, not the transcript.** Every answer is one constrained token of a speech LLM: nothing is
+  decoded, so the decision does not wait for STT.
+- **Fast.** Ten decisions about one utterance take **92 ms** on one GPU, against **1,978 ms** for ASR → LLM with
+  the same LLM.
+- **Accurate.** On the CoDeTT turn-taking benchmark (English, zero-shot), DuplexJev-32B-Turn scores **70.0**,
+  against **51.4** for Smart Turn v3. See the [paper](https://arxiv.org/abs/2610.02638).
+- **More than turns, same request.** Ask for emotion, non-verbal sounds or your own multiple-choice questions.
+- **Chinese and English.** CPU only on the agent side: the plugin calls an HTTP API.
+
+Tested with `livekit-agents` 1.8.6. Maintained by Adventists.ai (AI降临派).
+
+## Install
+
+```bash
+pip install livekit-plugins-duplexjev
+```
+
+## Use
+
+```python
+from livekit.agents import AgentSession
+from livekit.plugins import duplexjev, silero
+
+session = AgentSession(
+    stt=..., llm=..., tts=...,
+    vad=silero.VAD.load(),
+    turn_handling={"turn_detection": duplexjev.TurnDetector(
+        api_url="http://localhost:8420",       # your own gateway; omit for the free hosted trial API
+        extra_questions=["emotion", "sound"],
+        on_answers=lambda a: print({k: v["answer"] for k, v in a.items()}),
+    )},
+)
+```
+
+`AgentSession(turn_detection=duplexjev.TurnDetector(), ...)` works too (LiveKit marks that argument as deprecated).
+A complete agent is in [`examples/agent.py`](examples/agent.py).
+
+**A VAD is required.** LiveKit ignores a streaming turn detector when the session has no VAD. The plugin buffers the
+user's audio, and after about 200 ms of VAD silence LiveKit asks it for a prediction: the last 8 s of the current
+user turn go to DuplexJev, and P(finished) becomes LiveKit's `end_of_turn_probability`. Below `unlikely_threshold`
+the session waits `max_delay` instead of `min_delay` before replying. The VAD's `min_silence_duration` must be at
+least 0.25 s (Silero's default is 0.55 s).
+
+**STT is optional for the decision.** If the session has an STT, LiveKit still waits for its transcript before it
+commits the turn, as with any turn detector, because the LLM needs the text.
+
+## Run the model yourself (recommended for real-time)
+
+The default URL is our free trial API (rate limited to 30 requests per minute; the round trip from outside mainland China adds network latency). For a live agent, serve the model next to it (DuplexJev-4B-Para needs about 10 GB of GPU memory):
+
+```bash
+pip install "vllm[audio]>=0.29" duplexjev-vllm "duplexjev[server]>=0.4.1"
+vllm serve adventists-ai/DuplexJev-4B-Para --max-model-len 4096 --port 8000 &
+duplexjev gateway --vllm http://localhost:8000/v1 --port 8420
+```
+
+Then pass `api_url="http://localhost:8420"` (or set `DUPLEXJEV_API_URL`).
+
+## Options
+
+| argument | default | |
+|---|---|---|
+| `api_url` | hosted trial API | base URL of a `duplexjev gateway` (or `DUPLEXJEV_API_URL`) |
+| `api_key` | `None` | bearer key, if your gateway requires one (or `DUPLEXJEV_API_KEY`) |
+| `lang` | `"en"` | `"en"` or `"zh"`: wording of the questions (the model hears both languages either way) |
+| `unlikely_threshold` | `0.5` | below this P(finished), wait `max_delay` instead of `min_delay` |
+| `backchannel_threshold` | `None` | if set, also asks "What should the assistant do now?" and reports P(short acknowledgement) as LiveKit's backchannel probability |
+| `extra_questions` | `[]` | `"emotion"`, `"sound"`, `"barge_in"`, or dicts `{"id", "text", "options"}` |
+| `on_answers` | `None` | callback with every answer dict; the latest is also on `detector.last_answers` |
+| `window_s` | `8.0` | seconds of the current user turn sent with each request |
+| `trim_silence` | `True` | drop the silence before the user started talking (keeps 0.3 s) |
+| `prediction_timeout` | `4.0` hosted, `1.0` own gateway | how long LiveKit waits for a prediction |
+| `fallback_probability` | `1.0` | P(finished) reported if the gateway fails, so the conversation never blocks |
+
+## License
+
+The plugin code is BSD-2-Clause. DuplexJev model weights are CC BY-NC 4.0 (non-commercial); see the
+[model cards](https://huggingface.co/adventists-ai). For commercial use, contact jiejin@adventists.ai.

livekit_plugins_duplexjev-0.1.0/README.md

@@ -0,0 +1,86 @@
+# livekit-plugins-duplexjev
+
+**Audio end-of-turn detection for [LiveKit Agents](https://github.com/livekit/agents), powered by
+[DuplexJev](https://github.com/adventists-ai/duplexjev).** It listens to *how* the user speaks, not only what they
+say, and tells your agent whether the user is **finished**, **still talking**, **just backchanneling** ("mm-hmm") or
+**asking you to wait**. The same request can also return **emotion**, **laughter / breathing / coughs / sighs** and
+**barge-in**.
+
+- **Reads the audio, not the transcript.** Every answer is one constrained token of a speech LLM: nothing is
+  decoded, so the decision does not wait for STT.
+- **Fast.** Ten decisions about one utterance take **92 ms** on one GPU, against **1,978 ms** for ASR → LLM with
+  the same LLM.
+- **Accurate.** On the CoDeTT turn-taking benchmark (English, zero-shot), DuplexJev-32B-Turn scores **70.0**,
+  against **51.4** for Smart Turn v3. See the [paper](https://arxiv.org/abs/2610.02638).
+- **More than turns, same request.** Ask for emotion, non-verbal sounds or your own multiple-choice questions.
+- **Chinese and English.** CPU only on the agent side: the plugin calls an HTTP API.
+
+Tested with `livekit-agents` 1.8.6. Maintained by Adventists.ai (AI降临派).
+
+## Install
+
+```bash
+pip install livekit-plugins-duplexjev
+```
+
+## Use
+
+```python
+from livekit.agents import AgentSession
+from livekit.plugins import duplexjev, silero
+
+session = AgentSession(
+    stt=..., llm=..., tts=...,
+    vad=silero.VAD.load(),
+    turn_handling={"turn_detection": duplexjev.TurnDetector(
+        api_url="http://localhost:8420",       # your own gateway; omit for the free hosted trial API
+        extra_questions=["emotion", "sound"],
+        on_answers=lambda a: print({k: v["answer"] for k, v in a.items()}),
+    )},
+)
+```
+
+`AgentSession(turn_detection=duplexjev.TurnDetector(), ...)` works too (LiveKit marks that argument as deprecated).
+A complete agent is in [`examples/agent.py`](examples/agent.py).
+
+**A VAD is required.** LiveKit ignores a streaming turn detector when the session has no VAD. The plugin buffers the
+user's audio, and after about 200 ms of VAD silence LiveKit asks it for a prediction: the last 8 s of the current
+user turn go to DuplexJev, and P(finished) becomes LiveKit's `end_of_turn_probability`. Below `unlikely_threshold`
+the session waits `max_delay` instead of `min_delay` before replying. The VAD's `min_silence_duration` must be at
+least 0.25 s (Silero's default is 0.55 s).
+
+**STT is optional for the decision.** If the session has an STT, LiveKit still waits for its transcript before it
+commits the turn, as with any turn detector, because the LLM needs the text.
+
+## Run the model yourself (recommended for real-time)
+
+The default URL is our free trial API (rate limited to 30 requests per minute; the round trip from outside mainland China adds network latency). For a live agent, serve the model next to it (DuplexJev-4B-Para needs about 10 GB of GPU memory):
+
+```bash
+pip install "vllm[audio]>=0.29" duplexjev-vllm "duplexjev[server]>=0.4.1"
+vllm serve adventists-ai/DuplexJev-4B-Para --max-model-len 4096 --port 8000 &
+duplexjev gateway --vllm http://localhost:8000/v1 --port 8420
+```
+
+Then pass `api_url="http://localhost:8420"` (or set `DUPLEXJEV_API_URL`).
+
+## Options
+
+| argument | default | |
+|---|---|---|
+| `api_url` | hosted trial API | base URL of a `duplexjev gateway` (or `DUPLEXJEV_API_URL`) |
+| `api_key` | `None` | bearer key, if your gateway requires one (or `DUPLEXJEV_API_KEY`) |
+| `lang` | `"en"` | `"en"` or `"zh"`: wording of the questions (the model hears both languages either way) |
+| `unlikely_threshold` | `0.5` | below this P(finished), wait `max_delay` instead of `min_delay` |
+| `backchannel_threshold` | `None` | if set, also asks "What should the assistant do now?" and reports P(short acknowledgement) as LiveKit's backchannel probability |
+| `extra_questions` | `[]` | `"emotion"`, `"sound"`, `"barge_in"`, or dicts `{"id", "text", "options"}` |
+| `on_answers` | `None` | callback with every answer dict; the latest is also on `detector.last_answers` |
+| `window_s` | `8.0` | seconds of the current user turn sent with each request |
+| `trim_silence` | `True` | drop the silence before the user started talking (keeps 0.3 s) |
+| `prediction_timeout` | `4.0` hosted, `1.0` own gateway | how long LiveKit waits for a prediction |
+| `fallback_probability` | `1.0` | P(finished) reported if the gateway fails, so the conversation never blocks |
+
+## License
+
+The plugin code is BSD-2-Clause. DuplexJev model weights are CC BY-NC 4.0 (non-commercial); see the
+[model cards](https://huggingface.co/adventists-ai). For commercial use, contact jiejin@adventists.ai.

livekit_plugins_duplexjev-0.1.0/examples/agent.py

@@ -0,0 +1,43 @@
+"""A LiveKit voice agent whose end-of-turn decisions come from DuplexJev.
+
+    pip install livekit-plugins-duplexjev "livekit-agents[silero]>=1.8"
+    export LIVEKIT_URL=... LIVEKIT_API_KEY=... LIVEKIT_API_SECRET=...
+    python examples/agent.py console      # or: dev / start
+
+STT, LLM and TTS go through LiveKit Inference here; swap in any plugins you like. DuplexJev only replaces the
+turn detector. Set DUPLEXJEV_API_URL to your own gateway for real-time use (the default hosted trial API is
+rate limited and served from mainland China).
+"""
+import logging
+
+from livekit.agents import Agent, AgentServer, AgentSession, JobContext, cli
+from livekit.plugins import duplexjev, silero
+
+logger = logging.getLogger("duplexjev-agent")
+server = AgentServer()
+
+
+def log_answers(answers: dict) -> None:
+    logger.info("duplexjev %s", {k: v["answer"] for k, v in answers.items()})
+
+
+@server.rtc_session()
+async def entrypoint(ctx: JobContext) -> None:
+    session = AgentSession(
+        stt="deepgram/nova-3",
+        llm="openai/gpt-4.1-mini",
+        tts="cartesia/sonic-2",
+        vad=silero.VAD.load(),  # required: LiveKit asks the turn detector after ~200 ms of VAD silence
+        turn_handling={
+            "turn_detection": duplexjev.TurnDetector(
+                extra_questions=["emotion", "sound"],  # answered in the same request
+                on_answers=log_answers,
+            ),
+        },
+    )
+    await session.start(agent=Agent(instructions="You are a friendly, concise voice assistant."), room=ctx.room)
+    await session.generate_reply(instructions="Greet the user.")
+
+
+if __name__ == "__main__":
+    cli.run_app(server)

livekit_plugins_duplexjev-0.1.0/livekit/plugins/duplexjev/__init__.py

@@ -0,0 +1,45 @@
+"""DuplexJev audio turn detection for LiveKit Agents.
+
+    from livekit.plugins import duplexjev, silero
+    session = AgentSession(turn_detection=duplexjev.TurnDetector(), vad=silero.VAD.load(), ...)
+"""
+
+from livekit.agents import Plugin
+
+from .log import logger
+from .turn_detector import (
+    DEFAULT_URL,
+    PRESETS,
+    REPLY_QUESTION,
+    TURN_QUESTION,
+    TurnDetector,
+    TurnDetectorStream,
+)
+from .version import __version__
+
+__all__ = [
+    "TurnDetector",
+    "TurnDetectorStream",
+    "DEFAULT_URL",
+    "PRESETS",
+    "TURN_QUESTION",
+    "REPLY_QUESTION",
+    "__version__",
+]
+
+
+class DuplexJevPlugin(Plugin):
+    def __init__(self) -> None:
+        super().__init__(__name__, __version__, __package__, logger)
+
+
+Plugin.register_plugin(DuplexJevPlugin())
+
+# Cleanup docs of unexported modules
+_module = dir()
+NOT_IN_ALL = [m for m in _module if m not in __all__]
+
+__pdoc__ = {}
+
+for n in NOT_IN_ALL:
+    __pdoc__[n] = False

livekit_plugins_duplexjev-0.1.0/livekit/plugins/duplexjev/log.py

@@ -0,0 +1,3 @@
+import logging
+
+logger = logging.getLogger("livekit.plugins.duplexjev")

livekit_plugins_duplexjev-0.1.0/livekit/plugins/duplexjev/turn_detector.py

@@ -0,0 +1,432 @@
+"""DuplexJev audio turn detector for LiveKit Agents.
+
+DuplexJev reads the turn state (finished / still talking / backchannel / asking to wait) straight from the user's
+audio as one constrained token of a speech LLM, so the decision needs no transcript and no decoding. Extra questions
+(emotion, non-verbal sounds, barge-in, your own multiple-choice questions) are answered in the same request and
+exposed on ``last_answers`` / ``on_answers``.
+
+This module implements LiveKit's *streaming* (audio) turn-detector protocol: ``AgentSession`` pushes every input
+audio frame into the stream, calls ``predict()`` once the VAD has seen ~200 ms of silence, and waits up to
+``prediction_timeout`` for the resulting ``TurnDetectionEvent``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import io
+import itertools
+import os
+import time
+import wave
+from typing import Any, Callable
+
+import aiohttp
+import numpy as np
+
+from livekit import rtc
+from livekit.agents import DEFAULT_API_CONNECT_OPTIONS, APIConnectOptions, utils
+from livekit.agents.language import LanguageCode
+from livekit.agents.voice.turn import TurnDetectionEvent
+
+from .log import logger
+
+DEFAULT_URL = "https://api.adventists.cn/duplexjev"
+SAMPLE_RATE = 16000
+
+TURN_QUESTION = {
+    "en": {"id": "turn", "text": "Has the user finished speaking?",
+           "options": ["finished, the assistant can reply", "not finished, still talking",
+                       "just a backchannel, not taking the turn", "hesitating or asking to wait"], "lang": "en"},
+    "zh": {"id": "turn", "text": "用户现在处于什么话轮状态？",
+           "options": ["话说完了，可以接话", "句子没说完，还在继续", "简短附和，不是要接话", "还在组织语言，或要求先等一下"],
+           "lang": "zh"},
+}
+
+# "What should the assistant do now?" -- its "short acknowledgement" option is what LiveKit means by a backchannel
+# opportunity (the *agent* says "mm-hmm"). Only asked when ``backchannel_threshold`` is set.
+REPLY_QUESTION = {
+    "en": {"id": "reply", "text": "What should the assistant do now?",
+           "options": ["reply now", "keep listening", "give a short acknowledgement"], "lang": "en"},
+    "zh": {"id": "reply", "text": "助手现在应该怎么做？",
+           "options": ["马上回复", "继续听", "简短回应一下"], "lang": "zh"},
+}
+
+PRESETS = {
+    "emotion": {"en": ("What is the speaker's emotional state?", ["neutral", "happy", "angry", "sad"]),
+                "zh": ("说话人当时的情绪状态是？", ["中性", "高兴", "生气", "伤心"])},
+    "sound": {"en": ("Besides speech, which sound can be heard in this audio?",
+                     ["laughter", "breathing", "coughing", "a sigh", "None of these"]),
+              "zh": ("除了说话，这段音频里还有哪种声音？", ["笑声", "呼吸声", "咳嗽", "叹气", "都没有"])},
+    "barge_in": {"en": ("Is the user trying to interrupt or take over the conversation?", ["yes", "no"]),
+                 "zh": ("用户是不是想打断或者抢话？", ["是", "不是"])},
+}
+
+HOSTED_PREDICTION_TIMEOUT = 4.0
+"""The free hosted API is served from mainland China: a round trip is often 2-3 s from elsewhere."""
+SELF_HOSTED_PREDICTION_TIMEOUT = 1.0
+
+
+def wav16k(pcm: np.ndarray) -> bytes:
+    """16 kHz mono int16 samples -> WAV bytes."""
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(SAMPLE_RATE)
+        w.writeframes(np.asarray(pcm, dtype="<i2").tobytes())
+    return buf.getvalue()
+
+
+def trim_leading_silence(pcm: np.ndarray, *, preroll_s: float = 0.3, block_s: float = 0.05) -> np.ndarray:
+    """Drop quiet audio before the first loud block (keeping ``preroll_s``), so the window holds the utterance."""
+    n = int(block_s * SAMPLE_RATE)
+    if len(pcm) < 2 * n:
+        return pcm
+    blocks = pcm[: len(pcm) // n * n].astype(np.float32).reshape(-1, n)
+    rms = np.sqrt(np.mean(blocks * blocks, axis=1))
+    peak = float(rms.max())
+    if peak < 100.0:  # nothing that looks like speech: send as is
+        return pcm
+    first = int(np.argmax(rms >= max(0.1 * peak, 60.0)))
+    start = max(0, first * n - int(preroll_s * SAMPLE_RATE))
+    return pcm[start:]
+
+
+class TurnDetector:
+    """Audio end-of-turn detection with DuplexJev, via the hosted API or your own ``duplexjev gateway``.
+
+    Pass it as ``AgentSession(turn_detection=TurnDetector(), vad=silero.VAD.load(), ...)``. A VAD is required:
+    LiveKit drops a streaming turn detector when the session has none.
+
+    Args:
+        api_url: base URL of a DuplexJev gateway. Defaults to the free hosted trial API (rate limited, served from
+            mainland China). For production run your own: ``vllm serve adventists-ai/DuplexJev-4B-Para`` +
+            ``duplexjev gateway``. Also read from ``DUPLEXJEV_API_URL``.
+        api_key: bearer key, if the gateway requires one. Also read from ``DUPLEXJEV_API_KEY``.
+        lang: ``"en"`` or ``"zh"``: wording of the questions (the model hears both languages either way).
+        unlikely_threshold: LiveKit's knob. When P(finished) is below it, the session waits ``max_delay`` instead
+            of ``min_delay`` before committing the turn.
+        backchannel_threshold: if set, also asks "What should the assistant do now?" and reports P("give a short
+            acknowledgement") as ``backchannel_probability``; LiveKit raises a backchannel opportunity at or above
+            this value. ``None`` (default) disables it and keeps the request to one question.
+        extra_questions: names from ``PRESETS`` (``"emotion"``, ``"sound"``, ``"barge_in"``) or question dicts
+            ``{"id", "text", "options"}``, answered in the same request; see ``last_answers``.
+        on_answers: optional callback ``f(answers: dict)`` called after every successful prediction.
+        window_s: seconds of the current user turn sent with each request (the most recent ones).
+        trim_silence: drop the quiet audio before the user started talking, keeping 0.3 s of pre-roll.
+        prediction_timeout: how long LiveKit waits for a prediction before committing without one. Defaults to
+            4 s for the hosted API and 1 s for your own gateway.
+        fallback_probability: P(finished) reported when the gateway fails (network error, HTTP error, rate limit).
+            ``1.0`` (like LiveKit's own detector) commits after ``min_delay``; ``0.0`` waits ``max_delay``.
+        http_session: an ``aiohttp.ClientSession`` to reuse. By default the job's session is used, or one is
+            created per stream.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_url: str | None = None,
+        api_key: str | None = None,
+        lang: str = "en",
+        unlikely_threshold: float = 0.5,
+        backchannel_threshold: float | None = None,
+        extra_questions: list[str | dict[str, Any]] | None = None,
+        on_answers: Callable[[dict[str, Any]], Any] | None = None,
+        window_s: float = 8.0,
+        trim_silence: bool = True,
+        prediction_timeout: float | None = None,
+        fallback_probability: float = 1.0,
+        http_session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        if lang not in TURN_QUESTION:
+            raise ValueError("lang must be 'en' or 'zh'")
+        api_url = api_url or os.environ.get("DUPLEXJEV_API_URL") or DEFAULT_URL
+        self._base_url = api_url.rstrip("/")
+        self._decide_url = self._base_url + "/v1/decide"
+        api_key = api_key or os.environ.get("DUPLEXJEV_API_KEY")
+        self._headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+        self._lang = lang
+        self._unlikely_threshold = unlikely_threshold
+        self._backchannel_threshold = backchannel_threshold
+        self._on_answers = on_answers
+        self._window_s = window_s
+        self._trim_silence = trim_silence
+        if prediction_timeout is None:
+            prediction_timeout = (
+                HOSTED_PREDICTION_TIMEOUT if self._base_url == DEFAULT_URL else SELF_HOSTED_PREDICTION_TIMEOUT
+            )
+        self._prediction_timeout = prediction_timeout
+        self._fallback_probability = fallback_probability
+        self._http_session = http_session
+
+        self._questions: list[dict[str, Any]] = [TURN_QUESTION[lang]]
+        if backchannel_threshold is not None:
+            self._questions.append(REPLY_QUESTION[lang])
+        self._questions += [self._as_question(q) for q in (extra_questions or [])]
+        ids = [q["id"] for q in self._questions]
+        if len(set(ids)) != len(ids):
+            raise ValueError(f"duplicate question ids: {ids}")
+
+        self._model_name = "DuplexJev"
+        self.last_answers: dict[str, Any] = {}
+        """Answers of the latest successful request: ``{id: {"answer", "confidence", "probs"}}``."""
+        self.last_server_ms: float | None = None
+        """Server-side model time of the latest request, in milliseconds."""
+
+    def _as_question(self, q: str | dict[str, Any]) -> dict[str, Any]:
+        if isinstance(q, str):
+            if q not in PRESETS:
+                raise ValueError(f"unknown preset {q!r}; choose from {sorted(PRESETS)} or pass a dict")
+            text, options = PRESETS[q][self._lang]
+            return {"id": q, "text": text, "options": options, "lang": self._lang}
+        d = dict(q)
+        if not {"id", "text", "options"} <= d.keys():
+            raise ValueError("a question dict needs 'id', 'text' and 'options'")
+        d.setdefault("lang", self._lang)
+        return d
+
+    @property
+    def model(self) -> str:
+        return self._model_name
+
+    @property
+    def provider(self) -> str:
+        return "duplexjev"
+
+    @property
+    def questions(self) -> list[dict[str, Any]]:
+        return list(self._questions)
+
+    def stream(self, *, conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS) -> TurnDetectorStream:
+        return TurnDetectorStream(detector=self, conn_options=conn_options)
+
+    # the capability methods below are mirrored on the stream, which is what AudioRecognition queries
+    async def unlikely_threshold(self, language: LanguageCode | None) -> float | None:
+        return self._unlikely_threshold
+
+    async def backchannel_threshold(self, language: LanguageCode | None) -> float | None:
+        return self._backchannel_threshold
+
+    async def supports_language(self, language: LanguageCode | None) -> bool:
+        return True
+
+
+class TurnDetectorStream:
+    """Per-session audio buffer and inference requests. Created by ``TurnDetector.stream()``."""
+
+    def __init__(self, *, detector: TurnDetector, conn_options: APIConnectOptions) -> None:
+        self._detector = detector
+        self._conn_options = conn_options
+        self._chunks: list[np.ndarray] = []
+        self._n_samples = 0
+        self._max_samples = int(max(detector._window_s, 1.0) * SAMPLE_RATE * 2)
+        self._in_rate: int | None = None
+        self._resampler: rtc.AudioResampler | None = None
+        self._last_audio_at: float | None = None
+        self._closed = False
+
+        self._ids = itertools.count(1)
+        self._request_id: int | None = None
+        self._request_fut: asyncio.Future[TurnDetectionEvent] | None = None
+        self._request_task: asyncio.Task[None] | None = None
+        self._session: aiohttp.ClientSession | None = detector._http_session
+        self._owns_session = False
+        self._warned = False
+
+        self.last_answers: dict[str, Any] = {}
+        self.last_server_ms: float | None = None
+
+    # region: protocol properties
+    @property
+    def model(self) -> str:
+        return self._detector.model
+
+    @property
+    def provider(self) -> str:
+        return self._detector.provider
+
+    @property
+    def is_fallback(self) -> bool:
+        return False
+
+    @property
+    def prediction_timeout(self) -> float:
+        return self._detector._prediction_timeout
+
+    async def unlikely_threshold(self, language: LanguageCode | None) -> float | None:
+        return await self._detector.unlikely_threshold(language)
+
+    async def backchannel_threshold(self, language: LanguageCode | None) -> float | None:
+        return await self._detector.backchannel_threshold(language)
+
+    async def supports_language(self, language: LanguageCode | None) -> bool:
+        return await self._detector.supports_language(language)
+
+    # endregion
+
+    # region: audio
+    def push_audio(self, frame: rtc.AudioFrame) -> None:
+        if self._closed:
+            return
+        pcm = np.frombuffer(frame.data, dtype=np.int16)
+        if frame.num_channels > 1:
+            pcm = pcm.reshape(-1, frame.num_channels).mean(axis=1).astype(np.int16)
+        if frame.sample_rate != self._in_rate:
+            self._in_rate = frame.sample_rate
+            self._resampler = (
+                rtc.AudioResampler(frame.sample_rate, SAMPLE_RATE, num_channels=1,
+                                   quality=rtc.AudioResamplerQuality.QUICK)
+                if frame.sample_rate != SAMPLE_RATE else None
+            )
+        if self._resampler is None:
+            self._append(pcm.copy())
+        else:
+            mono = rtc.AudioFrame(pcm.tobytes(), frame.sample_rate, 1, len(pcm))
+            for out in self._resampler.push(mono):
+                self._append(np.frombuffer(out.data, dtype=np.int16).copy())
+        self._last_audio_at = time.time()
+
+    def _append(self, pcm: np.ndarray) -> None:
+        if not len(pcm):
+            return
+        self._chunks.append(pcm)
+        self._n_samples += len(pcm)
+        while self._n_samples - len(self._chunks[0]) >= self._max_samples:
+            self._n_samples -= len(self._chunks.pop(0))
+
+    def _window(self) -> np.ndarray:
+        if not self._chunks:
+            return np.zeros(0, np.int16)
+        pcm = np.concatenate(self._chunks)[-int(self._detector._window_s * SAMPLE_RATE):]
+        return trim_leading_silence(pcm) if self._detector._trim_silence else pcm
+
+    def _clear_audio(self) -> None:
+        self._chunks = []
+        self._n_samples = 0
+        self._in_rate = None
+        self._resampler = None
+
+    # endregion
+
+    # region: inference
+    def predict(self) -> asyncio.Future[TurnDetectionEvent]:
+        """Send the recent audio of the current user turn and return the future prediction."""
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future[TurnDetectionEvent] = loop.create_future()
+        if self._closed:
+            fut.set_result(self._event(1.0))
+            return fut
+        self.cancel_inference()  # supersede any previous request
+        pcm = self._window()
+        request_id = next(self._ids)
+        self._request_id, self._request_fut = request_id, fut
+        if not len(pcm):
+            self._resolve(request_id, self._event(self._detector._fallback_probability))
+            return fut
+        self._request_task = asyncio.create_task(self._run(request_id, wav16k(pcm), self._last_audio_at))
+        return fut
+
+    def cancel_inference(self, *, timed_out: bool = False) -> None:
+        """Abandon the in-flight request (new speech, turn boundary, prediction timeout, mode change)."""
+        task, fut = self._request_task, self._request_fut
+        self._request_id = self._request_fut = self._request_task = None
+        if task is not None and not task.done():
+            task.cancel()
+        if fut is not None and not fut.done():
+            fut.set_result(self._event(0.0))
+        if timed_out:
+            logger.debug("DuplexJev prediction timed out", extra={"timeout": self.prediction_timeout})
+
+    def flush(self, reason: str | None = None) -> None:
+        """Start a new user turn: forget the buffered audio and any in-flight request."""
+        self.cancel_inference()
+        self._clear_audio()
+
+    def end_input(self) -> None:
+        self.flush(reason="end_input")
+        self._closed = True
+
+    async def aclose(self) -> None:
+        self.end_input()
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+        self._session = None
+
+    def _http(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            try:
+                self._session = utils.http_context.http_session()
+            except RuntimeError:
+                self._session = aiohttp.ClientSession()
+                self._owns_session = True
+        return self._session
+
+    async def _run(self, request_id: int, wav: bytes, last_audio_at: float | None) -> None:
+        det = self._detector
+        payload = {"audio_b64": base64.b64encode(wav).decode(), "format": "wav", "lang": det._lang,
+                   "questions": det._questions}
+        try:
+            async with self._http().post(
+                det._decide_url, json=payload, headers=det._headers,
+                timeout=aiohttp.ClientTimeout(total=self._conn_options.timeout),
+            ) as resp:
+                if resp.status != 200:
+                    body = (await resp.text())[:200]
+                    raise RuntimeError(f"HTTP {resp.status}: {body}")
+                data = await resp.json()
+            answers: dict[str, Any] = data["answers"]
+            probs = answers["turn"]["probs"]
+            p_finished = float(probs.get(TURN_QUESTION[det._lang]["options"][0], 0.0))
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:  # network or server error: never block the conversation
+            if not self._warned:
+                logger.warning("DuplexJev request failed (%s); reporting P(finished)=%s",
+                               e, det._fallback_probability)
+                self._warned = True
+            else:
+                logger.debug("DuplexJev request failed: %s", e)
+            self._resolve(request_id, self._event(det._fallback_probability))
+            return
+
+        if request_id != self._request_id:
+            return  # superseded while the response was in flight
+        server_ms = data.get("ms")
+        if data.get("model"):
+            det._model_name = str(data["model"])
+        backchannel = None
+        if "reply" in answers and det._backchannel_threshold is not None:
+            backchannel = float(answers["reply"]["probs"].get(REPLY_QUESTION[det._lang]["options"][2], 0.0))
+        now = time.time()
+        self.last_answers = det.last_answers = answers
+        self.last_server_ms = det.last_server_ms = server_ms
+        event = TurnDetectionEvent(
+            type="eot_prediction",
+            end_of_turn_probability=p_finished,
+            last_speaking_time=now,
+            detection_delay=now - last_audio_at if last_audio_at is not None else None,
+            inference_duration=float(server_ms) / 1000 if server_ms is not None else None,
+            backchannel_probability=backchannel,
+        )
+        if det._on_answers is not None:
+            try:
+                det._on_answers(answers)
+            except Exception as e:
+                logger.warning("on_answers callback raised: %s", e)
+        self._resolve(request_id, event)
+
+    def _resolve(self, request_id: int, event: TurnDetectionEvent) -> None:
+        if request_id != self._request_id:
+            return  # stale: superseded or cancelled
+        fut = self._request_fut
+        self._request_id = self._request_fut = self._request_task = None
+        if fut is not None and not fut.done():
+            fut.set_result(event)
+
+    @staticmethod
+    def _event(probability: float) -> TurnDetectionEvent:
+        return TurnDetectionEvent(type="eot_prediction", end_of_turn_probability=probability,
+                                  last_speaking_time=time.time())
+
+    # endregion

livekit_plugins_duplexjev-0.1.0/livekit/plugins/duplexjev/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

livekit_plugins_duplexjev-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "livekit-plugins-duplexjev"
+dynamic = ["version"]
+description = "Audio end-of-turn detection for LiveKit Agents with DuplexJev: turn state, emotion and non-verbal sounds from one request, no transcript needed."
+readme = "README.md"
+license = { text = "BSD-2-Clause" }
+authors = [{ name = "Jie Jin", email = "jiejin@adventists.ai" }]
+requires-python = ">=3.10"
+dependencies = ["livekit-agents>=1.8,<2", "aiohttp", "numpy"]
+keywords = ["livekit", "livekit-agents", "turn-detection", "end-of-turn", "voice-agent", "speech-llm", "duplexjev"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: BSD License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/adventists-ai/duplexjev/tree/main/integrations/livekit"
+Models = "https://huggingface.co/adventists-ai/DuplexJev-4B-Para"
+Paper = "https://arxiv.org/abs/2610.02638"
+
+[tool.hatch.version]
+path = "livekit/plugins/duplexjev/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["livekit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/livekit", "/tests", "/examples", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

livekit_plugins_duplexjev-0.1.0/tests/conftest.py

@@ -0,0 +1,76 @@
+import asyncio
+import io
+import wave
+
+import numpy as np
+import pytest
+from aiohttp import web
+
+from livekit import rtc
+
+
+def frames(seconds: float, *, sample_rate: int = 48000, channels: int = 1, freq: float = 220.0,
+           amplitude: float = 0.3, frame_ms: int = 10):
+    """Fake microphone frames: a sine tone (or silence with amplitude=0), interleaved int16."""
+    n = int(sample_rate * frame_ms / 1000)
+    t0 = 0
+    for _ in range(int(seconds * 1000 / frame_ms)):
+        t = (np.arange(n) + t0) / sample_rate
+        x = (amplitude * 32767 * np.sin(2 * np.pi * freq * t)).astype(np.int16)
+        t0 += n
+        data = np.repeat(x, channels) if channels > 1 else x
+        yield rtc.AudioFrame(data.tobytes(), sample_rate, channels, n)
+
+
+def read_wav(b: bytes):
+    with wave.open(io.BytesIO(b)) as w:
+        return w.getframerate(), w.getnchannels(), np.frombuffer(w.readframes(w.getnframes()), np.int16)
+
+
+class FakeGateway:
+    """Mimics ``duplexjev gateway``'s POST /v1/decide."""
+
+    def __init__(self):
+        self.p_finished = 0.9
+        self.p_ack = 0.7
+        self.delay = 0.0
+        self.status = 200
+        self.requests: list[dict] = []
+
+    async def decide(self, request: web.Request) -> web.Response:
+        body = await request.json()
+        self.requests.append(body)
+        if self.delay:
+            await asyncio.sleep(self.delay)
+        if self.status != 200:
+            return web.Response(status=self.status, text="rate limited")
+        answers = {}
+        for q in body["questions"]:
+            opts = q["options"]
+            probs = {o: 0.0 for o in opts}
+            if q["id"] == "turn":
+                probs[opts[0]] = self.p_finished
+                probs[opts[1]] = 1 - self.p_finished
+            elif q["id"] == "reply":
+                probs[opts[2]] = self.p_ack
+                probs[opts[1]] = 1 - self.p_ack
+            else:
+                probs[opts[0]] = 1.0
+            best = max(probs, key=probs.get)
+            answers[q["id"]] = {"answer": best, "confidence": probs[best], "probs": probs}
+        return web.json_response({"answers": answers, "ms": 42.0, "model": "DuplexJev-Fake"})
+
+
+@pytest.fixture()
+async def gateway():
+    gw = FakeGateway()
+    app = web.Application()
+    app.router.add_post("/v1/decide", gw.decide)
+    runner = web.AppRunner(app)
+    await runner.setup()
+    site = web.TCPSite(runner, "127.0.0.1", 0)
+    await site.start()
+    port = site._server.sockets[0].getsockname()[1]
+    gw.url = f"http://127.0.0.1:{port}"
+    yield gw
+    await runner.cleanup()

livekit_plugins_duplexjev-0.1.0/tests/test_live.py

@@ -0,0 +1,48 @@
+"""Live check against the hosted DuplexJev API. Skipped unless DUPLEXJEV_LIVE=1.
+
+Clips are read from DUPLEXJEV_CLIPS (default: the repo's docs/audio). ex4.wav is a finished sentence, ex3.wav an
+unfinished one. Run with ``DUPLEXJEV_LIVE=1 pytest -s tests/test_live.py`` to see the probabilities.
+"""
+import os
+import time
+import wave
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from livekit import rtc
+from livekit.plugins import duplexjev
+
+pytestmark = pytest.mark.skipif(os.environ.get("DUPLEXJEV_LIVE") != "1", reason="set DUPLEXJEV_LIVE=1")
+
+CLIPS = Path(os.environ.get("DUPLEXJEV_CLIPS", Path(__file__).resolve().parents[3] / "docs" / "audio"))
+
+
+def clip_frames(path: Path, frame_ms: int = 20):
+    with wave.open(str(path)) as w:
+        sr, ch = w.getframerate(), w.getnchannels()
+        x = np.frombuffer(w.readframes(w.getnframes()), np.int16)
+    n = sr * frame_ms // 1000
+    x = np.concatenate([x, np.zeros(n * ch * 15, np.int16)])  # + 300 ms of silence, as when VAD fires
+    for i in range(0, len(x) // (n * ch) * n * ch, n * ch):
+        yield rtc.AudioFrame(x[i:i + n * ch].tobytes(), sr, ch, n)
+
+
+@pytest.mark.parametrize("name,finished", [("ex4.wav", True), ("ex3.wav", False)])
+async def test_live_clip(name, finished):
+    path = CLIPS / name
+    if not path.exists():
+        pytest.skip(f"{path} not found; set DUPLEXJEV_CLIPS")
+    det = duplexjev.TurnDetector(extra_questions=["emotion"])
+    stream = det.stream()
+    for f in clip_frames(path):
+        stream.push_audio(f)
+    t = time.time()
+    ev = await stream.predict()
+    rtt = time.time() - t
+    await stream.aclose()
+    print(f"\n{name}: P(finished)={ev.end_of_turn_probability:.3f} turn={det.last_answers['turn']['answer']!r} "
+          f"emotion={det.last_answers['emotion']['answer']} server={ev.inference_duration * 1000:.1f} ms "
+          f"round trip={rtt * 1000:.0f} ms model={det.model}")
+    assert (ev.end_of_turn_probability >= 0.5) == finished

livekit_plugins_duplexjev-0.1.0/tests/test_turn_detector.py

@@ -0,0 +1,174 @@
+import asyncio
+
+import numpy as np
+import pytest
+from conftest import frames, read_wav
+
+from livekit.agents.voice.turn import (
+    _resolve_endpointing,
+    _StreamingTurnDetector,
+    _StreamingTurnDetectorStream,
+)
+from livekit.plugins import duplexjev
+from livekit.plugins.duplexjev.turn_detector import trim_leading_silence
+
+
+def push(stream, *args, **kw):
+    for f in frames(*args, **kw):
+        stream.push_audio(f)
+
+
+async def test_satisfies_livekit_streaming_protocol(gateway):
+    det = duplexjev.TurnDetector(api_url=gateway.url)
+    assert isinstance(det, _StreamingTurnDetector)
+    stream = det.stream()
+    assert isinstance(stream, _StreamingTurnDetectorStream)
+    # AgentSession picks the tighter streaming endpointing defaults for it
+    assert _resolve_endpointing(turn_detection=det)["min_delay"] == 0.3
+    assert stream.prediction_timeout == 1.0  # self-hosted default
+    assert duplexjev.TurnDetector().stream().prediction_timeout == 4.0  # hosted API default
+    assert await stream.unlikely_threshold(None) == 0.5
+    assert await stream.backchannel_threshold(None) is None
+    assert await stream.supports_language(None)
+    await stream.aclose()
+
+
+async def test_predict_sends_16k_mono_and_returns_event(gateway):
+    seen = []
+    det = duplexjev.TurnDetector(api_url=gateway.url, extra_questions=["emotion", "sound"],
+                                 on_answers=seen.append)
+    stream = det.stream()
+    push(stream, 1.0, sample_rate=48000, channels=2)
+    push(stream, 0.2, sample_rate=48000, channels=2, amplitude=0.0)
+    ev = await asyncio.wait_for(stream.predict(), 2)
+
+    assert ev.type == "eot_prediction"
+    assert ev.end_of_turn_probability == pytest.approx(0.9)
+    assert ev.inference_duration == pytest.approx(0.042)
+    assert ev.backchannel_probability is None
+    assert ev.detection_delay is not None and ev.detection_delay >= 0
+
+    body = gateway.requests[-1]
+    assert [q["id"] for q in body["questions"]] == ["turn", "emotion", "sound"]
+    assert body["questions"][0]["text"] == "Has the user finished speaking?"
+    sr, ch, pcm = read_wav(__import__("base64").b64decode(body["audio_b64"]))
+    assert (sr, ch) == (16000, 1)
+    assert abs(len(pcm) - 1.2 * 16000) < 400  # resampler latency only
+    assert np.abs(pcm).max() > 5000
+
+    assert stream.last_answers["emotion"]["answer"] == "neutral"
+    assert det.last_answers is stream.last_answers and det.last_server_ms == 42.0
+    assert seen and seen[-1]["sound"]["answer"] == "laughter"
+    assert det.model == "DuplexJev-Fake"
+
+    gateway.p_finished = 0.1
+    ev = await asyncio.wait_for(stream.predict(), 2)
+    assert ev.end_of_turn_probability == pytest.approx(0.1)
+    await stream.aclose()
+
+
+async def test_backchannel_opportunity_uses_reply_question(gateway):
+    det = duplexjev.TurnDetector(api_url=gateway.url, backchannel_threshold=0.6, lang="zh")
+    stream = det.stream()
+    push(stream, 0.5, sample_rate=16000)
+    ev = await stream.predict()
+    assert [q["id"] for q in gateway.requests[-1]["questions"]] == ["turn", "reply"]
+    assert gateway.requests[-1]["lang"] == "zh"
+    assert ev.backchannel_probability == pytest.approx(0.7)
+    assert await stream.backchannel_threshold(None) == 0.6
+    await stream.aclose()
+
+
+async def test_window_keeps_only_recent_audio(gateway):
+    stream = duplexjev.TurnDetector(api_url=gateway.url, window_s=3.0, trim_silence=False).stream()
+    push(stream, 7.0, sample_rate=24000)
+    await stream.predict()
+    _, _, pcm = read_wav(__import__("base64").b64decode(gateway.requests[-1]["audio_b64"]))
+    assert len(pcm) == 3 * 16000
+    await stream.aclose()
+
+
+async def test_cancel_inference_resolves_zero_and_ignores_late_reply(gateway):
+    gateway.delay = 0.5
+    stream = duplexjev.TurnDetector(api_url=gateway.url).stream()
+    push(stream, 0.5)
+    fut = stream.predict()
+    await asyncio.sleep(0.1)
+    stream.cancel_inference()
+    assert fut.done() and fut.result().end_of_turn_probability == 0.0
+    await asyncio.sleep(0.6)
+    assert stream.last_answers == {}  # the late response was dropped
+    await stream.aclose()
+
+
+async def test_new_predict_supersedes_previous(gateway):
+    gateway.delay = 0.2
+    stream = duplexjev.TurnDetector(api_url=gateway.url).stream()
+    push(stream, 0.5)
+    first = stream.predict()
+    second = stream.predict()
+    assert first.done() and first.result().end_of_turn_probability == 0.0
+    assert (await second).end_of_turn_probability == pytest.approx(0.9)
+    await stream.aclose()
+
+
+async def test_flush_starts_a_new_turn(gateway):
+    stream = duplexjev.TurnDetector(api_url=gateway.url, fallback_probability=0.25).stream()
+    push(stream, 2.0)
+    stream.flush(reason="turn committed")
+    ev = await stream.predict()  # nothing buffered: no request is sent
+    assert ev.end_of_turn_probability == 0.25 and gateway.requests == []
+    push(stream, 0.4)
+    await stream.predict()
+    _, _, pcm = read_wav(__import__("base64").b64decode(gateway.requests[-1]["audio_b64"]))
+    assert len(pcm) < 0.5 * 16000
+    await stream.aclose()
+
+
+async def test_http_error_and_unreachable_gateway_fall_back(gateway):
+    gateway.status = 429
+    stream = duplexjev.TurnDetector(api_url=gateway.url).stream()
+    push(stream, 0.5)
+    assert (await stream.predict()).end_of_turn_probability == 1.0
+    await stream.aclose()
+
+    stream = duplexjev.TurnDetector(api_url="http://127.0.0.1:9", fallback_probability=0.0).stream()
+    push(stream, 0.5)
+    assert (await asyncio.wait_for(stream.predict(), 5)).end_of_turn_probability == 0.0
+    await stream.aclose()
+
+
+async def test_end_input_and_aclose(gateway):
+    stream = duplexjev.TurnDetector(api_url=gateway.url).stream()
+    push(stream, 0.5)
+    stream.end_input()
+    push(stream, 0.5)  # ignored
+    assert (await stream.predict()).end_of_turn_probability == 1.0
+    assert gateway.requests == []
+    await stream.aclose()
+    await stream.aclose()  # idempotent
+
+
+def test_trim_leading_silence():
+    sil = np.zeros(32000, np.int16)
+    speech = (np.sin(np.arange(16000) / 5) * 8000).astype(np.int16)
+    out = trim_leading_silence(np.concatenate([sil, speech]))
+    assert abs(len(out) - (16000 + 0.3 * 16000)) <= 800
+    assert len(trim_leading_silence(sil)) == len(sil)
+
+
+def test_bad_arguments():
+    with pytest.raises(ValueError):
+        duplexjev.TurnDetector(lang="fr")
+    with pytest.raises(ValueError):
+        duplexjev.TurnDetector(extra_questions=["nope"])
+    with pytest.raises(ValueError):
+        duplexjev.TurnDetector(extra_questions=[{"id": "turn", "text": "x", "options": ["a", "b"]}])
+
+
+async def test_agent_session_accepts_it(gateway):
+    from livekit.agents import AgentSession
+
+    det = duplexjev.TurnDetector(api_url=gateway.url)
+    session = AgentSession(turn_handling={"turn_detection": det})
+    assert session.turn_detection is det