v0.7.0 - Crash Groups

Crash Groups

From v0.7.0 of membrane_core it's possible to group elements and bins into crash groups.
Crash group is a logical entity that prevents the whole pipeline from crashing when one of its children crashes.

Adding children to the Crash Group

children = %{
  {:endpoint_bin, endpoint_id} => %EndpointBin{
    # ... 
  }
}

spec = %ParentSpec{children: children, crash_group: {endpoint_id, :temporary}}

In this case we create a new children - EndpointBin and we add it to crash group with id endpoint_id. When EndpointBin crashes the whole pipeline will still be alive.

Handling crash of Crash Group

When some child in a crash group crashes the callback handle_crash_group_down/3 is called.

@impl true
def handle_crash_group_down(crash_group_id, ctx, state) do
  Membrane.Logger.info("Crash group: #{inspect(crash_group_id)} is down.")
  # do some stuff 
end

Limitations

At this moment Crash Groups are only useful for elements with dynamic pads.

Condidional Linking

In this version we also introduce an enhancement in linking elements.
Sometimes there is a situation you want to link or create an element only when some requirements are met.
To make it easier we introduce a new syntax that looks like below

encoding_specific_links =
  case encoding do
    # when encoding is :H264 we want to add one additional element -- H264 parser.
    :H264 -> &to(&1, {:h264_parser, ssrc}, %Membrane.H264.FFmpeg.Parser{alignment: :nal}) 
    # when encoding is :OPUS we just passes what we got 
    :OPUS -> & &1 
  end

links = [
  link_bin_input(pad)
  |> pipe_fun(encoding_specific_links)
  |> to({:track_filter, track_id}, %Membrane.WebRTC.TrackFilter{enabled: track_enabled})
  # ...
]

defp pipe_fun(term, fun), do: fun.(term)

Breaking changes

From now Testing.Source sends a new type of caps - RemoteStream. This can break some of your already existing tests.

v0.6.1

This release includes several bug fixes:

• bin pad opts handling #282
• docs generation #283
• children playback state management #284

v0.6.0

Breaking changes

• Callbacks in pipelines and bins now have the context argument #278
• [Fix] Remove stale Membrane.Event.{StartOfStream, EndOfStream} events. Since v0.5.0 they're replaced with dedicated action and callbacks #280

Other changes

• Bins and pipelines can now use timers #264
• forward action in pipelines and bins now accepts list #279
• Docs fixes #280
• Started integration with telemetry #269

v0.5.3

• fix stopping timers bug #268
• update CI docker image

v0.5.2

• Fix RC when terminating #252 (turned out not to be fully fixed by v0.5.1)
• Fix warnings on Elixir 1.10 #241
• Add NTP timestamp conversion to Membrane Time #248

v0.5.1

• Improved log pruning, other performance improvements #246, #244
• Fix in timer time conversion algorithm #226
• Fixes related to the end of stream generation #216
• Lots of tests, docs and type specs improvements
• Synchronous pipeline termination #233
• timer_interval action #222
• New Membrane.Time as_* functions #223

v0.4.3 - Backport of bug fixes

• Fix missing key in InputBuffer warning
• Fix log pruning

v0.5.0 - Bins and links

Membrane Framework 0.5 release notes

Links

Although the main feature of this release is the introduction of bins, let's start with the refreshed syntax for links, as we'll need them for bins also. Until now, the way you declared links was the following:

links = %{
   {:file_src, :output} => {:decoder, :input},
   {:decoder, :output} => {:converter, :input},
   {:converter, :output} => {:player, :input}
 }

That was a bit too verbose and made trouble when linking a dynamic output pad multiple times, causing repeated keys in the map. The new way solves both problems:

links = [
  link(:file_src) |> to(:decoder) |> to(:converter) |> to(:player)
]

If a pipeline is not linear, more elements can be added to the list:

links = [
  link(:microphone) |> to(:tee) |> to(:player),
  link(:tee) |> to(:file)
]

As :output and :input are default pad names, there is no need to provide them explicitly. If a custom name or pad options should be passed, via_out/2 and via_in/2 functions come to help.

links = [
  link(:element1)
  |> via_out(:custom_output, options: [key: :value])
  |> via_in(:custom_input)
  |> to(:element2)
]

Also, the way dynamic pads are referenced has been unified. Now, instead of passing a pad name and id to a link, full reference should be passed. As the existing format of references {:dynamic, name, id} would be a bit cumbersome for that, it is now handled with Membrane.Pad.ref(name, id) macro.

links = [
  link(:file_src) |> via_in(Pad.ref(:input, 3)) |> to(:mixer)
]

See the docs for Membrane.ParentSpec for more details.

Bins

Bins - entities that enable creating reusable, dynamically customisable groups of elements, are now available in Membrane. Bins can spawn their children like pipelines and have pads like elements, so they can be embedded within a pipeline (or another bin). Bins' pads proxy the stream between their siblings and children.

To use a bin, add it to children and link the same way as elements:

children = [
  element1: Element1,
  my_bin: My.Bin,
  element2: Element2
]

links = [
  link(:element1) |> to(:my_bin) |> to(:element2)
]

When linking children within a bin, you can connect them to bin's pad with use of link_bin_input/2 and to_bin_output/3 from Membrane.ParentSpec.

links = [
  link_bin_input() |> to(:child1) |> to(:child2) |> to_bin_output(:custom_output)
]

Bins can also have dynamic pads, and the new way of referencing them is intended to make this powerful blend straightforward to reason about.

@impl true
def handle_pad_added(Pad.ref(:input, _) = pad, _ctx, state) do
  links = [link_bin_input(pad) |> to(:mixer)]
  {{:ok, spec: %ParentSpec{links: links}}, state}
end

For more about bins check out the guide chapter about bins, see how to create and deal with bins in the documentation for Membrane.Bin, or have a look at RTP bin or RTP demo.

Breaking changes

• Membrane.Pipeline.Spec is now Membrane.ParentSpec
• Dynamic pads are now referenced by Membrane.Pad.ref(name, id) macro instead of {:dynamic, name, id} tuple
• Links are specified in a new way, described in docs for Membrane.ParentSpec
• Field pipeline_clock became parent_clock in all the callback contexts

v0.4.2 - Bug fix release

This release fixes warning printed when pipeline is stopped via stop_and_terminate function.

v0.4.1

• A fix for #185 - bug that prevented using monitors from elements
• Fix a crash when using start_timer without explicitly passing a clock (#195)
• Fix synchronization of elements spawned dynamically (after init) (#198)
• Other minor improvements in docs, tests and typespecs