livekit-plugins-spatialreal 1.4.4__tar.gz → 1.4.5__tar.gz

{livekit_plugins_spatialreal-1.4.4 → livekit_plugins_spatialreal-1.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: livekit-plugins-spatialreal
-Version: 1.4.4
+Version: 1.4.5
 Summary: Agent Framework plugin for SpatialReal Avatar
 Project-URL: Documentation, https://docs.spatialreal.com
 Project-URL: Website, https://www.spatialreal.ai/
@@ -22,7 +22,7 @@ Classifier: Topic :: Multimedia :: Sound/Audio
 Classifier: Topic :: Multimedia :: Video
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.10.0
-Requires-Dist: avatarkit>=0.1.4
+Requires-Dist: avatarkit>=0.1.7
 Requires-Dist: livekit-agents>=1.2.9
 Description-Content-Type: text/markdown
 

{livekit_plugins_spatialreal-1.4.4 → livekit_plugins_spatialreal-1.4.5}/livekit/plugins/spatialreal/__init__.py

@@ -3,7 +3,7 @@
 This plugin provides integration with SpatialReal's avatar service for
 lip-synced avatar rendering in LiveKit voice agents.
 
-See https://docs.spatialreal.com for more information.
+See https://docs.spatialreal.ai for more information.
 
 Usage:
     from livekit.plugins.spatialreal import AvatarSession

{livekit_plugins_spatialreal-1.4.4 → livekit_plugins_spatialreal-1.4.5}/livekit/plugins/spatialreal/avatar.py

@@ -23,8 +23,9 @@ from avatarkit import (
     new_avatar_session,
 )
 from avatarkit.proto.generated import message_pb2 as _message_pb2
-from livekit.agents import AgentSession, UserStateChangedEvent
+from livekit.agents import AgentSession, UserStateChangedEvent, get_job_context
 from livekit.agents.voice.avatar import AudioSegmentEnd, QueueAudioOutput
+from livekit.agents.voice.room_io import ATTRIBUTE_PUBLISH_ON_BEHALF
 
 from livekit import rtc
 
@@ -39,6 +40,8 @@ DEFAULT_SAMPLE_RATE = 24000
 MIN_COMPLETION_TIMEOUT_SECONDS = 3.0
 COMPLETION_TIMEOUT_BUFFER_SECONDS = 2.0
 ACTIVE_SEGMENT_IDLE_END_SECONDS = 1.0
+DEFAULT_SESSION_TTL = timedelta(hours=1)
+LIVEKIT_AVATAR_PUBLISH_SOURCES = ["camera", "microphone"]
 
 DEFAULT_CONSOLE_ENDPOINT = "https://console.us-west.spatialwalk.cloud/v1/console"
 DEFAULT_INGRESS_ENDPOINT = "wss://api.us-west.spatialwalk.cloud/v2/driveningress"
@@ -175,25 +178,36 @@ class AvatarSession:
         lk_api_key = livekit_api_key or os.getenv("LIVEKIT_API_KEY")
         lk_api_secret = livekit_api_secret or os.getenv("LIVEKIT_API_SECRET")
 
-        if not lk_url or not lk_api_key or not lk_api_secret:
+        if not lk_url:
+            raise SpatialRealException("livekit_url must be provided or LIVEKIT_URL environment variable must be set")
+
+        if not lk_api_key or not lk_api_secret:
             raise SpatialRealException(
-                "livekit_url, livekit_api_key, and livekit_api_secret must be provided "
-                "or LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET environment variables must be set"
+                "livekit_api_key and livekit_api_secret must be provided "
+                "or LIVEKIT_API_KEY and LIVEKIT_API_SECRET environment variables must be set"
             )
 
         room_name = room.name
-        agent_participant_identity = room.local_participant.identity
+        agent_participant_identity = self._resolve_local_participant_identity(room)
         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}
+        egress_attributes = {ATTRIBUTE_PUBLISH_ON_BEHALF: agent_participant_identity}
+        session_expire_at = datetime.now(timezone.utc) + DEFAULT_SESSION_TTL
+        resolved_lk_api_token = self._generate_livekit_api_token(
+            room_name=room_name,
+            livekit_api_key=lk_api_key,
+            livekit_api_secret=lk_api_secret,
+            publisher_identity=self._avatar_participant_identity,
+            publisher_attributes=egress_attributes,
+            ttl=DEFAULT_SESSION_TTL,
+        )
 
         # Create LiveKit egress configuration for the avatar to join the room
         livekit_egress_kwargs: dict[str, Any] = {
             "url": lk_url,
-            "api_key": lk_api_key,
-            "api_secret": lk_api_secret,
+            "api_token": resolved_lk_api_token,
             "room_name": room_name,
             "publisher_id": self._avatar_participant_identity,
             "extra_attributes": egress_attributes,
@@ -218,7 +232,7 @@ class AvatarSession:
                 avatar_id=self._avatar_id,
                 console_endpoint_url=self._console_endpoint_url,
                 ingress_endpoint_url=self._ingress_endpoint_url,
-                expire_at=datetime.now(timezone.utc) + timedelta(hours=1),
+                expire_at=session_expire_at,
                 livekit_egress=livekit_egress,
                 sample_rate=resolved_sample_rate,
                 transport_frames=self._on_transport_frame,
@@ -283,11 +297,64 @@ class AvatarSession:
         reason = self._format_error_reason(error)
         return (
             "Failed to start SpatialReal avatar session. "
-            "Check SpatialReal credentials, endpoint URLs, and outbound network access. "
+            "Check SpatialReal credentials, LiveKit room auth/token configuration, "
+            "endpoint URLs, and outbound network access. "
             f"room={room_name}, avatar_id={self._avatar_id}, ingress_endpoint_url={self._ingress_endpoint_url}, "
             f"sample_rate={sample_rate}. Reason: {reason}"
         )
 
+    @staticmethod
+    def _generate_livekit_api_token(
+        *,
+        room_name: str,
+        livekit_api_key: str,
+        livekit_api_secret: str,
+        publisher_identity: str,
+        publisher_attributes: dict[str, str],
+        ttl: timedelta,
+    ) -> str:
+        try:
+            from livekit import api as livekit_api
+        except ImportError as exc:
+            raise SpatialRealException(
+                "livekit-api must be installed to generate LiveKit access tokens for avatar egress"
+            ) from exc
+
+        try:
+            return (
+                livekit_api.AccessToken(livekit_api_key, livekit_api_secret)
+                .with_kind("agent")
+                .with_identity(publisher_identity)
+                .with_name(publisher_identity)
+                .with_ttl(ttl)
+                .with_attributes(publisher_attributes)
+                .with_grants(
+                    livekit_api.VideoGrants(
+                        room_join=True,
+                        room=room_name,
+                        can_subscribe=False,
+                        can_publish_data=False,
+                        can_publish_sources=LIVEKIT_AVATAR_PUBLISH_SOURCES,
+                    )
+                )
+                .to_jwt()
+            )
+        except Exception as exc:
+            raise SpatialRealException(
+                "Failed to generate LiveKit access token for avatar worker. "
+                f"room={room_name}, publisher_identity={publisher_identity}. "
+                f"Reason: {AvatarSession._format_error_reason(exc)}"
+            ) from exc
+
+    @staticmethod
+    def _resolve_local_participant_identity(room: rtc.Room) -> str:
+        try:
+            return get_job_context().token_claims().identity
+        except RuntimeError as exc:
+            if not room.isconnected():
+                raise SpatialRealException("failed to get local participant identity") from exc
+            return room.local_participant.identity
+
     @staticmethod
     def _format_error_reason(error: BaseException) -> str:
         root_error = error
@@ -420,12 +487,18 @@ class AvatarSession:
             active_segment = self._segments.pop(active_req_id, None)
             segment = self._segments.get(req_id)
 
+            if active_segment is None and segment is None:
+                logger.debug(
+                    "Avatar: Segment completed before finalization finished "
+                    f"(request_id={active_req_id}, finalize_request_id={req_id}, source={source})"
+                )
+                return True
+
             if segment is None:
-                if active_segment is not None:
-                    active_segment.req_id = req_id
-                    segment = active_segment
-                else:
-                    segment = _SegmentState(req_id=req_id)
+                if active_segment is None:
+                    return True
+                active_segment.req_id = req_id
+                segment = active_segment
                 self._segments[req_id] = segment
             elif active_segment is not None and segment is not active_segment:
                 segment.pushed_duration = max(segment.pushed_duration, active_segment.pushed_duration)
@@ -574,10 +647,18 @@ class AvatarSession:
         try:
             interrupted_id = await self._avatarkit_session.interrupt()
 
-            if not self._complete_segment(req_id=interrupted_id, interrupted=True, reason="interrupt"):
-                # Fallback: a race can leave the request id unmatched.
-                if self._active_req_id is not None:
-                    self._complete_segment(req_id=self._active_req_id, interrupted=True, reason="interrupt_fallback")
+            async with self._segment_finalize_lock:
+                if not self._complete_segment(req_id=interrupted_id, interrupted=True, reason="interrupt"):
+                    # Fallback: a race can leave the request id unmatched.
+                    if self._active_req_id is not None:
+                        self._complete_segment(
+                            req_id=self._active_req_id,
+                            interrupted=True,
+                            reason="interrupt_fallback",
+                        )
+                # Complete any remaining pending segments that were also interrupted
+                for req_id in list(self._segments.keys()):
+                    self._complete_segment(req_id=req_id, interrupted=True, reason="interrupt_remaining")
 
             logger.debug(f"Avatar interrupted, request_id={interrupted_id}")
         except Exception as e:

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

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

{livekit_plugins_spatialreal-1.4.4 → livekit_plugins_spatialreal-1.4.5}/pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
 ]
 dependencies = [
     "livekit-agents>=1.2.9",
-    "avatarkit>=0.1.4",
+    "avatarkit>=0.1.7",
 ]
 
 [project.urls]

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

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