spatialreal 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spatialreal
-Version: 0.3.0
+Version: 0.4.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/
@@ -64,30 +64,33 @@ 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.
+### Agora playback defaults
+
+`AgoraEgressConfig(channel_name=..., token=..., uid=...)` defaults to
+`source_timeline_only=True` and `BOUNDED_BURST_V1`. Current SpatialReal Web SDK
+viewers detect this profile from the actual media, so no playback flags are
+needed on either side. Audio input formats and sample rates are unchanged.
+
+Before sending audio, `start()` requires both `agora_source_timeline_only` and
+`agora_source_burst_v1` in the server's actual confirmation. Missing acceptance
+raises `UnsupportedConfigurationError` (`protocolError`, `websocket_handshake`,
+not retryable) and closes the connection. Policy rejection (`1008`) is also not
+retryable; ordinary transport failures retain their existing retry policy.
+`session.capabilities` is the read-only tuple from the handshake.
+
+For older viewers that require native audio, explicitly set
+`source_timeline_only=False`; the omitted profile then resolves to
+`RtcSourcePlaybackProfile.UNSPECIFIED`/0. An explicit `source_playback_profile=0`
+with source-only enabled preserves the earlier source-only contract. `None`
+selects the profile from `source_timeline_only`; booleans and unknown profile
+values are rejected. Burst with source-only disabled is invalid.
+
+This changes the default for Agora publishers and requires a compatible server
+and viewer SDK. The publisher handshake cannot discover or upgrade room viewers.
+An incompatible server fails explicitly rather than silently falling back. Use a
+Web SDK build with automatic profile detection, or explicitly configure
+`agora.sourcePlaybackProfile: "bounded-burst-v1"` on Web SDK 1.0.0-beta.6.
+Upgrading the publisher alone does not upgrade existing viewers.
 
 ### Pause / resume (egress mode)
 
@@ -127,6 +130,13 @@ implements the server's WebSocket close-code contract (40xx: don't retry,
 
 ## What's new
 
+- 0.4.0: **Behaviour change** — the Agora publisher default is now source-timeline-only
+  playback with the bounded burst profile: a plain `AgoraEgressConfig(channel_name=..., token=..., uid=...)`
+  requests `source_timeline_only=True` and `BOUNDED_BURST_V1`. Viewers need a Web SDK with
+  automatic profile detection (1.0.0-beta.7+), or must set
+  `agora.sourcePlaybackProfile: 'bounded-burst-v1'` explicitly on 1.0.0-beta.6. Pass
+  `source_timeline_only=False` for compatibility mode (older/native-audio viewers); the
+  omitted profile then resolves to zero. Server capability checks remain mandatory.
 - 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

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

@@ -31,30 +31,33 @@ 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.
+### Agora playback defaults
+
+`AgoraEgressConfig(channel_name=..., token=..., uid=...)` defaults to
+`source_timeline_only=True` and `BOUNDED_BURST_V1`. Current SpatialReal Web SDK
+viewers detect this profile from the actual media, so no playback flags are
+needed on either side. Audio input formats and sample rates are unchanged.
+
+Before sending audio, `start()` requires both `agora_source_timeline_only` and
+`agora_source_burst_v1` in the server's actual confirmation. Missing acceptance
+raises `UnsupportedConfigurationError` (`protocolError`, `websocket_handshake`,
+not retryable) and closes the connection. Policy rejection (`1008`) is also not
+retryable; ordinary transport failures retain their existing retry policy.
+`session.capabilities` is the read-only tuple from the handshake.
+
+For older viewers that require native audio, explicitly set
+`source_timeline_only=False`; the omitted profile then resolves to
+`RtcSourcePlaybackProfile.UNSPECIFIED`/0. An explicit `source_playback_profile=0`
+with source-only enabled preserves the earlier source-only contract. `None`
+selects the profile from `source_timeline_only`; booleans and unknown profile
+values are rejected. Burst with source-only disabled is invalid.
+
+This changes the default for Agora publishers and requires a compatible server
+and viewer SDK. The publisher handshake cannot discover or upgrade room viewers.
+An incompatible server fails explicitly rather than silently falling back. Use a
+Web SDK build with automatic profile detection, or explicitly configure
+`agora.sourcePlaybackProfile: "bounded-burst-v1"` on Web SDK 1.0.0-beta.6.
+Upgrading the publisher alone does not upgrade existing viewers.
 
 ### Pause / resume (egress mode)
 
@@ -94,6 +97,13 @@ implements the server's WebSocket close-code contract (40xx: don't retry,
 
 ## What's new
 
+- 0.4.0: **Behaviour change** — the Agora publisher default is now source-timeline-only
+  playback with the bounded burst profile: a plain `AgoraEgressConfig(channel_name=..., token=..., uid=...)`
+  requests `source_timeline_only=True` and `BOUNDED_BURST_V1`. Viewers need a Web SDK with
+  automatic profile detection (1.0.0-beta.7+), or must set
+  `agora.sourcePlaybackProfile: 'bounded-burst-v1'` explicitly on 1.0.0-beta.6. Pass
+  `source_timeline_only=False` for compatibility mode (older/native-audio viewers); the
+  omitted profile then resolves to zero. Server capability checks remain mandatory.
 - 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

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

@@ -13,7 +13,7 @@ from .proto.generated import message_pb2
 
 
 class RtcSourcePlaybackProfile(IntEnum):
-    """Explicit source playback contract; independent RTC viewers must also opt in."""
+    """Source playback contract; current Web SDK viewers detect it automatically."""
 
     UNSPECIFIED = message_pb2.RTC_SOURCE_PLAYBACK_PROFILE_UNSPECIFIED
     BOUNDED_BURST_V1 = message_pb2.RTC_SOURCE_PLAYBACK_PROFILE_BOUNDED_BURST_V1
@@ -60,14 +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
+    # Current viewers play source-timeline audio and manage entry locally.
+    # The server must explicitly acknowledge both capabilities before start.
+    # Set source_timeline_only=False for legacy/native-audio viewers.
+    source_timeline_only: bool = True
+    # None selects burst with source-only, otherwise the compatibility profile.
+    source_playback_profile: RtcSourcePlaybackProfile | None = None
 
     def __post_init__(self) -> None:
         if not isinstance(self.source_timeline_only, bool):
             raise ValueError("source_timeline_only must be a boolean")
+        if self.source_playback_profile is None:
+            self.source_playback_profile = (
+                RtcSourcePlaybackProfile.BOUNDED_BURST_V1
+                if self.source_timeline_only
+                else RtcSourcePlaybackProfile.UNSPECIFIED
+            )
         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:

spatialreal-0.4.0/spatialreal/version.py

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

spatialreal-0.3.0/spatialreal/version.py

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