View Source Membrane.RTC.Engine.Subscriber behaviour (Membrane RTC Engine v0.23.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

Types

subscribe_result()
t()

This struct contains

tracks_t()

Callbacks

add_endpoints(endpoints, subscriptions_state)

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.

handle_new_tracks(tracks, subscriptions_state)

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

add_endpoints(endpoints, subscriptions_state)

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.

get_track(state, track_id)
get_tracks(state)
handle_new_tracks(tracks, subscriptions_state)

Provide new tracks for subscriber, that will try to subscribe on them if they satisfy conditions required by :subscriber_mode.

pop_track!(state, track_id)
remove_track(state, track_id)
subscribe_for_tracks(tracks, endpoint_id, rtc_engine)

Try to subscribe on tracks.

update_endpoints(state, endpoints)
update_tracks(state, tracks)

Types

Link to this type

subscribe_result()

View Source 
@type subscribe_result() :: {[Membrane.RTC.Engine.Track.t()], t()}
Link to this type

t()

View Source 
@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 endpoint
  • rtc_engine - pid of engine pipeline
  • subscribe_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 subscribed
  • endpoints - set of endpoints, endpoint will try to subscribe on tracks of these endpoints. Used only in :manual mode.
Link to this type

tracks_t()

View Source 
@type tracks_t() :: %{
  required(Membrane.RTC.Engine.Track.id()) => Membrane.RTC.Engine.Track.t()
}

Callbacks

Link to this callback

add_endpoints(endpoints, subscriptions_state)

View Source 
@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.

Link to this callback

handle_new_tracks(tracks, subscriptions_state)

View Source 
@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

Link to this function

add_endpoints(endpoints, subscriptions_state)

View Source 
@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.

Link to this function

get_track(state, track_id)

View Source 
@spec get_track(state :: t(), track_id :: Membrane.RTC.Engine.Track.id()) ::
  Membrane.RTC.Engine.Track.t() | nil
Link to this function

get_tracks(state)

View Source 
@spec get_tracks(state :: t()) :: tracks_t()
Link to this function

handle_new_tracks(tracks, subscriptions_state)

View Source 
@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
Link to this function

pop_track!(state, track_id)

View Source 
@spec pop_track!(t(), Membrane.RTC.Engine.Track.id()) ::
  {Membrane.RTC.Engine.Track.t(), t()}
Link to this function

remove_track(state, track_id)

View Source 
@spec remove_track(state :: t(), track_id :: Membrane.RTC.Engine.Track.id()) :: t()
Link to this function

subscribe_for_tracks(tracks, endpoint_id, rtc_engine)

View Source 
@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

Link to this function

update_endpoints(state, endpoints)

View Source 
@spec update_endpoints(t(), [Membrane.RTC.Engine.Endpoint.id()]) :: t()
Link to this function

update_tracks(state, tracks)

View Source 
@spec update_tracks(t(), [Membrane.RTC.Engine.Track.t()]) :: t()