Merge branch 'master' into migrate-to-github-actions

Author: khamilowicz

.claude-plugin/marketplace.json

@@ -1,21 +1,19 @@
 {
-  "name": "membrane-framework",
-  "description": "Membrane multimedia streaming framework skill for Elixir — provides architectural guidance, callback and action references, and code patterns for building pipelines, elements, and bins with membrane_core.",
+  "name": "membrane",
+  "description": "Skills for Membrane multimedia streaming and processing framework in Elixir.",
   "owner": {
     "name": "Software Mansion",
     "url": "https://github.com/membraneframework"
   },
   "plugins": [
     {
-      "name": "membrane-core",
-      "description": "Work with the Membrane multimedia streaming framework in Elixir. Provides architectural guidance, callback/action references, and code patterns for pipelines, elements, and bins.",
-      "version": "1.0.0",
+      "name": "membrane-framework",
+      "description": "AI coding skill for the Membrane Framework in Elixir. Build or debug Membrane multimedia processing and streaming pipelines and write custom Membrane Elements, Bins, and Filters.",
+      "version": "0.1.0",
       "source": "./",
       "category": "development",
       "homepage": "https://github.com/membraneframework/membrane_core",
-      "skills": [
-        "./skills/membrane-framework"
-      ]
+      "skills": ["./skills/membrane-framework"]
     }
   ]
 }

.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "membrane-framework",
+  "description": "AI coding skill  for the Membrane Framework in Elixir. Build or debug Membrane multimedia processing and streaming pipelines and write custom Membrane Elements, Bins, and Filters.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Software Mansion",
+    "url": "https://github.com/membraneframework"
+  },
+  "homepage": "https://github.com/membraneframework/membrane_core",
+  "skills": ["./skills/membrane-framework"]
+}

README.md

@@ -21,6 +21,8 @@ You can also [follow Membrane on X (Twitter)](https://twitter.com/ElixirMembrane
 
 If you already had a chance to use Membrane, we will be greateful if could fill out quick [survey](https://forms.gle/dgVDFHUD7CUGxU5VA) to help us improve framework and decide on what to do next.
 
+For people who write Membrane code with AI assistants, we ship a [dedicated skill](#membrane-skill-for-ai-assistants) for them.
+
 Membrane is maintained by [Software Mansion](https://swmansion.com).
 
 ## Quick start
@@ -71,6 +73,27 @@ To learn step-by-step what exactly happens here, follow [this tutorial](https://
 
 The best place to learn Membrane is the [membrane.stream/learn](https://membrane.stream/learn) website and the [membrane_demo](https://github.com/membraneframework/membrane_demo) repository. Try them out, then hack something exciting!
 
+## Membrane skill for AI assistants
+
+This repo includes [`skills/membrane-framework/SKILL.md`](skills/membrane-framework/SKILL.md), a structured guide that helps AI coding assistants write Membrane code.
+
+If you use [Claude Code](https://docs.claude.com/en/docs/claude-code), install it via the plugin system:
+
+```
+/plugin marketplace add membraneframework/membrane_core
+/plugin install membrane-framework@membrane
+```
+
+After install, Claude automatically pulls in the skill whenever you work on Membrane code (mentioning `Membrane.Pipeline`, `Bin`, `Filter`, `Pad`, etc).
+
+If you use [Cursor](https://www.cursor.com/), drop the skill into your project's rules directory:
+
+```
+mkdir -p .cursor/rules && curl -fL https://raw.githubusercontent.com/membraneframework/membrane_core/master/skills/membrane-framework/SKILL.md -o .cursor/rules/membrane-framework.mdc
+```
+
+For other agents, include the `SKILL.md` file directly in the agent's context. If your tool doesn't support that, copy the file's contents into whatever instruction file it reads.
+
 ## Structure of the framework
 
 The most basic media processing entities of Membrane are `Element`s. An element might be able, for example, to mux incoming audio and video streams into MP4, or play raw audio using your sound card. You can create elements yourself, or choose from the ones provided by the framework.

lib/membrane/core/subprocess_supervisor.ex

@@ -139,7 +139,8 @@ defmodule Membrane.Core.SubprocessSupervisor do
           name: {__MODULE__, name},
           type: :supervisor,
           child_pid: child_pid,
-          role: :subprocess_supervisor
+          role: :subprocess_supervisor,
+          pending_child_death: nil
         })
 
       {:reply, {:ok, child_pid}, state}
@@ -221,7 +222,7 @@ defmodule Membrane.Core.SubprocessSupervisor do
 
   defp do_handle_info({:EXIT, pid, reason}, state) do
     {data, state} = pop_in(state, [:children, pid])
-    handle_exit(data, reason, state)
+    state = handle_exit(data, reason, state)
 
     case state do
       %{parent_process: :exit_requested, children: children} when children == %{} ->
@@ -245,27 +246,33 @@ defmodule Membrane.Core.SubprocessSupervisor do
   end
 
   defp handle_exit(%{role: :subprocess_supervisor} = data, reason, state) do
-    case Map.fetch(state.children, data.child_pid) do
+    with :error <- Map.fetch(state.children, data.child_pid),
+         %{pending_child_death: {child_name, death_reason}} <- data do
+      Message.send(state.parent_component, :child_death, [child_name, death_reason])
+    else
       {:ok, child_data} ->
         raise "Subprocess supervisor failure #{inspect(child_data.name)}, reason: #{inspect(reason)}"
 
-      :error ->
+      _no_pending_death ->
         :ok
     end
+
+    state
   end
 
   defp handle_exit(%{role: :component} = data, reason, state) do
     Process.exit(data.supervisor_pid, :shutdown)
-    Message.send(state.parent_component, :child_death, [data.name, reason])
+
+    put_in(state.children[data.supervisor_pid].pending_child_death, {data.name, reason})
   end
 
-  defp handle_exit(%{role: :utility}, _reason, _state) do
-    :ok
+  defp handle_exit(%{role: :utility}, _reason, state) do
+    state
   end
 
   # Clause handling the case when child start function returns error
   # and we don't know its PID, but we still receive exit signal from it.
-  defp handle_exit(nil, _reason, _state) do
-    :ok
+  defp handle_exit(nil, _reason, state) do
+    state
   end
 end

mix.exs

@@ -108,19 +108,31 @@ defmodule Membrane.Mixfile do
         Membrane.RCMessage
       ],
       groups_for_modules: groups_for_modules(),
-      groups_for_extras: groups_for_extras()
+      groups_for_extras: groups_for_extras(),
+      before_closing_head_tag: &before_closing_head_tag/1
     ]
   end
 
+  # Hides the AI skill page from the sidebar while keeping it published and linked from llms.txt.
+  defp before_closing_head_tag(:html) do
+    """
+    <style>
+      #sidebar li:has(> a[href$="skill.html"]),
+      #sidebar a[href$="skill.html"] { display: none; }
+    </style>
+    """
+  end
+
+  defp before_closing_head_tag(_format), do: ""
+
   defp packages_in_ecosystem do
     {packages, _bindings} = Code.eval_file(@hex_packages_path)
     packages
   end
 
   defp extras do
     [
-      {"skills/membrane-framework/SKILL.md",
-       [title: "Membrane Framework AI Skill", hidden: true]},
+      {"skills/membrane-framework/SKILL.md", [title: "Membrane Framework AI Skill"]},
       "README.md",
       {"guides/llms/packages_list.md",
        [title: "Packages in the Membrane ecosystem", hidden: true]},

skills/membrane-framework/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: membrane-framework
 description: Work with the Membrane multimedia streaming framework in Elixir. Use this skill whenever the user is building or debugging Membrane pipelines, writing custom Elements, Bins, or Filters, connecting pads, implementing callbacks, handling stream formats or EOS, or asking about Membrane architecture. Trigger on any mention of membrane_core, membrane, membrane framework, Membrane.Pipeline, Membrane.Sink, Membrane.Source, Membrane.Filter, Membrane.Endpoint, Membrane.Bin, Membrane.Pad, or multimedia streaming in an Elixir context — even if the user doesn't say "Membrane" explicitly but is clearly working on this codebase.
+globs: ["**/*.ex", "**/*.exs"]
+alwaysApply: false
 ---
 
 # Membrane Framework
 
-**Package**: `membrane_core` ~> 1.2 | **Docs**: https://hexdocs.pm/membrane_core/ | **Module index**: https://hexdocs.pm/membrane_core/llms.txt | **Demos**: https://github.com/membraneframework/membrane_demo | **All packages**: [packages_list.md](../../guides/llms/packages_list.md)
+**Package**: `membrane_core` ~> 1.3 | **Docs**: https://hexdocs.pm/membrane_core/ | **Module index**: https://hexdocs.pm/membrane_core/llms.txt | **Demos**: https://github.com/membraneframework/membrane_demo | **All packages**: [packages_list.md](../../guides/llms/packages_list.md)
 
 ## How to Approach Tasks
 

test/membrane/integration/callbacks_test.exs

@@ -121,4 +121,61 @@ defmodule Membrane.Integration.CallbacksTest do
       {:DOWN, _ref, _process, ^pipeline, _reason} -> :ok
     end
   end
+
+  defmodule BinWithTwoChildren do
+    use Membrane.Bin
+
+    alias Membrane.Integration.CallbacksTest.PadlessElement
+
+    @impl true
+    def handle_init(_ctx, _opts) do
+      {[spec: [child(:child_a, PadlessElement), child(:child_b, PadlessElement)]], %{}}
+    end
+
+    @impl true
+    def handle_playing(ctx, state) do
+      {[notify_parent: {:children_pids, ctx.children.child_a.pid, ctx.children.child_b.pid}],
+       state}
+    end
+  end
+
+  defmodule BinTerminationPipeline do
+    use Membrane.Pipeline
+
+    @impl true
+    def handle_child_notification({:children_pids, a_pid, b_pid}, :bin, _ctx, state) do
+      {[], %{state | a_pid: a_pid, b_pid: b_pid}}
+    end
+
+    @impl true
+    def handle_child_terminated(:bin, _ctx, state) do
+      send(
+        state.test_pid,
+        {:terminated, Process.alive?(state.a_pid), Process.alive?(state.b_pid)}
+      )
+
+      {[], state}
+    end
+  end
+
+  test "handle_child_terminated fires only after bin's subprocess_supervisor dies, ensuring bin's children are already dead" do
+    pipeline =
+      Testing.Pipeline.start_link_supervised!(
+        module: BinTerminationPipeline,
+        custom_args: %{test_pid: self(), a_pid: nil, b_pid: nil}
+      )
+
+    Testing.Pipeline.execute_actions(pipeline,
+      spec: {child(:bin, BinWithTwoChildren), group: :bin_group, crash_group_mode: :temporary}
+    )
+
+    assert_pipeline_notified(pipeline, :bin, {:children_pids, _a_pid, _b_pid})
+
+    Testing.Pipeline.get_child_pid!(pipeline, :bin)
+    |> Process.exit(:crash)
+
+    assert_receive {:terminated, false, false}, 1000
+
+    Testing.Pipeline.terminate(pipeline)
+  end
 end