README
¶
realtime
Framework-independent WebSocket abstraction for OpenAI-compatible Realtime API sessions. Bridges a client WebSocket connection with an upstream provider WebSocket, forwarding events bidirectionally while accumulating usage metrics.
Key Types
Conn-- minimal WebSocket connection interface (ReadMessage,WriteMessage,Close). Satisfied by*gorilla/websocket.Conn.Connector-- interface for dialing an upstream realtime WebSocket. Implementations are provider-specific.SessionConfig-- parameters for opening a session (model, voice, instructions, modalities, audio formats, tools, API key, base URL).Session-- bridges a client and upstream connection, accumulates usage, and optionally records to ameter.Meter.OpenAIConnector--Connectorimplementation for the OpenAI Realtime API.
Usage
session := realtime.NewSession(clientConn, realtime.SessionConfig{
Model: "gpt-4o-realtime-preview",
Modalities: []string{"text", "audio"},
InputAudioFormat: "pcm16",
OutputAudioFormat: "pcm16",
APIKey: apiKey,
})
session.SetMeter(meter.NewMemoryMeter(), "openai")
connector := realtime.NewOpenAIConnector(apiKey, "gpt-4o-realtime-preview")
if err := session.Connect(ctx, connector); err != nil {
log.Printf("session ended: %v", err)
}
fmt.Printf("Usage: %+v\n", session.Usage())
Documentation
¶
Overview ¶
Package realtime provides a framework-independent WebSocket abstraction for OpenAI-compatible Realtime API sessions.
It bridges a client WebSocket connection with an upstream provider WebSocket, forwarding events bidirectionally while accumulating usage/token metrics. The design avoids any HTTP framework coupling: callers supply a `Conn`-compatible WebSocket and a `Connector` that knows how to dial the upstream provider.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Conn ¶
type Conn interface {
// ReadMessage returns the next message from the peer.
ReadMessage() (messageType int, p []byte, err error)
// WriteMessage writes a message to the peer.
WriteMessage(messageType int, data []byte) error
// Close closes the connection.
Close() error
}
Conn is the minimal WebSocket connection interface used by the bridge. It is satisfied by *gorilla/websocket.Conn and by test doubles.
type Connector ¶
type Connector interface {
// Dial connects to the upstream realtime endpoint and returns the
// upstream Conn. The returned Conn must be closed by the caller.
Dial(ctx context.Context, session *Session) (Conn, error)
}
Connector dials an upstream realtime WebSocket for a given session. Implementations are provider-specific (OpenAI, Azure, etc.).
type OpenAIConnector ¶
type OpenAIConnector struct {
// BaseURL is the WebSocket endpoint, e.g. "wss://api.openai.com/v1/realtime".
// If empty, defaults to the public OpenAI endpoint.
BaseURL string
// APIKey is the OpenAI API key.
APIKey string
// Model is the realtime model to connect to (e.g. "gpt-4o-realtime-preview").
// If non-empty, it is appended as a query parameter.
Model string
}
OpenAIConnector dials the OpenAI Realtime API over WebSocket.
func NewOpenAIConnector ¶
func NewOpenAIConnector(apiKey, model string) *OpenAIConnector
NewOpenAIConnector creates a connector for the OpenAI Realtime API.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a realtime session bridging a client and upstream connection.
func NewSession ¶
func NewSession(client Conn, cfg SessionConfig) *Session
NewSession creates a new realtime session. The client Conn must already be accepted/upgraded by the caller.
func (*Session) Config ¶
func (s *Session) Config() SessionConfig
Config returns the session configuration.
func (*Session) Connect ¶
Connect dials the upstream provider using the supplied Connector and begins bridging messages bidirectionally. It blocks until either side closes or the context is cancelled.
func (*Session) SetMeter ¶
SetMeter attaches a usage meter. If set, usage events are recorded on close.
func (*Session) Usage ¶
func (s *Session) Usage() dto.RealtimeUsage
Usage returns the accumulated upstream usage so far.
type SessionConfig ¶
type SessionConfig struct {
// Model is the upstream realtime model name (e.g. "gpt-4o-realtime-preview").
Model string
// Voice is the voice to use for output (optional, provider-specific).
Voice string
// Instructions is the system instruction for the session (optional).
Instructions string
// Modalities is the list of modalities (e.g. ["text","audio"]).
Modalities []string
// InputAudioFormat / OutputAudioFormat are codec names (e.g. "pcm16").
InputAudioFormat string
OutputAudioFormat string
// Temperature is the sampling temperature (optional).
Temperature *float64
// Tools is the list of tools the model may call.
Tools []dto.RealTimeTool
// APIKey is the upstream API key.
APIKey string
// BaseURL is the upstream WebSocket base URL (e.g. "wss://api.openai.com/v1/realtime").
BaseURL string
}
SessionConfig carries the parameters needed to open a realtime session.
Source Files