feat(api): support audio fixture playback in Live sessions

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: 7ee6ff28-c1e4-4284-98f1-fa5d0c410e20
-openapi_spec_hash: e004507264375728a48a36cfa571544e
-openapi_transformed_spec_hash: bb7d73817be9bf23b859a5dfd4e15b11
-config_hash: 47b922b06d16fe0e7595c5eacbbb5495
-codegen_sha: 17b4aa72eb7729595f4446e2310cabba7a743280
-codegen_hash: 38a88497ad58fa758bb623d316d312745e2e820216e6fb5b824185a693bd9abd
-public_codegen_sha: 500f1e917e9dfac7d20c20857dc72ec1aac09686
+generation_id: 158c74da-f640-42bc-9051-dc5c15f35612
+openapi_spec_hash: e81fa0fd2133715dabef9f00a42557a9
+openapi_transformed_spec_hash: bea7a30d23deed3fc8f1c6413a38d354
+config_hash: c9c8b98008c6a5069191c1f38273d8ca
+codegen_sha: 9144bd2d5b14c91d677edca7a1757c32af1e1baa
+codegen_hash: ad31b796363b7ccd1828db887233e9f5090e1cd768c6b743a41b208ad4a447cb
+public_codegen_sha: c22f6d6207a8f4b7a456392c48c283ed71e39164

api_reference/openapi.transformed.yml

@@ -50637,6 +50637,7 @@ components:
       - $ref: '#/components/schemas/LiveInputAudioAppendEvent'
       - $ref: '#/components/schemas/LiveInputAudioMuteParam'
       - $ref: '#/components/schemas/LiveInputAudioUnmuteParam'
+      - $ref: '#/components/schemas/LiveOutputAudioFixturePlayParam'
       - $ref: '#/components/schemas/LiveInstructionsAppendParam'
       - $ref: '#/components/schemas/LiveThinkingAppendParam'
       - $ref: '#/components/schemas/LiveCommentaryAppendParam'
@@ -50694,6 +50695,7 @@ components:
       - $ref: '#/components/schemas/LiveInputAudioAppendEvent'
       - $ref: '#/components/schemas/LiveInputAudioMuteParam'
       - $ref: '#/components/schemas/LiveInputAudioUnmuteParam'
+      - $ref: '#/components/schemas/LiveOutputAudioFixturePlayParam'
       - $ref: '#/components/schemas/LiveInstructionsAppendParam'
       - $ref: '#/components/schemas/LiveThinkingAppendParam'
       - $ref: '#/components/schemas/LiveCommentaryAppendParam'
@@ -50881,13 +50883,14 @@ components:
       - session
       - transport
     LiveSidebandClientEvent:
-      description: Client events accepted by an attached Live sideband WebSocket. The session is already started; send audio over the primary connection.
+      description: Client events accepted by an attached Live sideband WebSocket. The session has already started. Send input audio over the primary connection.
       discriminator:
         propertyName: type
       anyOf:
       - $ref: '#/components/schemas/LiveSessionUpdateParam'
       - $ref: '#/components/schemas/LiveInputAudioMuteParam'
       - $ref: '#/components/schemas/LiveInputAudioUnmuteParam'
+      - $ref: '#/components/schemas/LiveOutputAudioFixturePlayParam'
       - $ref: '#/components/schemas/LiveInstructionsAppendParam'
       - $ref: '#/components/schemas/LiveThinkingAppendParam'
       - $ref: '#/components/schemas/LiveCommentaryAppendParam'
@@ -50920,6 +50923,8 @@ components:
       - $ref: '#/components/schemas/LiveSessionUpdated'
       - $ref: '#/components/schemas/LiveInputAudioMuted'
       - $ref: '#/components/schemas/LiveInputAudioUnmuted'
+      - $ref: '#/components/schemas/LiveOutputAudioFixturePlaying'
+      - $ref: '#/components/schemas/LiveOutputAudioFixturePlayed'
       - $ref: '#/components/schemas/LiveInstructionsAppended'
       - $ref: '#/components/schemas/LiveThinkingAppended'
       - $ref: '#/components/schemas/LiveCommentaryAppended'
@@ -92107,6 +92112,39 @@ components:
         example:
           type: session.input_audio.unmute
           event_id: evt_unmute_001
+    LiveOutputAudioFixturePlayParam:
+      description: Play one complete audio fixture through the session output. Send this event over the primary WebSocket or a server sideband. Audio must be raw mono PCM16 little-endian at 24 kHz, regardless of the session audio format, and at most 30 seconds. The entire payload is validated before model speech is interrupted and input is muted. Only one fixture can be active. fixture.playing acknowledges acceptance and fixture.played reports server mixer drain. These notifications are not exact transport-media boundaries. Input arriving during playback is dropped and not replayed.
+      example:
+        type: session.output_audio.fixture.play
+        event_id: evt_play_001
+        audio: AAAAAA==
+      type: object
+      properties:
+        event_id:
+          anyOf:
+          - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id.
+            type: string
+            maxLength: 512
+          - type: 'null'
+        type:
+          default: session.output_audio.fixture.play
+          x-stainless-const: true
+          type: string
+          enum:
+          - session.output_audio.fixture.play
+        audio:
+          description: Base64-encoded raw mono PCM16 audio, little-endian, at 24 kHz. Do not include a WAV or other container header.
+          type: string
+          minLength: 1
+          maxLength: 1920000
+      required:
+      - type
+      - audio
+      x-oaiMeta:
+        example:
+          type: session.output_audio.fixture.play
+          event_id: evt_play_001
+          audio: AAAAAA==
     LiveInstructionsAppendParam:
       description: Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation.
       example:
@@ -92624,6 +92662,62 @@ components:
           type: session.input_audio.unmuted
           event_id: evt_unmuted_001
           client_event_id: evt_unmute_001
+    LiveOutputAudioFixturePlaying:
+      description: The existing playback path has accepted the validated audio fixture. This acknowledgment does not identify when the listener receives the first sample. The optional client_event_id echoes the play command.
+      example:
+        type: session.output_audio.fixture.playing
+        event_id: evt_playing_001
+        client_event_id: evt_play_001
+      type: object
+      properties:
+        event_id:
+          description: The unique ID of the Live server event.
+          type: string
+        client_event_id:
+          description: The event_id of the client command associated with this server event, when supplied.
+          type: string
+        type:
+          default: session.output_audio.fixture.playing
+          x-stainless-const: true
+          type: string
+          enum:
+          - session.output_audio.fixture.playing
+      required:
+      - event_id
+      - type
+      x-oaiMeta:
+        example:
+          type: session.output_audio.fixture.playing
+          event_id: evt_playing_001
+          client_event_id: evt_play_001
+    LiveOutputAudioFixturePlayed:
+      description: The complete audio fixture has drained from the server mixer and normal inference has resumed. Transport buffers may still contain audio; this event does not prove listener-side completion. The optional client_event_id echoes the play command. This event is not emitted for canceled or failed playback.
+      example:
+        type: session.output_audio.fixture.played
+        event_id: evt_played_001
+        client_event_id: evt_play_001
+      type: object
+      properties:
+        event_id:
+          description: The unique ID of the Live server event.
+          type: string
+        client_event_id:
+          description: The event_id of the client command associated with this server event, when supplied.
+          type: string
+        type:
+          default: session.output_audio.fixture.played
+          x-stainless-const: true
+          type: string
+          enum:
+          - session.output_audio.fixture.played
+      required:
+      - event_id
+      - type
+      x-oaiMeta:
+        example:
+          type: session.output_audio.fixture.played
+          event_id: evt_played_001
+          client_event_id: evt_play_001
     LiveInstructionsAppended:
       description: Returned when a session.instructions.append command is accepted into the Live session timeline. Acknowledges the appended instructions without guaranteeing that the model has acted on them.
       example:
@@ -93487,6 +93581,8 @@ components:
       - $ref: '#/components/schemas/LiveSessionUpdated'
       - $ref: '#/components/schemas/LiveInputAudioMuted'
       - $ref: '#/components/schemas/LiveInputAudioUnmuted'
+      - $ref: '#/components/schemas/LiveOutputAudioFixturePlaying'
+      - $ref: '#/components/schemas/LiveOutputAudioFixturePlayed'
       - $ref: '#/components/schemas/LiveInstructionsAppended'
       - $ref: '#/components/schemas/LiveThinkingAppended'
       - $ref: '#/components/schemas/LiveCommentaryAppended'
@@ -107960,6 +108056,9 @@ x-oaiMeta:
     - type: object
       key: LiveInputAudioUnmuteParam
       path: <auto>
+    - type: object
+      key: LiveOutputAudioFixturePlayParam
+      path: <auto>
     - type: object
       key: LiveInstructionsAppendParam
       path: <auto>
@@ -108004,6 +108103,12 @@ x-oaiMeta:
     - type: object
       key: LiveInputAudioUnmuted
       path: <auto>
+    - type: object
+      key: LiveOutputAudioFixturePlaying
+      path: <auto>
+    - type: object
+      key: LiveOutputAudioFixturePlayed
+      path: <auto>
     - type: object
       key: LiveInstructionsAppended
       path: <auto>

src/openai/_constants.py

@@ -7,6 +7,8 @@
 DEFAULT_TIMEOUT = httpx2.Timeout(timeout=600, connect=5.0)
 DEFAULT_MAX_RETRIES = 2
 DEFAULT_CONNECTION_LIMITS = httpx2.Limits(max_connections=1000, max_keepalive_connections=100)
+# A 30-second Live PCM16 fixture takes 1,920,000 base64 bytes before its JSON envelope.
+DEFAULT_LIVE_SEND_QUEUE_MAX_BYTES = 2_097_152
 
 INITIAL_RETRY_DELAY = 0.5
 MAX_RETRY_DELAY = 8.0

src/openai/resources/live/api.md

@@ -32,6 +32,9 @@ from openai.types.live import (
     MediaSessionConfigParam,
     MediaSessionForkConfigParam,
     OutputAudioDeltaEvent,
+    OutputAudioFixturePlayEvent,
+    OutputAudioFixturePlayedEvent,
+    OutputAudioFixturePlayingEvent,
     OutputTranscriptDeltaEvent,
     ResponseCreateEvent,
     ResponseEvent,

src/openai/resources/live/forks.py

@@ -16,6 +16,7 @@
 from ..._compat import cached_property
 from ..._models import FinalRequestOptions, construct_type_unchecked
 from ..._resource import SyncAPIResource, AsyncAPIResource
+from ..._constants import DEFAULT_LIVE_SEND_QUEUE_MAX_BYTES
 from ..._exceptions import OpenAIError, WebSocketConnectionClosedError
 from ..._send_queue import SendQueue
 from ..._base_client import _merge_mappings
@@ -54,7 +55,7 @@ def connect(
         max_retries: int = 5,
         initial_delay: float = 0.5,
         max_delay: float = 8.0,
-        max_queue_size: int = 1_048_576,
+        max_queue_size: int = DEFAULT_LIVE_SEND_QUEUE_MAX_BYTES,
     ) -> ForksConnectionManager:
         """Fork a stored Live session over WebSocket.
 
@@ -86,7 +87,7 @@ def connect(
         max_retries: int = 5,
         initial_delay: float = 0.5,
         max_delay: float = 8.0,
-        max_queue_size: int = 1_048_576,
+        max_queue_size: int = DEFAULT_LIVE_SEND_QUEUE_MAX_BYTES,
     ) -> AsyncForksConnectionManager:
         """Fork a stored Live session over WebSocket.
 
@@ -136,7 +137,9 @@ def __init__(
             max_delay=max_delay,
             extra_query=extra_query,
             extra_headers=extra_headers,
-            send_queue=send_queue,
+            send_queue=(
+                send_queue if send_queue is not None else SendQueue(max_bytes=DEFAULT_LIVE_SEND_QUEUE_MAX_BYTES)
+            ),
             logger=log,
         )
         self._event_handler_registry = EventHandlerRegistry(use_lock=False)
@@ -337,7 +340,7 @@ def __init__(
         max_retries: int = 5,
         initial_delay: float = 0.5,
         max_delay: float = 8.0,
-        max_queue_size: int = 1_048_576,
+        max_queue_size: int = DEFAULT_LIVE_SEND_QUEUE_MAX_BYTES,
     ) -> None:
         self.__client = client
         self.__session_id = session_id
@@ -532,7 +535,9 @@ def __init__(
             max_delay=max_delay,
             extra_query=extra_query,
             extra_headers=extra_headers,
-            send_queue=send_queue,
+            send_queue=(
+                send_queue if send_queue is not None else SendQueue(max_bytes=DEFAULT_LIVE_SEND_QUEUE_MAX_BYTES)
+            ),
             logger=log,
         )
         self._event_handler_registry = EventHandlerRegistry(use_lock=True)
@@ -727,7 +732,7 @@ def __init__(
         max_retries: int = 5,
         initial_delay: float = 0.5,
         max_delay: float = 8.0,
-        max_queue_size: int = 1_048_576,
+        max_queue_size: int = DEFAULT_LIVE_SEND_QUEUE_MAX_BYTES,
     ) -> None:
         self.__client = client
         self.__session_id = session_id
@@ -910,6 +915,10 @@ def input_audio(self) -> ForksSessionInputAudioResource:
     def instructions(self) -> ForksSessionInstructionsResource:
         return ForksSessionInstructionsResource(self._connection)
 
+    @cached_property
+    def output_audio(self) -> ForksSessionOutputAudioResource:
+        return ForksSessionOutputAudioResource(self._connection)
+
     @cached_property
     def thinking(self) -> ForksSessionThinkingResource:
         return ForksSessionThinkingResource(self._connection)
@@ -1021,6 +1030,12 @@ def append(self, *, content: str, delegation_id: Optional[str], event_id: Option
         )
 
 
+class ForksSessionOutputAudioResource(BaseForksConnectionResource):
+    @cached_property
+    def fixture(self) -> ForksSessionOutputAudioFixtureResource:
+        return ForksSessionOutputAudioFixtureResource(self._connection)
+
+
 class ForksSessionThinkingResource(BaseForksConnectionResource):
     def append(self, *, content: str, delegation_id: Optional[str], event_id: Optional[str] | Omit = omit) -> None:
         """
@@ -1041,6 +1056,20 @@ def append(self, *, content: str, delegation_id: Optional[str], event_id: Option
         )
 
 
+class ForksSessionOutputAudioFixtureResource(BaseForksConnectionResource):
+    def play(self, *, audio: str, event_id: Optional[str] | Omit = omit) -> None:
+        """Play one complete audio fixture through the session output.
+
+        Send this event over the primary WebSocket or a server sideband. Audio must be raw mono PCM16 little-endian at 24 kHz, regardless of the session audio format, and at most 30 seconds. The entire payload is validated before model speech is interrupted and input is muted. Only one fixture can be active. fixture.playing acknowledges acceptance and fixture.played reports server mixer drain. These notifications are not exact transport-media boundaries. Input arriving during playback is dropped and not replayed.
+        """
+        self._connection.send(
+            cast(
+                ForkClientEventParam,
+                strip_not_given({"type": "session.output_audio.fixture.play", "audio": audio, "event_id": event_id}),
+            )
+        )
+
+
 class ForksResponseResource(BaseForksConnectionResource):
     @cached_property
     def item(self) -> ForksResponseItemResource:
@@ -1090,6 +1119,10 @@ def input_audio(self) -> AsyncForksSessionInputAudioResource:
     def instructions(self) -> AsyncForksSessionInstructionsResource:
         return AsyncForksSessionInstructionsResource(self._connection)
 
+    @cached_property
+    def output_audio(self) -> AsyncForksSessionOutputAudioResource:
+        return AsyncForksSessionOutputAudioResource(self._connection)
+
     @cached_property
     def thinking(self) -> AsyncForksSessionThinkingResource:
         return AsyncForksSessionThinkingResource(self._connection)
@@ -1205,6 +1238,12 @@ async def append(
         )
 
 
+class AsyncForksSessionOutputAudioResource(BaseAsyncForksConnectionResource):
+    @cached_property
+    def fixture(self) -> AsyncForksSessionOutputAudioFixtureResource:
+        return AsyncForksSessionOutputAudioFixtureResource(self._connection)
+
+
 class AsyncForksSessionThinkingResource(BaseAsyncForksConnectionResource):
     async def append(
         self, *, content: str, delegation_id: Optional[str], event_id: Optional[str] | Omit = omit
@@ -1227,6 +1266,20 @@ async def append(
         )
 
 
+class AsyncForksSessionOutputAudioFixtureResource(BaseAsyncForksConnectionResource):
+    async def play(self, *, audio: str, event_id: Optional[str] | Omit = omit) -> None:
+        """Play one complete audio fixture through the session output.
+
+        Send this event over the primary WebSocket or a server sideband. Audio must be raw mono PCM16 little-endian at 24 kHz, regardless of the session audio format, and at most 30 seconds. The entire payload is validated before model speech is interrupted and input is muted. Only one fixture can be active. fixture.playing acknowledges acceptance and fixture.played reports server mixer drain. These notifications are not exact transport-media boundaries. Input arriving during playback is dropped and not replayed.
+        """
+        await self._connection.send(
+            cast(
+                ForkClientEventParam,
+                strip_not_given({"type": "session.output_audio.fixture.play", "audio": audio, "event_id": event_id}),
+            )
+        )
+
+
 class AsyncForksResponseResource(BaseAsyncForksConnectionResource):
     @cached_property
     def item(self) -> AsyncForksResponseItemResource: