I built a plug-in. I followed the doc structure. I...
# ask-ain
nutritious-butcher-39524
03/02/2026, 12:43 PMI built a plug-in. I followed the doc structure. I wanted to raise a LiveKit PR in order to get my plug-in listed officially as LiveKit's plug-in. What do I do?
t
tall-airline-16756
03/02/2026, 12:43 PMThanks for reaching out, Mythri. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.
tall-airline-16756
03/02/2026, 12:44 PMThanks — that’s great you’ve built a plugin and want it listed officially. I’ll walk you through the steps to submit a PR so your plugin can be considered for inclusion.
Quick question before steps: Is your plugin written for Python or Node.js? The repo and exact file layout differ slightly between the two, so tell me which one and I’ll tailor the exact PR checklist.
If you’re ready, here’s the general process and checklist you can follow now:
1) Pick the right repo
• Python plugins: contribute to the livekit/agents repository.
• Node.js plugins: contribute to the livekit/agents-js repository.
2) Ensure your plugin implements the standard interfaces and registration pattern
• Implement the appropriate plugin base class and interfaces for your plugin type (e.g., STT, TTS, LLM).
• Use the plugin registration pattern used by other plugins in the repo so it’s discoverable by the Agents framework.
3) Add the plugin as an optional dependency and include metadata
• For Python: add your package as an optional dependency in the package/dependency files (e.g., pyproject.toml or equivalent used by the repo).
• For Node.js: publish as an npm package and add it according to the repo’s plugin consumption pattern.
• Include clear metadata such as package name, version, supported runtimes, and any configuration keys.
4) Documentation and examples (required)
• Add a README describing what the plugin does, configuration and authentication steps, usage examples, and any setup required.
• Provide a minimal code snippet showing how to register and use the plugin with an AgentSession (or equivalent) and how it fits in the STT→LLM→TTS pipeline if applicable.
5) Tests and validation
• Include basic tests or an example app that demonstrates the plugin registration and a normal usage flow.
• Make sure your plugin handles lifecycle events and streaming I/O the same way other plugins do (e.g., streaming audio chunks, error handling, and shutdown).
6) Coding standards and error handling
• Follow the repository’s style and linting rules.
• Ensure robust logging and clear error messages for misconfiguration or auth failures.
7) Prepare your PR
• Fork the appropriate repo and create a feature branch.
• Add your plugin files, tests, and docs.
• Update any central index or dependency manifests the repo uses to list optional plugins.
• Create a descriptive PR title and description that explains what the plugin does, how to configure it, and any relevant example usage or test instructions.
8) Submit the PR and include reviewers’ guidance
• In the PR description, include:
◦ Language (Python / Node.js)
◦ Short summary and supported features (e.g., streaming STT, chunked TTS)
◦ Any external credentials or steps needed to test
◦ A pointer to example code or a small demo project
• Ask maintainers to run any provided tests and point them to files showing the registration pattern.
If you want, I can:
• Review your plugin checklist or README before you open the PR.
• Point out the exact files to modify in the correct repo once you tell me Python vs Node.js.
• Provide a PR description template you can paste into GitHub.
Which language is your plugin for, and would you like me to review your README or a short PR description draft?
Sources: Large language models (LLM) overview | LiveKit Documentation | Agents (Python) | livekit/livekit_composite | DeepWiki | Models overview | LiveKit Documentation
n
nutritious-butcher-39524
03/02/2026, 1:39 PMYes, sure, you can review my readme file, this is the link to my GitHub plugin. You can go through the entire code, the file structure, and everything : https://github.com/pinch-eng/livekit-plugins-pinch
t
tall-airline-16756
03/02/2026, 1:39 PMThanks — I can definitely review your README and the repo structure. I can’t fetch external URLs directly, so please paste the README contents (or the key files/folders you want reviewed) here.
To make the review most useful, please include:
• The full README.md
• Any plugin registration or entry files (e.g., the file that implements the Plugin class or exports the package)
• The package manifest (e.g.,
pyproject.tomlsetup.pypackage.jsonn
nutritious-butcher-39524
03/02/2026, 2:48 PMThis is my pyproject.toml file :
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "livekit-plugins-pinch"
version = "0.1.0"
description = "LiveKit Agents plugin for Pinch real-time speech-to-speech translation"
readme = "README.md"
license = { text = "Apache-2.0" }
authors = [{ name = "Pinch", email = "support@startpinch.com" }]
keywords = [
"livekit",
"agents",
"translation",
"speech-to-speech",
"real-time",
"pinch",
]
classifiers = [
"Intended Audience :: Developers",
"License :: OSI Approved :: Apache Software License",
"Topic :: Multimedia :: Sound/Audio :: Speech",
"Topic :: Scientific/Engineering :: Artificial Intelligence",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
]
requires-python = ">=3.10"
dependencies = [
"pinch-sdk>=0.1.1",
"livekit>=0.12.0",
"livekit-agents>=0.8.0",
]
[project.urls]
Homepage = "https://www.startpinch.com"
Documentation = "https://www.startpinch.com/docs"
Repository = "https://github.com/pinch-eng/livekit-plugins-pinch"
"Bug Tracker" = "https://github.com/pinch-eng/livekit-plugins-pinch/issues"
# ---------------------------------------------------------------------------
# Hatchling build — namespace package configuration
#
# livekit/ and livekit/plugins/ are implicit namespace packages (PEP 420)
# and intentionally contain no init.py. Hatchling includes the entire
# livekit/ tree; pip will merge it with any other livekit.* packages already
# installed in the same environment.
# ---------------------------------------------------------------------------
[tool.hatch.build.targets.wheel]
packages = ["livekit"]
[tool.hatch.build.targets.sdist]
include = [
"livekit/",
"examples/",
"README.md",
"pyproject.toml",
]
t
tall-airline-16756
03/02/2026, 2:48 PMThanks — I’ve got your
pyproject.tomllivekitlivekit-agentspinch-sdklivekitlivekit-agentslivekit/livekit>=3.10>=3.10optional-dependencieslivekit/plugins/…livekit/agentslivekit/agentsn
nutritious-butcher-39524
03/02/2026, 3:04 PMlivekit/plugins/pinch/__init__.py:
"""livekit-plugins-pinch — real-time speech-to-speech translation via Pinch."""
from .models import TranscriptEvent, TranslatorOptions
from .translator import (
PinchAuthError,
PinchError,
PinchRateLimitError,
PinchSessionError,
Translator,
)
from .version import version
all = [
# Core classes
"Translator",
"TranslatorOptions",
"TranscriptEvent",
# Exceptions
"PinchError",
"PinchAuthError",
"PinchRateLimitError",
"PinchSessionError",
# Version
"__version__",
]
livekit/plugins/pinch/log.py:
import logging
logger = logging.getLogger("livekit.plugins.pinch")
livekit/plugins/pinch/models.py:
from future import annotations
from dataclasses import dataclass, field
@dataclass
class TranslatorOptions:
"""Configuration options for a Pinch real-time translation session.
Attributes:
source_language: BCP-47 language code for the input audio
(e.g. ``"en-US"``). Pinch uses this as a hint to improve
accuracy even when auto-detection is on.
target_language: BCP-47 language code for the translated output
(e.g. ``"es-ES"``).
voice_type: Voice style for the synthesised translation.
One of ``"clone"`` (default), ``"female"``, or ``"male"``.
"""
source_language: str
target_language: str
voice_type: str = field(default="clone")
def __post_init__(self) -> None:
allowed_voice_types = {"clone", "female", "male"}
if self.voice_type not in allowed_voice_types:
raise ValueError(
f"voice_type must be one of {allowed_voice_types!r}, got {self.voice_type!r}."
)
@dataclass
class TranscriptEvent:
"""A transcript message emitted from the Pinch data channel.
Both interim and final transcripts for the source language as well as
the translated language are delivered through this object.
Attributes:
type: Message kind — either ``"original_transcript"`` (source
language recognition) or ``"translated_transcript"`` (target
language output).
text: The recognised or translated text for this segment.
is_final: ``True`` once Pinch has committed the segment and will
not update it further.
language_detected: BCP-47 code of the language Pinch detected in
the audio (e.g. ``"en-US"``).
timestamp: Unix timestamp (seconds, fractional) reported by Pinch
for when the utterance ended.
confidence: Raw confidence score returned by Pinch (0–1 range,
``0`` when not provided).
"""
type: str
text: str
is_final: bool
language_detected: str
timestamp: float
confidence: float = field(default=0.0)
@property
def is_original(self) -> bool:
"""``True`` if this is a source-language transcript."""
return self.type == "original_transcript"
@property
def is_translated(self) -> bool:
"""``True`` if this is a translated-language transcript."""
return self.type == "translated_transcript"
livekit/plugins/pinch/translator.py,
nutritious-butcher-39524
03/02/2026, 3:04 PMreadme:
# livekit-plugins-pinch
Real-time voice translation for [LiveKit Agents](https://github.com/livekit/agents), powered by [Pinch](https://www.startpinch.com).
---
## What it does
Drop this plugin into any LiveKit room and it will:
- Translate spoken audio in real time from one language to another
- Publish the translated audio back into the room as a separate track
- Emit transcripts (original + translated) via a simple callback
---
## Installation
Copy code
bash
pip install livekit-plugins-pinch Copy code
bash
export PINCH_API_KEY=pk_your_key_here Copy code
python
from livekit import rtc
from livekit.plugins.pinch import Translator, TranslatorOptions
async def entrypoint(ctx: JobContext):
await ctx.connect()
translator = Translator(
options=TranslatorOptions(
source_language="en-US",
target_language="es-ES",
voice_type="clone", # "clone" | "female" | "male"
)
)
@translator.on_transcript
def on_transcript(event):
if event.is_final:
print(f"[{event.type}] {event.text}")
await translator.start(ctx.room)clonefemalemalet
tall-airline-16756
03/02/2026, 3:05 PMThanks — this is a great, clear start. I reviewed the files you pasted (pyproject.toml, package init, models, README) and below I’ve listed: (A) quick fixes and clarifications, (B) recommended README/UX improvements, (C) suggested code/package checks for PR readiness, and (D) a PR checklist and ready-to-paste PR description template. I also note a few files I still need to fully verify integration.
A — Quick fixes and clarifications
• In pyproject.toml,
requires-python>=3.10>=3.10tool.hatch.build.targets.wheel.packages = ["livekit"]livekitlivekit.plugins.pinchlivekit-agents>=0.8.0pip install livekit-plugins-pinchAgentSessionJobContextPluginstart(ctx.room)@translator.on_transcriptlivekit.plugins.pinchpyproject.toml>=3.10translator.pylivekit/plugins/pinch/python -m buildhatch buildfrom livekit.plugins.pinch import TranslatorPINCH_API_KEYlivekitlivekit.plugins.pinchn
nutritious-butcher-39524
03/02/2026, 3:12 PMlivekit/plugins/pinch/translator.py:
"""Pinch real-time speech-to-speech translation plugin for LiveKit Agents."""
from future import annotations
import asyncio
import contextlib
import json
import os
import time
from typing import Callable
from livekit import rtc
from .log import logger
from .models import TranscriptEvent, TranslatorOptions
_SAMPLE_RATE = 48_000
_NUM_CHANNELS = 1
_MAX_CONNECT_RETRIES = 3
_RETRY_BASE_DELAY = 1.0
_AGENT_TRACK_TIMEOUT = 30.0
class PinchError(Exception):
"""Base class for all Pinch plugin errors."""
class PinchAuthError(PinchError):
"""Raised when the API key is invalid or missing (HTTP 401)."""
class PinchRateLimitError(PinchError):
"""Raised when the API rate limit is exceeded (HTTP 429)."""
class PinchSessionError(PinchError):
"""Raised when session creation or room connection fails."""
class Translator:
"""Real-time speech-to-speech translation via the Pinch API.
Usage::
from livekit.plugins.pinch import Translator, TranslatorOptions
translator = Translator(
options=TranslatorOptions(
source_language="en-US",
target_language="es-ES",
voice_type="clone",
)
)
@translator.on_transcript
def handle(event):
if event.is_translated and event.is_final:
print(f"[{event.language_detected}] {event.text}")
await translator.start(room)
await translator.stop()
Parameters
----------
api_key:
Pinch API key. Falls back to the ``PINCH_API_KEY`` environment variable.
options:
Source/target languages and voice type.
"""
def __init__(
self,
*,
options: TranslatorOptions,
api_key: str | None = None,
) -> None:
resolved_key = api_key or os.environ.get("PINCH_API_KEY")
if not resolved_key:
raise ValueError(
"A Pinch API key is required. Supply it via the
api_keynutritious-butcher-39524
03/02/2026, 3:12 PMasync def _run_source_to_pinch_bridge(self) -> None:
if self._source_room is None:
return
streaming_tasks: list[asyncio.Task] = []
async def _stream_track(track: rtc.RemoteAudioTrack) -> None:
try:
audio_stream = rtc.AudioStream(
track, sample_rate=_SAMPLE_RATE, num_channels=_NUM_CHANNELS
)
async for event in audio_stream:
if self._stopped:
break
if self._pinch_audio_source is not None:
await self._pinch_audio_source.capture_frame(event.frame)
except asyncio.CancelledError:
pass
except Exception as exc:
if not self._stopped:
logger.warning("source→Pinch bridge error on track %s: %s", track.sid, exc)
def start_streaming(track: rtc.Track) -> None:
if isinstance(track, rtc.RemoteAudioTrack):
streaming_tasks.append(asyncio.ensure_future(_stream_track(track)))
for participant in self._source_room.remote_participants.values():
for pub in participant.track_publications.values():
if pub.track is not None:
start_streaming(pub.track)
@self._source_room.on("track_subscribed")
def _on_track_subscribed(
track: rtc.Track,
publication: rtc.RemoteTrackPublication,
participant: rtc.RemoteParticipant,
) -> None:
start_streaming(track)
try:
while not self._stopped:
await asyncio.sleep(0.5)
except asyncio.CancelledError:
pass
finally:
self._source_room.off("track_subscribed", _on_track_subscribed)
for t in streaming_tasks:
t.cancel()
if streaming_tasks:
await asyncio.gather(*streaming_tasks, return_exceptions=True)
async def _run_pinch_to_source_bridge(self) -> None:
if self._pinch_room is None:
return
streaming_tasks: list[asyncio.Task] = []
async def _stream_track(track: rtc.RemoteAudioTrack) -> None:
try:
audio_stream = rtc.AudioStream(
track, sample_rate=_SAMPLE_RATE, num_channels=_NUM_CHANNELS
)
async for event in audio_stream:
if self._stopped:
break
if self._source_audio_source is not None:
await self._source_audio_source.capture_frame(event.frame)
except asyncio.CancelledError:
pass
except Exception as exc:
if not self._stopped:
logger.warning("Pinch→source bridge error on track %s: %s", track.sid, exc)
def start_streaming(track: rtc.Track) -> None:
if isinstance(track, rtc.RemoteAudioTrack):
logger.info(
"Pinch agent published audio track sid=%s — forwarding to source room.",
track.sid,
)
streaming_tasks.append(asyncio.ensure_future(_stream_track(track)))
for participant in self._pinch_room.remote_participants.values():
for pub in participant.track_publications.values():
if pub.track is not None:
start_streaming(pub.track)
if not any(
isinstance(pub.track, rtc.RemoteAudioTrack)
for p in self._pinch_room.remote_participants.values()
for pub in p.track_publications.values()
):
logger.info(
"Waiting for Pinch translation agent to publish audio (timeout=%.0fs)…",
_AGENT_TRACK_TIMEOUT,
)
@self._pinch_room.on("track_subscribed")
def _on_pinch_track_subscribed(
track: rtc.Track,
publication: rtc.RemoteTrackPublication,
participant: rtc.RemoteParticipant,
) -> None:
start_streaming(track)
try:
while not self._stopped:
await asyncio.sleep(0.5)
except asyncio.CancelledError:
pass
finally:
self._pinch_room.off("track_subscribed", _on_pinch_track_subscribed)
for t in streaming_tasks:
t.cancel()
if streaming_tasks:
await asyncio.gather(*streaming_tasks, return_exceptions=True)
def _on_pinch_data_received(self, data_packet: rtc.DataPacket) -> None:
try:
raw = data_packet.data
if isinstance(raw, (bytes, bytearray, memoryview)):
raw = bytes(raw).decode("utf-8")
msg: dict = json.loads(raw)
except Exception as exc:
logger.warning("Failed to decode Pinch data message: %s", exc)
return
msg_type = msg.get("type", "")
if msg_type not in ("original_transcript", "translated_transcript"):
return
event = TranscriptEvent(
type=msg_type,
text=msg.get("text", ""),
is_final=bool(msg.get("is_final", False)),
language_detected=msg.get("language_detected", ""),
timestamp=float(msg.get("timestamp", time.time())),
confidence=float(msg.get("confidence", 0.0)),
)
logger.debug("Transcript [%s] final=%s %r", event.type, event.is_final, event.text[:80])
self._emit_transcript(event)
def _emit_transcript(self, event: TranscriptEvent) -> None:
for cb in self._transcript_callbacks:
try:
cb(event)
except Exception as exc:
logger.exception("Unhandled exception in transcript callback %r: %s", cb, exc)
def __repr__(self) -> str:
return (
f"<Translator src={self._options.source_language!r} "
f"tgt={self._options.target_language!r} "
f"voice={self._options.voice_type!r} "
f"started={self._started} stopped={self._stopped}>"
)
nutritious-butcher-39524
03/02/2026, 3:12 PMThat's the full code for translator.py
t
tall-airline-16756
03/02/2026, 3:13 PMThanks — this is great; I can now do a full review of your README, packaging, and translator implementation. I’ll keep this concise and action-focused so you can prepare a PR that lands quickly.
Summary of what I checked
• pyproject.toml: package metadata and hatch config present; namespace packaging into the livekit/ tree.
• README.md: clear, good examples; missing a few details that reviewers expect.
• livekit/plugins/pinch package: init.py, models, log, and the complete translator.py implementation.
High-priority fixes and clarifications to address before opening the PR
1. pyproject.toml: fix the HTML-escaped Python requirement. Replace
>=3.10>=3.10from livekit.plugins.pinch import Translatorlivekit-agents >=0.8.0textroomrequires-python>=3.10livekit.plugins.pinchlivekitn
nutritious-butcher-39524
03/02/2026, 7:17 PMYeah, I checked everything. I raised the review like I raised a PR, and three skipped six test cases passed, and it says that the review is required. How long will it take for my PR to get approved?
t
tall-airline-16756
03/02/2026, 7:17 PMThanks — and congrats on getting tests passing and opening the PR. I know waiting for review can be stressful; I’ll be direct about what I can and can’t confirm, then give practical next steps you can take to help move it along.
Short answer
• I cannot confirm an exact review/approval timeframe for LiveKit PRs — there’s no published SLA or timeline in the project sources.
• LiveKit is an active open-source project and maintainers do review community PRs, but review times vary.
What affects review time (so you know what to expect)
• Maintainer availability and current workload.
• How complete the PR is (docs, tests, CI green, clear description).
• Whether the change affects core behavior, APIs, or packaging (bigger changes take longer).
• CI results and skipped tests: maintainers may ask for skipped tests to be fixed or justified.
• Whether reviewers need to run integration checks that require credentials or more setup.
Practical actions you can take to nudge the review forward
• Add a clear PR description and checklist (if you haven’t already). Include:
◦ What the plugin does, how to test it, how to reproduce the skipped tests, and any required credentials (or how to run with mocks).
◦ A short “How to test locally” section with commands you ran (build, pytest, example).
• Mark the PR with the appropriate labels (if the repo uses them) and request reviewers explicitly in the GitHub UI — name maintainers or team members if you know them.
• Reply to the PR thread with:
◦ A short summary of the current status (e.g., “3 skipped, 6 passed” and why the skipped tests exist).
◦ Any follow-up actions you’re willing to take if maintainers request changes.
• Provide deterministic demos/tests:
◦ Add a small test or example that runs without real Pinch credentials (mocking).
◦ If a skipped test requires secrets, explain why it’s skipped and how a reviewer can run it.
• Share compatibility notes and CI links in the PR so reviewers don’t have to guess (Python versions tested, livekit-agents version, packaging note about namespace).
• If the repo has a community channel (Slack or similar), post a polite note linking the PR and asking for review — maintainers sometimes respond faster there.
If you want, I can:
• Draft a short, copy-paste PR comment that explains the skipped tests and how to run them locally.
• Prepare a follow-up message to post in the LiveKit community (Slack) that summarizes the PR and calls out reviewers politely.
• Create a minimal CI/test guidance snippet to add to the PR so reviewers can run the same steps locally.
Which of the above would be most helpful right now — a PR comment draft, a Slack/community message, or the short checklist to add to your PR description?
Sources: Yeah, but can it run DOOM? | And…we’re Live(Kit)! | LiveKit Community Day
2 Views