spatialreal 0.2.2__tar.gz → 0.3.0__tar.gz

{spatialreal-0.2.2 → spatialreal-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spatialreal
-Version: 0.2.2
+Version: 0.3.0
 Summary: SpatialReal Python SDK — realtime avatar sessions (audio in, animation/egress out)
 Project-URL: Documentation, https://docs.spatialreal.ai
 Project-URL: Website, https://www.spatialreal.ai/
@@ -22,10 +22,10 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.10.0
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: nanoid>=2.0
-Requires-Dist: protobuf<8,>=6.31
+Requires-Dist: protobuf<8,>=5.29
 Requires-Dist: websockets>=12
 Provides-Extra: dev
-Requires-Dist: grpcio-tools==1.75.1; extra == 'dev'
+Requires-Dist: grpcio-tools==1.71.2; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-asyncio; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
@@ -46,8 +46,8 @@ from spatialreal import LiveKitEgressConfig, new_avatar_session
 
 session = new_avatar_session(
     api_key="...",
-    app_id="...",
     avatar_id="...",
+    # app_id is optional: the app is derived from the API key server-side
     expire_at=datetime.now(timezone.utc) + timedelta(hours=1),
     sample_rate=16000,
     livekit_egress=LiveKitEgressConfig(url=..., api_token=..., room_name=..., publisher_id=...),
@@ -64,6 +64,31 @@ await session.interrupt()  # interrupts the latest request
 await session.close()
 ```
 
+### Agora source-timeline-only viewers
+
+Set `AgoraEgressConfig(source_timeline_only=True, ...)` only when every viewer
+plays the source-timeline audio and manages its own entry transition. The default
+is `False`, which retains the existing RTC delivery policy. This setting does not
+change input sample rates or audio data.
+
+`start()` requires the server's `agora_source_timeline_only` capability when this
+mode is requested. A confirmation without it raises `UnsupportedConfigurationError`
+(`protocolError`, `websocket_handshake`, not retryable) and closes the connection
+before audio is sent. A standard WebSocket policy rejection (`1008`) is also not
+retryable. Other transport failures retain their normal retry behavior.
+
+For the coordinated bounded-burst profile, also set
+`source_playback_profile=RtcSourcePlaybackProfile.BOUNDED_BURST_V1` (import the
+enum from `spatialreal`). It requires `source_timeline_only=True` and both
+`agora_source_timeline_only` and `agora_source_burst_v1` in the server's actual
+confirmation. `session.capabilities` is the read-only tuple from that handshake.
+Missing acceptance closes the connection before the read loop or audio starts;
+there is no silent fallback. The default `UNSPECIFIED`/0 is omitted on the wire
+and retains existing behavior. Unknown values and booleans are rejected.
+
+Every animation viewer must independently opt into the same profile using a
+compatible viewer SDK; the publisher's handshake cannot negotiate room viewers.
+
 ### Pause / resume (egress mode)
 
 When the server declares the `playback_control` capability, the current
@@ -102,6 +127,14 @@ implements the server's WebSocket close-code contract (40xx: don't retry,
 
 ## What's new
 
+- 0.3.0: Agora source playback negotiation. `AgoraEgressConfig(source_timeline_only=True)`
+  requests source-timeline-only playback; `source_playback_profile=RtcSourcePlaybackProfile.BOUNDED_BURST_V1`
+  requests the bounded source playback profile. `start()` refuses the session
+  (`UnsupportedConfigurationError`, not retryable) before any audio is sent when the
+  server does not confirm the matching capabilities (`agora_source_timeline_only`,
+  `agora_source_burst_v1`). Defaults are unchanged.
+- 0.2.3: `app_id` is optional (the API key identifies the app); protobuf floor lowered
+  to 5.29 so the SDK installs next to packages that pin protobuf 5.x (TEN Framework agents).
 - `on_playback(PlaybackSignal)` — structured playback lifecycle; no protobuf
   parsing in caller code (`transport_frames(raw, is_last)` still exists).
 - `CloseCode` + `AvatarSDKError.retryable` — the reconnect contract as API.

{spatialreal-0.2.2 → spatialreal-0.3.0}/README.md

@@ -13,8 +13,8 @@ from spatialreal import LiveKitEgressConfig, new_avatar_session
 
 session = new_avatar_session(
     api_key="...",
-    app_id="...",
     avatar_id="...",
+    # app_id is optional: the app is derived from the API key server-side
     expire_at=datetime.now(timezone.utc) + timedelta(hours=1),
     sample_rate=16000,
     livekit_egress=LiveKitEgressConfig(url=..., api_token=..., room_name=..., publisher_id=...),
@@ -31,6 +31,31 @@ await session.interrupt()  # interrupts the latest request
 await session.close()
 ```
 
+### Agora source-timeline-only viewers
+
+Set `AgoraEgressConfig(source_timeline_only=True, ...)` only when every viewer
+plays the source-timeline audio and manages its own entry transition. The default
+is `False`, which retains the existing RTC delivery policy. This setting does not
+change input sample rates or audio data.
+
+`start()` requires the server's `agora_source_timeline_only` capability when this
+mode is requested. A confirmation without it raises `UnsupportedConfigurationError`
+(`protocolError`, `websocket_handshake`, not retryable) and closes the connection
+before audio is sent. A standard WebSocket policy rejection (`1008`) is also not
+retryable. Other transport failures retain their normal retry behavior.
+
+For the coordinated bounded-burst profile, also set
+`source_playback_profile=RtcSourcePlaybackProfile.BOUNDED_BURST_V1` (import the
+enum from `spatialreal`). It requires `source_timeline_only=True` and both
+`agora_source_timeline_only` and `agora_source_burst_v1` in the server's actual
+confirmation. `session.capabilities` is the read-only tuple from that handshake.
+Missing acceptance closes the connection before the read loop or audio starts;
+there is no silent fallback. The default `UNSPECIFIED`/0 is omitted on the wire
+and retains existing behavior. Unknown values and booleans are rejected.
+
+Every animation viewer must independently opt into the same profile using a
+compatible viewer SDK; the publisher's handshake cannot negotiate room viewers.
+
 ### Pause / resume (egress mode)
 
 When the server declares the `playback_control` capability, the current
@@ -69,6 +94,14 @@ implements the server's WebSocket close-code contract (40xx: don't retry,
 
 ## What's new
 
+- 0.3.0: Agora source playback negotiation. `AgoraEgressConfig(source_timeline_only=True)`
+  requests source-timeline-only playback; `source_playback_profile=RtcSourcePlaybackProfile.BOUNDED_BURST_V1`
+  requests the bounded source playback profile. `start()` refuses the session
+  (`UnsupportedConfigurationError`, not retryable) before any audio is sent when the
+  server does not confirm the matching capabilities (`agora_source_timeline_only`,
+  `agora_source_burst_v1`). Defaults are unchanged.
+- 0.2.3: `app_id` is optional (the API key identifies the app); protobuf floor lowered
+  to 5.29 so the SDK installs next to packages that pin protobuf 5.x (TEN Framework agents).
 - `on_playback(PlaybackSignal)` — structured playback lifecycle; no protobuf
   parsing in caller code (`transport_frames(raw, is_last)` still exists).
 - `CloseCode` + `AvatarSDKError.retryable` — the reconnect contract as API.

{spatialreal-0.2.2 → spatialreal-0.3.0}/pyproject.toml

@@ -26,12 +26,12 @@ classifiers = [
 dependencies = [
     "aiohttp>=3.9",
     "websockets>=12",
-    "protobuf>=6.31,<8",
+    "protobuf>=5.29,<8",
     "nanoid>=2.0",
 ]
 
 [project.optional-dependencies]
-dev = ["pytest", "pytest-asyncio", "grpcio-tools==1.75.1", "ruff"]
+dev = ["pytest", "pytest-asyncio", "grpcio-tools==1.71.2", "ruff"]
 
 [project.urls]
 Documentation = "https://docs.spatialreal.ai"

{spatialreal-0.2.2 → spatialreal-0.3.0}/spatialreal/__init__.py

@@ -24,9 +24,10 @@ from .config import (
     AgoraEgressConfig,
     AudioFormat,
     LiveKitEgressConfig,
+    RtcSourcePlaybackProfile,
     SessionConfig,
 )
-from .errors import AvatarSDKError, AvatarSDKErrorCode, CloseCode, SessionTokenError
+from .errors import AvatarSDKError, AvatarSDKErrorCode, CloseCode, SessionTokenError, UnsupportedConfigurationError
 from .events import InterruptReason, PlaybackSignal, PlaybackState, PlaybackStateEvent
 from .logid import generate_log_id
 from .session import AvatarSession, new_avatar_session
@@ -40,12 +41,14 @@ __all__ = [
     "AvatarSession",
     "CloseCode",
     "LiveKitEgressConfig",
+    "RtcSourcePlaybackProfile",
     "PlaybackSignal",
     "PlaybackStateEvent",
     "PlaybackState",
     "InterruptReason",
     "SessionConfig",
     "SessionTokenError",
+    "UnsupportedConfigurationError",
     "__version__",
     "generate_log_id",
     "new_avatar_session",

{spatialreal-0.2.2 → spatialreal-0.3.0}/spatialreal/config.py

@@ -5,10 +5,18 @@ from __future__ import annotations
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from datetime import datetime
-from enum import Enum
+from enum import Enum, IntEnum
 
 from .environments import DEFAULT_ENVIRONMENT
 from .events import PlaybackSignal, PlaybackStateEvent
+from .proto.generated import message_pb2
+
+
+class RtcSourcePlaybackProfile(IntEnum):
+    """Explicit source playback contract; independent RTC viewers must also opt in."""
+
+    UNSPECIFIED = message_pb2.RTC_SOURCE_PLAYBACK_PROFILE_UNSPECIFIED
+    BOUNDED_BURST_V1 = message_pb2.RTC_SOURCE_PLAYBACK_PROFILE_BOUNDED_BURST_V1
 
 
 class AudioFormat(str, Enum):
@@ -52,6 +60,22 @@ class AgoraEgressConfig:
     token: str = field(default="", repr=False)
     uid: int = 0
     publisher_id: str = ""
+    # Only for viewers that play source-timeline audio and manage entry locally.
+    # The server must explicitly acknowledge this mode during the handshake.
+    source_timeline_only: bool = False
+    source_playback_profile: RtcSourcePlaybackProfile = RtcSourcePlaybackProfile.UNSPECIFIED
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.source_timeline_only, bool):
+            raise ValueError("source_timeline_only must be a boolean")
+        if isinstance(self.source_playback_profile, bool) or not isinstance(self.source_playback_profile, int):
+            raise ValueError("source_playback_profile must be a known RtcSourcePlaybackProfile")
+        try:
+            self.source_playback_profile = RtcSourcePlaybackProfile(self.source_playback_profile)
+        except ValueError as exc:
+            raise ValueError("source_playback_profile must be a known RtcSourcePlaybackProfile") from exc
+        if self.source_playback_profile and not self.source_timeline_only:
+            raise ValueError("source_playback_profile requires source_timeline_only=True")
 
 
 @dataclass

{spatialreal-0.2.2 → spatialreal-0.3.0}/spatialreal/errors.py

@@ -12,6 +12,8 @@ from __future__ import annotations
 
 from enum import Enum, IntEnum
 
+from websockets.frames import CloseCode as WebSocketCloseCode
+
 
 class AvatarSDKErrorCode(str, Enum):
     """Stable, log-friendly error codes surfaced by the SDK."""
@@ -117,6 +119,8 @@ class AvatarSDKError(Exception):
             )
         if self.close_code in _RETRYABLE_CLOSE_CODES:
             return True
+        if self.close_code == WebSocketCloseCode.POLICY_VIOLATION:
+            return False
         if 4000 <= self.close_code < 4500:
             return False
         return True
@@ -125,6 +129,22 @@ class AvatarSDKError(Exception):
         return f"{self.code.value}: {self.message}"
 
 
+class UnsupportedConfigurationError(AvatarSDKError):
+    """The server confirmed a session without accepting a required mode.
+
+    This is a local handshake classification, not a new wire error code.
+    Retrying the same configuration cannot negotiate the missing capability.
+    """
+
+    def __init__(self, message: str, *, connection_id: str | None = None):
+        super().__init__(
+            code=AvatarSDKErrorCode.protocolError,
+            message=message,
+            phase="websocket_handshake",
+            connection_id=connection_id,
+        )
+
+
 class SessionTokenError(AvatarSDKError):
     """Raised when the session-token exchange with the console API fails."""
 

spatialreal-0.3.0/spatialreal/proto/generated/message_pb2.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: driveningress/v2/driveningress.proto
+# Protobuf Python Version: 5.29.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    5,
+    29,
+    0,
+    '',
+    'driveningress/v2/driveningress.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n$driveningress/v2/driveningress.proto\x12\x10\x64riveningress.v2\"\xa7\x02\n\x13LiveKitEgressConfig\x12\x0b\n\x03url\x18\x01 \x01(\t\x12\x0f\n\x07\x61pi_key\x18\x02 \x01(\t\x12\x12\n\napi_secret\x18\x03 \x01(\t\x12\x11\n\troom_name\x18\x04 \x01(\t\x12\x14\n\x0cpublisher_id\x18\x05 \x01(\t\x12T\n\x10\x65xtra_attributes\x18\x06 \x03(\x0b\x32:.driveningress.v2.LiveKitEgressConfig.ExtraAttributesEntry\x12\x14\n\x0cidle_timeout\x18\x07 \x01(\x05\x12\x11\n\tapi_token\x18\x08 \x01(\t\x1a\x36\n\x14\x45xtraAttributesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"\xc6\x01\n\x11\x41goraEgressConfig\x12\x14\n\x0c\x63hannel_name\x18\x01 \x01(\t\x12\r\n\x05token\x18\x02 \x01(\t\x12\x0b\n\x03uid\x18\x03 \x01(\r\x12\x14\n\x0cpublisher_id\x18\x04 \x01(\t\x12\x1c\n\x14source_timeline_only\x18\x06 \x01(\x08\x12K\n\x17source_playback_profile\x18\x07 \x01(\x0e\x32*.driveningress.v2.RtcSourcePlaybackProfile\"\xe7\x02\n\x16\x43lientConfigureSession\x12\x13\n\x0bsample_rate\x18\x01 \x01(\x05\x12\x0f\n\x07\x62itrate\x18\x02 \x01(\x05\x12\x33\n\x0c\x61udio_format\x18\x03 \x01(\x0e\x32\x1d.driveningress.v2.AudioFormat\x12\x45\n\x15transport_compression\x18\x04 \x01(\x0e\x32&.driveningress.v2.TransportCompression\x12\x31\n\x0b\x65gress_type\x18\x05 \x01(\x0e\x32\x1c.driveningress.v2.EgressType\x12=\n\x0elivekit_egress\x18\x06 \x01(\x0b\x32%.driveningress.v2.LiveKitEgressConfig\x12\x39\n\x0c\x61gora_egress\x18\x07 \x01(\x0b\x32#.driveningress.v2.AgoraEgressConfig\"C\n\x14ServerConfirmSession\x12\x15\n\rconnection_id\x18\x01 \x01(\t\x12\x14\n\x0c\x63\x61pabilities\x18\x02 \x03(\t\">\n\x10\x43lientAudioInput\x12\x0e\n\x06req_id\x18\x01 \x01(\t\x12\x0b\n\x03\x65nd\x18\x02 \x01(\x08\x12\r\n\x05\x61udio\x18\x03 \x01(\x0c\"S\n\x0bServerError\x12\x15\n\rconnection_id\x18\x01 \x01(\t\x12\x0e\n\x06req_id\x18\x02 \x01(\t\x12\x0c\n\x04\x63ode\x18\x03 \x01(\x05\x12\x0f\n\x07message\x18\x04 \x01(\t\"s\n\x17ServerResponseAnimation\x12\x15\n\rconnection_id\x18\x01 \x01(\t\x12\x0e\n\x06req_id\x18\x02 \x01(\t\x12\x0b\n\x03\x65nd\x18\x03 \x01(\x08\x12\x11\n\tanimation\x18\x04 \x01(\x0c\x12\x11\n\tavatar_id\x18\x05 \x01(\t\"!\n\x0f\x43lientInterrupt\x12\x0e\n\x06req_id\x18\x01 \x01(\t\"\x1d\n\x0b\x43lientPause\x12\x0e\n\x06req_id\x18\x01 \x01(\t\"\x1e\n\x0c\x43lientResume\x12\x0e\n\x06req_id\x18\x01 \x01(\t\"\xf0\x01\n\x13ServerPlaybackState\x12\x15\n\rconnection_id\x18\x01 \x01(\t\x12\x0e\n\x06req_id\x18\x02 \x01(\t\x12:\n\x05state\x18\x03 \x01(\x0e\x32+.driveningress.v2.ServerPlaybackState.State\x12\x11\n\tplayed_ms\x18\x04 \x01(\x03\x12\x0e\n\x06reason\x18\x05 \x01(\t\"S\n\x05State\x12\x15\n\x11STATE_UNSPECIFIED\x10\x00\x12\x0b\n\x07PLAYING\x10\x01\x12\n\n\x06PAUSED\x10\x02\x12\t\n\x05\x45NDED\x10\x03\x12\x0f\n\x0bINTERRUPTED\x10\x04\"\x9c\x05\n\x07Message\x12+\n\x04type\x18\x01 \x01(\x0e\x32\x1d.driveningress.v2.MessageType\x12L\n\x18\x63lient_configure_session\x18\x02 \x01(\x0b\x32(.driveningress.v2.ClientConfigureSessionH\x00\x12H\n\x16server_confirm_session\x18\x03 \x01(\x0b\x32&.driveningress.v2.ServerConfirmSessionH\x00\x12@\n\x12\x63lient_audio_input\x18\x04 \x01(\x0b\x32\".driveningress.v2.ClientAudioInputH\x00\x12\x35\n\x0cserver_error\x18\x05 \x01(\x0b\x32\x1d.driveningress.v2.ServerErrorH\x00\x12N\n\x19server_response_animation\x18\x06 \x01(\x0b\x32).driveningress.v2.ServerResponseAnimationH\x00\x12=\n\x10\x63lient_interrupt\x18\x08 \x01(\x0b\x32!.driveningress.v2.ClientInterruptH\x00\x12\x35\n\x0c\x63lient_pause\x18\t \x01(\x0b\x32\x1d.driveningress.v2.ClientPauseH\x00\x12\x37\n\rclient_resume\x18\n \x01(\x0b\x32\x1e.driveningress.v2.ClientResumeH\x00\x12\x46\n\x15server_playback_state\x18\x0b \x01(\x0b\x32%.driveningress.v2.ServerPlaybackStateH\x00\x42\x06\n\x04\x64\x61taJ\x04\x08\x07\x10\x08*\xcd\x02\n\x0bMessageType\x12\x17\n\x13MESSAGE_UNSPECIFIED\x10\x00\x12$\n MESSAGE_CLIENT_CONFIGURE_SESSION\x10\x01\x12\"\n\x1eMESSAGE_SERVER_CONFIRM_SESSION\x10\x02\x12\x1e\n\x1aMESSAGE_CLIENT_AUDIO_INPUT\x10\x03\x12\x18\n\x14MESSAGE_SERVER_ERROR\x10\x04\x12%\n!MESSAGE_SERVER_RESPONSE_ANIMATION\x10\x05\x12\x1c\n\x18MESSAGE_CLIENT_INTERRUPT\x10\x07\x12\x18\n\x14MESSAGE_CLIENT_PAUSE\x10\x08\x12\x19\n\x15MESSAGE_CLIENT_RESUME\x10\t\x12!\n\x1dMESSAGE_SERVER_PLAYBACK_STATE\x10\n\"\x04\x08\x06\x10\x06*D\n\x0b\x41udioFormat\x12\x1a\n\x16\x41UDIO_FORMAT_PCM_S16LE\x10\x00\x12\x19\n\x15\x41UDIO_FORMAT_OGG_OPUS\x10\x01*6\n\x14TransportCompression\x12\x1e\n\x1aTRANSPORT_COMPRESSION_NONE\x10\x00*Y\n\nEgressType\x12\x1b\n\x17\x45GRESS_TYPE_UNSPECIFIED\x10\x00\x12\x17\n\x13\x45GRESS_TYPE_LIVEKIT\x10\x01\x12\x15\n\x11\x45GRESS_TYPE_AGORA\x10\x02*y\n\x18RtcSourcePlaybackProfile\x12+\n\'RTC_SOURCE_PLAYBACK_PROFILE_UNSPECIFIED\x10\x00\x12\x30\n,RTC_SOURCE_PLAYBACK_PROFILE_BOUNDED_BURST_V1\x10\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'driveningress.v2.driveningress_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_LIVEKITEGRESSCONFIG_EXTRAATTRIBUTESENTRY']._loaded_options = None
+  _globals['_LIVEKITEGRESSCONFIG_EXTRAATTRIBUTESENTRY']._serialized_options = b'8\001'
+  _globals['_MESSAGETYPE']._serialized_start=2267
+  _globals['_MESSAGETYPE']._serialized_end=2600
+  _globals['_AUDIOFORMAT']._serialized_start=2602
+  _globals['_AUDIOFORMAT']._serialized_end=2670
+  _globals['_TRANSPORTCOMPRESSION']._serialized_start=2672
+  _globals['_TRANSPORTCOMPRESSION']._serialized_end=2726
+  _globals['_EGRESSTYPE']._serialized_start=2728
+  _globals['_EGRESSTYPE']._serialized_end=2817
+  _globals['_RTCSOURCEPLAYBACKPROFILE']._serialized_start=2819
+  _globals['_RTCSOURCEPLAYBACKPROFILE']._serialized_end=2940
+  _globals['_LIVEKITEGRESSCONFIG']._serialized_start=59
+  _globals['_LIVEKITEGRESSCONFIG']._serialized_end=354
+  _globals['_LIVEKITEGRESSCONFIG_EXTRAATTRIBUTESENTRY']._serialized_start=300
+  _globals['_LIVEKITEGRESSCONFIG_EXTRAATTRIBUTESENTRY']._serialized_end=354
+  _globals['_AGORAEGRESSCONFIG']._serialized_start=357
+  _globals['_AGORAEGRESSCONFIG']._serialized_end=555
+  _globals['_CLIENTCONFIGURESESSION']._serialized_start=558
+  _globals['_CLIENTCONFIGURESESSION']._serialized_end=917
+  _globals['_SERVERCONFIRMSESSION']._serialized_start=919
+  _globals['_SERVERCONFIRMSESSION']._serialized_end=986
+  _globals['_CLIENTAUDIOINPUT']._serialized_start=988
+  _globals['_CLIENTAUDIOINPUT']._serialized_end=1050
+  _globals['_SERVERERROR']._serialized_start=1052
+  _globals['_SERVERERROR']._serialized_end=1135
+  _globals['_SERVERRESPONSEANIMATION']._serialized_start=1137
+  _globals['_SERVERRESPONSEANIMATION']._serialized_end=1252
+  _globals['_CLIENTINTERRUPT']._serialized_start=1254
+  _globals['_CLIENTINTERRUPT']._serialized_end=1287
+  _globals['_CLIENTPAUSE']._serialized_start=1289
+  _globals['_CLIENTPAUSE']._serialized_end=1318
+  _globals['_CLIENTRESUME']._serialized_start=1320
+  _globals['_CLIENTRESUME']._serialized_end=1350
+  _globals['_SERVERPLAYBACKSTATE']._serialized_start=1353
+  _globals['_SERVERPLAYBACKSTATE']._serialized_end=1593
+  _globals['_SERVERPLAYBACKSTATE_STATE']._serialized_start=1510
+  _globals['_SERVERPLAYBACKSTATE_STATE']._serialized_end=1593
+  _globals['_MESSAGE']._serialized_start=1596
+  _globals['_MESSAGE']._serialized_end=2264
+# @@protoc_insertion_point(module_scope)

{spatialreal-0.2.2 → spatialreal-0.3.0}/spatialreal/proto/generated/message_pb2.pyi

@@ -2,8 +2,7 @@ from google.protobuf.internal import containers as _containers
 from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import message as _message
-from collections.abc import Iterable as _Iterable, Mapping as _Mapping
-from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
 
 DESCRIPTOR: _descriptor.FileDescriptor
 
@@ -34,6 +33,11 @@ class EgressType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
     EGRESS_TYPE_UNSPECIFIED: _ClassVar[EgressType]
     EGRESS_TYPE_LIVEKIT: _ClassVar[EgressType]
     EGRESS_TYPE_AGORA: _ClassVar[EgressType]
+
+class RtcSourcePlaybackProfile(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    RTC_SOURCE_PLAYBACK_PROFILE_UNSPECIFIED: _ClassVar[RtcSourcePlaybackProfile]
+    RTC_SOURCE_PLAYBACK_PROFILE_BOUNDED_BURST_V1: _ClassVar[RtcSourcePlaybackProfile]
 MESSAGE_UNSPECIFIED: MessageType
 MESSAGE_CLIENT_CONFIGURE_SESSION: MessageType
 MESSAGE_SERVER_CONFIRM_SESSION: MessageType
@@ -50,6 +54,8 @@ TRANSPORT_COMPRESSION_NONE: TransportCompression
 EGRESS_TYPE_UNSPECIFIED: EgressType
 EGRESS_TYPE_LIVEKIT: EgressType
 EGRESS_TYPE_AGORA: EgressType
+RTC_SOURCE_PLAYBACK_PROFILE_UNSPECIFIED: RtcSourcePlaybackProfile
+RTC_SOURCE_PLAYBACK_PROFILE_BOUNDED_BURST_V1: RtcSourcePlaybackProfile
 
 class LiveKitEgressConfig(_message.Message):
     __slots__ = ("url", "api_key", "api_secret", "room_name", "publisher_id", "extra_attributes", "idle_timeout", "api_token")
@@ -79,16 +85,20 @@ class LiveKitEgressConfig(_message.Message):
     def __init__(self, url: _Optional[str] = ..., api_key: _Optional[str] = ..., api_secret: _Optional[str] = ..., room_name: _Optional[str] = ..., publisher_id: _Optional[str] = ..., extra_attributes: _Optional[_Mapping[str, str]] = ..., idle_timeout: _Optional[int] = ..., api_token: _Optional[str] = ...) -> None: ...
 
 class AgoraEgressConfig(_message.Message):
-    __slots__ = ("channel_name", "token", "uid", "publisher_id")
+    __slots__ = ("channel_name", "token", "uid", "publisher_id", "source_timeline_only", "source_playback_profile")
     CHANNEL_NAME_FIELD_NUMBER: _ClassVar[int]
     TOKEN_FIELD_NUMBER: _ClassVar[int]
     UID_FIELD_NUMBER: _ClassVar[int]
     PUBLISHER_ID_FIELD_NUMBER: _ClassVar[int]
+    SOURCE_TIMELINE_ONLY_FIELD_NUMBER: _ClassVar[int]
+    SOURCE_PLAYBACK_PROFILE_FIELD_NUMBER: _ClassVar[int]
     channel_name: str
     token: str
     uid: int
     publisher_id: str
-    def __init__(self, channel_name: _Optional[str] = ..., token: _Optional[str] = ..., uid: _Optional[int] = ..., publisher_id: _Optional[str] = ...) -> None: ...
+    source_timeline_only: bool
+    source_playback_profile: RtcSourcePlaybackProfile
+    def __init__(self, channel_name: _Optional[str] = ..., token: _Optional[str] = ..., uid: _Optional[int] = ..., publisher_id: _Optional[str] = ..., source_timeline_only: bool = ..., source_playback_profile: _Optional[_Union[RtcSourcePlaybackProfile, str]] = ...) -> None: ...
 
 class ClientConfigureSession(_message.Message):
     __slots__ = ("sample_rate", "bitrate", "audio_format", "transport_compression", "egress_type", "livekit_egress", "agora_egress")

{spatialreal-0.2.2 → spatialreal-0.3.0}/spatialreal/session.py

@@ -27,6 +27,7 @@ from .errors import (
     AvatarSDKError,
     AvatarSDKErrorCode,
     SessionTokenError,
+    UnsupportedConfigurationError,
     error_code_for_close_code,
 )
 from .events import PlaybackSignal, PlaybackState, PlaybackStateEvent
@@ -40,6 +41,11 @@ SESSION_TOKEN_PATH = "/v1/auth/session-token"
 LEGACY_CONSOLE_SUFFIX = "/v1/console"
 DRIVENINGRESS_PATH = "/v2/driveningress"
 INGRESS_WEBSOCKET_PATH = "/websocket"
+# A configuration rejection may carry an unclassified ServerError followed by
+# the authoritative standard close. Bound the wait; no close retains the error.
+CONFIGURE_CLOSE_GRACE_SECONDS = 1.0
+_SOURCE_TIMELINE_CAPABILITY = "agora_source_timeline_only"
+_SOURCE_BURST_CAPABILITY = "agora_source_burst_v1"
 
 logger = logging.getLogger(__name__)
 
@@ -155,8 +161,6 @@ class AvatarSession:
             raise ValueError("Session not initialized (call init() first)")
         if not self._config.avatar_id:
             raise ValueError("Missing avatar ID")
-        if not self._config.app_id:
-            raise ValueError("Missing app ID")
         if self._config.livekit_egress is not None and self._config.agora_egress is not None:
             raise ValueError("Cannot configure both livekit_egress and agora_egress")
 
@@ -192,12 +196,17 @@ class AvatarSession:
 
         query = parse_qs(parsed.query)
         query["id"] = [self._config.avatar_id]
+        # The app is derived server-side from the API key; ``app_id`` is optional and only
+        # forwarded when set (the server ignores an absent X-App-ID / appId).
         headers: dict[str, str] = {}
         if self._config.use_query_auth:
-            query["appId"] = [self._config.app_id]
+            if self._config.app_id:
+                query["appId"] = [self._config.app_id]
             query["sessionKey"] = [self._session_token or ""]
         else:
-            headers = {"X-App-ID": self._config.app_id, "X-Session-Key": self._session_token or ""}
+            headers = {"X-Session-Key": self._session_token or ""}
+            if self._config.app_id:
+                headers["X-App-ID"] = self._config.app_id
 
         return (
             urlunparse((ws_scheme, parsed.netloc, parsed.path, parsed.params, urlencode(query, doseq=True), "")),
@@ -237,6 +246,8 @@ class AvatarSession:
             s.agora_egress.token = ag.token
             s.agora_egress.uid = ag.uid
             s.agora_egress.publisher_id = ag.publisher_id
+            s.agora_egress.source_timeline_only = ag.source_timeline_only
+            s.agora_egress.source_playback_profile = ag.source_playback_profile
 
         try:
             await self._connection.send(msg.SerializeToString())
@@ -277,10 +288,40 @@ class AvatarSession:
             # Forward-compatible: the field lands with server-side playback
             # control; older protos simply don't have it.
             self._capabilities = tuple(getattr(confirm, "capabilities", ()) or ())
+            if (
+                self._config.agora_egress is not None
+                and self._config.agora_egress.source_timeline_only
+                and _SOURCE_TIMELINE_CAPABILITY not in self._capabilities
+            ):
+                raise UnsupportedConfigurationError(
+                    "Server did not accept the requested Agora source-timeline-only mode",
+                    connection_id=confirm.connection_id,
+                )
+            if (
+                self._config.agora_egress is not None
+                and self._config.agora_egress.source_playback_profile
+                and _SOURCE_BURST_CAPABILITY not in self._capabilities
+            ):
+                raise UnsupportedConfigurationError(
+                    "Server did not accept the requested Agora source playback profile",
+                    connection_id=confirm.connection_id,
+                )
             return confirm.connection_id
 
         if envelope.type == message_pb2.MESSAGE_SERVER_ERROR:
-            raise _server_error(envelope.server_error, phase="websocket_handshake")
+            error = _server_error(envelope.server_error, phase="websocket_handshake")
+            if (
+                self._config.agora_egress is not None
+                and self._config.agora_egress.source_timeline_only
+                and error.close_code is None
+            ):
+                try:
+                    await asyncio.wait_for(self._connection.wait_closed(), timeout=CONFIGURE_CLOSE_GRACE_SECONDS)
+                except asyncio.TimeoutError:
+                    pass
+                else:
+                    error.close_code = self._connection.close_code
+            raise error
 
         raise AvatarSDKError(
             code=AvatarSDKErrorCode.protocolError,

spatialreal-0.3.0/spatialreal/version.py

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

spatialreal-0.2.2/spatialreal/proto/generated/message_pb2.py

@@ -1,72 +0,0 @@
-# -*- coding: utf-8 -*-
-# Generated by the protocol buffer compiler.  DO NOT EDIT!
-# NO CHECKED-IN PROTOBUF GENCODE
-# source: driveningress/v2/driveningress.proto
-# Protobuf Python Version: 6.31.1
-"""Generated protocol buffer code."""
-from google.protobuf import descriptor as _descriptor
-from google.protobuf import descriptor_pool as _descriptor_pool
-from google.protobuf import runtime_version as _runtime_version
-from google.protobuf import symbol_database as _symbol_database
-from google.protobuf.internal import builder as _builder
-_runtime_version.ValidateProtobufRuntimeVersion(
-    _runtime_version.Domain.PUBLIC,
-    6,
-    31,
-    1,
-    '',
-    'driveningress/v2/driveningress.proto'
-)
-# @@protoc_insertion_point(imports)
-
-_sym_db = _symbol_database.Default()
-
-
-
-
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n$driveningress/v2/driveningress.proto\x12\x10\x64riveningress.v2\"\xa7\x02\n\x13LiveKitEgressConfig\x12\x0b\n\x03url\x18\x01 \x01(\t\x12\x0f\n\x07\x61pi_key\x18\x02 \x01(\t\x12\x12\n\napi_secret\x18\x03 \x01(\t\x12\x11\n\troom_name\x18\x04 \x01(\t\x12\x14\n\x0cpublisher_id\x18\x05 \x01(\t\x12T\n\x10\x65xtra_attributes\x18\x06 \x03(\x0b\x32:.driveningress.v2.LiveKitEgressConfig.ExtraAttributesEntry\x12\x14\n\x0cidle_timeout\x18\x07 \x01(\x05\x12\x11\n\tapi_token\x18\x08 \x01(\t\x1a\x36\n\x14\x45xtraAttributesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"[\n\x11\x41goraEgressConfig\x12\x14\n\x0c\x63hannel_name\x18\x01 \x01(\t\x12\r\n\x05token\x18\x02 \x01(\t\x12\x0b\n\x03uid\x18\x03 \x01(\r\x12\x14\n\x0cpublisher_id\x18\x04 \x01(\t\"\xe7\x02\n\x16\x43lientConfigureSession\x12\x13\n\x0bsample_rate\x18\x01 \x01(\x05\x12\x0f\n\x07\x62itrate\x18\x02 \x01(\x05\x12\x33\n\x0c\x61udio_format\x18\x03 \x01(\x0e\x32\x1d.driveningress.v2.AudioFormat\x12\x45\n\x15transport_compression\x18\x04 \x01(\x0e\x32&.driveningress.v2.TransportCompression\x12\x31\n\x0b\x65gress_type\x18\x05 \x01(\x0e\x32\x1c.driveningress.v2.EgressType\x12=\n\x0elivekit_egress\x18\x06 \x01(\x0b\x32%.driveningress.v2.LiveKitEgressConfig\x12\x39\n\x0c\x61gora_egress\x18\x07 \x01(\x0b\x32#.driveningress.v2.AgoraEgressConfig\"C\n\x14ServerConfirmSession\x12\x15\n\rconnection_id\x18\x01 \x01(\t\x12\x14\n\x0c\x63\x61pabilities\x18\x02 \x03(\t\">\n\x10\x43lientAudioInput\x12\x0e\n\x06req_id\x18\x01 \x01(\t\x12\x0b\n\x03\x65nd\x18\x02 \x01(\x08\x12\r\n\x05\x61udio\x18\x03 \x01(\x0c\"S\n\x0bServerError\x12\x15\n\rconnection_id\x18\x01 \x01(\t\x12\x0e\n\x06req_id\x18\x02 \x01(\t\x12\x0c\n\x04\x63ode\x18\x03 \x01(\x05\x12\x0f\n\x07message\x18\x04 \x01(\t\"s\n\x17ServerResponseAnimation\x12\x15\n\rconnection_id\x18\x01 \x01(\t\x12\x0e\n\x06req_id\x18\x02 \x01(\t\x12\x0b\n\x03\x65nd\x18\x03 \x01(\x08\x12\x11\n\tanimation\x18\x04 \x01(\x0c\x12\x11\n\tavatar_id\x18\x05 \x01(\t\"!\n\x0f\x43lientInterrupt\x12\x0e\n\x06req_id\x18\x01 \x01(\t\"\x1d\n\x0b\x43lientPause\x12\x0e\n\x06req_id\x18\x01 \x01(\t\"\x1e\n\x0c\x43lientResume\x12\x0e\n\x06req_id\x18\x01 \x01(\t\"\xf0\x01\n\x13ServerPlaybackState\x12\x15\n\rconnection_id\x18\x01 \x01(\t\x12\x0e\n\x06req_id\x18\x02 \x01(\t\x12:\n\x05state\x18\x03 \x01(\x0e\x32+.driveningress.v2.ServerPlaybackState.State\x12\x11\n\tplayed_ms\x18\x04 \x01(\x03\x12\x0e\n\x06reason\x18\x05 \x01(\t\"S\n\x05State\x12\x15\n\x11STATE_UNSPECIFIED\x10\x00\x12\x0b\n\x07PLAYING\x10\x01\x12\n\n\x06PAUSED\x10\x02\x12\t\n\x05\x45NDED\x10\x03\x12\x0f\n\x0bINTERRUPTED\x10\x04\"\x9c\x05\n\x07Message\x12+\n\x04type\x18\x01 \x01(\x0e\x32\x1d.driveningress.v2.MessageType\x12L\n\x18\x63lient_configure_session\x18\x02 \x01(\x0b\x32(.driveningress.v2.ClientConfigureSessionH\x00\x12H\n\x16server_confirm_session\x18\x03 \x01(\x0b\x32&.driveningress.v2.ServerConfirmSessionH\x00\x12@\n\x12\x63lient_audio_input\x18\x04 \x01(\x0b\x32\".driveningress.v2.ClientAudioInputH\x00\x12\x35\n\x0cserver_error\x18\x05 \x01(\x0b\x32\x1d.driveningress.v2.ServerErrorH\x00\x12N\n\x19server_response_animation\x18\x06 \x01(\x0b\x32).driveningress.v2.ServerResponseAnimationH\x00\x12=\n\x10\x63lient_interrupt\x18\x08 \x01(\x0b\x32!.driveningress.v2.ClientInterruptH\x00\x12\x35\n\x0c\x63lient_pause\x18\t \x01(\x0b\x32\x1d.driveningress.v2.ClientPauseH\x00\x12\x37\n\rclient_resume\x18\n \x01(\x0b\x32\x1e.driveningress.v2.ClientResumeH\x00\x12\x46\n\x15server_playback_state\x18\x0b \x01(\x0b\x32%.driveningress.v2.ServerPlaybackStateH\x00\x42\x06\n\x04\x64\x61taJ\x04\x08\x07\x10\x08*\xcd\x02\n\x0bMessageType\x12\x17\n\x13MESSAGE_UNSPECIFIED\x10\x00\x12$\n MESSAGE_CLIENT_CONFIGURE_SESSION\x10\x01\x12\"\n\x1eMESSAGE_SERVER_CONFIRM_SESSION\x10\x02\x12\x1e\n\x1aMESSAGE_CLIENT_AUDIO_INPUT\x10\x03\x12\x18\n\x14MESSAGE_SERVER_ERROR\x10\x04\x12%\n!MESSAGE_SERVER_RESPONSE_ANIMATION\x10\x05\x12\x1c\n\x18MESSAGE_CLIENT_INTERRUPT\x10\x07\x12\x18\n\x14MESSAGE_CLIENT_PAUSE\x10\x08\x12\x19\n\x15MESSAGE_CLIENT_RESUME\x10\t\x12!\n\x1dMESSAGE_SERVER_PLAYBACK_STATE\x10\n\"\x04\x08\x06\x10\x06*D\n\x0b\x41udioFormat\x12\x1a\n\x16\x41UDIO_FORMAT_PCM_S16LE\x10\x00\x12\x19\n\x15\x41UDIO_FORMAT_OGG_OPUS\x10\x01*6\n\x14TransportCompression\x12\x1e\n\x1aTRANSPORT_COMPRESSION_NONE\x10\x00*Y\n\nEgressType\x12\x1b\n\x17\x45GRESS_TYPE_UNSPECIFIED\x10\x00\x12\x17\n\x13\x45GRESS_TYPE_LIVEKIT\x10\x01\x12\x15\n\x11\x45GRESS_TYPE_AGORA\x10\x02\x62\x06proto3')
-
-_globals = globals()
-_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
-_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'driveningress.v2.driveningress_pb2', _globals)
-if not _descriptor._USE_C_DESCRIPTORS:
-  DESCRIPTOR._loaded_options = None
-  _globals['_LIVEKITEGRESSCONFIG_EXTRAATTRIBUTESENTRY']._loaded_options = None
-  _globals['_LIVEKITEGRESSCONFIG_EXTRAATTRIBUTESENTRY']._serialized_options = b'8\001'
-  _globals['_MESSAGETYPE']._serialized_start=2159
-  _globals['_MESSAGETYPE']._serialized_end=2492
-  _globals['_AUDIOFORMAT']._serialized_start=2494
-  _globals['_AUDIOFORMAT']._serialized_end=2562
-  _globals['_TRANSPORTCOMPRESSION']._serialized_start=2564
-  _globals['_TRANSPORTCOMPRESSION']._serialized_end=2618
-  _globals['_EGRESSTYPE']._serialized_start=2620
-  _globals['_EGRESSTYPE']._serialized_end=2709
-  _globals['_LIVEKITEGRESSCONFIG']._serialized_start=59
-  _globals['_LIVEKITEGRESSCONFIG']._serialized_end=354
-  _globals['_LIVEKITEGRESSCONFIG_EXTRAATTRIBUTESENTRY']._serialized_start=300
-  _globals['_LIVEKITEGRESSCONFIG_EXTRAATTRIBUTESENTRY']._serialized_end=354
-  _globals['_AGORAEGRESSCONFIG']._serialized_start=356
-  _globals['_AGORAEGRESSCONFIG']._serialized_end=447
-  _globals['_CLIENTCONFIGURESESSION']._serialized_start=450
-  _globals['_CLIENTCONFIGURESESSION']._serialized_end=809
-  _globals['_SERVERCONFIRMSESSION']._serialized_start=811
-  _globals['_SERVERCONFIRMSESSION']._serialized_end=878
-  _globals['_CLIENTAUDIOINPUT']._serialized_start=880
-  _globals['_CLIENTAUDIOINPUT']._serialized_end=942
-  _globals['_SERVERERROR']._serialized_start=944
-  _globals['_SERVERERROR']._serialized_end=1027
-  _globals['_SERVERRESPONSEANIMATION']._serialized_start=1029
-  _globals['_SERVERRESPONSEANIMATION']._serialized_end=1144
-  _globals['_CLIENTINTERRUPT']._serialized_start=1146
-  _globals['_CLIENTINTERRUPT']._serialized_end=1179
-  _globals['_CLIENTPAUSE']._serialized_start=1181
-  _globals['_CLIENTPAUSE']._serialized_end=1210
-  _globals['_CLIENTRESUME']._serialized_start=1212
-  _globals['_CLIENTRESUME']._serialized_end=1242
-  _globals['_SERVERPLAYBACKSTATE']._serialized_start=1245
-  _globals['_SERVERPLAYBACKSTATE']._serialized_end=1485
-  _globals['_SERVERPLAYBACKSTATE_STATE']._serialized_start=1402
-  _globals['_SERVERPLAYBACKSTATE_STATE']._serialized_end=1485
-  _globals['_MESSAGE']._serialized_start=1488
-  _globals['_MESSAGE']._serialized_end=2156
-# @@protoc_insertion_point(module_scope)

spatialreal-0.2.2/spatialreal/version.py

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