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

74 lines
2.8 KiB
YAML

---
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:
description:
type: object
title: Description
description: The session description object
properties:
type:
type: string
enum:
- offer
- answer
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 negotiation is valid for.
Once the negotiation age exceeds this value, clients should discard it.
required:
- description
- lifetime
type:
type: string
enum:
- m.call.negotiate