View Source Membrane.RTC.Engine.Subscriber behaviour (Membrane RTC Engine v0.22.0)
Module representing a state needed for subscribing on tracks in RTC Engine. Besides a struct this module provide a helper functions that simplify whole process of subscribing on tracks and provides two different strategies for subscribing on tracks:
:auto
- in this strategy subscriber subscribes on every provided track:manual
- in this strategy subscriber subscribe only on tracks from selected endpoints. After adding an endpoint subscriber will also subscribe on all existing tracks from this added endpoint.
Summary
Callbacks
Callback invoked when endpoint decided that it want to subscribe on specific endpoints.
It should return an updated struct and it will try to subscribe on all tracks from these endpoints.
This function is useless in :auto
subscribe_mode.
Callback invoked when a new tracks are added by engine. It should return an updated struct and it will try to subscribe on valid tracks.
Functions
Provide new endpoint for subscriber, that will try to subscribe on their tracks.
It makes sense only to use this method when subscriber is in mode :manual
.
Provide new tracks for subscriber, that will try to subscribe on them if they satisfy
conditions required by :subscriber_mode
.
Try to subscribe on tracks.
Types
@type subscribe_result() :: {[Membrane.RTC.Engine.Track.t()], t()}
@type t() :: %Membrane.RTC.Engine.Subscriber{ endpoint_id: Membrane.RTC.Engine.Endpoint.id(), endpoints: MapSet.t(), rtc_engine: pid(), subscribe_mode: :auto | :manual, tracks: tracks_t() }
This struct contains:
endpoint_id
- id of endpointrtc_engine
- pid of engine pipelinesubscribe_mode
- mode of subscription. In:auto
mode endpoint will try to subscribe on all available tracks. In:manual
mode endpoint will subscribe only on tracks from endpoints that were previously added to state.tracks
- map of tracks on which that endpoint subscribedendpoints
- set of endpoints, endpoint will try to subscribe on tracks of these endpoints. Used only in:manual
mode.
@type tracks_t() :: %{ required(Membrane.RTC.Engine.Track.id()) => Membrane.RTC.Engine.Track.t() }
Callbacks
@callback add_endpoints( endpoints :: [Membrane.RTC.Engine.Endpoint.id()], subscriptions_state :: t() ) :: t()
Callback invoked when endpoint decided that it want to subscribe on specific endpoints.
It should return an updated struct and it will try to subscribe on all tracks from these endpoints.
This function is useless in :auto
subscribe_mode.
@callback handle_new_tracks( tracks :: [Membrane.RTC.Engine.Track.t()], subscriptions_state :: t() ) :: t()
Callback invoked when a new tracks are added by engine. It should return an updated struct and it will try to subscribe on valid tracks.
Functions
@spec add_endpoints( endpoints :: [Membrane.RTC.Engine.Endpoint.id()], subscriptions_state :: t() ) :: t()
Provide new endpoint for subscriber, that will try to subscribe on their tracks.
It makes sense only to use this method when subscriber is in mode :manual
.
@spec get_track(state :: t(), track_id :: Membrane.RTC.Engine.Track.id()) :: Membrane.RTC.Engine.Track.t() | nil
@spec handle_new_tracks( tracks :: [Membrane.RTC.Engine.Track.t()], subscriptions_state :: t() ) :: t()
Provide new tracks for subscriber, that will try to subscribe on them if they satisfy
conditions required by :subscriber_mode
.
The easiest usage would be to call this function during handling :new_tracks
message from engine
like in example below.
Examples
@impl true
def handle_parent_notification({:new_tracks, tracks}, _ctx, state) do
subscriber = Subscriber.handle_new_tracks(tracks, state.subscriber)
{[], %{state | subscriber: subscriber}}
end
@spec pop_track!(t(), Membrane.RTC.Engine.Track.id()) :: {Membrane.RTC.Engine.Track.t(), t()}
@spec remove_track(state :: t(), track_id :: Membrane.RTC.Engine.Track.id()) :: t()
@spec subscribe_for_tracks( [Membrane.RTC.Engine.Track.t()], Membrane.RTC.Engine.Endpoint.id(), pid() ) :: [Membrane.RTC.Engine.Track.t()]
Try to subscribe on tracks.
It returns a list of valid tracks that were successfully subscribed
@spec update_endpoints(t(), [Membrane.RTC.Engine.Endpoint.id()]) :: t()
@spec update_tracks(t(), [Membrane.RTC.Engine.Track.t()]) :: t()