webrtc/signalling/Protocol.md

   1 ## Terminology
   2
   3 ### Client
   4
   5 A GStreamer-based application
   6
   7 ### Browser
   8
   9 A JS application that runs in the browser and uses built-in browser webrtc APIs
  10
  11 ### Peer
  12
  13 Any webrtc-using application that can participate in a call
  14
  15 ### Signalling server
  16
  17 Basic websockets server implemented in Python that manages the peers list and shovels data between peers
  18
  19 ## Overview
  20
  21 This is a basic protocol for doing 1-1 audio+video calls between a gstreamer app and a JS app in a browser.
  22
  23 ## Peer registration
  24
  25 Peers must register with the signalling server before a call can be initiated. The server connection should stay open as long as the peer is available or in a call.
  26
  27 This protocol builds upon https://github.com/shanet/WebRTC-Example/
  28
  29 * Connect to the websocket server
  30 * Send `HELLO <uid>` where `<uid>` is a string which will uniquely identify this peer
  31 * Receive `HELLO`
  32 * Any other message starting with `ERROR` is an error.
  33
  34 ### 1-1 calls with a 'session'
  35
  36 * To connect to a single peer, send `SESSION <uid>` where `<uid>` identifies the peer to connect to, and receive `SESSION_OK`
  37 * All further messages will be forwarded to the peer
  38 * The call negotiation with the peer can be started by sending JSON encoded SDP (the offer) and ICE
  39 * You can also ask the peer to send the SDP offer and begin sending ICE candidates. After `SESSION_OK` if you send `OFFER_REQUEST`, the peer will take over. (NEW in 1.19, not all clients support this)
  40
  41 * Closure of the server connection means the call has ended; either because the other peer ended it or went away
  42 * To end the call, disconnect from the server. You may reconnect again whenever you wish.
  43
  44 ### Multi-party calls with a 'room'
  45
  46 * To create a multi-party call, you must first register (or join) a room. Send `ROOM <room_id>` where `<room_id>` is a unique room name
  47 * Receive `ROOM_OK ` from the server if this is a new room, or `ROOM_OK <peer1_id> <peer2_id> ...` where `<peerN_id>` are unique identifiers for the peers already in the room
  48 * To send messages to a specific peer within the room for call negotiation (or any other purpose, use `ROOM_PEER_MSG <peer_id> <msg>`
  49 * When a new peer joins the room, you will receive a `ROOM_PEER_JOINED <peer_id>` message
  50  - For the purposes of convention and to avoid overwhelming newly-joined peers, offers must only be sent by the newly-joined peer
  51 * When a peer leaves the room, you will receive a `ROOM_PEER_LEFT <peer_id>` message
  52   - You should stop sending/receiving media from/to this peer
  53 * To get a list of all peers currently in the room, send `ROOM_PEER_LIST` and receive `ROOM_PEER_LIST <peer1_id> ...`
  54   - This list will never contain your own `<uid>`
  55   - In theory you should never need to use this since you are guaranteed to receive JOINED and LEFT messages for all peers in a room
  56 * You may stay connected to a room for as long as you like
  57
  58 ## Negotiation
  59
  60 Once a call has been setup with the signalling server, the peers must negotiate SDP and ICE candidates with each other.
  61
  62 The calling side must create an SDP offer and send it to the peer as a JSON object:
  63
  64 ```json
  65 {
  66     "sdp": {
  67                 "sdp": "o=- [....]",
  68                 "type": "offer"
  69     }
  70 }
  71 ```
  72
  73 The callee must then reply with an answer:
  74
  75 ```json
  76 {
  77     "sdp": {
  78                 "sdp": "o=- [....]",
  79                 "type": "answer"
  80     }
  81 }
  82 ```
  83
  84 ICE candidates must be exchanged similarly by exchanging JSON objects:
  85
  86
  87 ```json
  88 {
  89     "ice": {
  90                 "candidate": ...,
  91                 "sdpMLineIndex": ...,
  92                 ...
  93     }
  94 }
  95 ```
  96
  97 Note that the structure of these is the same as that specified by the WebRTC spec.