Local LiveKit Plugins Development

A skill for working with local STT/TTS plugins for LiveKit Agents that run entirely locally without cloud APIs.

Project Overview

This project provides custom Speech-to-Text (STT) and Text-to-Speech (TTS) plugins for LiveKit Agents that eliminate the need for cloud API dependencies by running entirely on local hardware.

**Repository:** `CoreWorxLab/local-livekit-plugins`

Architecture

The project follows a clean separation between the installable package and demonstration code:

```

src/local_livekit_plugins/ # The installable Python package

├── faster_whisper_stt.py # STT plugin using faster-whisper (GPU-accelerated)

└── piper_tts.py # TTS plugin using Piper

examples/ # Demo code (not part of installed package)

├── voice_agent.py

└── .env.local.example

```

Core Components

Critical Technical Constraints

Plugin Import Rules

**CRITICAL:** Plugin imports must be at module level. LiveKit requires plugins to be registered on the main thread.

❌ **NEVER** import plugins inside functions:

```python

def setup():

from local_livekit_plugins import FasterWhisperSTT # WRONG

```

✅ **ALWAYS** import at module level:

```python

from local_livekit_plugins import FasterWhisperSTT # CORRECT

def setup():

# use the plugin here

```

CUDA and GPU Support

Development Workflow

Setup

```bash

Install all dependencies

uv sync

```

Environment Configuration

Create `.env.local` in the `examples/` directory by copying the example:

```bash

cp examples/.env.local.example examples/.env.local

```

Running the Voice Agent

```bash

Run with LiveKit playground (development mode)

uv run examples/voice_agent.py dev

Run in console mode (CLI testing)

uv run examples/voice_agent.py console

```

Code Quality

```bash

Lint the source code

uv run ruff check src/

Type checking

uv run mypy src/

Run tests

uv run pytest

```

Common Tasks

Adding a New Plugin

1. Create the plugin file in `src/local_livekit_plugins/`

2. Ensure imports are at module level (never inside functions)

3. Add appropriate type hints for mypy

4. Write tests in the `tests/` directory

5. Update documentation

Debugging GPU Issues

Testing Changes

1. Run linter: `uv run ruff check src/`

2. Run type checker: `uv run mypy src/`

3. Run tests: `uv run pytest`

4. Test with voice agent: `uv run examples/voice_agent.py dev`

Best Practices

Constraints