Metadata-Version: 2.5
Name: spatius
Version: 1.0.5
Summary: Python SDK for avatar WebSocket services with audio streaming and animation frame reception
Author-email: 3DRX <3drxkjy@gmail.com>
License-File: LICENSE
Keywords: animation,audio,avatar,protobuf,sdk,websocket
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: nanoid>=2.0.0
Requires-Dist: opentelemetry-api>=1.28.2
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.28.2
Requires-Dist: opentelemetry-sdk>=1.28.2
Requires-Dist: protobuf>=5.28.3
Requires-Dist: websockets>=10.0
Provides-Extra: opus
Requires-Dist: opuslib-next>=1.3.0; extra == 'opus'
Description-Content-Type: text/markdown

# Spatius Python SDK

Python server SDK for creating Spatius avatar sessions.

## Installation

```bash
pip install spatius
```

Install the optional Ogg Opus encoder support when you want the SDK to encode raw PCM before sending:

```bash
pip install "spatius[opus]"
```

## Telemetry

The SDK exports anonymous OpenTelemetry metrics and traces by default. Configure the process-wide OTLP base endpoint before using a session, or disable export with an empty string:

```python
from spatius import configure_telemetry, shutdown_telemetry

configure_telemetry("https://telemetry.example.com")
# configure_telemetry("")  # disable metrics and traces

# Useful for short-lived processes that exit immediately after a session.
shutdown_telemetry()
```

The first audio message for each request carries W3C trace context to the backend. Later chunks omit it. OTel resources include `service.name=spatius-python`, `sdk.platform=python`, `app_id`, and the resolved `region`. The server SDK exports metrics and traces only; it does not upload telemetry logs.

## Documentation

See the full Python SDK guide at [docs.spatius.ai/sdk-reference/python-sdk/python-sdk](https://docs.spatius.ai/sdk-reference/python-sdk/python-sdk).

## License

MIT
