RTC Engine implementation.

RTC Engine is an abstraction layer responsible for linking together different types of Endpoints. From the implementation point of view, RTC Engine is a Membrane.Pipeline.

messages

Messages

The RTC Engine works by sending messages which notify user logic about important events. To receive RTC Engine messages you have to register your process so that RTC Engine will know where to send them. All messages RTC Engine can emit are described in Membrane.RTC.Engine.Message docs.

registering-for-messages

Registering for messages

Registration can be done using register/2 e.g.

Engine.register(rtc_engine, self())

This will register your process to receive RTC Engine messages. You can register multiple processes to receive messages from an RTC Engine instance. In such a case each message will be sent to each registered process.

peers

Peers

deprecation-notice

Deprecation notice

Peers are deprecated as of version 0.10.0 and will be removed in the future

While Peers are still present in the RTC Engine, it's not recommended to use this feature in new applications.

Existing applications should take steps to move away from using built-in concept of peers.

Each peer represents some user that can possess some metadata. In RTC Engine, each peer is represented by an endpoint and from the purposes of the Engine, it is an enpdoint that we happen to store additional information about, metadata in particular. The peer doesn't exist without their endpoint.

adding-a-peer

Adding a peer

The only way to add a peer to the RTC Engine is to assign a peer_id to the endpoint representing it. This is done when adding an endpoint to the Engine by passing a peer_id option.

Example

:ok = Engine.add_endpoint(webrtc_endpoint, peer_id: "Peer1")

Each peer then needs to declare itself as ready before being fully connected to RTC Engine.

readiness-state

Readiness state

Each peer endpoint is presumed to be initially inactive and has to declare itself ready to fully join the Engine.

Before it does, it:

• will not receive notifications about other peers and their metadata
• will not receive information about tracks
• will not be able to publish any tracks
• will not be able to update their metadata

When declaring itself as ready, the peer also has an opportunity to set their metadata. To mark the peer as active, their endpoint has to send the ready_action_t/0.

Example

@impl true
def handle_other({:media_event, %{type: "join", metadata: metadata}}, _context, state) do
  {{:ok, notify: {:ready, metadata}}, state}
end

@impl true
def handle_other(:ready, _context, state) do
  Membrane.Logger.debug("Succesfully activated the peer")
  {:ok, state}
end

endpoints

Endpoints

Endpoints are Membrane.Bins able to publish their own tracks and subscribe to tracks from other Endpoints. One can think about Endpoint as an entity responsible for handling some specific task. An Endpoint can be added and removed using add_endpoint/3 and remove_endpoint/2 respectively.

There are two types of Endpoints:

• Standalone Endpoints - they are in most cases spawned only once per RTC Engine instance and they are not associated with any peer.
• Peer Endpoints - they are associated with some peer. Associating Endpoint with Peer will cause RTC Engine to send some Media Events to the Enpoint's Client Library e.g. one which indicates which tracks belong to which peer.

Currently RTC Engine ships with the implementation of two Endpoints:

• Membrane.RTC.Engine.Endpoint.WebRTC which is responsible for establishing a connection with some WebRTC peer (mainly browser) and exchanging media with it. WebRTC Endpoint is a Peer Endpoint.
• Membrane.RTC.Engine.Endpoint.HLS which is responsible for receiving media tracks from all other Endpoints and saving them to files by creating HLS playlists. HLS Endpoint is a Standalone Endpoint.

User can also implement custom Endpoints, see Custom Endpoints guide.