livekit-plugins-synthesia 1.8.2__tar.gz

livekit_plugins_synthesia-1.8.2/.gitignore

@@ -0,0 +1,180 @@
+**/.vscode
+**/.DS_Store
+.env
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# trunk
+.trunk/
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+node_modules
+
+credentials.json
+pyrightconfig.json
+docs/
+
+# Database files
+*.db
+
+
+# Examples for development
+examples/dev/*

livekit_plugins_synthesia-1.8.2/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: livekit-plugins-synthesia
+Version: 1.8.2
+Summary: LiveKit Agents plugin for Synthesia interactive avatars
+Project-URL: Documentation, https://docs.livekit.io
+Project-URL: Website, https://livekit.io/
+Project-URL: Source, https://github.com/livekit/agents
+Author-email: LiveKit <support@livekit.io>
+License-Expression: Apache-2.0
+Keywords: ai,audio,avatar,livekit,realtime,synthesia,video,voice,webrtc
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10.0
+Requires-Dist: livekit-agents>=1.8.2
+Description-Content-Type: text/markdown
+
+# Synthesia plugin for LiveKit Agents
+
+Attach a [Synthesia](https://www.synthesia.io/) interactive avatar to a LiveKit voice agent. The avatar joins
+the room and lip-syncs the agent's speech in real time.
+
+See the [Synthesia integration docs](https://docs.livekit.io/agents/models/avatar/plugins/synthesia/) for more information.
+
+## Installation
+
+```bash
+pip install livekit-plugins-synthesia
+```
+
+## Pre-requisites
+
+You'll need an API key from Synthesia. It can be set as an environment variable:
+`SYNTHESIA_API_KEY`
+
+## Usage
+
+```python
+from livekit.plugins import synthesia
+
+avatar = synthesia.AvatarSession(
+    synthesia.AvatarConfig(
+        avatar_ids=["03cee7ec-ac90-45ec-8c20-74a399cf3dc4"]
+    ),  # SYNTHESIA_API_KEY from env
+)
+await avatar.start(session, room=ctx.room)  # before session.start
+await session.start(agent=Agent(...), room=ctx.room)
+```
+
+Set your Synthesia workspace API key in `SYNTHESIA_API_KEY`, or pass `api_key=`.
+`avatar_ids` takes one to five gallery ids of avatars available to your
+workspace. The first is the active avatar; the rest are precomputed by the
+worker so `swap_avatar()` can switch to them mid-session. An id your workspace
+cannot access raises `synthesia.SynthesiaError` with `type=synthesia.ErrorType.UNKNOWN_AVATAR`.
+
+```python
+await avatar.swap_avatar("<another-id-from-avatar-ids>")  # switch mid-session
+await avatar.swap_avatar("default")  # back to the first id
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `avatar_participant_identity` | `"synthesia-avatar-agent"` | The LiveKit identity the avatar joins under. Must be unique per concurrent avatar in a room: LiveKit evicts an existing participant when a second joins with the same identity, so give each avatar its own identity to run several in one room. |
+| `avatar_participant_name` | `"Synthesia avatar"` | The LiveKit display name the avatar joins under. |
+
+```python
+avatar = synthesia.AvatarSession(
+    synthesia.AvatarConfig(avatar_ids=["03cee7ec-ac90-45ec-8c20-74a399cf3dc4"]),
+    avatar_participant_identity="avatar-host",
+)
+```

livekit_plugins_synthesia-1.8.2/README.md

@@ -0,0 +1,56 @@
+# Synthesia plugin for LiveKit Agents
+
+Attach a [Synthesia](https://www.synthesia.io/) interactive avatar to a LiveKit voice agent. The avatar joins
+the room and lip-syncs the agent's speech in real time.
+
+See the [Synthesia integration docs](https://docs.livekit.io/agents/models/avatar/plugins/synthesia/) for more information.
+
+## Installation
+
+```bash
+pip install livekit-plugins-synthesia
+```
+
+## Pre-requisites
+
+You'll need an API key from Synthesia. It can be set as an environment variable:
+`SYNTHESIA_API_KEY`
+
+## Usage
+
+```python
+from livekit.plugins import synthesia
+
+avatar = synthesia.AvatarSession(
+    synthesia.AvatarConfig(
+        avatar_ids=["03cee7ec-ac90-45ec-8c20-74a399cf3dc4"]
+    ),  # SYNTHESIA_API_KEY from env
+)
+await avatar.start(session, room=ctx.room)  # before session.start
+await session.start(agent=Agent(...), room=ctx.room)
+```
+
+Set your Synthesia workspace API key in `SYNTHESIA_API_KEY`, or pass `api_key=`.
+`avatar_ids` takes one to five gallery ids of avatars available to your
+workspace. The first is the active avatar; the rest are precomputed by the
+worker so `swap_avatar()` can switch to them mid-session. An id your workspace
+cannot access raises `synthesia.SynthesiaError` with `type=synthesia.ErrorType.UNKNOWN_AVATAR`.
+
+```python
+await avatar.swap_avatar("<another-id-from-avatar-ids>")  # switch mid-session
+await avatar.swap_avatar("default")  # back to the first id
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `avatar_participant_identity` | `"synthesia-avatar-agent"` | The LiveKit identity the avatar joins under. Must be unique per concurrent avatar in a room: LiveKit evicts an existing participant when a second joins with the same identity, so give each avatar its own identity to run several in one room. |
+| `avatar_participant_name` | `"Synthesia avatar"` | The LiveKit display name the avatar joins under. |
+
+```python
+avatar = synthesia.AvatarSession(
+    synthesia.AvatarConfig(avatar_ids=["03cee7ec-ac90-45ec-8c20-74a399cf3dc4"]),
+    avatar_participant_identity="avatar-host",
+)
+```

livekit_plugins_synthesia-1.8.2/livekit/plugins/synthesia/__init__.py

@@ -0,0 +1,52 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# 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.
+
+"""Synthesia plugin for LiveKit Agents
+
+See https://docs.livekit.io/agents/models/avatar/plugins/synthesia/ for more information.
+"""
+
+from .avatar import AvatarSession
+from .errors import ErrorType, SynthesiaError
+from .types import AvatarConfig
+from .version import __version__
+
+__all__ = [
+    "AvatarSession",
+    "AvatarConfig",
+    "SynthesiaError",
+    "ErrorType",
+    "__version__",
+]
+
+from livekit.agents import Plugin
+
+from .log import logger
+
+
+class SynthesiaPlugin(Plugin):
+    def __init__(self) -> None:
+        super().__init__(__name__, __version__, __package__, logger)
+
+
+Plugin.register_plugin(SynthesiaPlugin())
+
+# 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_synthesia-1.8.2/livekit/plugins/synthesia/api.py

@@ -0,0 +1,275 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# 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.
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import aiohttp
+
+from livekit.agents import DEFAULT_API_CONNECT_OPTIONS, APIConnectOptions, utils
+
+from .errors import ErrorType, SynthesiaError
+from .log import logger
+from .types import StartSessionRequest, StartSessionResponse
+
+SESSION_PATH = "/api/interactive-avatars/sessions"
+_AVATAR_ID_PREFIX = "av_"
+
+# Machine-readable error codes returned by the backend in the response body.
+_CODE_TO_ERROR: dict[str, ErrorType] = {
+    "unauthorized": ErrorType.AUTH,
+    "invalid_api_key": ErrorType.AUTH,
+    "unknown_avatar": ErrorType.UNKNOWN_AVATAR,
+    "avatar_not_accessible": ErrorType.UNKNOWN_AVATAR,
+    "quota_exceeded": ErrorType.QUOTA_EXCEEDED,
+    "rate_limited": ErrorType.RATE_LIMITED,
+    "invalid_token": ErrorType.INVALID_ROOM_TOKEN,
+    "invalid_livekit_credentials": ErrorType.LIVEKIT_CREDENTIALS_REJECTED,
+    "validation_error": ErrorType.INVALID_SESSION_REQUEST,
+    "bad_request": ErrorType.INVALID_SESSION_REQUEST,
+    "unknown_reference": ErrorType.UNKNOWN_AVATAR,
+    "unauthenticated": ErrorType.AUTH,
+    "forbidden": ErrorType.AUTH,
+    "insufficient_scope": ErrorType.AUTH,
+    "not_authorized": ErrorType.AUTH,
+    "feature_not_in_plan": ErrorType.FEATURE_NOT_IN_PLAN,
+    "payment_required": ErrorType.QUOTA_EXCEEDED,
+    "concurrency_limit": ErrorType.CONCURRENCY_LIMIT,
+    # Production still emits this until the taxonomy rename reaches prod. Drop
+    # once the API only sends "concurrency_limit".
+    "concurrency_limit_exceeded": ErrorType.CONCURRENCY_LIMIT,
+}
+
+# Fallback when the body carries no code. A bare 401 is ambiguous
+# between the two credentials in play, so it stays the broader auth error.
+_STATUS_TO_ERROR: dict[int, ErrorType] = {
+    401: ErrorType.AUTH,
+    403: ErrorType.AUTH,
+    402: ErrorType.QUOTA_EXCEEDED,
+    404: ErrorType.UNKNOWN_AVATAR,
+    429: ErrorType.RATE_LIMITED,
+}
+
+
+class SynthesiaAPI:
+    """Async client for the Synthesia interactive-avatar session API.
+
+    Opens one session per ``start_session`` call. Pass ``session`` to reuse an
+    ``aiohttp.ClientSession``; when omitted the LiveKit Agents shared session is
+    used.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        api_url: str,
+        session: aiohttp.ClientSession | None = None,
+        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
+    ) -> None:
+        self._api_key = api_key
+        self._api_url = api_url.rstrip("/")
+        self._session = session
+        self._conn_options = conn_options
+
+    def _http(self) -> aiohttp.ClientSession:
+        return self._session or utils.http_context.http_session()
+
+    async def start_session(
+        self,
+        request: StartSessionRequest,
+        *,
+        conn_options: APIConnectOptions | None = None,
+    ) -> StartSessionResponse:
+        conn_options = conn_options or self._conn_options
+        url = self._api_url + SESSION_PATH
+        headers = {"Authorization": self._api_key}
+        payload: dict[str, object] = {
+            "avatarIds": [_public_avatar_id(a) for a in request.avatar_ids],
+            "livekitUrl": request.livekit_url,
+            "livekitToken": request.lk_token,
+        }
+        timeout = aiohttp.ClientTimeout(total=conn_options.timeout)
+
+        last_status: int | None = None
+        last_body: object = None
+        last_exc: Exception | None = None
+
+        for attempt in range(conn_options.max_retry + 1):
+            status: int | None = None
+            try:
+                async with self._http().post(
+                    url, headers=headers, json=payload, timeout=timeout
+                ) as resp:
+                    status = resp.status
+                    body = await _read_json(resp)
+                    if resp.ok:
+                        return self._parse_success(body)
+                    if status < 500:
+                        raise self._mapped_error(resp, body)
+                    last_status, last_body, last_exc = status, body, None
+                    logger.debug(
+                        "synthesia session request failed, retrying",
+                        extra={"status": status},
+                    )
+            except (aiohttp.ClientError, asyncio.TimeoutError) as e:
+                # A 5xx whose body fails to arrive is still a 5xx, not a transport failure.
+                last_status = status if status is not None and status >= 500 else None
+                last_body, last_exc = None, e
+                logger.debug(
+                    "synthesia session request errored, retrying",
+                    extra={"error": type(e).__name__},
+                )
+
+            if attempt < conn_options.max_retry:
+                await asyncio.sleep(conn_options.retry_interval)
+
+        raise SynthesiaError(
+            _exhausted_message(conn_options.max_retry + 1, last_status, last_body),
+            type=ErrorType.CONNECTION,
+            body=last_body,
+            status=last_status,
+            request_id=_body_request_id(last_body),
+        ) from last_exc
+
+    def _parse_success(self, body: object) -> StartSessionResponse:
+        if isinstance(body, dict):
+            session_id = body.get("id") or body.get("session_id")
+            if isinstance(session_id, str) and session_id:
+                return StartSessionResponse(session_id=session_id)
+        raise SynthesiaError("Synthesia response did not contain a session id")
+
+    def _mapped_error(self, resp: aiohttp.ClientResponse, body: object) -> SynthesiaError:
+        code = _body_code(body)
+        error_type = _CODE_TO_ERROR.get(code or "")
+        if error_type is None:
+            # A problem body names its code; an unknown one is a new code, not a hint to
+            # guess the type from the status.
+            error_type = (
+                None
+                if _is_problem(body) and code is not None
+                else _STATUS_TO_ERROR.get(resp.status)
+            )
+        message = _body_message(body) or (
+            f"Synthesia request failed ({code or f'HTTP {resp.status}'})"
+        )
+        request_id = _body_request_id(body)
+        retry_after = (
+            _parse_retry_after(resp, body)
+            if error_type in (ErrorType.RATE_LIMITED, ErrorType.CONCURRENCY_LIMIT)
+            else None
+        )
+        return SynthesiaError(
+            message,
+            type=error_type,
+            retry_after=retry_after,
+            body=body,
+            status=resp.status,
+            request_id=request_id,
+        )
+
+
+def _exhausted_message(attempts: int, status: int | None, body: object) -> str:
+    message = "could not start a Synthesia session"
+    if attempts > 1:
+        message = f"{message} after {attempts} attempts"
+    if status is None:
+        return f"{message}; last attempt: connection error"
+    message = f"{message}; last attempt: HTTP {status}"
+    detail = _body_message(body)
+    if detail is not None:
+        message = f"{message}: {detail}"
+    request_id = _body_request_id(body)
+    if request_id is not None:
+        message = f"{message} (request {request_id})"
+    return message
+
+
+def _is_problem(body: object) -> bool:
+    return isinstance(body, dict) and isinstance(body.get("type"), str)
+
+
+def _body_code(body: object) -> str | None:
+    if not isinstance(body, dict):
+        return None
+    err = body.get("error")
+    code = err.get("code") if isinstance(err, dict) else None
+    code = code or body.get("code")
+    return code if isinstance(code, str) else None
+
+
+def _body_message(body: object) -> str | None:
+    if not isinstance(body, dict):
+        return None
+    if _is_problem(body):
+        candidates = (body.get("detail"), body.get("title"))
+        return next((c for c in candidates if isinstance(c, str) and c), None)
+    err = body.get("error")
+    message = err.get("message") if isinstance(err, dict) else None
+    # Some responses use a flat shape, e.g.
+    # {"error": "Forbidden", "context": "User is not authenticated"}.
+    detail = message or body.get("message") or body.get("context")
+    if detail is None:
+        return err if isinstance(err, str) else None
+    if isinstance(detail, str):
+        return detail
+    detail = json.dumps(detail, separators=(", ", ": "))
+    code = _body_code(body)
+    return f"{code}: {detail}" if code else detail
+
+
+def _body_request_id(body: object) -> str | None:
+    if isinstance(body, dict):
+        request_id = body.get("requestId")
+        if isinstance(request_id, str):
+            return request_id
+    return None
+
+
+def _public_avatar_id(avatar_id: str) -> str:
+    """Prefix a gallery id for the wire, leaving an already-prefixed id alone.
+
+    Callers pass the raw gallery id they see in Synthesia, and the API takes the
+    namespaced form.
+    """
+    return avatar_id if avatar_id.startswith(_AVATAR_ID_PREFIX) else _AVATAR_ID_PREFIX + avatar_id
+
+
+def _parse_retry_after(resp: aiohttp.ClientResponse, body: object) -> float | None:
+    header = resp.headers.get("Retry-After")
+    if header is not None:
+        try:
+            return float(header)
+        except ValueError:
+            pass
+    if isinstance(body, dict):
+        candidates = [body.get("retry_after")]
+        err = body.get("error")
+        if isinstance(err, dict):
+            candidates.append(err.get("retry_after"))
+        for value in candidates:
+            if isinstance(value, (int, float)) and not isinstance(value, bool):
+                return float(value)
+    return None
+
+
+async def _read_json(resp: aiohttp.ClientResponse) -> object:
+    # Errors arrive as application/problem+json, which aiohttp refuses by default,
+    # so the content type is checked here rather than delegated.
+    try:
+        return await resp.json(content_type=resp.content_type)
+    except (aiohttp.ContentTypeError, ValueError):
+        return None

livekit_plugins_synthesia-1.8.2/livekit/plugins/synthesia/avatar.py

@@ -0,0 +1,405 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# 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.
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import enum
+import json
+import os
+from typing import TypeGuard
+
+from livekit import api, rtc
+from livekit.agents import DEFAULT_API_CONNECT_OPTIONS, AgentSession, get_job_context
+from livekit.agents.types import ATTRIBUTE_PUBLISH_ON_BEHALF
+from livekit.agents.voice.avatar import AvatarSession as BaseAvatarSession, DataStreamAudioOutput
+
+from .api import SynthesiaAPI
+from .errors import ErrorType, SynthesiaError
+from .log import logger
+from .types import (
+    AVATAR_IDENTITY,
+    AVATAR_NAME,
+    DEFAULT_API_URL,
+    DEFAULT_JOIN_TIMEOUT,
+    DEFAULT_SWAP_TIMEOUT,
+    TOKEN_TTL,
+    AvatarConfig,
+    SessionConfig,
+    StartSessionRequest,
+)
+
+
+def _present(value: str | None) -> TypeGuard[str]:
+    return bool(value and value.strip())
+
+
+def _to_ws_url(url: str) -> str:
+    """Coerce a LiveKit URL to the ws(s):// scheme Synthesia requires; LiveKit
+    Cloud injects https:// on deployed agents."""
+    if url.startswith("https://"):
+        return "wss://" + url[len("https://") :]
+    if url.startswith("http://"):
+        return "ws://" + url[len("http://") :]
+    return url
+
+
+class _State(enum.Enum):
+    IDLE = "idle"
+    STARTED = "started"
+    CLOSED = "closed"
+
+
+class AvatarSession(BaseAvatarSession):
+    """A Synthesia interactive avatar for a LiveKit voice agent.
+
+    Construct with up to five gallery ``avatar_ids`` and call ``start()`` before
+    ``AgentSession.start()``. The first id is the active avatar and the rest are
+    precomputed for a future mid-session swap. Credentials fall back to the
+    ``SYNTHESIA_API_KEY`` and ``SYNTHESIA_API_URL`` environment variables.
+
+    Logs when the room ends cleanly and when the avatar track drops
+    unexpectedly mid-session.
+
+    Pass ``avatar_participant_identity`` to override the LiveKit identity the
+    avatar joins under. It must be unique per concurrent avatar in a room, since
+    LiveKit evicts an existing participant when a second joins with the same
+    identity. It defaults to ``synthesia-avatar-agent``.
+    """
+
+    def __init__(
+        self,
+        avatar_config: AvatarConfig,
+        *,
+        api_key: str | None = None,
+        api_url: str | None = None,
+        join_timeout: float = DEFAULT_JOIN_TIMEOUT,
+        avatar_participant_identity: str | None = None,
+        avatar_participant_name: str | None = None,
+    ) -> None:
+        super().__init__()
+
+        if avatar_participant_identity is not None and not avatar_participant_identity.strip():
+            raise SynthesiaError("avatar_participant_identity must be a non-empty string")
+        if avatar_participant_name is not None and not avatar_participant_name.strip():
+            raise SynthesiaError("avatar_participant_name must be a non-empty string")
+        self._avatar_identity = avatar_participant_identity or AVATAR_IDENTITY
+        self._avatar_name = avatar_participant_name or AVATAR_NAME
+
+        key = api_key or os.environ.get("SYNTHESIA_API_KEY")
+        if not key:
+            raise SynthesiaError(
+                "a Synthesia API key is required: pass api_key or set SYNTHESIA_API_KEY"
+            )
+
+        url = api_url or os.environ.get("SYNTHESIA_API_URL") or DEFAULT_API_URL
+
+        self._config = SessionConfig(
+            avatar_ids=tuple(avatar_config.avatar_ids),
+            api_key=key,
+            api_url=url,
+            join_timeout=join_timeout,
+        )
+        self._state = _State.IDLE
+        # Guards against re-entrant start() calls. Distinct from _state: while a
+        # start is awaiting a prior teardown the lifecycle is still its old
+        # state, so this cannot be folded into _state.
+        self._starting = False
+        self._close_done = asyncio.Event()
+        self._session_id: str | None = None
+        self._teardown_task: asyncio.Task[None] | None = None
+        # The exact sink this session installed, tracked by identity rather than
+        # type or chain position: AgentSession.start() can wrap it in
+        # TranscriptSynchronizer/RecorderAudioOutput, and a caller may already
+        # have their own DataStreamAudioOutput installed before start() runs.
+        self._audio_output: DataStreamAudioOutput | None = None
+
+    @property
+    def avatar_identity(self) -> str:
+        return self._avatar_identity
+
+    @property
+    def provider(self) -> str:
+        return "synthesia"
+
+    async def start(
+        self,
+        agent_session: AgentSession,
+        room: rtc.Room,
+        *,
+        livekit_url: str | None = None,
+        livekit_api_key: str | None = None,
+        livekit_api_secret: str | None = None,
+    ) -> None:
+        if self._starting:
+            raise SynthesiaError("start() is already in progress")
+        self._starting = True
+        try:
+            if self._teardown_task is not None:
+                teardown = self._teardown_task
+                await asyncio.shield(asyncio.gather(teardown, return_exceptions=True))
+                if not teardown.cancelled() and teardown.exception() is not None:
+                    raise SynthesiaError(
+                        "the previous avatar session did not tear down cleanly; not restarting"
+                    ) from teardown.exception()
+            if self._state is _State.STARTED:
+                return
+
+            url = livekit_url or os.environ.get("LIVEKIT_URL")
+            lk_key = livekit_api_key or os.environ.get("LIVEKIT_API_KEY")
+            lk_secret = livekit_api_secret or os.environ.get("LIVEKIT_API_SECRET")
+            # A blank key or secret still mints a syntactically valid token that
+            # Synthesia accepts, since it cannot verify a signature made with the
+            # developer's own secret. LiveKit only rejects it once the avatar
+            # tries to join, so catch it here instead.
+            if not _present(url) or not _present(lk_key) or not _present(lk_secret):
+                raise SynthesiaError(
+                    "LiveKit url, API key, and API secret are required: pass them or "
+                    "set LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET"
+                )
+            url = _to_ws_url(url)
+            if not url.startswith(("ws://", "wss://")):
+                raise SynthesiaError(f"livekit_url {url!r} is not a ws:// or wss:// URL")
+
+            self._state = _State.IDLE
+            self._close_done.clear()
+            self._teardown_task = None
+
+            try:
+                await super().start(agent_session, room)
+                token = self._mint_token(room=room, lk_key=lk_key, lk_secret=lk_secret)
+                client = SynthesiaAPI(api_key=self._config.api_key, api_url=self._config.api_url)
+                launch_conn = dataclasses.replace(
+                    DEFAULT_API_CONNECT_OPTIONS,
+                    timeout=self._config.join_timeout,
+                    max_retry=0,
+                )
+                response = await client.start_session(
+                    StartSessionRequest(
+                        avatar_ids=list(self._config.avatar_ids),
+                        livekit_url=url,
+                        lk_token=token,
+                    ),
+                    conn_options=launch_conn,
+                )
+                self._session_id = response.session_id
+
+                # TODO: confirm the avatar worker's expected audio sample rate and
+                # pass sample_rate explicitly once it is verified against the real
+                # worker.
+                audio_output = DataStreamAudioOutput(
+                    room,
+                    destination_identity=self.avatar_identity,
+                    wait_remote_track=rtc.TrackKind.KIND_VIDEO,
+                )
+                # replace_audio_tail keeps any wrapper AgentSession.start() adds
+                # later (TranscriptSynchronizer, RecorderAudioOutput) attached.
+                agent_session.output.replace_audio_tail(audio_output)
+                self._audio_output = audio_output
+
+                await self.wait_for_join(timeout=self._config.join_timeout)
+            except asyncio.TimeoutError as e:
+                await self.aclose()
+                await self._discard_partial_start()
+                raise SynthesiaError(
+                    f"avatar did not join within {self._config.join_timeout}s",
+                    type=ErrorType.TIMEOUT,
+                ) from e
+            except BaseException:
+                await self.aclose()
+                await self._discard_partial_start()
+                raise
+
+            if self._state is _State.CLOSED:
+                await self._close_done.wait()
+                await self._discard_partial_start()
+                raise SynthesiaError("avatar session was closed while starting")
+
+            room.on("disconnected", self._on_room_disconnected)
+            room.on("track_unpublished", self._on_track_unpublished)
+            room.on("participant_disconnected", self._on_participant_disconnected)
+            self._state = _State.STARTED
+        finally:
+            self._starting = False
+
+    async def _discard_partial_start(self) -> None:
+        # An aclose() that ran concurrently with start() cannot see the audio
+        # output and session id that start() set after it completed, so a failed
+        # start cleans them up itself, closing the audio output's background
+        # tasks rather than just dropping the reference. Only the sink this
+        # session installed is touched: it may now be wrapped by
+        # AgentSession.start() (TranscriptSynchronizer, RecorderAudioOutput), and
+        # the caller may have had their own DataStreamAudioOutput before this
+        # session ever ran, so neither the current chain head nor its type says
+        # what to close.
+        audio_output, self._audio_output = self._audio_output, None
+        if audio_output is not None and hasattr(audio_output, "aclose"):
+            await audio_output.aclose()
+        self._session_id = None
+
+    async def swap_avatar(self, avatar_id: str, *, timeout: float = DEFAULT_SWAP_TIMEOUT) -> str:
+        """Switch the rendered avatar mid-session.
+
+        ``avatar_id`` must be one of the ids passed in ``AvatarConfig``, or
+        ``"default"`` for the first id in that list. Returns the now-active
+        avatar id once the swap has taken effect. Raises a ``SynthesiaError``
+        of type ``UNKNOWN_AVATAR`` for an id that was not precomputed,
+        ``CONNECTION`` if the worker cannot be reached, and no ``type`` if the
+        worker rejects the swap.
+        """
+        if self._state is not _State.STARTED or self._ending() or self._room is None:
+            raise SynthesiaError("swap_avatar() requires a started avatar session")
+        if avatar_id != "default" and avatar_id not in self._config.avatar_ids:
+            raise SynthesiaError(
+                f"avatar {avatar_id!r} was not in initial list of avatar_ids",
+                type=ErrorType.UNKNOWN_AVATAR,
+            )
+
+        try:
+            raw = await self._room.local_participant.perform_rpc(
+                destination_identity=self.avatar_identity,
+                method="swapAvatar",
+                payload=json.dumps({"avatar_id": avatar_id}),
+                response_timeout=timeout,
+            )
+        except Exception as e:
+            raise SynthesiaError(f"avatar swap RPC failed: {e}", type=ErrorType.CONNECTION) from e
+
+        try:
+            response = json.loads(raw)
+        except ValueError as e:
+            raise SynthesiaError("avatar swap returned a malformed response") from e
+        avatar_id_result = response.get("avatar_id") if isinstance(response, dict) else None
+        if (
+            not isinstance(response, dict)
+            or response.get("error")
+            or not isinstance(avatar_id_result, str)
+        ):
+            detail = response.get("error") if isinstance(response, dict) else None
+            raise SynthesiaError(f"avatar swap failed: {detail or raw}")
+        return avatar_id_result
+
+    def _mint_token(self, *, room: rtc.Room, lk_key: str, lk_secret: str) -> str:
+        # Synthesia rejects a token whose publish-on-behalf attribute is empty,
+        # since the worker has no agent to publish the avatar's audio for. Prefer
+        # the job context over room.local_participant: inside a job, the room may
+        # not have finished connecting yet when start() runs. Standalone callers
+        # (no job context) connect the room themselves before calling start(), so
+        # room.local_participant is safe there.
+        job_ctx = get_job_context(required=False)
+        agent_identity = (
+            job_ctx.local_participant_identity
+            if job_ctx is not None
+            else room.local_participant.identity
+        )
+        if not _present(agent_identity):
+            raise SynthesiaError(
+                "the room's local participant has no identity; connect the room "
+                "before starting the avatar session"
+            )
+
+        token = (
+            api.AccessToken(lk_key, lk_secret)
+            .with_identity(self.avatar_identity)
+            .with_name(self._avatar_name)
+            .with_kind("agent")
+            .with_grants(
+                api.VideoGrants(
+                    room_join=True,
+                    room=room.name,
+                    can_publish=True,
+                    can_subscribe=True,
+                    can_publish_data=True,
+                )
+            )
+            .with_attributes({ATTRIBUTE_PUBLISH_ON_BEHALF: agent_identity})
+            .with_ttl(TOKEN_TTL)
+        )
+        return token.to_jwt()
+
+    def _on_room_disconnected(self, *args: object) -> None:
+        if self._ending():
+            return
+        logger.info("avatar session ended")
+        self._begin_teardown()
+
+    def _on_track_unpublished(
+        self,
+        publication: rtc.RemoteTrackPublication,
+        participant: rtc.RemoteParticipant,
+    ) -> None:
+        if (
+            participant.identity == self.avatar_identity
+            and publication.kind == rtc.TrackKind.KIND_VIDEO
+        ):
+            self._report_avatar_lost()
+
+    def _on_participant_disconnected(self, participant: rtc.RemoteParticipant) -> None:
+        if participant.identity == self.avatar_identity:
+            self._report_avatar_lost()
+
+    def _report_avatar_lost(self) -> None:
+        if self._ending():
+            return
+        # The avatar leaving while the room is still up is a worker crash. If the
+        # room itself is going down, this is a clean end and _on_room_disconnected
+        # reports it instead.
+        if self._room is not None and not self._room.isconnected():
+            return
+        logger.warning("avatar left the room unexpectedly")
+        self._begin_teardown()
+
+    def _ending(self) -> bool:
+        return self._state is _State.CLOSED or self._teardown_task is not None
+
+    def _begin_teardown(self) -> None:
+        if self._teardown_task is None and self._state is not _State.CLOSED:
+            self._teardown_task = asyncio.create_task(self.aclose())
+            self._teardown_task.add_done_callback(self._on_teardown_done)
+
+    def _on_teardown_done(self, task: asyncio.Task[None]) -> None:
+        if task.cancelled():
+            return
+        exc = task.exception()
+        if exc is not None:
+            logger.error("avatar teardown failed", exc_info=exc)
+
+    async def aclose(self) -> None:
+        if self._state is _State.CLOSED:
+            await self._close_done.wait()
+            return
+        self._state = _State.CLOSED
+        self._session_id = None
+
+        try:
+            # Only the sink this session installed is closed, by identity: it may
+            # now be wrapped by AgentSession.start() (TranscriptSynchronizer,
+            # RecorderAudioOutput), and the caller may have had their own
+            # DataStreamAudioOutput before this session ever ran, so neither the
+            # current chain head nor its type says what to close. The wrapper
+            # chain itself is left in place; there is no public API to remove a
+            # tail sink from it without supplying a replacement.
+            audio_output, self._audio_output = self._audio_output, None
+            if audio_output is not None and hasattr(audio_output, "aclose"):
+                await audio_output.aclose()
+
+            if self._room is not None:
+                self._room.off("disconnected", self._on_room_disconnected)
+                self._room.off("track_unpublished", self._on_track_unpublished)
+                self._room.off("participant_disconnected", self._on_participant_disconnected)
+
+            await super().aclose()
+        finally:
+            self._close_done.set()

livekit_plugins_synthesia-1.8.2/livekit/plugins/synthesia/errors.py

@@ -0,0 +1,133 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# 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.
+
+from __future__ import annotations
+
+import enum
+import json
+
+from livekit.agents import APIError
+
+__all__ = [
+    "ErrorType",
+    "SynthesiaError",
+]
+
+
+class ErrorType(enum.Enum):
+    """What went wrong, for callers that want to branch on it."""
+
+    AUTH = "auth"
+    """The API key is invalid, expired, or lacks the scope this endpoint requires."""
+
+    FEATURE_NOT_IN_PLAN = "feature_not_in_plan"
+    """The workspace's plan does not include interactive avatars."""
+
+    INVALID_ROOM_TOKEN = "invalid_room_token"
+    """The room token cannot produce a joined session.
+
+    Distinct from ``AUTH``, which concerns the Synthesia API key. Raised for a
+    token that is malformed or missing the attribute naming the agent the
+    avatar publishes audio for.
+    """
+
+    LIVEKIT_CREDENTIALS_REJECTED = "livekit_credentials_rejected"
+    """The LiveKit project the token was signed for would not accept it.
+
+    The token itself is well formed, so the API key and secret it was minted
+    with are the thing to check, not the Synthesia credentials.
+    """
+
+    INVALID_SESSION_REQUEST = "invalid_session_request"
+    """The backend rejected the session request payload."""
+
+    UNKNOWN_AVATAR = "unknown_avatar"
+    """Avatar is not in the gallery or not accessible to the workspace."""
+
+    QUOTA_EXCEEDED = "quota_exceeded"
+    """The workspace's session quota is exhausted."""
+
+    RATE_LIMITED = "rate_limited"
+    """The request was throttled. ``retry_after`` may carry the back-off."""
+
+    CONCURRENCY_LIMIT = "concurrency_limit"
+    """Every concurrent-session slot is in use.
+
+    The API sends no ``Retry-After`` for this today, so ``retry_after`` is
+    normally ``None``; it is honoured if one ever arrives.
+    """
+
+    TIMEOUT = "timeout"
+    """The avatar did not join within ``join_timeout``."""
+
+    CONNECTION = "connection"
+    """No usable response after retries.
+
+    The last attempt either failed to connect or was answered with a 5xx;
+    ``status`` and ``request_id`` describe that answer when there was one.
+    """
+
+
+_RETRYABLE_TYPES = {
+    ErrorType.RATE_LIMITED,
+    ErrorType.CONCURRENCY_LIMIT,
+    ErrorType.TIMEOUT,
+    ErrorType.CONNECTION,
+}
+
+
+class SynthesiaError(APIError):
+    """Every error the Synthesia plugin raises. Also a :class:`~livekit.agents.APIError`.
+
+    - ``type`` identifies what went wrong; see :class:`ErrorType`.
+    - ``retryable`` reports whether retrying the same call could plausibly
+      succeed, and defaults based on ``type`` unless overridden.
+    - ``retry_after`` carries the server-provided back-off in seconds for a
+      ``RATE_LIMITED`` or ``CONCURRENCY_LIMIT`` error, when the backend
+      supplied one.
+    - ``status`` is the HTTP status the API answered, or ``None`` when no
+      answer arrived.
+    - ``request_id`` is the API's ``requestId`` when the body carried one.
+      Quote it when contacting support.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        type: ErrorType | None = None,
+        body: object | None = None,
+        retryable: bool | None = None,
+        retry_after: float | None = None,
+        status: int | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        if not isinstance(message, str):
+            message = _stringify(message)
+        self.type = type
+        self.retry_after = retry_after
+        self.status = status
+        self.request_id = request_id
+        if retryable is None:
+            retryable = type in _RETRYABLE_TYPES
+        super().__init__(message, body=body, retryable=retryable)
+
+
+def _stringify(value: object) -> str:
+    if isinstance(value, (dict, list)):
+        try:
+            return json.dumps(value, separators=(", ", ": "))
+        except (TypeError, ValueError):
+            pass
+    return str(value)

livekit_plugins_synthesia-1.8.2/livekit/plugins/synthesia/log.py

@@ -0,0 +1,17 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# 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.
+
+import logging
+
+logger = logging.getLogger("livekit.plugins.synthesia")

livekit_plugins_synthesia-1.8.2/livekit/plugins/synthesia/types.py

@@ -0,0 +1,72 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# 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.
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from datetime import timedelta
+
+DEFAULT_API_URL = "https://developers.synthesia.io"
+DEFAULT_JOIN_TIMEOUT = 30.0
+DEFAULT_SWAP_TIMEOUT = 15.0
+AVATAR_IDENTITY = "synthesia-avatar-agent"
+AVATAR_NAME = "Synthesia avatar"
+MAX_AVATAR_IDS = 5
+
+# Lifetime of the room-join token minted for the avatar worker. Long enough to
+# cover the full session and any reconnects.
+TOKEN_TTL = timedelta(hours=6)
+
+
+@dataclass
+class AvatarConfig:
+    """The avatars to render in the room.
+
+    ``avatar_ids`` holds one to five gallery ids of Synthesia avatars available
+    to your workspace. The first id is the active avatar; the rest are
+    available for swapping in during the session. Normalized to a tuple.
+    """
+
+    avatar_ids: Sequence[str]
+
+    def __post_init__(self) -> None:
+        if isinstance(self.avatar_ids, (str, bytes)):
+            raise ValueError("avatar_ids must be a list of ids, not a single string")
+        self.avatar_ids = tuple(self.avatar_ids)
+        if not 1 <= len(self.avatar_ids) <= MAX_AVATAR_IDS:
+            raise ValueError(
+                f"avatar_ids must contain between 1 and {MAX_AVATAR_IDS} ids, "
+                f"got {len(self.avatar_ids)}"
+            )
+
+
+@dataclass(frozen=True)
+class SessionConfig:
+    avatar_ids: tuple[str, ...]
+    api_key: str = field(repr=False)
+    api_url: str
+    join_timeout: float
+
+
+@dataclass(frozen=True)
+class StartSessionRequest:
+    avatar_ids: list[str]
+    livekit_url: str
+    lk_token: str = field(repr=False)
+
+
+@dataclass(frozen=True)
+class StartSessionResponse:
+    session_id: str

livekit_plugins_synthesia-1.8.2/livekit/plugins/synthesia/version.py

@@ -0,0 +1,15 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# 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.
+
+__version__ = "1.8.2"

livekit_plugins_synthesia-1.8.2/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "livekit-plugins-synthesia"
+dynamic = ["version"]
+description = "LiveKit Agents plugin for Synthesia interactive avatars"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10.0"
+authors = [{ name = "LiveKit", email = "support@livekit.io" }]
+keywords = ["voice", "ai", "realtime", "audio", "video", "livekit", "webrtc", "avatar", "synthesia"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["livekit-agents>=1.8.2"]
+
+[project.urls]
+Documentation = "https://docs.livekit.io"
+Website = "https://livekit.io/"
+Source = "https://github.com/livekit/agents"
+
+[tool.hatch.version]
+path = "livekit/plugins/synthesia/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["livekit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/livekit"]
+
+[tool.uv]
+exclude-newer = "7 days"
+exclude-newer-package = { livekit-agents = "0 days" }