From 379711dc543997954d0c3a1de3bec0b4b825d98e Mon Sep 17 00:00:00 2001 From: "feliks.pobiedzinski@swmansion.com" Date: Thu, 2 Jan 2025 14:02:50 +0100 Subject: [PATCH] Add svg images visualizing pipeline topology --- assets/images/spec_with_audio.svg | 4 ++++ assets/images/spec_without_audio.svg | 4 ++++ guides/components_lifecycle.md | 12 +++++----- lib/membrane/bin/action.ex | 34 ++++++---------------------- 4 files changed, 21 insertions(+), 33 deletions(-) create mode 100644 assets/images/spec_with_audio.svg create mode 100644 assets/images/spec_without_audio.svg diff --git a/assets/images/spec_with_audio.svg b/assets/images/spec_with_audio.svg new file mode 100644 index 000000000..9d13f6a25 --- /dev/null +++ b/assets/images/spec_with_audio.svg @@ -0,0 +1,4 @@ + + + +
:file_source
:file_s...
:demuxer
:demuxer
:decoder
:decoder
:ai_filter
:ai_fil...
:encoder
:encoder
:webrtc_sink
:webrtc...
:output
:output
:input
:input
:video
:video
:input
:input
:output
:output
:output
:output
:output
:output
:video
:video
:input
:input
:input
:input
:scratch_remover
:scratch_remover
:audio
:audio
:audio
:audio
:output
:output
:input
:input \ No newline at end of file diff --git a/assets/images/spec_without_audio.svg b/assets/images/spec_without_audio.svg new file mode 100644 index 000000000..82184489b --- /dev/null +++ b/assets/images/spec_without_audio.svg @@ -0,0 +1,4 @@ + + + +
:file_source
:file_s...
:demuxer
:demuxer
:decoder
:decoder
:ai_filter
:ai_fil...
:encoder
:encoder
:webrtc_sink
:webrtc...
:output
:output
:input
:input
:video
:video
:input
:input
:output
:output
:output
:output
:output
:output
:video
:video
:input
:input
:input
:input \ No newline at end of file diff --git a/guides/components_lifecycle.md b/guides/components_lifecycle.md index 2965e565a..f2aed4898 100644 --- a/guides/components_lifecycle.md +++ b/guides/components_lifecycle.md @@ -8,7 +8,7 @@ The first callback executed in every Membrane Component is `handle_init/2`. This ## Setup Following `handle_init/2` is `handle_setup/2`, which is executed asynchronously. This is an optimal time to set up resources or perform other intensive operations required for the element to function properly. -## Linking the Pads +## Linking pads For components with pads having `availability: :on_request`, the corresponding `handle_pad_added/3` callbacks are called between `handle_setup/2` and `handle_playing/2` if they are linked in the same spec where the component was spawned. Linking the pad in a different spec from the one spawning the element may lead to `handle_pad_added/3` being invoked after `handle_playing/2`. ## Playing @@ -17,7 +17,7 @@ Once setup is completed, a component can enter the `:playing` state by invoking - Elements and Bins wait for their parent to enter the `playing` state before executing `handle_playing/2`. - By default, after `handle_setup/2`, a component's setup is considered complete. This behavior can be modified by returning `setup: :incomplete` from `handle_setup/2`. The component must then mark its setup as completed by returning `setup: :complete` from another callback, like `handle_info/3`, to enter `:playing` playback. -## Processing the Data (Applies Only to `Elements`) +## Processing the data (applies only to Elements) After `handle_playing/2`, Elements are prepared to process data flowing through their pads. ### Events @@ -35,17 +35,17 @@ The core of multimedia processing involves handling `Membrane.Buffer`s, which co ### Demands If the Element has pads with `flow_control: :manual`, entering `:playing` playback allows it to send demand using `:demand` action or to receive it in `handle_demand/5` callback. -## After Processing the Data +## After processing the data When an element determines that it will no longer send buffers from a specific pad, it can return `:end_of_stream` action to that pad. The linked element receives this in `handle_end_of_stream/3`. The parent component (either a Bin or Pipeline) is notified via `handle_element_end_of_stream/4`. ## Terminating Typically, the last callback executed within a Membrane Component is `handle_terminate_request`. By default, it returns a `terminate: :normal` action, concluding the component's lifespan with the reason `:normal`. This behavior can be modified by overriding the default implementation, but ensure to return a `terminate: reason` elsewhere to avoid termination issues in your Pipeline. -## Callbacks Not Strictly Related to the Lifecycle +## Callbacks not strictly related to the lifecycle Some callbacks are not confined to specific stages of the Membrane Component lifecycle. -### Handling Parent/Child Notification +### Handling parent or child notification `handle_parent_notification/3` and `handle_child_notification/4` can occur at any point during the component's lifecycle and are tasked with managing notifications from a parent or child component, respectively. -### Handling Messages from Non-Membrane Processes +### Handling messages from non-Membrane Erlang Processes The `handle_info/3` callback is present in all Membrane Components and `handle_call/3` in Membrane Pipelines. These can be triggered at any time while the component is alive, functioning similarly to their substituted in `GenServer`. \ No newline at end of file diff --git a/lib/membrane/bin/action.ex b/lib/membrane/bin/action.ex index 5c0a47812..2d7f5e101 100644 --- a/lib/membrane/bin/action.ex +++ b/lib/membrane/bin/action.ex @@ -39,7 +39,7 @@ defmodule Membrane.Bin.Action do Children's playback is changed to the current bin playback. `c:Membrane.Parent.handle_spec_started/3` callback is executed once the children are spawned. - This is an example of spec + This is an example of a value that could be passed within `spec` action ```elixir child(:file_source, %My.File.Source{path: path}) |> child(:demuxer, My.Demuxer) @@ -51,19 +51,10 @@ defmodule Membrane.Bin.Action do |> child(:webrtc_sink, My.WebRTC.Sink) ``` along with it's visualisation - ```mermaid - graph TB; - file_source(File Source) --> demuxer(Demuxer); - demuxer -->|video| decoder(Decoder); - decoder --> ai_filter(AI Filter); - ai_filter --> encoder(Encoder); - encoder --> |video| webrtc_sink(WebRTC Sink); - - classDef default fill:#add8e6, stroke:#333, stroke-width:2px, color:black; - linkStyle default stroke:#333, stroke-width:2px, fill:none; - ``` - Returning another spec like this + ![](assets/images/spec_without_audio.svg) + + Returning another spec ```elixir get_child(:demuxer) |> via_out(:audio) @@ -72,20 +63,9 @@ defmodule Membrane.Bin.Action do |> get_child(:webrtc_sink) ``` - will result in having such a pipeline topology: - ```mermaid - graph TB; - file_source(File Source) --> demuxer(Demuxer); - demuxer -->|video| decoder(Decoder); - decoder --> ai_filter(AI Filter); - ai_filter --> encoder(Encoder); - encoder -->|video| webrtc_sink(WebRTC Sink); - demuxer -->|audio| scratch_remover(Scratch Remover); - scratch_remover -->|audio| webrtc_sink; - - classDef default fill:#add8e6, stroke:#333, stroke-width:2px, color:black; - linkStyle default stroke:#333, stroke-width:2px, fill:none; - ``` + will result in having following children topology: + + ![](assets/images/spec_with_audio.svg) """ @type spec :: {:spec, ChildrenSpec.t()}