Skip to main content

Event Structures

The ODIN Core SDK communicates key state changes and events through RPC (Remote Procedure Calls). These events are delivered to your application via the on_rpc callback in the OdinConnectionPoolSettings (see Quick Start).

The payload of these RPCs is encoded using MessagePack, which deserializes into a JSON-compatible structure. This page describes the JSON schema for the various events you will encounter.

Overview​

All RPC events are delivered as a variant structure capable of representing different event types. The top-level structure typically differentiates between:

  • Command Responses: Results of commands you sent.
  • Room Updates: Changes to the room state (joins, leaves).
  • Peer Updates: Changes to other peers (media start/stop).
  • Message Received: Arbitrary data sent by other peers.
  • Room Status Changed: Connection health updates.

Basic Structures​

Media​

Represents a media stream (audio/video).

{
  "id": "integer (uint16)",
  "properties": "object (arbitrary JSON)",
  "paused": "boolean"
}

Peer​

Represents a user connected to the room.

{
  "id": "integer (uint64)",
  "user_id": "string",
  "user_data": "binary (byte array)",
  "medias": "array of Media",
  "tags": "array of strings"
}

Room​

Represents the room itself.

{
  "id": "string",
  "customer": "string",
  "user_data": "binary (byte array)",
  "peers": "array of Peer"
}

Room Updates​

These events are grouped under the RoomUpdated category.

Joined​

Emitted when you successfully join a room and initial state is processed.

{
  "kind": "Joined",
  "room": "Room Object",
  "media_ids": "array of integers (uint16)",
  "own_peer_id": "integer (uint64)"
}

UserDataChanged (Room)​

Emitted when the global room user data is updated.

{
  "kind": "UserDataChanged",
  "user_data": "binary (byte array)"
}

Left​

Emitted after being removed from a room (e.g., kicked or connection lost).

{
  "kind": "Left",
  "reason": "string"
}

PeerJoined​

Emitted when another peer joins the room.

{
  "kind": "PeerJoined",
  "peer": "Peer Object"
}

PeerLeft​

Emitted when a peer leaves the room.

{
  "kind": "PeerLeft",
  "peer_id": "integer (uint64)"
}

Peer Updates​

These events are grouped under the PeerUpdated category and relate to specific peers.

UserDataChanged (Peer)​

Emitted when a peer updates their user data.

{
  "kind": "UserDataChanged",
  "peer_id": "integer (uint64)",
  "user_data": "binary (byte array)"
}

MediaStarted​

Emitted when a peer starts a media stream (e.g., starts audio).

{
  "kind": "MediaStarted",
  "peer_id": "integer (uint64)",
  "media": "Media Object",
  "properties": "object (deprecated)"
}

MediaStopped​

Emitted when a peer stops a media stream.

{
  "kind": "MediaStopped",
  "peer_id": "integer (uint64)",
  "media_id": "integer (uint16)"
}

TagsChanged​

Emitted when a peer's tags are updated.

{
  "kind": "TagsChanged",
  "peer_id": "integer (uint64)",
  "tags": "array of strings"
}

Other Events​

MessageReceived​

Emitted when an arbitrary message is received from a peer.

{
  "sender_peer_id": "integer (uint64)",
  "message": "binary (byte array)"
}

RoomStatusChanged​

Emitted when the underlying connection status changes (e.g., "Connecting", "Online", "Offline").

{
  "status": "string",
  "message": "string (optional)"
}

Client Commands (RPC)​

You can also send commands to the server via RPC.

UpdatePeer​

Update your own user data.

{
  "user_data": "binary (byte array)"
}

UpdatePosition​

Update your position in 3D space (for proximity chat).

{
  "coordinates": "array of floats [x, y, z]"
}

Media Signaling​

Control your media streams.

  • StartMedia: { "media_id": uint16, "properties": object }
  • StopMedia: { "media_id": uint16 }
  • PauseMedia: { "media_id": uint16 }
  • ResumeMedia: { "media_id": uint16 }

SendMessage​

Send arbitrary data to other peers.

{
  "message": "binary (byte array)",
  "target_peer_ids": "array of uint64 (optional)"
}