livekit-plugins-turn-detector


Namelivekit-plugins-turn-detector JSON
Version 1.2.1 PyPI version JSON
download
home_pageNone
SummaryEnd of utterance detection for LiveKit Agents
upload_time2025-07-17 18:42:20
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9.0
licenseNone
keywords audio livekit realtime video webrtc
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Turn detector plugin for LiveKit Agents

This plugin introduces end-of-turn detection for LiveKit Agents using a custom open-weight model to determine when a user has finished speaking.

Traditional voice agents use VAD (voice activity detection) for end-of-turn detection. However, VAD models lack language understanding, often causing false positives where the agent interrupts the user before they finish speaking.

By leveraging a language model specifically trained for this task, this plugin offers a more accurate and robust method for detecting end-of-turns.

See [https://docs.livekit.io/agents/build/turns/turn-detector/](https://docs.livekit.io/agents/build/turns/turn-detector/) for more information.

## Installation

```bash
pip install livekit-plugins-turn-detector
```

## Usage

### English model

The English model is the smaller of the two models. It requires 200MB of RAM and completes inference in ~10ms

```python
from livekit.plugins.turn_detector.english import EnglishModel

session = AgentSession(
    ...
    turn_detection=EnglishModel(),
)
```

### Multilingual model

We've trained a separate multilingual model that supports the following languages: `English, French, Spanish, German, Italian, Portuguese, Dutch, Chinese, Japanese, Korean, Indonesian, Russian, Turkish`

The multilingual model requires ~400MB of RAM and completes inferences in ~25ms.

```python
from livekit.plugins.turn_detector.multilingual import MultilingualModel

session = AgentSession(
    ...
    turn_detection=MultilingualModel(),
)
```

### Usage with RealtimeModel

The turn detector can be used even with speech-to-speech models such as OpenAI's Realtime API. You'll need to provide a separate STT to ensure our model has access to the text content.

```python
session = AgentSession(
    ...
    stt=deepgram.STT(model="nova-3", language="multi"),
    llm=openai.realtime.RealtimeModel(),
    turn_detection=MultilingualModel(),
)
```

## Running your agent

This plugin requires model files. Before starting your agent for the first time, or when building Docker images for deployment, run the following command to download the model files:

```bash
python my_agent.py download-files
```

## Model system requirements

The end-of-turn model is optimized to run on CPUs with modest system requirements. It is designed to run on the same server hosting your agents.

The model requires <500MB of RAM and runs within a shared inference server, supporting multiple concurrent sessions.

## License

The plugin source code is licensed under the Apache-2.0 license.

The end-of-turn model is licensed under the [LiveKit Model License](https://huggingface.co/livekit/turn-detector/blob/main/LICENSE).

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "livekit-plugins-turn-detector",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9.0",
    "maintainer_email": null,
    "keywords": "audio, livekit, realtime, video, webrtc",
    "author": null,
    "author_email": "LiveKit <hello@livekit.io>",
    "download_url": "https://files.pythonhosted.org/packages/55/13/3a493656351903f6d945816bac565bf0d1200d0e7c6e9ef3531014fce214/livekit_plugins_turn_detector-1.2.1.tar.gz",
    "platform": null,
    "description": "# Turn detector plugin for LiveKit Agents\n\nThis plugin introduces end-of-turn detection for LiveKit Agents using a custom open-weight model to determine when a user has finished speaking.\n\nTraditional voice agents use VAD (voice activity detection) for end-of-turn detection. However, VAD models lack language understanding, often causing false positives where the agent interrupts the user before they finish speaking.\n\nBy leveraging a language model specifically trained for this task, this plugin offers a more accurate and robust method for detecting end-of-turns.\n\nSee [https://docs.livekit.io/agents/build/turns/turn-detector/](https://docs.livekit.io/agents/build/turns/turn-detector/) for more information.\n\n## Installation\n\n```bash\npip install livekit-plugins-turn-detector\n```\n\n## Usage\n\n### English model\n\nThe English model is the smaller of the two models. It requires 200MB of RAM and completes inference in ~10ms\n\n```python\nfrom livekit.plugins.turn_detector.english import EnglishModel\n\nsession = AgentSession(\n    ...\n    turn_detection=EnglishModel(),\n)\n```\n\n### Multilingual model\n\nWe've trained a separate multilingual model that supports the following languages: `English, French, Spanish, German, Italian, Portuguese, Dutch, Chinese, Japanese, Korean, Indonesian, Russian, Turkish`\n\nThe multilingual model requires ~400MB of RAM and completes inferences in ~25ms.\n\n```python\nfrom livekit.plugins.turn_detector.multilingual import MultilingualModel\n\nsession = AgentSession(\n    ...\n    turn_detection=MultilingualModel(),\n)\n```\n\n### Usage with RealtimeModel\n\nThe turn detector can be used even with speech-to-speech models such as OpenAI's Realtime API. You'll need to provide a separate STT to ensure our model has access to the text content.\n\n```python\nsession = AgentSession(\n    ...\n    stt=deepgram.STT(model=\"nova-3\", language=\"multi\"),\n    llm=openai.realtime.RealtimeModel(),\n    turn_detection=MultilingualModel(),\n)\n```\n\n## Running your agent\n\nThis plugin requires model files. Before starting your agent for the first time, or when building Docker images for deployment, run the following command to download the model files:\n\n```bash\npython my_agent.py download-files\n```\n\n## Model system requirements\n\nThe end-of-turn model is optimized to run on CPUs with modest system requirements. It is designed to run on the same server hosting your agents.\n\nThe model requires <500MB of RAM and runs within a shared inference server, supporting multiple concurrent sessions.\n\n## License\n\nThe plugin source code is licensed under the Apache-2.0 license.\n\nThe end-of-turn model is licensed under the [LiveKit Model License](https://huggingface.co/livekit/turn-detector/blob/main/LICENSE).\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "End of utterance detection for LiveKit Agents",
    "version": "1.2.1",
    "project_urls": {
        "Documentation": "https://docs.livekit.io",
        "Source": "https://github.com/livekit/agents",
        "Website": "https://livekit.io/"
    },
    "split_keywords": [
        "audio",
        " livekit",
        " realtime",
        " video",
        " webrtc"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "19858a4573bde7c485b3625de5cff9c37314a4cb580490d657da8dde3da40f16",
                "md5": "9003b59bb09dd8ac14af3243e3cd149d",
                "sha256": "347acfea1aaa04c9c7ba940929d37a2ff6a81d7741f86365f3c4690cce59a258"
            },
            "downloads": -1,
            "filename": "livekit_plugins_turn_detector-1.2.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9003b59bb09dd8ac14af3243e3cd149d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9.0",
            "size": 9691,
            "upload_time": "2025-07-17T18:42:19",
            "upload_time_iso_8601": "2025-07-17T18:42:19.287714Z",
            "url": "https://files.pythonhosted.org/packages/19/85/8a4573bde7c485b3625de5cff9c37314a4cb580490d657da8dde3da40f16/livekit_plugins_turn_detector-1.2.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "55133a493656351903f6d945816bac565bf0d1200d0e7c6e9ef3531014fce214",
                "md5": "c9802c6945e46b833b5098d2a4fbafc3",
                "sha256": "2963788028d5f18aecdf3e70b65948df2598df3a5f453add2be3190d64a8f3fe"
            },
            "downloads": -1,
            "filename": "livekit_plugins_turn_detector-1.2.1.tar.gz",
            "has_sig": false,
            "md5_digest": "c9802c6945e46b833b5098d2a4fbafc3",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9.0",
            "size": 7934,
            "upload_time": "2025-07-17T18:42:20",
            "upload_time_iso_8601": "2025-07-17T18:42:20.082115Z",
            "url": "https://files.pythonhosted.org/packages/55/13/3a493656351903f6d945816bac565bf0d1200d0e7c6e9ef3531014fce214/livekit_plugins_turn_detector-1.2.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-17 18:42:20",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "livekit",
    "github_project": "agents",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "livekit-plugins-turn-detector"
}
        
Elapsed time: 0.70127s