Add support for muting in VoIP calls

changelogs/client_server/newsfragments/1755.clarification

@@ -0,0 +1 @@
+Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291).

content/client-server-api/modules/voip_events.md

@@ -174,16 +174,34 @@ In response to an incoming invite, a client may do one of several things:
 Clients may send more than one stream in a VoIP call. The streams should be
 differentiated by including metadata in the [`m.call.invite`](/client-server-api/#mcallinvite),
 [`m.call.answer`](/client-server-api/#mcallanswer) and [`m.call.negotiate`](/client-server-api/#mcallnegotiate)
-events, using the `sdp_stream_metadata` property.
+events, using the `sdp_stream_metadata` property. An [`m.call.sdp_stream_metadata_changed`](/client-server-api/#mcallsdp_stream_metadata_changed)
+event can be sent when the metadata changes but no negotiation is required.
 
 `sdp_stream_metadata` maps from the `id` of a stream in the session description, 
-to metadata about that stream. Currently only one property is defined for the
-metadata. This is `purpose`, which should be a string indicating the purpose of
-the stream. The following `purpose`s are defined:
+to metadata about that stream. Currently three properties are defined for the
+metadata: `purpose`, `audio_muted` and `video_muted`.
+
+`purpose` should be a string indicating the purpose of the stream. The following
+`purpose`s are defined:
 
 *  `m.usermedia` - stream that contains the webcam and/or microphone tracks
 *  `m.screenshare` - stream with the screen-sharing tracks
 
+`audio_muted` and `video_muted` are booleans that indicate whether the audio and
+video tracks in the stream are muted, respectively. All tracks should be assumed
+unmuted unless specified otherwise.
+
+Clients are recommended to not mute the audio of WebRTC tracks locally when an
+incoming stream has the `audio_muted` field set to `true`. This is because when
+the other user unmutes themselves, there may be a slight delay between their
+client sending audio and the [`m.call.sdp_stream_metadata_changed`](/client-server-api/#mcallsdp_stream_metadata_changed)
+event arriving and any audio sent in between will not be heard. The other user
+will still stop transmitting audio once they mute on their side, so no audio is
+sent without the user's knowledge.
+
+The same suggestion does not apply to `video_muted`. Clients _should_ mute video
+locally, so that the receiving side doesn't see a black video.
+
 If `sdp_stream_metadata` is present and an incoming stream is not listed in it,
 the stream should be ignored. If a stream has a `purpose` of an unknown type, it
 should also be ignored.

data/event-schemas/examples/m.call.sdp_stream_metadata_changed.yaml

@@ -0,0 +1,16 @@
+{
+  "$ref": "core/room_event.json",
+  "type": "m.call.sdp_stream_metadata_changed",
+  "content": {
+    "version": "1",
+    "call_id": "1414213562373095",
+    "party_id": "1732050807568877",
+    "sdp_stream_metadata": {
+        "2311546231": {
+            "purpose": "m.usermedia",
+            "audio_muted:": true,
+            "video_muted": true
+        }
+    }
+  }
+}

data/event-schemas/schema/components/sdp_stream_metadata.yaml

@@ -13,8 +13,8 @@ additionalProperties:
     purpose:
       type: string
       enum:
-        - m.usermedia
-        - m.screenshare
+      - m.usermedia
+      - m.screenshare
       description: |-
         The purpose of the stream.
 
@@ -23,5 +23,17 @@ additionalProperties:
         * `m.usermedia`: Stream that contains the webcam and/or microphone
           tracks.
         * `m.screenshare`: Stream with the screen-sharing tracks.
+    audio_muted:
+      type: boolean
+      description: |-
+        Whether the audio track in the stream is muted.
+
+        Defaults to `false` if not present.
+    video_muted:
+      type: boolean
+      description: |-
+        Whether the video track in the stream is muted.
+
+        Defaults to `false` if not present.
   required:
-    - purpose
+  - purpose

data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml

@@ -0,0 +1,21 @@
+type: object
+x-addedInMatrixVersion: "1.10"
+description: |-
+  This event is sent by callers when they wish to update a stream's metadata
+  but no negotiation is required.
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+properties:
+  content:
+    type: object
+    allOf:
+    - $ref: core-event-schema/call_event.yaml
+    properties:
+      sdp_stream_metadata:
+        $ref: components/sdp_stream_metadata.yaml
+    required:
+    - sdp_stream_metadata
+  type:
+    type: string
+    enum:
+    - m.call.sdp_stream_metadata_changed