Merge pull request #79 from matrix-org/module-voip

VoIP module

api/client-server/v1/voip.yaml

@@ -0,0 +1,68 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Voice over IP API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/turnServer":
+    get:
+      summary: Obtain TURN server credentials.
+      description: |-
+        This API provides credentials for the client to use when initiating
+        calls.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The TURN server credentials.
+          examples:
+            application/json: |-
+              {
+                "username":"1443779631:@user:example.com",
+                "password":"JlKfBy1QwLrO20385QyAtEyIv0=",
+                "uris":[
+                  "turn:turn.example.com:3478?transport=udp",
+                  "turn:10.20.30.40:3478?transport=tcp",
+                  "turns:10.20.30.40:443?transport=tcp"
+                ],
+                "ttl":86400
+              }
+          schema:
+            type: object
+            properties:
+              username:
+                type: string
+                description: |-
+                  The username to use.
+              password:
+                type: string
+                description: |-
+                  The password to use.
+              uris:
+                type: array
+                items:
+                  type: string
+                description: A list of TURN URIs
+              ttl:
+                type: integer
+                description: The time-to-live in seconds
+            required: ["username", "password", "uris", "ttl"]
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+

specification/1-client_server_api.rst

@@ -427,6 +427,8 @@ the complete dataset is provided in "chunk".
 Events
 ------
 
+.. _sect:events:
+
 Overview
 ~~~~~~~~
 

specification/modules/voip_events.rst

@@ -1,20 +1,26 @@
 Voice over IP
--------------
+=============
 
 .. _module:voip:
 
-Matrix can also be used to set up VoIP calls. This is part of the core
-specification, although is at a relatively early stage. Voice (and video) over
-Matrix is built on the WebRTC 1.0 standard. Call events are sent to a room, like
-any other event. This means that clients must only send call events to rooms
-with exactly two participants as currently the WebRTC standard is based around
-two-party communication.
+This module outlines how two users in a room can set up a Voice over IP (VoIP)
+call to each other. Voice and video calls are built upon the WebRTC 1.0 standard.
+Call signalling is achieved by sending `message events`_ to the room. As a result,
+this means that clients MUST only send call events to rooms with exactly two
+participants as currently the WebRTC standard is based around two-party
+communication.
+
+.. _message events: `sect:events`_
+
+Events
+------
 
 {{voip_events}}
 
-Message Exchange
-~~~~~~~~~~~~~~~~
-A call is set up with messages exchanged as follows:
+Client behaviour
+----------------
+
+A call is set up with message events exchanged as follows:
 
 ::
 
@@ -41,28 +47,55 @@ Or a rejected call:
 
 Calls are negotiated according to the WebRTC specification.
 
-
 Glare
 ~~~~~
-This specification aims to address the problem of two users calling each other
-at roughly the same time and their invites crossing on the wire. It is a far
-better experience for the users if their calls are connected if it is clear
-that their intention is to set up a call with one another. In Matrix, calls are
-to rooms rather than users (even if those rooms may only contain one other user)
-so we consider calls which are to the same room. The rules for dealing with such
-a situation are as follows:
-
- - If an invite to a room is received whilst the client is preparing to send an
-   invite to the same room, the client should cancel its outgoing call and
-   instead automatically accept the incoming call on behalf of the user.
- - If an invite to a room is received after the client has sent an invite to
-   the same room and is waiting for a response, the client should perform a
-   lexicographical comparison of the call IDs of the two calls and use the
-   lesser of the two calls, aborting the greater. If the incoming call is the
-   lesser, the client should accept this call on behalf of the user.
+
+"Glare" is a problem which occurs when two users call each other at roughly the
+same time. This results in the call failing to set up as there already is an
+incoming/outgoing call. A glare resolution algorithm can be used to determine
+which call to hangup and which call to answer. If both clients implement the
+same algorithm then they will both select the same call and the call will be
+successfully connected.
+
+
+As calls are "placed" to rooms rather than users, the glare resolution algorithm
+outlined below is only considered for calls which are to the same room. The
+algorithm is as follows:
+
+ - If an ``m.call.invite`` to a room is received whilst the client is
+   **preparing to send** an ``m.call.invite`` to the same room:
+
+    * the client should cancel its outgoing call and instead
+      automatically accept the incoming call on behalf of the user.
+
+ - If an ``m.call.invite`` to a room is received **after the client has sent**
+   an ``m.call.invite`` to the same room and is waiting for a response:
+
+    * the client should perform a lexicographical comparison of the call IDs of
+      the two calls and use the *lesser* of the two calls, aborting the
+      greater. If the incoming call is the lesser, the client should accept
+      this call on behalf of the user.
+
 
 The call setup should appear seamless to the user as if they had simply placed
-a call and the other party had accepted. Thusly, any media stream that had been
+a call and the other party had accepted. This means any media stream that had been
 setup for use on a call should be transferred and used for the call that
 replaces it.
 
+Server behaviour
+----------------
+
+The homeserver MAY provide a TURN server which clients can use to contact the
+remote party. The following HTTP API endpoints will be used by clients in order
+to get information about the TURN server.
+
+{{voip_http_api}}
+
+
+Security considerations
+-----------------------
+
+Calls should only be placed to rooms with one other user in them. If they are
+placed to group chat rooms it is possible that another user will intercept and
+answer the call.
+