what's the main difference between the livekit-agents[speechmatics] and livekit-plugin-speechmatics? What are the recommended scenarios to use each?

Thanks for reaching out, Jeslyn. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.

Following up, I noticed there are changes in the web voice agent setup sandbox. I wanted to use Speechmatics as the STT and got this error Traceback (most recent call last): File "/root/livekit-test/plugin1215/src/agent.py", line 17, in <module> from livekit.plugins import speechmatics ImportError: cannot import name 'speechmatics' from 'livekit.plugins' (unknown location)

It looks like you’re encountering the error

ImportError: cannot import name 'speechmatics' from 'livekit.plugins'

. This usually happens when the

livekit-plugins-speechmatics

package isn’t installed or imported correctly. Don’t worry, I’m here to help you get this sorted out! Here’s what you can do: 1. Install the Speechmatics plugin: First, make sure the plugin is installed by running:

pip install livekit-plugins-speechmatics

2. Check your import statement: Make sure you’re using the right syntax:

from livekit.plugins import speechmatics

3. Set up your authentication: Double-check that your Speechmatics API key is properly set using the

SPEECHMATICS_API_KEY

environment variable or a

.env.local

file. 4. Verify your Python environment: It’s important the package is installed in the environment you’re working in. Run: `pip show livekit-plugins-speechmatics`and confirm that the

Location

matches your project’s environment. 5. Restart your development server or IDE: Sometimes a quick restart helps your environment recognize new changes. 6. Update the package: To make sure you have the latest features and fixes, run:

pip install --upgrade livekit-plugins-speechmatics

If you’re still running into issues after trying these steps, please don’t hesitate to reach out. I’m happy to help you troubleshoot further and get everything working smoothly! Sources: livekit-plugins/livekit-plugins-sarvam/livekit/plugins/sarvam/__init__.py | Speechmatics STT plugin guide | LiveKit Docs

I've re-do it but still getting this (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215# uv run python src/agent.py download-files warning:

VIRTUAL_ENV=venv

does not match the project environment path

.venv

and will be ignored; use

--active

to target the active environment instead 2025-10-16 110429.432631395 [WonnxruntimeDefault, device_discovery.cc:164 DiscoverDevicesForPlatform] GPU device discovery failed: device_discovery.cc:89 ReadFileContents Failed to open file: "/sys/class/drm/card0/device/vendor" Traceback (most recent call last): File "/root/livekit-test/plugin1215/src/agent.py", line 15, in <module> from livekit.plugins import noise_cancellation, silero, speechmatics ImportError: cannot import name 'speechmatics' from 'livekit.plugins' (unknown location)

I'm sorry to hear the error is still giving you trouble. It might be related to the installation, environment, or dependencies. Let’s work through this together with these steps to help get things running smoothly: 1. Verify Installation: First, let's make sure the Speechmatics plugin is installed properly: `pip install --force-reinstall livekit-plugins-speechmatics`Also, double-check that the necessary dependencies are installed:

pip install --upgrade livekit-agents
pip show speechmatics-rt

2. Test Import in Isolation: Try running this simple script to see if the import works: `try: from livekit.plugins import speechmatics print("✅ Import successful") except ImportError as e: print("❌ Import failed:", e)`This will help us pinpoint if the issue is with the import itself. 3. Check Environment: Sometimes the package might be installed in a different environment than the one you’re using. Please activate your environment and verify with: `pip show livekit-plugins-speechmatics`If things still seem off, creating a fresh environment might help:

python -m venv venv
source venv/bin/activate
pip install livekit-plugins-speechmatics

4. Clear Python Cache: Cached files can occasionally cause conflicts. You can clear them with:

find . -type d -name "__pycache__" -exec rm -rf {} +

5. Verify Plugin Registration: Please check that the

livekit.plugins

directory contains a

speechmatics

subdirectory and that the plugin is properly registered in the

__init__.py

file. 6. Set Authentication: Don’t forget to set your

SPEECHMATICS_API_KEY

in your environment variables or in a

.env

file to ensure authentication works correctly. If you’re still facing issues after trying these steps, please share the results from the import test and any other error messages you see. I’m here to help you get this resolved! Sources: livekit-plugins/livekit-plugins-speechify/livekit/plugins/speechify/py.type... | Speechmatics STT plugin guide | LiveKit Docs

what should I put in the init.py file?

Hi there! To get the

livekit.plugins.speechmatics

plugin up and running smoothly, your

__init__.py

file should include the following content. This will help properly define and register the Speechmatics plugin:

# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# you may obtain a copy of the License at
#
#     <http://www.apache.org/licenses/LICENSE-2.0>
#
# Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Speechmatics STT plugin for LiveKit Agents

See <https://docs.livekit.io/agents/integrations/stt/speechmatics/> for more information.
"""

from .stt import STT, SpeechStream
from .types import (
    AdditionalVocabEntry,
    AudioSettings,
    DiarizationFocusMode,
    DiarizationKnownSpeaker,
    EndOfUtteranceMode,
    TranscriptionConfig,
)
from .version import __version__

__all__ = [
    "STT",
    "SpeechStream",
    "AdditionalVocabEntry",
    "AudioSettings",
    "DiarizationFocusMode",
    "DiarizationKnownSpeaker",
    "EndOfUtteranceMode",
    "TranscriptionConfig",
    "logger",
    "__version__",
]

from livekit.agents import Plugin

from .log import logger

class SpeechmaticsPlugin(Plugin):
    def __init__(self) -> None:
        super().__init__(__name__, __version__, __package__, logger)

Plugin.register_plugin(SpeechmaticsPlugin())

# 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

Here’s a quick overview of what this file does: • It imports and exports important components like

STT

and

SpeechStream

, so they’re ready to use. • It registers the

SpeechmaticsPlugin

with LiveKit Agents, making sure everything connects properly. • It takes care of logging and tidies up the documentation by hiding unexported modules. If anything feels unclear or if you’d like me to walk you through any part of this, please don’t hesitate to ask. I’m here to help! Sources: livekit-plugins/livekit-plugins-gladia/livekit/plugins/gladia/__init__.py

I've copied the speechmatics plugins init.py instead here # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Speechmatics STT plugin for LiveKit Agents See https://docs.livekit.io/agents/integrations/stt/speechmatics/ for more information. """ from .stt import STT, SpeechStream from .types import ( AdditionalVocabEntry, AudioSettings, DiarizationFocusMode, DiarizationKnownSpeaker, EndOfUtteranceMode, TranscriptionConfig, ) from .version import version all = [ "STT", "SpeechStream", "AdditionalVocabEntry", "AudioSettings", "DiarizationFocusMode", "DiarizationKnownSpeaker", "EndOfUtteranceMode", "TranscriptionConfig", "logger", "__version__", ] from livekit.agents import Plugin from .log import logger class SpeechmaticsPlugin(Plugin): def __init__(self) -> None: super().__init__(name, version, package, logger) Plugin.register_plugin(SpeechmaticsPlugin()) # 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 however, I'm still getting the same error (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215# uv run python src/agent.py console warning:

VIRTUAL_ENV=venv

does not match the project environment path

.venv

and will be ignored; use

--active

to target the active environment instead 2025-10-16 111039.058564607 [WonnxruntimeDefault, device_discovery.cc:164 DiscoverDevicesForPlatform] GPU device discovery failed: device_discovery.cc:89 ReadFileContents Failed to open file: "/sys/class/drm/card0/device/vendor" Traceback (most recent call last): File "/root/livekit-test/plugin1215/src/agent.py", line 15, in <module> from livekit.plugins import noise_cancellation, silero, speechmatics ImportError: cannot import name 'speechmatics' from 'livekit.plugins' (unknown location)

I'm sorry to hear the error is still happening. It looks like copying just the

__init__.py

file skips the full installation and registration process for the Speechmatics plugin. Let's work through this together to get it sorted out: 1. Install the Speechmatics plugin: Please run this command to make sure the plugin is installed properly: `pip install livekit-plugins-speechmatics`This will set up all the necessary parts, including the registration logic. 2. Verify the installation: You can check if the package is installed and accessible by running: `pip show livekit-plugins-speechmatics`Look for the package name, version, and where it’s installed to confirm it’s all set. 3. Test the import: Try this simple script to see if the plugin imports without issues:

from livekit.plugins import speechmatics
stt = speechmatics.STT()
print("Speechmatics plugin imported successfully.")

4. Check your environment: It’s important to be in the right virtual environment. Activate it, then reinstall the plugin just to be sure:

pip uninstall livekit-plugins-speechmatics
pip install livekit-plugins-speechmatics

5. Set the API key: Make sure your

SPEECHMATICS_API_KEY

is set in your environment or in a

.env

file, like this: `SPEECHMATICS_API_KEY=your_api_key_here`Then load it in your code with:

from dotenv import load_dotenv
load_dotenv()

6. Check for conflicts: Sometimes local files named

livekit.py

,

plugins.py

, or

speechmatics.py

can interfere by shadowing the installed modules. Make sure those aren’t present in your project. Once you’ve gone through these steps, the import should work smoothly. If you run into any more trouble or have questions, please don’t hesitate to reach out—I’m here to help! Sources: Speechmatics STT plugin guide | LiveKit Docs | livekit-plugins/livekit-plugins-speechify/livekit/plugins/speechify/py.type...

I've tried that simple script

from livekit.plugins import speechmatics

stt = speechmatics.STT()

print("Speechmatics plugin imported successfully.")

and returned this error. But I'm not able to find the speechmatics directory under the plugins as well. attached the screenshot (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215# nano stt-test.py (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215# python3 stt-test.py Traceback (most recent call last): File "/root/livekit-test/plugin1215/stt-test.py", line 2, in <module> stt = speechmatics.STT() ^^^^^^^^^^^^^^^^^^ File "/root/livekit-test/plugin1215/venv/lib/python3.12/site-packages/livekit/plugins/speechmatics/stt.py", line 316, in init raise ValueError("Missing Speechmatics API key") ValueError: Missing Speechmatics API key (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215# python3 stt-test.py Traceback (most recent call last): File "/root/livekit-test/plugin1215/stt-test.py", line 2, in <module> stt = speechmatics.STT() ^^^^^^^^^^^^^^^^^^ File "/root/livekit-test/plugin1215/venv/lib/python3.12/site-packages/livekit/plugins/speechmatics/stt.py", line 316, in init raise ValueError("Missing Speechmatics API key") ValueError: Missing Speechmatics API key

It looks like the error is telling us that the Speechmatics plugin is installed, but the Speechmatics API key is missing. Also, from the screenshot, it seems the

speechmatics

directory isn’t showing up under

livekit/plugins

. No worries—let’s work through these together: 1. Set the Speechmatics API Key: The plugin needs the

SPEECHMATICS_API_KEY

to work properly. You can add it to your environment like this: `export SPEECHMATICS_API_KEY="your_api_key_here"`Or, if you prefer, create a

.env

file in your project directory with this inside: `SPEECHMATICS_API_KEY=your_api_key_here`Then, make sure to load it in your script:

from dotenv import load_dotenv
load_dotenv()

2. Verify Plugin Installation: Since the

speechmatics

folder is missing, it might mean the plugin didn’t install correctly. Let’s reinstall it to be sure all files are there: `pip uninstall livekit-plugins-speechmatics pip install livekit-plugins-speechmatics`After that, double-check that the directory appears under

livekit/plugins

. 3. Check Python Environment: It’s important to use the right virtual environment. Activate it and confirm the plugin is installed: `source venv/bin/activate # On Windows: venv\Scripts\activate pip show livekit-plugins-speechmatics`You should see details like the package name, version, and where it’s installed. 4. Clear Python Cache: Sometimes cached files can cause hiccups. Let’s clear them out:

find . -type d -name "__pycache__" -exec rm -rf {} +

Once you’ve gone through these steps, try running your script again. If anything still feels off or you run into other issues, just let me know—I’m here to help!

ok I've found it under /root/livekit-test/plugin1215/venv/lib/python3.12/site-packages/livekit_plugins_speechmatics-1.2.15.dist-info/* What should I add to any of these files/ under this directory specifically?

Hi there! It looks like the directory

livekit_plugins_speechmatics-1.2.15.dist-info

is actually just a metadata folder for the installed package and doesn’t contain the actual plugin code. The real plugin code should be inside the

livekit/plugins/speechmatics

directory. Since that folder is missing, it seems like the plugin installation might not have completed properly. Here’s a friendly step-by-step guide to help you get this sorted out: 1. Reinstall the Plugin: Let’s try uninstalling and then reinstalling the Speechmatics plugin to make sure all the necessary files are in place:

pip uninstall livekit-plugins-speechmatics
pip install livekit-plugins-speechmatics

2. Verify Installation: After reinstalling, please check that the

speechmatics

directory now exists under

livekit/plugins

by running: `ls /root/livekit-test/plugin1215/venv/lib/python3.12/site-packages/livekit/plugins`You should see the

speechmatics

folder alongside other plugins like

noise_cancellation

and

silero

. 3. Check Python Environment: It’s important to make sure you’re working in the right virtual environment. Activate it and verify the plugin installation with: `source venv/bin/activate # On Windows: venv\Scripts\activate pip show livekit-plugins-speechmatics`This should display the package name, version, and where it’s installed. 4. Clear Python Cache: Sometimes cached files can cause issues. You can safely remove them by running:

find . -type d -name "__pycache__" -exec rm -rf {} +

Once you’ve gone through these steps, the

speechmatics

directory should show up under

livekit/plugins

, and the plugin should be ready to use. If you run into any more hiccups or have questions, please don’t hesitate to reach out—I’m here to help!

OK I found the folder plugins/speechmatics and init.py with info. Now how should I solve the issues with API key

Let's work together to fix the issue with the missing Speechmatics API key. You’ll need to set the

SPEECHMATICS_API_KEY

environment variable, and I’m here to guide you through it step-by-step: 1. Set the API Key in the Environment: Open your terminal and run this command to set the API key for your current session: `export SPEECHMATICS_API_KEY="your_api_key_here"`Just swap out

your_api_key_here

with your actual Speechmatics API key. 2. Use a .env File (Optional): If you’d rather keep the API key in a file, simply create a

.env

file in your project folder with this line: `SPEECHMATICS_API_KEY=your_api_key_here`Then, in your Python script, load it by adding:

from dotenv import load_dotenv
load_dotenv()

3. Verify the Key is Set: To double-check everything is set correctly, run: `echo $SPEECHMATICS_API_KEY`You should see your API key displayed. 4. Restart Your Environment: If you’re running your script in an IDE or any persistent environment, just restart it to make sure the new environment variables take effect. After setting the API key, try running your script again. This should resolve the error. If you run into any other hiccups or have questions, please don’t hesitate to reach out—I’m here to help!

I have the speechmatics plugin here (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215# python3 stt-test.py Traceback (most recent call last): File "/root/livekit-test/plugin1215/stt-test.py", line 2, in <module> stt = speechmatics.STT() ^^^^^^^^^^^^^^^^^^ File "/root/livekit-test/plugin1215/venv/lib/python3.12/site-packages/livekit/plugins/speechmatics/stt.py", line 316, in init raise ValueError("Missing Speechmatics API key") ValueError: Missing Speechmatics API key (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215# python3 stt-test.py Traceback (most recent call last): File "/root/livekit-test/plugin1215/stt-test.py", line 2, in <module> stt = speechmatics.STT() ^^^^^^^^^^^^^^^^^^ File "/root/livekit-test/plugin1215/venv/lib/python3.12/site-packages/livekit/plugins/speechmatics/stt.py", line 316, in init raise ValueError("Missing Speechmatics API key") ValueError: Missing Speechmatics API key But still unable to run it and says cannot import, why? (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215# uv run python src/agent.py download-files warning:

VIRTUAL_ENV=venv

does not match the project environment path

.venv

and will be ignored; use

--active

to target the active environment instead 2025-10-16 115722.560228611 [WonnxruntimeDefault, device_discovery.cc:164 DiscoverDevicesForPlatform] GPU device discovery failed: device_discovery.cc:89 ReadFileContents Failed to open file: "/sys/class/drm/card0/device/vendor" Traceback (most recent call last): File "/root/livekit-test/plugin1215/src/agent.py", line 15, in <module> from livekit.plugins import ( ImportError: cannot import name 'speechmatics' from 'livekit.plugins' (unknown location) (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215#

It looks like you're encountering two separate issues, and I’m here to help you through them: 1. ImportError: This usually means the Speechmatics plugin isn’t installed yet. No worries! You can easily install it by running this command: `pip install livekit-plugins-speechmatics`This will add the Speechmatics plugin to the

livekit.plugins

namespace, making it ready to use. 2. ValueError (Missing API Key): The Speechmatics plugin needs the

SPEECHMATICS_API_KEY

to work properly. You can set this up in one of two ways: ◦ Set it as an environment variable by running:

export SPEECHMATICS_API_KEY="your_api_key_here"

◦ Or, create a

.env

file in your project folder with this line: `SPEECHMATICS_API_KEY=your_api_key_here`Then, just load it in your script like this:

from dotenv import load_dotenv
load_dotenv()

Once you’ve done these steps, try running a simple test script to make sure everything’s set up correctly:

from livekit.plugins import speechmatics
stt = speechmatics.STT()
print("Speechmatics plugin imported successfully.")

If you still run into any issues, please don’t hesitate to share the exact error message or describe what’s happening. I’m here to help you get this working smoothly! Sources: Speechmatics STT plugin guide | LiveKit Docs | .github/workflows/evals.yml

This is what it says in the stt.py self._api_key: str = api_key if is_given(api_key) else os.getenv("SPEECHMATICS_API_KEY", "") self._base_url: str = ( base_url if is_given(base_url) else os.getenv("SPEECHMATICS_RT_URL", "wss://eu2.rt.speechmatics.com/v2") ) if not self._api_key: raise ValueError("Missing Speechmatics API key") if not self._base_url: raise ValueError("Missing Speechmatics base URL") This is what I put .env.local LIVEKIT_API_KEY="APIScX3pphZu6fX" LIVEKIT_API_SECRET="tY1NxWCxPjPYiSvmdG8xJEVO8Vr6olUAL5v0etEq9wV" LIVEKIT_URL="wss://speechmatics-test-9cif3csq.livekit.cloud" SPEECHMATICS_API_KEY="uhIufevmidZRc2nmUbebiIlbzzvMEwgE"

Thanks for sharing the code snippet from

stt.py

! It looks like the Speechmatics plugin is set up to get the API key and base URL from environment variables, and your

.env.local

file seems correctly configured with the

SPEECHMATICS_API_KEY

. To help make sure the plugin can access these variables smoothly, here are a few friendly steps you can follow: 1. Verify the .env File is Loaded: Double-check that your script is actually loading the

.env.local

file. You can add this snippet to your script to do that: `from dotenv import load_dotenv load_dotenv(dotenv_path=".env.local")`This will explicitly load your

.env.local

file and make those variables available. 2. Check Environment Variables: It’s a good idea to confirm the variables are accessible. You can print them out in your script like this: `import os print("SPEECHMATICS_API_KEY:", os.getenv("SPEECHMATICS_API_KEY"))`This should show you the API key you set, so you know it’s being picked up correctly. 3. Verify Base URL: The default base URL is

<wss://eu2.rt.speechmatics.com/v2>

. If you happen to need a custom URL, just make sure you have

SPEECHMATICS_RT_URL

set in your

.env.local

file. 4. Restart Your Environment: If you’re running your script inside an IDE or any environment that stays running, it’s helpful to restart it. This ensures any changes to environment variables take effect. Once you’ve gone through these steps, please try running your script again. If you still run into any issues, feel free to share the exact error message or what’s happening, and I’ll be happy to help you troubleshoot further!

2025-10-16 122944.430511677 [WonnxruntimeDefault, device_discovery.cc:164 DiscoverDevicesForPlatform] GPU device discovery failed: device_discovery.cc:89 ReadFileContents Failed to open file: "/sys/class/drm/card0/device/vendor" 2025-10-16 122944,465 - DEBUG asyncio - Using selector: EpollSelector ================================================== Livekit Agents - Console ================================================== Press [Ctrl+B] to toggle between Text/Audio mode, [Q] to quit. 2025-10-16 122944,467 - INFO livekit.agents - starting worker {"version": "1.2.15", "rtc-version": "1.0.16"} 2025-10-16 122944,467 - INFO livekit.agents - preloading plugins {"packages": ["livekit.plugins.silero", "livekit.plugins.turn_detector", "av"]} 2025-10-16 122944,472 - INFO livekit.agents - starting inference executor 2025-10-16 122947.682104462 [WonnxruntimeDefault, device_discovery.cc:164 DiscoverDevicesForPlatform] GPU device discovery failed: device_discovery.cc:89 ReadFileContents Failed to open file: "/sys/class/drm/card0/device/vendor" 2025-10-16 122948,408 - INFO livekit.agents - initializing process {"pid": 36366, "inference": true} 2025-10-16 122948,729 - DEBUG livekit.agents - initializing inference runner {"runner": "lk_end_of_utterance_multilingual", "pid": 36366, "inference": true} None of PyTorch, TensorFlow >= 2.0, or Flax have been found. Models won't be available and only tokenizers, configuration and file/data utilities can be used. 2025-10-16 122957,471 - DEBUG livekit.agents - inference runner initialized {"runner": "lk_end_of_utterance_multilingual", "elapsed_time": 8.741914787000496, "pid": 36366, "inference": true} 2025-10-16 122957,497 - INFO livekit.agents - process initialized {"pid": 36366, "inference": true, "elapsed_time": 9.08} 2025-10-16 122957,478 - DEBUG asyncio - Using selector: EpollSelector {"pid": 36366, "inference": true} 2025-10-16 122957,561 - INFO livekit.agents - initializing job runner {"tid": 36427} 2025-10-16 122957,663 - DEBUG asyncio - Using selector: EpollSelector 2025-10-16 122957,664 - INFO livekit.agents - job runner initialized {"tid": 36427, "elapsed_time": 0.1} 2025-10-16 122958,013 - ERROR livekit.agents - unhandled exception while running the job task {"room": "mock_room"} Traceback (most recent call last): File "/root/livekit-test/plugin1215/.venv/lib/python3.12/site-packages/opentelemetry/util/_decorator.py", line 71, in async_wrapper return await func(*args, **kwargs) # type: ignore ^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/root/livekit-test/plugin1215/.venv/lib/python3.12/site-packages/livekit/agents/ipc/job_proc_lazy_main.py", line 240, in _traceable_entrypoint await self._job_entrypoint_fnc(job_ctx) File "/root/livekit-test/plugin1215/src/agent.py", line 68, in entrypoint stt=speechmatics.STT( ^^^^^^^^^^^^ NameError: name 'speechmatics' is not defined

I'm sorry to hear you're encountering the error

NameError: name 'speechmatics' is not defined

. This usually happens when the Speechmatics plugin hasn't been properly imported in your script. Let's work through this together to get it sorted out: 1. Make Sure the Plugin is Installed: First, let's check that the Speechmatics plugin is installed. You can do this by running:

pip install livekit-plugins-speechmatics

2. Import the Plugin Correctly: Next, please add this import statement to your script: `from livekit.plugins import speechmatics`This step is important because it allows you to access the

speechmatics.STT

class and other features. 3. Set Your API Key: Don’t forget to set your

SPEECHMATICS_API_KEY

in your environment or within a

.env

file. For example: `SPEECHMATICS_API_KEY=your_api_key_here`Then, load it in your script with:

from dotenv import load_dotenv
load_dotenv()

4. Try a Simple Test: To make sure everything is working, run this quick test script:

from livekit.plugins import speechmatics
stt = speechmatics.STT()
print("Speechmatics plugin imported successfully.")

5. Verify Your Environment: Lastly, double-check that you’re using the right virtual environment where the plugin is installed. Activate it and confirm by running:

pip show livekit-plugins-speechmatics

If you’re still running into trouble after these steps, please don’t hesitate to share the exact error message and your import statements with me. I’m here to help you get this resolved! Sources: Speechmatics STT plugin guide | LiveKit Docs | .github/workflows/evals.yml

I can get my API key working now but the module is not recognized (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215# uv run python src/agent.py console warning:

VIRTUAL_ENV=venv

does not match the project environment path

.venv

and will be ignored; use

--active

to target the active environment instead SPEECHMATICS_API_KEY: uhIufevmidZRc2nmUbebiIlbzzvMEwgE 2025-10-16 124116.927181150 [WonnxruntimeDefault, device_discovery.cc:164 DiscoverDevicesForPlatform] GPU device discovery failed: device_discovery.cc:89 ReadFileContents Failed to open file: "/sys/class/drm/card0/device/vendor" 2025-10-16 124116,934 - DEBUG asyncio - Using selector: EpollSelector ================================================== Livekit Agents - Console ================================================== Press [Ctrl+B] to toggle between Text/Audio mode, [Q] to quit. 2025-10-16 124116,935 - INFO livekit.agents - starting worker {"version": "1.2.15", "rtc-version": "1.0.16"} 2025-10-16 124116,935 - INFO livekit.agents - preloading plugins {"packages": ["livekit.plugins.silero", "livekit.plugins.turn_detector", "av"]} 2025-10-16 124116,937 - INFO livekit.agents - starting inference executor 2025-10-16 124117.047196250 [WonnxruntimeDefault, device_discovery.cc:164 DiscoverDevicesForPlatform] GPU device discovery failed: device_discovery.cc:89 ReadFileContents Failed to open file: "/sys/class/drm/card0/device/vendor" 2025-10-16 124117,691 - INFO livekit.agents - initializing process {"pid": 39657, "inference": true} SPEECHMATICS_API_KEY: uhIufevmidZRc2nmUbebiIlbzzvMEwgE 2025-10-16 124117,867 - DEBUG livekit.agents - initializing inference runner {"runner": "lk_end_of_utterance_multilingual", "pid": 39657, "inference": true} None of PyTorch, TensorFlow >= 2.0, or Flax have been found. Models won't be available and only tokenizers, configuration and file/data utilities can be used. 2025-10-16 124119,982 - INFO livekit.agents - process initialized {"pid": 39657, "inference": true, "elapsed_time": 2.29} 2025-10-16 124119,981 - DEBUG livekit.agents - inference runner initialized {"runner": "lk_end_of_utterance_multilingual", "elapsed_time": 2.113389592999738, "pid": 39657, "inference": true} 2025-10-16 124119,982 - DEBUG asyncio - Using selector: EpollSelector {"pid": 39657, "inference": true} 2025-10-16 124119,987 - INFO livekit.agents - initializing job runner {"tid": 39694} 2025-10-16 124120,040 - INFO livekit.agents - job runner initialized {"tid": 39694, "elapsed_time": 0.05} 2025-10-16 124120,040 - DEBUG asyncio - Using selector: EpollSelector 2025-10-16 124120,102 - ERROR livekit.agents - unhandled exception while running the job task {"room": "mock_room"} Traceback (most recent call last): File "/root/livekit-test/plugin1215/.venv/lib/python3.12/site-packages/opentelemetry/util/_decorator.py", line 71, in async_wrapper return await func(*args, **kwargs) # type: ignore ^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/root/livekit-test/plugin1215/.venv/lib/python3.12/site-packages/livekit/agents/ipc/job_proc_lazy_main.py", line 240, in _traceable_entrypoint await self._job_entrypoint_fnc(job_ctx) File "/root/livekit-test/plugin1215/src/agent.py", line 72, in entrypoint stt=speechmatics.STT( ^^^^^^^^^^^^ NameError: name 'speechmatics' is not defined import logging from dotenv import load_dotenv import os load_dotenv(dotenv_path=".env.local") print("SPEECHMATICS_API_KEY:", os.getenv("SPEECHMATICS_API_KEY")) from livekit.agents import ( Agent, AgentSession, JobContext, JobProcess, MetricsCollectedEvent, RoomInputOptions, WorkerOptions, cli, metrics, ) from livekit.plugins import ( noise_cancellation, silero, ) from livekit.plugins.turn_detector.multilingual import MultilingualModel logger = logging.getLogger("agent") class Assistant(Agent): def __init__(self) -> None: super().__init__( instructions="""You are a helpful voice AI assistant. The user is interacting with you via voice, even if you perceive the conversation as text. You eagerly assist users with their questions by providing information from your extensive knowledge. Your responses are concise, to the point, and without any complex formatting or punctuation including emojis, asterisks, or other symbols. You are curious, friendly, and have a sense of humor.""", ) # To add tools, use the @function_tool decorator. # Here's an example that adds a simple weather tool. # You also have to add

from livekit.agents import function_tool, RunContext

to the top of this file # @function_tool # async def lookup_weather(self, context: RunContext, location: str): # """Use this tool to look up current weather information in the given location. # # If the location is not supported by the weather service, the tool will indicate this. You must tell the user the location's weather is unavailable. # # Args: # location: The location to look up weather information for (e.g. city name) # """ # # logger.info(f"Looking up weather for {location}") # # return "sunny with a temperature of 70 degrees." def prewarm(proc: JobProcess): proc.userdata["vad"] = silero.VAD.load() async def entrypoint(ctx: JobContext): # Logging setup # Add any other context you want in all log entries here ctx.log_context_fields = { "room": ctx.room.name, } # Set up a voice AI pipeline using OpenAI, Cartesia, AssemblyAI, and the LiveKit turn detector session = AgentSession( # Speech-to-text (STT) is your agent's ears, turning the user's speech into text that the LLM can understand # See all available models at https://docs.livekit.io/agents/models/stt/ stt=speechmatics.STT( end_of_utterance_silence_trigger=0.5, enable_diarization=True, speaker_active_format="<{speaker_id}>{text}</{speaker_id}>", additional_vocab=[ speechmatics.types.AdditionalVocabEntry( content="LiveKit", #sounds_like=["live kit"], ), ], #transcription_config=speechmatics.types.TranscriptionConfig( language="en", operating_point="enhanced", enable_partials=True, max_delay=0.7, #), ), # A Large Language Model (LLM) is your agent's brain, processing user input and generating a response # See all available models at https://docs.livekit.io/agents/models/llm/ llm="openai/gpt-4.1-mini", # Text-to-speech (TTS) is your agent's voice, turning the LLM's text into speech that the user can hear # See all available models as well as voice selections at https://docs.livekit.io/agents/models/tts/ tts="cartesia/sonic-2:9626c31c-bec5-4cca-baa8-f8ba9e84c8bc", # VAD and turn detection are used to determine when the user is speaking and when the agent should respond # See more at https://docs.livekit.io/agents/build/turns turn_detection=MultilingualModel(), vad=ctx.proc.userdata["vad"], # allow the LLM to generate a response while waiting for the end of turn # See more at https://docs.livekit.io/agents/build/audio/#preemptive-generation preemptive_generation=True, ) # To use a realtime model instead of a voice pipeline, use the following session setup instead. # (Note: This is for the OpenAI Realtime API. For other providers, see https://docs.livekit.io/agents/models/realtime/)) # 1. Install livekit-agents[openai] # 2. Set OPENAI_API_KEY in .env.local # 3. Add

from livekit.plugins import openai

to the top of this file # 4. Use the following session setup instead of the version above # session = AgentSession( # llm=openai.realtime.RealtimeModel(voice="marin") # ) # Metrics collection, to measure pipeline performance # For more information, see https://docs.livekit.io/agents/build/metrics/ usage_collector = metrics.UsageCollector() @session.on("metrics_collected") def _on_metrics_collected(ev: MetricsCollectedEvent): metrics.log_metrics(ev.metrics) usage_collector.collect(ev.metrics) async def log_usage(): summary = usage_collector.get_summary() logger.info(f"Usage: {summary}") ctx.add_shutdown_callback(log_usage) # # Add a virtual avatar to the session, if desired # # For other providers, see https://docs.livekit.io/agents/models/avatar/ # avatar = hedra.AvatarSession( # avatar_id="...", # See https://docs.livekit.io/agents/models/avatar/plugins/hedra # ) # # Start the avatar and wait for it to join # await avatar.start(session, room=ctx.room) # Start the session, which initializes the voice pipeline and warms up the models await session.start( agent=Assistant(), room=ctx.room, room_input_options=RoomInputOptions( # For telephony applications, use

BVCTelephony

for best results noise_cancellation=noise_cancellation.BVC(), ), ) # Join the room and connect to the user await ctx.connect() if name == "__main__": cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint, prewarm_fnc=prewarm))

It looks like you're seeing the error

NameError: name 'speechmatics' is not defined

because the Speechmatics plugin hasn’t been imported into your script yet. No worries, I’m here to help you get this sorted out! Here’s what you can do: 1. Import the Speechmatics Plugin: Make sure to add this import statement at the top of your script: `from livekit.plugins import speechmatics`This step is important so you can use the

speechmatics.STT

class without any issues. 2. Verify the Plugin Installation: Double-check that the Speechmatics plugin is installed in your environment by running: `pip show livekit-plugins-speechmatics`If it’s installed, you’ll see details about the package here. 3. Check Your Virtual Environment: Sometimes the plugin might be installed in a different environment. Be sure you’re working in the right one by activating it and confirming the installation:

source venv/bin/activate  # On Windows: venv\Scripts\activate
pip list | grep livekit

4. Test the Import: To be extra sure everything is set up correctly, try running a quick test script like this:

from livekit.plugins import speechmatics
stt = speechmatics.STT()
print("Speechmatics plugin imported successfully.")

Once you’ve done these steps, the

NameError

should be resolved. If you run into any other questions or need a hand with anything else, just let me know—I’m here to help!

yes but otherwise it gives this error (venv) root@JESLYNY-F1BZTQ3:~/livekit-test/plugin1215# uv run python src/agent.py console warning:

VIRTUAL_ENV=venv

does not match the project environment path

.venv

and will be ignored; use

--active

to target the active environment instead SPEECHMATICS_API_KEY: uhIufevmidZRc2nmUbebiIlbzzvMEwgE 2025-10-16 124308.441917313 [WonnxruntimeDefault, device_discovery.cc:164 DiscoverDevicesForPlatform] GPU device discovery failed: device_discovery.cc:89 ReadFileContents Failed to open file: "/sys/class/drm/card0/device/vendor" Traceback (most recent call last): File "/root/livekit-test/plugin1215/src/agent.py", line 19, in <module> from livekit.plugins import ( ImportError: cannot import name 'speechmatics' from 'livekit.plugins' (unknown location)

I'm sorry you're running into the error

ImportError: cannot import name 'speechmatics' from 'livekit.plugins'

. This usually happens when the Speechmatics plugin isn't installed or imported correctly. Let’s work through some steps together to get this sorted out: 1. Install the Speechmatics Plugin: First, please make sure the plugin is installed by running:

pip install livekit-plugins-speechmatics

2. Verify Dependencies: Next, let’s ensure all the necessary dependencies are up to date: `pip install --upgrade livekit-agents speechmatics-rt`Also, double-check your Python version (it should be 3.9 or higher) by running:

python --version

3. Set Up Authentication: It’s important that your

SPEECHMATICS_API_KEY

is set properly, either in your environment variables or a

.env.local

file. For example: `SPEECHMATICS_API_KEY=your_api_key_here`And don’t forget to load it in your script like this:

from dotenv import load_dotenv
load_dotenv()

4. Test the Import: To check if everything is working, try running a simple script:

from livekit.plugins import speechmatics
print("Speechmatics plugin imported successfully.")

5. Check Your Virtual Environment: Sometimes the issue is with the environment you’re using. Make sure you’ve activated the right virtual environment where the plugin is installed. You can verify it by running:

pip show livekit-plugins-speechmatics

If you’re still seeing the error, it might help to reinstall the plugin in a fresh virtual environment. Here’s how you can do that:

python -m venv fresh_env
source fresh_env/bin/activate  # On Windows: fresh_env\Scripts\activate
pip install livekit-plugins-speechmatics

Please don’t hesitate to reach out if you hit any other bumps along the way. I’m here to help! Sources: livekit-plugins/livekit-plugins-spitch/livekit/plugins/spitch/__init__.py | Speechmatics STT plugin guide | LiveKit Docs