livekit-plugins-spatialreal 1.3.12__tar.gz → 1.4.3__tar.gz

{livekit_plugins_spatialreal-1.3.12 → livekit_plugins_spatialreal-1.4.3}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: livekit-plugins-spatialreal
-Version: 1.3.12
+Version: 1.4.3
 Summary: Agent Framework plugin for SpatialReal Avatar
 Project-URL: Documentation, https://docs.spatialreal.com
-Project-URL: Website, https://spatialreal.com/
-Project-URL: Source, https://github.com/spatialreal/livekit-plugins-spatialreal
+Project-URL: Website, https://www.spatialreal.ai/
+Project-URL: Source, https://github.com/spatialwalk/livekit-plugins-spatialreal
 Author-email: 3DRX <3drxkjy@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -13,14 +13,16 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
 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
 Classifier: Topic :: Multimedia :: Sound/Audio
 Classifier: Topic :: Multimedia :: Video
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: >=3.9.0
-Requires-Dist: avatarkit>=0.1.3
+Requires-Python: >=3.10.0
+Requires-Dist: avatarkit>=0.1.4
 Requires-Dist: livekit-agents>=1.2.9
 Description-Content-Type: text/markdown
 
@@ -113,12 +115,16 @@ Main class for integrating SpatialReal avatars with LiveKit agents.
 | `console_endpoint_url` | `str` | Custom console endpoint URL |
 | `ingress_endpoint_url` | `str` | Custom ingress endpoint URL |
 | `avatar_participant_identity` | `str` | LiveKit identity for avatar participant |
+| `idle_timeout_seconds` | `int` | LiveKit egress idle timeout in seconds (`0` uses server defaults) |
 
 #### Methods
 
 - `start(agent_session, room, *, livekit_url, livekit_api_key, livekit_api_secret)`: Start the avatar session and hook into the agent's audio output.
 - `aclose()`: Clean up avatar session resources.
 
+When starting, the plugin automatically sets `lk.publish_on_behalf` to the
+agent participant identity for avatar worker association in LiveKit frontends.
+
 ### `SpatialRealException`
 
 Exception raised for SpatialReal-related errors.

{livekit_plugins_spatialreal-1.3.12 → livekit_plugins_spatialreal-1.4.3}/README.md

@@ -87,12 +87,16 @@ Main class for integrating SpatialReal avatars with LiveKit agents.
 | `console_endpoint_url` | `str` | Custom console endpoint URL |
 | `ingress_endpoint_url` | `str` | Custom ingress endpoint URL |
 | `avatar_participant_identity` | `str` | LiveKit identity for avatar participant |
+| `idle_timeout_seconds` | `int` | LiveKit egress idle timeout in seconds (`0` uses server defaults) |
 
 #### Methods
 
 - `start(agent_session, room, *, livekit_url, livekit_api_key, livekit_api_secret)`: Start the avatar session and hook into the agent's audio output.
 - `aclose()`: Clean up avatar session resources.
 
+When starting, the plugin automatically sets `lk.publish_on_behalf` to the
+agent participant identity for avatar worker association in LiveKit frontends.
+
 ### `SpatialRealException`
 
 Exception raised for SpatialReal-related errors.

{livekit_plugins_spatialreal-1.3.12 → livekit_plugins_spatialreal-1.4.3}/livekit/plugins/spatialreal/avatar.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import asyncio
 import os
 from datetime import datetime, timedelta, timezone
+from typing import Any
 
 from avatarkit import (
     AvatarSession as AvatarkitSession,
@@ -18,7 +19,7 @@ from avatarkit import (
     LiveKitEgressConfig,
     new_avatar_session,
 )
-from livekit.agents import AgentSession
+from livekit.agents import AgentSession, UserStateChangedEvent
 from livekit.agents.voice.avatar import AudioSegmentEnd, QueueAudioOutput
 
 from livekit import rtc
@@ -30,7 +31,6 @@ __all__ = ["AvatarSession", "SpatialRealException"]
 DEFAULT_AVATAR_PARTICIPANT_IDENTITY = "spatialreal-avatar"
 DEFAULT_SAMPLE_RATE = 24000
 
-# Default endpoints (China)
 DEFAULT_CONSOLE_ENDPOINT = "https://console.us-west.spatialwalk.cloud/v1/console"
 DEFAULT_INGRESS_ENDPOINT = "wss://api.us-west.spatialwalk.cloud/v2/driveningress"
 
@@ -56,6 +56,8 @@ class AvatarSession:
         ingress_endpoint_url: Ingress endpoint URL. Falls back to
             SPATIALREAL_INGRESS_ENDPOINT env var or default.
         avatar_participant_identity: LiveKit identity for the avatar participant.
+        idle_timeout_seconds: Idle timeout in seconds for the egress connection.
+            A value of 0 uses server defaults.
 
     Usage:
         avatar = AvatarSession()
@@ -71,6 +73,7 @@ class AvatarSession:
         console_endpoint_url: str | None = None,
         ingress_endpoint_url: str | None = None,
         avatar_participant_identity: str | None = None,
+        idle_timeout_seconds: int = 0,
     ) -> None:
         # Resolve API key
         self._api_key = api_key or os.getenv("SPATIALREAL_API_KEY")
@@ -102,6 +105,10 @@ class AvatarSession:
         # Avatar participant configuration
         self._avatar_participant_identity = avatar_participant_identity or DEFAULT_AVATAR_PARTICIPANT_IDENTITY
 
+        if idle_timeout_seconds < 0:
+            raise SpatialRealException("idle_timeout_seconds must be greater than or equal to 0")
+        self._idle_timeout_seconds = idle_timeout_seconds
+
         # Internal state
         self._avatarkit_session: AvatarkitSession | None = None
         self._agent_session: AgentSession | None = None
@@ -146,18 +153,24 @@ class AvatarSession:
             )
 
         room_name = room.name
+        agent_participant_identity = room.local_participant.identity
         logger.info(f"Initializing SpatialReal avatar session for room: {room_name}")
         logger.debug(f"Console endpoint: {self._console_endpoint_url}")
         logger.debug(f"Ingress endpoint: {self._ingress_endpoint_url}")
 
+        egress_attributes = {"lk.publish_on_behalf": agent_participant_identity}
+
         # Create LiveKit egress configuration for the avatar to join the room
-        livekit_egress = LiveKitEgressConfig(
-            url=lk_url,
-            api_key=lk_api_key,
-            api_secret=lk_api_secret,
-            room_name=room_name,
-            publisher_id=self._avatar_participant_identity,
-        )
+        livekit_egress_kwargs: dict[str, Any] = {
+            "url": lk_url,
+            "api_key": lk_api_key,
+            "api_secret": lk_api_secret,
+            "room_name": room_name,
+            "publisher_id": self._avatar_participant_identity,
+            "extra_attributes": egress_attributes,
+            "idle_timeout": self._idle_timeout_seconds,
+        }
+        livekit_egress = LiveKitEgressConfig(**livekit_egress_kwargs)
 
         # Create avatar session with LiveKit egress mode
         self._avatarkit_session = new_avatar_session(
@@ -190,6 +203,12 @@ class AvatarSession:
         def on_clear_buffer() -> None:
             asyncio.create_task(self._handle_interrupt())
 
+        # Register for user_state_changed events (interrupt on user speaking)
+        @agent_session.on("user_state_changed")
+        def on_user_state_changed(ev: UserStateChangedEvent) -> None:
+            if ev.new_state == "speaking":
+                asyncio.create_task(self._handle_interrupt())
+
         # Start the main task that forwards audio to avatar
         self._main_task = asyncio.create_task(self._run_main_task())
 

livekit_plugins_spatialreal-1.4.3/livekit/plugins/spatialreal/version.py

@@ -0,0 +1 @@
+__version__ = "1.4.3"

{livekit_plugins_spatialreal-1.3.12 → livekit_plugins_spatialreal-1.4.3}/pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "Agent Framework plugin for SpatialReal Avatar"
 readme = "README.md"
 license = "MIT"
-requires-python = ">=3.9.0"
+requires-python = ">=3.10.0"
 authors = [{ name = "3DRX", email = "3drxkjy@gmail.com" }]
 keywords = ["voice", "ai", "realtime", "audio", "video", "livekit", "webrtc", "avatar", "spatialreal"]
 classifiers = [
@@ -18,20 +18,22 @@ classifiers = [
     "Topic :: Multimedia :: Video",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3 :: Only",
 ]
 dependencies = [
     "livekit-agents>=1.2.9",
-    "avatarkit>=0.1.3",
+    "avatarkit>=0.1.4",
 ]
 
 [project.urls]
 Documentation = "https://docs.spatialreal.com"
-Website = "https://spatialreal.com/"
-Source = "https://github.com/spatialreal/livekit-plugins-spatialreal"
+Website = "https://www.spatialreal.ai/"
+Source = "https://github.com/spatialwalk/livekit-plugins-spatialreal"
 
 [tool.hatch.version]
 path = "livekit/plugins/spatialreal/version.py"
@@ -43,7 +45,7 @@ packages = ["livekit"]
 include = ["/livekit"]
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py310"
 line-length = 120
 
 [tool.ruff.lint]

livekit_plugins_spatialreal-1.3.12/livekit/plugins/spatialreal/version.py

@@ -1 +0,0 @@
-__version__ = "1.3.12"