LiveKit Agents Plugin for Spatius Avatar

LiveKit Agents plugin for Spatius avatar sessions. It forwards TTS audio from a LiveKit agent session to Spatius and lets the avatar publish synchronized audio and motion data back into the same room.

Client-side rendering

Spatius avatars are rendered on the client instead of being sent as conventional server-rendered video. The avatar's LiveKit video track carries motion data in otherwise black frames, so a standard LiveKit video renderer will display a black screen. Your frontend must use the Spatius client SDK and LiveKit adapter to decode the track and render the avatar.

See the client integration guide and the reference frontend for a working implementation.

Installation

pip install livekit-plugins-spatius

Quick Start

Set credentials:

export SPATIUS_API_KEY=your-api-key
export SPATIUS_APP_ID=your-app-id
export SPATIUS_AVATAR_ID=your-avatar-id

export LIVEKIT_URL=wss://your-livekit-host
export LIVEKIT_API_KEY=your-livekit-api-key
export LIVEKIT_API_SECRET=your-livekit-api-secret

Use plugin in your LiveKit agent:

from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import spatius


class VoiceAssistant(Agent):
    def __init__(self) -> None:
        super().__init__(instructions="You are a helpful voice assistant.")


async def entrypoint(ctx: JobContext) -> None:
    await ctx.connect()

    session = AgentSession(
        vad=vad,
        stt=stt,
        llm=llm,
        tts=tts,
    )

    avatar = spatius.AvatarSession()
    await avatar.start(session, room=ctx.room)

    await session.start(agent=VoiceAssistant(), room=ctx.room)


if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

For detailed usage, see the Spatius LiveKit Agents documentation.

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

livekit_plugins_spatius-1.6.6rc1.tar.gz (10.8 kB view details)

Uploaded Jul 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

livekit_plugins_spatius-1.6.6rc1-py3-none-any.whl (10.2 kB view details)

Uploaded Jul 12, 2026 Python 3

File details

Details for the file livekit_plugins_spatius-1.6.6rc1.tar.gz.

File metadata

Download URL: livekit_plugins_spatius-1.6.6rc1.tar.gz
Upload date: Jul 12, 2026
Size: 10.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for livekit_plugins_spatius-1.6.6rc1.tar.gz
Algorithm	Hash digest
SHA256	`15daec0af102d72ccdb9902ba8cf6242a6c64e8485d7df4253c60e56cbc8db31`
MD5	`ff993819f8e750c0bd8747724e6ed354`
BLAKE2b-256	`549e3f3f58a2f5e49e88ef12bcabfe0d0879094f859b10eeae6e5d0fda92234a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for livekit_plugins_spatius-1.6.6rc1.tar.gz:

Publisher: publish.yml on spatius-ai/livekit-plugins-spatius

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: livekit_plugins_spatius-1.6.6rc1.tar.gz
- Subject digest: 15daec0af102d72ccdb9902ba8cf6242a6c64e8485d7df4253c60e56cbc8db31
- Sigstore transparency entry: 2148311566
- Sigstore integration time: Jul 12, 2026
Source repository:
- Permalink: spatius-ai/livekit-plugins-spatius@e9a08281ff9fc97d5f2a11b4674c21b9a58dc093
- Branch / Tag: refs/tags/v1.6.6rc1
- Owner: https://github.com/spatius-ai
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@e9a08281ff9fc97d5f2a11b4674c21b9a58dc093
- Trigger Event: release