Membrane.RTC.Engine.Subscriber behaviour (Membrane RTC Engine v0.25.0)
View SourceModule 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 endpoint decided that it want to subscribe on specific tracks.
It should return an updated struct and it will try to subscribe on these tracks.
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 track for subscriber. It makes only sense 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.
Remove endpoints for subscriber, this will prevent new tracks from being subscribed.
Already subscribed tracks will remain subscribed and must be removed manually.
It makes sense only to use this method when subscriber is in mode :manual.
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, track_types: [:audio | :video], tracks: tracks_t() }
This struct contains:
endpoint_id- id of endpointrtc_engine- pid of engine pipelinesubscribe_mode- mode of subscription. In:automode endpoint will try to subscribe on all available tracks. In:manualmode 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:manualmode.track_types- if provided, only subscribe to tracks with type intrack_types
@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 add_tracks( track_ids :: [Membrane.RTC.Engine.Track.id()], subscriptions_state :: t() ) :: t()
Callback invoked when endpoint decided that it want to subscribe on specific tracks.
It should return an updated struct and it will try to subscribe on these tracks.
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 add_tracks( track_ids :: [Membrane.RTC.Engine.Track.id()], subscriptions_state :: t() ) :: t()
@spec add_tracks( track_ids :: [Membrane.RTC.Engine.Track.id()], subscriptions_state :: t() ) :: t()
Provide new track for subscriber. It makes only sense 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_endpoints(state :: t(), endpoints :: [Membrane.RTC.Engine.Endpoint.id()]) :: t()
Remove endpoints for subscriber, this will prevent new tracks from being subscribed.
Already subscribed tracks will remain subscribed and must be removed manually.
It makes sense only to use this method when subscriber is in mode :manual.
@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()