Package org.mockserver.llm.realtime

Class OpenAiRealtimeCodec

java.lang.Object
org.mockserver.llm.realtime.OpenAiRealtimeCodec
public final class OpenAiRealtimeCodec extends Object
Pure event codec for the OpenAI Realtime API (GA 2025 event protocol), spoken over a WebSocket at wss://api.openai.com/v1/realtime. It hand-assembles the provider-correct server event JSON frames a client receives, so an application using the Realtime SDK can be tested fully offline. Every user-supplied string is routed through JsonEscape.escape(String) before embedding.

Event coverage. The codec produces, for one response.create, the GA event lifecycle: response.created → response.output_item.added → response.content_part.added → (per token) response.output_audio_transcript.delta + response.output_audio.delta (audio modality) or response.output_text.delta (text modality) → response.output_audio_transcript.done/response.output_text.done → response.output_audio.done (audio) → response.content_part.done → response.output_item.done → response.done (with usage). It also produces the connect-time session.created, and the session.updated / conversation.item.created acknowledgements.

Deferred protocol corners (documented rather than half-implemented, see docs/code/ai-protocol-mocking.md): server-side VAD / input-audio-buffer events (input_audio_buffer.speech_started etc.), input-audio transcription events, function-call output items, rate_limits.updated, and error frames. The audio bytes are opaque silence placeholders — the fidelity target is the event protocol, not audio DSP.

  • Method Details

    • sessionCreated

      public static String sessionCreated(String model, String sessionId)
      The session.created frame a Realtime server sends immediately after the WebSocket handshake.

    • sessionUpdated

      public static String sessionUpdated(String model, String sessionId)
      The session.updated acknowledgement returned in response to a client session.update.

    • conversationItemCreated

      public static String conversationItemCreated(String itemId)
      The conversation.item.created acknowledgement returned in response to a client conversation.item.create.

    • responseSequence

      public static List<RealtimeEvent> responseSequence(RealtimeTurn turn, RealtimeModality modality, RealtimeStreamingPhysics physics)
      The full ordered server event sequence emitted for a single response.create.
      Parameters:
      turn - the scripted assistant response
      modality - RealtimeModality.AUDIO (transcript + audio deltas) or RealtimeModality.TEXT
      physics - streaming timing (per-delta delay, time-to-first-token)
      Returns:
      ordered event frames with per-frame delays