This is a list of all events that can be emitted by an instance of WebRtcEndpoint. This class belongs to a chain of inherited classes, so this list includes events from all of them, starting from the topmost class in the inheritance tree:

State = Flowing: Data is arriving from the KMS Pipeline, and flowing into the Element. Technically, this means that there are GStreamer Buffers flowing from the Pipeline to the Element’s sink pad. For example, with a Recorder element this event would fire when media arrives from the Pipeline to be written to disk.

State = NotFlowing: The Element is not receiving any input data from the Pipeline.

State = Flowing: There is data flowing out from the Element towards the KMS Pipeline. Technically, this means that there are GStreamer Buffers flowing from the Element’s src pad to the Pipeline. For example, with a Player element this event would fire when media is read from disk and is pushed to the Pipeline.

State = NotFlowing: The Element is not sending any output data to the Pipeline.

All Endpoint objects in Kurento Media Server embed a custom-made GStreamer element called agnosticbin. This element is used to provide seamless interconnection of components in the MediaPipeline, regardless of the format and codec configuration of the input and output media streams.

When media starts flowing through any MediaElement-derived object, an internal dynamic configuration is automatically done in order to match the incoming and outgoing media formats. If both input and output formats are compatible (at the codec level), then the media can be transferred directly without any extra processing. However, if the input and output media formats don’t match, the internal transcoding module will get enabled to convert between them.

For example: If a WebRtcEndpoint receives a VP8 video stream from a Chrome browser, and has to send it to a Safari browser (which only supports the H.264 codec), then the media needs to be transcoded. The WebRtcEndpoint will automatically do it.

State = Transcoding: The MediaElement will transcode the incoming media, because its format is not compatible with the requested output.

State = NotTranscoding: The MediaElement will not transcode the incoming media, because its format is compatible with the requested output.

These events provide information about the state of the RTP connection for each stream in the WebRTC call.

Note that the MediaStateChanged event is not 100% reliable to check if a RTP connection is active: RTCP packets do not usually flow at a constant rate. For example, minimizing a browser window with an RTCPeerConnection might affect this interval.

State = Connected: At least one of the audio or video RTP streams in the session is still alive (sending or receiving RTCP packets). Equivalent to the signal GstRtpBin::”on-ssrc-active”, which gets triggered whenever the GstRtpBin receives an RTCP Sender Report (RTCP SR) or RTCP Receiver Report (RTCP RR).

State = Disconnected: None of the RTP streams belonging to the session is alive (ie. no RTCP packets are sent or received for any of them).

These signals from GstRtpBin will trigger the MediaStateChanged event:

State = Connecting: The Endpoint has started the connectivity checks between at least one pair of local and remote candidates. These checks will always start as soon as possible (i.e. whenever the very first remote candidates arrive), so don’t assume that the candidate gathering has already finished, because it will probably still be running in parallel; some (possibly better) candidates might still be waiting to be found and gathered.

State = Connected: At least one candidate pair resulted in a successful connection. This happens right after the event NewCandidatePairSelected. When this event triggers, the effective communication between peers can start, and usually this means that media will start flowing between them. However, the candidate gathering hasn’t really finished yet, which means that some (possibly better) candidates might still be waiting to be found, gathered, checked for connectivity, and if that completes successfully, selected as new candidate pair.

State = Failed: All local candidates have been gathered, all pairs of local and remote candidates have been tested for connectivity, but still none of the connection checks was successful, so no connectivity was reached to the remote peer.

NiceAgent state: NICE_COMPONENT_STATE_FAILED, “Connectivity checks have been completed, but connectivity was not established”.

The states Ready and Failed indicate that the ICE transport has completed gathering and is currently idle. However, since events such as adding a new interface or a new TURN server will cause the state to go back, Ready and Failed are not terminal states.

All local candidates have been found, so the gathering process is finished for this peer. Note this doesn’t imply that the remote peer has finished its own gathering, so more remote candidates might still arrive. Equivalent to the signal NiceAgent::”candidate-gathering-done”.

During the connectivity checks one of the pairs happened to provide a successful connection, and the pair had a higher preference than the previously selected one (or there was no previously selected pair yet). Equivalent to the signal NiceAgent::”new-selected-pair”.

Once an instance of WebRtcEndpoint is created inside a Media Pipeline, an event handler should be added for each one of the events that can be emitted by the endpoint. Later, the endpoint should be instructed to do one of either:

Generate an SDP Offer, when KMS is the caller. Later, the remote peer will generate an SDP Answer as a reply, which must be provided to the endpoint.

Process an SDP Offer generated by the remote peer, when KMS is the callee. This will in turn generate an SDP Answer, which should be provided to the remote peer.

As a last step, the WebRtcEndpoint should be instructed to start the ICE Gathering process.

Repeated multiple times; tipically, candidates of type host (corresponding to the LAN, local network) are almost immediately found after starting the ICE gathering, and this event can arrive even before the event IceComponentStateChanged is emitted.

IceComponentStateChanged (state: Gathering)

At this point, the local peer is gathering more candidates, and it is also waiting for the candidates gathered by the remote peer, which could start arriving at any time.

AddIceCandidate

Repeated multiple times; the remote peer found some initial candidates, and started sending them. Typically, the first candidate received is of type host, because those are found the fastest.

IceComponentStateChanged (state: Connecting)

After receiving the very first of the remote candidates, the ICE Agent starts with the connectivity checks.

Kurento has been supported under Project LERNIM (RTC-2016-4674-7), co-funded by the Ministry of Economy, Finance and Competitiveness of Spain, as well as by the European Regional Development Fund, whose main goal is to promote technological development, innovation and high-quality research.