From 38f70f3871cdc85417428d2b3285455eefbff14d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 5 Mar 2024 18:08:20 +0100 Subject: [PATCH 1/4] Convert m.call.candidates schema to YAML MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../schema/m.call.candidates.yaml | 85 +++++++++---------- 1 file changed, 40 insertions(+), 45 deletions(-) diff --git a/data/event-schemas/schema/m.call.candidates.yaml b/data/event-schemas/schema/m.call.candidates.yaml index 6aa162296..62df3fb55 100644 --- a/data/event-schemas/schema/m.call.candidates.yaml +++ b/data/event-schemas/schema/m.call.candidates.yaml @@ -1,45 +1,40 @@ -{ - "type": "object", - "description": "This event is sent by callers after sending an invite and by the callee after answering. Its purpose is to give the other party additional ICE candidates to try using to communicate.", - "allOf": [{ - "$ref": "core-event-schema/room_event.yaml" - }], - "properties": { - "content": { - "type": "object", - "allOf": [{ - "$ref": "core-event-schema/call_event.yaml" - }], - "properties": { - "candidates": { - "type": "array", - "description": "Array of objects describing the candidates.", - "items": { - "type": "object", - "title": "Candidate", - "properties": { - "sdpMid": { - "type": "string", - "description": "The SDP media type this candidate is intended for." - }, - "sdpMLineIndex": { - "type": "number", - "description": "The index of the SDP 'm' line this candidate is intended for." - }, - "candidate": { - "type": "string", - "description": "The SDP 'a' line of the candidate." - } - }, - "required": ["candidate", "sdpMLineIndex", "sdpMid"] - } - } - }, - "required": ["candidates"] - }, - "type": { - "type": "string", - "enum": ["m.call.candidates"] - } - } -} +type: object +description: |- + This event is sent by callers after sending an invite and by the callee after + answering. Its purpose is to give the other party additional ICE candidates to + try using to communicate. +allOf: + - $ref: core-event-schema/room_event.yaml +properties: + content: + type: object + allOf: + - $ref: core-event-schema/call_event.yaml + properties: + candidates: + type: array + description: Array of objects describing the candidates. + items: + type: object + title: Candidate + properties: + sdpMid: + type: string + description: The SDP media type this candidate is intended for. + sdpMLineIndex: + type: number + description: The index of the SDP 'm' line this candidate is intended + for. + candidate: + type: string + description: The SDP 'a' line of the candidate. + required: + - candidate + - sdpMLineIndex + - sdpMid + required: + - candidates + type: + type: string + enum: + - m.call.candidates \ No newline at end of file From 7633d2c29964fde72dd0b562ea06598dd3ace969 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 5 Mar 2024 18:25:30 +0100 Subject: [PATCH 2/4] Clarify that sdpMid and sdpMLineIndex are not required in `m.call.candidates` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit MSC2746, merged in v1.17, introduced the end-of-candidates candidate, where only the `candidate` property is set to an empty string. Besides, the [WebRTC specification](https://www.w3.org/TR/webrtc/) says that only one of those fields is required in a normal candidate. Signed-off-by: Kévin Commaille --- .../schema/m.call.candidates.yaml | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/data/event-schemas/schema/m.call.candidates.yaml b/data/event-schemas/schema/m.call.candidates.yaml index 62df3fb55..c2961f1a5 100644 --- a/data/event-schemas/schema/m.call.candidates.yaml +++ b/data/event-schemas/schema/m.call.candidates.yaml @@ -20,18 +20,26 @@ properties: properties: sdpMid: type: string - description: The SDP media type this candidate is intended for. + description: |- + The SDP media type this candidate is intended for. + + At least one of `sdpMid` or `sdpMLineIndex` is required, unless + this an end-of-candidates candidate. sdpMLineIndex: type: number - description: The index of the SDP 'm' line this candidate is intended - for. + description: |- + The index of the SDP 'm' line this candidate is intended for. + + At least one of `sdpMid` or `sdpMLineIndex` is required, unless + this an end-of-candidates candidate. candidate: type: string - description: The SDP 'a' line of the candidate. + description: |- + The SDP 'a' line of the candidate. + + If this is an end-of-candidates candidate, this is empty. required: - candidate - - sdpMLineIndex - - sdpMid required: - candidates type: From 561767a5fd37678c40db608cb4c0e94d2c51b98d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 5 Mar 2024 18:35:14 +0100 Subject: [PATCH 3/4] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1742.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1742.clarification diff --git a/changelogs/client_server/newsfragments/1742.clarification b/changelogs/client_server/newsfragments/1742.clarification new file mode 100644 index 000000000..84f21b9ee --- /dev/null +++ b/changelogs/client_server/newsfragments/1742.clarification @@ -0,0 +1 @@ +Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`. \ No newline at end of file From 0d1d6c847acf24715be0c191dbede59c5de5e567 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 7 Mar 2024 11:20:18 +0100 Subject: [PATCH 4/4] Link to the "End-of-candidates" section, and clarify what "empty" means MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/event-schemas/schema/m.call.candidates.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/data/event-schemas/schema/m.call.candidates.yaml b/data/event-schemas/schema/m.call.candidates.yaml index c2961f1a5..d43ede986 100644 --- a/data/event-schemas/schema/m.call.candidates.yaml +++ b/data/event-schemas/schema/m.call.candidates.yaml @@ -37,7 +37,8 @@ properties: description: |- The SDP 'a' line of the candidate. - If this is an end-of-candidates candidate, this is empty. + If this is an [end-of-candidates](/client-server-api/#end-of-candidates) + candidate, this is the empty string. required: - candidate required: