Pads guide by Noarkhh · Pull Request #1031 · membraneframework/membrane_core

Noarkhh · 2025-11-27T09:32:48Z

No description provided.

mat-hek

Some examples from element's and bin's perspective (handle_pad_added, handle_pad_removed) would be useful. There's also handle_child_pad_removed. Maybe the flow of sending/receiving stream formats and handle_start_of_stream/handle_end_of_stream would be worth mentioning here too.

Noarkhh · 2025-12-10T11:48:23Z

Some examples from element's and bin's perspective (handle_pad_added, handle_pad_removed) would be useful. There's also handle_child_pad_removed. Maybe the flow of sending/receiving stream formats and handle_start_of_stream/handle_end_of_stream would be worth mentioning here too.

I'll add a brief lifecycle section, but I think the more in-depth interactions between callbacks, like the flow of events, stream formats and buffers, shouldn't be duplicated from the guide regarding component's lifecycle

FelonEkonom

LGTM in general, however I have added some minor comments in places where I think something might be unclear for somebody who doesn't know much about the framework

FelonEkonom · 2025-12-10T15:33:52Z

+* A pad of one component can only connect to a single pad of other component and
+only once two pads are linked communication through them can happen.
+* One pad needs to be an input pad, and the other an output pad.
+* The accepted stream formats of the pads need to match.


Make it more explicit that it doesn't mean that accepted formats must be equal. You don't have to follow the suggestion.

Suggested change

* The accepted stream formats of the pads need to match.

* The accepted stream formats of the pads cannot be disjoint.

I don't think the disjointness is that intuituve, but i wrote it more verbosely and łopatologically

FelonEkonom · 2025-12-10T15:41:44Z

+There are three types of information that can be exchanged between components
+through pads - [stream formats](`t:Membrane.StreamFormat.t/0`),
+[events](`t:Membrane.Event.t/0`) and [buffers](`t:Membrane.Buffer.t/0`)


you can also send EoS via pad

FelonEkonom · 2025-12-10T15:42:35Z

+There are three types of information that can be exchanged between components
+through pads - [stream formats](`t:Membrane.StreamFormat.t/0`),
+[events](`t:Membrane.Event.t/0`) and [buffers](`t:Membrane.Buffer.t/0`)
+
+When looking at the insides of components, the pads are their main way to
+communicate with other components in the pipeline. There are three types
+of informations that can be exchanged between components through pads -
+[stream formats](`t:Membrane.StreamFormat.t/0`),
+[events](`t:Membrane.Event.t/0`) and [buffers](`t:Membrane.Buffer.t/0`).


looks like you repeat yourself

FelonEkonom · 2025-12-10T15:49:42Z

+
+```elixir
+@impl true
+def some_callback(...) do


Suggested change

def some_callback(...) do

def hanlde_something(..., context, state) do

FelonEkonom · 2025-12-10T15:50:36Z

+Input pads can only be defined for Sinks, Filters and Endpoints, and output
+pads can only be defined for Sources, Filters and Endpoints.


What about bins?

FelonEkonom · 2025-12-10T16:00:40Z

+[`:spec`](`t:Membrane.Pipeline.Action.spec/0`) action linking the dynamic pad is
+being executed, then the pad is created dynamically and the component needs to
+handle this, in most cases with
+[`handle_pad_added/3`](`c:Membrane.Element.Base.handle_pad_added/3`).


please add an information that this callback is executed only for dynamic pads

FelonEkonom · 2025-12-10T16:01:51Z

+Another thing that's different are the pad references. The pad's name can't just
+be used as the pad's reference, because it wouldn't be unique. Dynamic pads are
+identified by [`Pad.ref/2`](`Membrane.Pad.ref/2`), that takes the pad's
+name and some unique reference as arguments. The result is a unique pad reference
+that is also associated with a given pad's specification through it's name.


Maybe you could mention that the reference of the specific pad can be known for the first time from hanlde_pad_added/3?

FelonEkonom · 2025-12-10T16:06:12Z

+Then the child with name `:some_child` would be stopped and removed from the
+pipeline, unlinking all it's pads. If an input pad of this child happened to be
+connected to our demuxer, then the
+[`handle_pad_removed/3`](`c:Membrane.Element.Base.handle_pad_removed/3`)
+would be called with a reference to the pad that was unlinked:
+
+```elixir
+@impl true
+def handle_pad_removed(Pad.ref(:output, unlinked_track_id), _context, state) do 
+  ...
+end
+```


Please make it more explicit that this callback is executed in demuxer

FelonEkonom · 2025-12-10T16:08:03Z

+
+### Removal
+
+Static pads are removed and unlinked once their component is terminated.


Suggested change

Static pads are removed and unlinked once their component is terminated.

Static pads are removed and unlinked only once their component is terminated.

FelonEkonom · 2025-12-10T16:09:24Z

+Because of this, each creation can be handled separately in
+[`handle_pad_added/3`](`c:Membrane.Element.Base.handle_pad_added/3`) callback,
+that's being called every time a new dynamic pad is linked, and therefore
+created.


Maybe we could explain how linking pads in the same spec as spawning a child affects its init -> setup -> playing flow? And that linking pads in the another spec doesn't affect it at all.

mat-hek · 2025-12-16T14:17:49Z

+something that can't be ignored. If you think about elements and bins (from now
+on referred to as components) as some
+sort of containers or boxes in which processing happens, then pads are the parts
+that with these containers are connected with. There are some constraints


Suggested change

that with these containers are connected with. There are some constraints

that these containers are connected with. There are some constraints

Let's pass this through grammarly/chat to fix typos like this

mat-hek

It would be nice to describe the lifecycle of bins pads - that they're linked extenrally and internally etc
A picture or two would be nice to have, for example for the bins part

mat-hek · 2025-12-19T09:50:35Z

+sent to whatever component is connected to the bin's newly created pad.
+
+It's worth noting that pads of bins are only an abstraction. When a component
+links with a bin, it actually links directly to the components inside of it to


Suggested change

links with a bin, it actually links directly to the components inside of it to

links with a bin, it actually links directly to one of the components inside the bin, to

Noarkhh added this to Smackore Nov 27, 2025

Noarkhh self-assigned this Nov 27, 2025

Noarkhh moved this to In Progress in Smackore Nov 27, 2025

Noarkhh added the no-changelog This label has to be added if changes from the PR are not meant to be placed in the CHANGELOG.md label Nov 27, 2025

Noarkhh force-pushed the dynamic-pads-guide branch 2 times, most recently from b7223f3 to 756d2e3 Compare November 27, 2025 17:32

Noarkhh requested review from FelonEkonom and varsill November 27, 2025 17:32

Noarkhh marked this pull request as ready for review December 3, 2025 17:07

Noarkhh requested a review from mat-hek as a code owner December 3, 2025 17:07

Noarkhh moved this from In Progress to In Review in Smackore Dec 3, 2025

Noarkhh changed the title ~~Start writing the pads guide~~ Pads guide Dec 3, 2025

mat-hek reviewed Dec 4, 2025

View reviewed changes

Noarkhh linked an issue Dec 4, 2025 that may be closed by this pull request

Identify and add missing explanations for Membrane concepts and use cases #1022

Closed

Noarkhh force-pushed the dynamic-pads-guide branch 2 times, most recently from 7548f9e to b8872bf Compare December 10, 2025 14:03

Noarkhh changed the base branch from master to elixir-update December 10, 2025 14:03

Noarkhh force-pushed the dynamic-pads-guide branch from b8872bf to 3262a1e Compare December 10, 2025 15:39

FelonEkonom reviewed Dec 10, 2025

View reviewed changes

mat-hek approved these changes Dec 16, 2025

View reviewed changes

mat-hek requested changes Dec 16, 2025

View reviewed changes

Noarkhh force-pushed the dynamic-pads-guide branch 2 times, most recently from 04135f3 to 487a251 Compare December 18, 2025 11:01

Noarkhh requested a review from mat-hek December 18, 2025 11:11

Base automatically changed from elixir-update to master December 18, 2025 15:58

mat-hek approved these changes Dec 19, 2025

View reviewed changes

Noarkhh added 3 commits December 19, 2025 13:46

Start writing the pads guide

ac62a53

Finish first version of the guide

6eb6210

Expand the guide

1d05350

Noarkhh added 5 commits December 19, 2025 13:46

Add pad lifecycle

fcc0a15

WIP

a9b2c10

Add section about bins, fix grammar

6a2df4f

Add demuxer diagram

d115a38

Apply reviewers suggestions

b4539b0

Noarkhh force-pushed the dynamic-pads-guide branch from 9841fae to b4539b0 Compare December 19, 2025 12:46

Noarkhh merged commit a1a88e4 into master Dec 19, 2025
5 of 6 checks passed

Noarkhh deleted the dynamic-pads-guide branch December 19, 2025 12:51

github-project-automation Bot moved this from In Review to Done in Smackore Dec 19, 2025

	* The accepted stream formats of the pads need to match.
	* The accepted stream formats of the pads cannot be disjoint.

	def some_callback(...) do
	def hanlde_something(..., context, state) do

		Input pads can only be defined for Sinks, Filters and Endpoints, and output
		pads can only be defined for Sources, Filters and Endpoints.


		### Removal

		Static pads are removed and unlinked once their component is terminated.

	Static pads are removed and unlinked once their component is terminated.
	Static pads are removed and unlinked only once their component is terminated.

	that with these containers are connected with. There are some constraints
	that these containers are connected with. There are some constraints

	links with a bin, it actually links directly to the components inside of it to
	links with a bin, it actually links directly to one of the components inside the bin, to

Uh oh!

Conversation

Noarkhh commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mat-hek left a comment

Choose a reason for hiding this comment

Uh oh!

Noarkhh commented Dec 10, 2025

Uh oh!

FelonEkonom left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FelonEkonom Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mat-hek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Noarkhh commented Nov 27, 2025 •

edited

Loading

FelonEkonom Dec 10, 2025 •

edited

Loading