diff --git a/changelogs/client_server/newsfragments/1755.clarification b/changelogs/client_server/newsfragments/1755.clarification new file mode 100644 index 00000000..65c5ba36 --- /dev/null +++ b/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). diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index 4df0ba13..c45a4824 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -174,15 +174,19 @@ 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. - -`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: - -* `m.usermedia` - stream that contains the webcam and/or microphone tracks -* `m.screenshare` - stream with the screen-sharing tracks +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. + +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 diff --git a/data/event-schemas/examples/m.call.sdp_stream_metadata_changed.yaml b/data/event-schemas/examples/m.call.sdp_stream_metadata_changed.yaml new file mode 100644 index 00000000..43b4fd75 --- /dev/null +++ b/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 + } + } + } +} diff --git a/data/event-schemas/schema/components/sdp_stream_metadata.yaml b/data/event-schemas/schema/components/sdp_stream_metadata.yaml index f16b4cbd..35566abe 100644 --- a/data/event-schemas/schema/components/sdp_stream_metadata.yaml +++ b/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,19 @@ 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. + x-addedInMatrixVersion: "1.11" + video_muted: + type: boolean + description: |- + Whether the video track in the stream is muted. + + Defaults to `false` if not present. + x-addedInMatrixVersion: "1.11" required: - - purpose + - purpose diff --git a/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml b/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml new file mode 100644 index 00000000..953817c2 --- /dev/null +++ b/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml @@ -0,0 +1,21 @@ +type: object +x-addedInMatrixVersion: "1.11" +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