You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/data/event-schemas/schema/m.call.negotiate.yaml

75 lines
2.9 KiB
YAML

Add spec for MSC2746 (#1511) * Change version field to a string And add the notes on how the version field works. * Add spec requiring tracks to be within streams. * Put streams spec in its own section * Add 'invitee' field * Add party_id * Remember how JSON works * Add m.call.select_answer * Update examples * Add select_answer to call flow example diagram * Add m.call.reject * Make party_id required in other events * Add possible ways for client to handle an invite * Convert hangup & reject events to YAML So we can have a bulleted list in the description for the values of 'reason'. * Add new reason codes to hangup & reject * Add m.call.negotiate * Add other sections * Revert changes to package lock * Typos * Fix type of other version fields, fix anchor. * Add newsfragment * Fix reason in hangup/reject * Change tense Co-authored-by: Hubert Chathi <hubertc@matrix.org> * Tense, typos & grammar Co-authored-by: Hubert Chathi <hubertc@matrix.org> * Linkify Co-authored-by: Hubert Chathi <hubertc@matrix.org> * Remove unnecessary parts from link Co-authored-by: Hubert Chathi <hubertc@matrix.org> * Capitalise Co-authored-by: Hubert Chathi <hubertc@matrix.org> * Fix hangup reasons * Clarify who can answer Co-authored-by: Hubert Chathi <hubertc@matrix.org> * Linkify Co-authored-by: Hubert Chathi <hubertc@matrix.org> * Remove reference to 'this MSC'. * Move common VoIP fields into a call event type. * Move common voip events to the content, not the actual event * Remove reason from reject event I confused myself, but it's not in the MSC and it shouldn't be. * Failure to YAML * Fix number of room members allowed when sending voip events. Co-authored-by: Hubert Chathi <hubertc@matrix.org> * Add 'added in' version Co-authored-by: Hubert Chathi <hubertc@matrix.org> * Another added-in Co-authored-by: Hubert Chathi <hubertc@matrix.org> * Add missing comma --------- Co-authored-by: Hubert Chathi <hubertc@matrix.org> Co-authored-by: Travis Ralston <travisr@matrix.org>
1 year ago
---
type: object
description: |
Provides SDP negotiation semantics for media pause, hold/resume, ICE restarts
and voice/video call up/downgrading. Clients should implement and honour hold
functionality as per [WebRTC's recommendation](https://www.w3.org/TR/webrtc/#hold-functionality).
If both the invite event and the accepted answer event have `version` equal
to `"1"`, either party may send `m.call.negotiate` with a `description` field
to offer new SDP to the other party. This event has `call_id` with the ID of
the call and `party_id` equal to the client's party ID for that call. The
caller ignores any negotiate events with `party_id` + `user_id` tuple not
equal to that of the answer it accepted and the callee ignores any negotiate
events with `party_id` + `user_id` tuple not equal to that of the caller.
Clients should use the `party_id` field to ignore the remote echo of their
own negotiate events.
This has a `lifetime` field as in `m.call.invite`, after which the sender of
the negotiate event should consider the negotiation failed (timed out) and
the recipient should ignore it.
The `description` field is the same as the `offer` field in `m.call.invite`
and `answer` field in `m.call.answer` and is an `RTCSessionDescriptionInit`
object as per https://www.w3.org/TR/webrtc/#dom-rtcsessiondescriptioninit.
Once an `m.call.negotiate` event is received, the client must respond with
another `m.call.negotiate` event, with the SDP answer (with `"type": "answer"`)
in the `description` property.
In the `m.call.invite` and `m.call.answer` events, the `offer` and `answer`
fields respectively are objects of type `RTCSessionDescriptionInit`. Hence
the `type` field, whilst redundant in these events, is included for ease of
working with the WebRTC API and is mandatory. Receiving clients should not
attempt to validate the `type` field, but simply pass the object into the
WebRTC API.
x-addedInMatrixVersion: "1.7"
allOf:
- "$ref": core-event-schema/room_event.yaml
properties:
content:
type: object
allOf:
- "$ref": core-event-schema/call_event.yaml
properties:
offer:
type: object
title: Offer
description: The session description object
properties:
type:
type: string
enum:
- offer
description: The type of session description.
sdp:
type: string
description: The SDP text of the session description.
required:
- type
- sdp
lifetime:
type: integer
description: The time in milliseconds that the invite is valid for.
Once the invite age exceeds this value, clients should discard it.
They should also no longer show the call as awaiting an answer in the
UI.
required:
- offer
- lifetime
type:
type: string
enum:
- m.call.negotiate