LiveKit Plugins Spatius
Agent Framework plugin for Spatius avatars.
See the Spatius documentation for Spatius account setup and avatar configuration.
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
Usage
from livekit.plugins import spatius
avatar = spatius.AvatarSession()
await avatar.start(session, room=ctx.room)
The plugin reads SPATIUS_API_KEY, SPATIUS_APP_ID, and SPATIUS_AVATAR_ID from the
environment when constructor arguments are omitted.
Warm-up
At session start, the Spatius SDK resolves the ingress region via the bootstrap API
(with the default region="auto") and exchanges the API key for a session token —
two sequential HTTPS round trips on the room-join critical path. Register the
plugin's prewarm function to move that work into process warm-up, before a job is
dispatched:
from livekit import agents
from livekit.plugins import spatius
def prewarm(proc: agents.JobProcess):
spatius.prewarm(proc)
if __name__ == "__main__":
agents.cli.run_app(
agents.WorkerOptions(entrypoint_fnc=entrypoint, prewarm_fnc=prewarm)
)
The spatius SDK caches the resolved region (5 minutes) and the prefetched session
token (until shortly before expiry) process-wide, so AvatarSession.start() in the
dispatched job reuses them and goes straight to the ingress WebSocket connect. It
also opens throwaway TLS connections to the console and ingress endpoints to prime
DNS and the shared TLS session cache. Warm-up is best-effort and never fails
process initialization; without it, everything resolves inline as before.
Session-token prefetch assumes the Spatius backend allows a token to back more than
one session; opt out with spatius.prewarm(proc, prefetch_session_token=False).
Metadata
Release files for livekit-plugins-spatius 1.8.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| livekit_plugins_spatius-1.8.3.tar.gz | 10.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| livekit_plugins_spatius-1.8.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 21.4 kB
Release files / livekit_plugins_spatius-1.8.3.tar.gz
| Download URL | livekit_plugins_spatius-1.8.3.tar.gz |
|---|---|
| Size | 10.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b2b19906a16d044ee8aeee471430e9dc7c6c8f0f688a32ebcb8f9f7b3cb25a61
|
|
BLAKE2b-256 checksum How to use checksums |
c4f9d63e405e878166b04baed223f3ae74d936688499c6231a94a12e6ffe3acb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / livekit_plugins_spatius-1.8.3-py3-none-any.whl
| Download URL | livekit_plugins_spatius-1.8.3-py3-none-any.whl |
|---|---|
| Size | 11.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4d1d0afa24e6d2404a611eb357d433b4a38baf806f6b0df0a19eb39b7357517a
|
|
BLAKE2b-256 checksum How to use checksums |
e19b87e648a6fce32922f4f6ebd2e4eb049e1528147f375cbf57e45c125d1341
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency log
