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).

Project links

Data verified by PyPI on Sep 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.8.2)

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: LiveKit

GitHub Statistics

Data verified by PyPI on Sep 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10.0

Tags

ai audio avatar livekit realtime spatius video voice webrtc

Classifiers

Report project as malware

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.8.1.tar.gz (10.1 kB view details)

Uploaded Source

Built Distribution

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

livekit_plugins_spatius-1.8.1-py3-none-any.whl (11.3 kB view details)

Uploaded Python 3

File details

Details for the file livekit_plugins_spatius-1.8.1.tar.gz.

File metadata

  • Download URL: livekit_plugins_spatius-1.8.1.tar.gz
  • Upload date:
  • Size: 10.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for livekit_plugins_spatius-1.8.1.tar.gz
Algorithm Hash digest
SHA256 d71b74eea79a58861c5893d67d4196d4a3deb2836c23cf4316759aae368b4b9d
MD5 5acef4728cf7e908377d77568905ab6d
BLAKE2b-256 3fa796d690fa9177fb29ae162fdd3957eee2c87ff3c0b9c4e85956532f94a779

See more details on using hashes here.

Provenance

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

Publisher: publish.yml on livekit/agents

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

File details

Details for the file livekit_plugins_spatius-1.8.1-py3-none-any.whl.

File metadata

File hashes

Hashes for livekit_plugins_spatius-1.8.1-py3-none-any.whl
Algorithm Hash digest
SHA256 234d2d0817e43a0aa736c2bfc698b364f6ad64c2ba55c469bab35169099f928e
MD5 1103a3ca90fdff4ebbf91837ea478c9a
BLAKE2b-256 f793b562e8e3ff22b19f69575302b41649bcde379497b73b2fc003f76553a8c4

See more details on using hashes here.

Provenance

The following attestation bundles were made for livekit_plugins_spatius-1.8.1-py3-none-any.whl:

Publisher: publish.yml on livekit/agents

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

Release history Release notifications | RSS feed

1.8.2

2 files

This release

1.8.1 This release

2 files

1.8.0

2 files

1.7.1

2 files

1.7.0

2 files

Pre-release

1.6.11rc1

2 files

1.6.10

2 files

1.6.9

2 files

1.6.8

2 files

1.6.7

2 files

Pre-release

1.6.6rc1

2 files

1.6.5

2 files

Pre-release

1.6.5rc1

2 files

1.6.4

2 files

Pre-release

1.6.4rc1

2 files

Pre-release

1.6.1rc1

2 files

1.6.0

2 files

Pre-release

1.6.0rc1

2 files

1.5.17

2 files

Pre-release

1.5.17rc1

2 files

1.5.15

2 files

Pre-release

1.5.15rc2

2 files

Pre-release

1.5.15rc1

2 files

1.5.8

2 files

Pre-release

1.5.8rc1

2 files

1.4.5

2 files

Pre-release

1.4.5rc1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page