Merge pull request #19 from membraneframework/add-vk-support-claude

Add optional Vulkan hardware acceleration for H.264 transcoding

Author: khamilowicz

README.md

@@ -17,7 +17,7 @@ The package can be installed by adding `membrane_transcoder_plugin` to your list
 ```elixir
 def deps do
   [
-    {:membrane_transcoder_plugin, "~> 0.3.3"}
+    {:membrane_transcoder_plugin, "~> 0.3.4"}
   ]
 end
 ```

examples/vp8_to_h264.exs

@@ -1,23 +1,40 @@
-Mix.install([
-  :membrane_file_plugin,
-  :membrane_ivf_plugin,
-  {:membrane_transcoder_plugin, path: __DIR__ |> Path.join("..") |> Path.expand()}
-])
+use_native = System.argv() |> Enum.member?("--native")
+
+vk_dep =
+  if use_native &&
+       match?({_, 0}, System.cmd("pkg-config", ["--exists", "vulkan"], stderr_to_stdout: true)) do
+    [{:membrane_vk_video_plugin, "~> 0.2.0"}]
+  else
+    []
+  end
+
+Mix.install(
+  vk_dep ++
+    [
+      :membrane_file_plugin,
+      :membrane_ivf_plugin,
+      {:membrane_transcoder_plugin, path: __DIR__ |> Path.join("..") |> Path.expand()}
+    ]
+)
 
 defmodule Example do
-  alias Membrane.RCPipeline
-  require Membrane.RCPipeline, as: RCPipeline
+  alias Membrane.{H264, RCPipeline}
+  require RCPipeline
+
   import Membrane.ChildrenSpec
 
-  def convert(input_file, output_file) do
+  def convert(input_file, output_file, native_acceleration) do
     pipeline = RCPipeline.start_link!()
 
     spec =
       child(%Membrane.File.Source{
         location: input_file
       })
       |> child(:deserializer, Membrane.IVF.Deserializer)
-      |> child(:transcoder, %Membrane.Transcoder{output_stream_format: Membrane.H264})
+      |> child(:transcoder, %Membrane.Transcoder{
+        output_stream_format: H264,
+        native_acceleration: native_acceleration
+      })
       |> child(:sink, %Membrane.File.Sink{location: output_file})
 
     RCPipeline.subscribe(pipeline, _any)
@@ -27,5 +44,25 @@ defmodule Example do
   end
 end
 
-File.mkdir("tmp")
-Example.convert(Path.join("./test/fixtures", "video_vp8.ivf"), Path.join("./tmp", "video.h264"))
+File.mkdir_p!("tmp")
+
+if use_native && !Membrane.Transcoder.vulkan_available?() do
+  raise "Vulkan is not available. Cannot run with --native flag."
+end
+
+acceleration = if use_native, do: :if_available, else: :never
+
+output_file = Path.join(__DIR__, "tmp/video.h264")
+
+if use_native do
+  IO.puts("Vulkan available: true")
+  IO.puts("Using native_acceleration: :if_available")
+end
+
+Example.convert(
+  Path.join(__DIR__, "../test/fixtures/video_vp8.ivf"),
+  output_file,
+  acceleration
+)
+
+IO.puts("Done. Output written to #{output_file}")

lib/transcoder.ex

@@ -26,6 +26,9 @@ defmodule Membrane.Transcoder do
   Now, the only supported stream parameters are:
   * `:pixel_format` in `Membrane.RawVideo`
   * `:alignment` and `:stream_structure` in `Membrane.H264` and `Membrane.H265`
+
+  When the `membrane_vk_video_plugin` dependency is present and Vulkan hardware is available,
+  H.264 encode/decode can be offloaded to the GPU by setting `native_acceleration: :if_available`.
   """
   use Membrane.Bin
 
@@ -139,6 +142,17 @@ defmodule Membrane.Transcoder do
 
                 If nil or not set, the input stream format won't be overriden.
                 """
+              ],
+              native_acceleration: [
+                spec: :never | :if_available,
+                default: :never,
+                description: """
+                Specifies whether to use Vulkan hardware acceleration for video transcoding.
+
+                Can be:
+                * `:never` - Always use software-based transcoding (default)
+                * `:if_available` - Use Vulkan acceleration when available on the system
+                """
               ]
 
   @impl true
@@ -155,12 +169,31 @@ defmodule Membrane.Transcoder do
       opts
       |> Map.from_struct()
       |> Map.merge(%{
-        input_stream_format: nil
+        input_stream_format: nil,
+        use_hardware_acceleration?: should_use_hardware_acceleration?(opts.native_acceleration)
       })
 
     {[spec: spec], state}
   end
 
+  defp should_use_hardware_acceleration?(:if_available), do: vulkan_available?()
+  defp should_use_hardware_acceleration?(_native_acceleration), do: false
+
+  @doc """
+  Returns `true` if the optional `membrane_vk_video_plugin` dependency is installed
+  and its modules can be loaded in the current runtime.
+
+  Note: a `true` result only confirms the plugin is loadable - it does not guarantee that the
+  host actually exposes Vulkan Video extensions with H.264 encode/decode capabilities. The
+  underlying plugin may still fail at runtime if the GPU/driver does not support them.
+  """
+  @spec vulkan_available?() :: boolean()
+  def vulkan_available?() do
+    Code.ensure_loaded?(Membrane.VKVideo.Decoder) and
+      Code.ensure_loaded?(Membrane.VKVideo.Encoder) and
+      Code.ensure_loaded?(Membrane.VKVideo.Native)
+  end
+
   defp maybe_plug_stream_format_changer(builder, nil), do: builder
 
   defp maybe_plug_stream_format_changer(builder, enforced_stream_format) do
@@ -187,7 +220,8 @@ defmodule Membrane.Transcoder do
       |> plug_transcoding(
         format,
         state.output_stream_format,
-        state.transcoding_policy
+        state.transcoding_policy,
+        state.use_hardware_acceleration?
       )
       |> get_child(:output_funnel)
 
@@ -232,15 +266,32 @@ defmodule Membrane.Transcoder do
     end
   end
 
-  defp plug_transcoding(builder, input_format, output_format, transcoding_policy)
+  defp plug_transcoding(
+         builder,
+         input_format,
+         output_format,
+         transcoding_policy,
+         _use_hardware_acceleration?
+       )
        when Audio.is_audio_format(input_format) do
     builder
     |> Audio.plug_audio_transcoding(input_format, output_format, transcoding_policy)
   end
 
-  defp plug_transcoding(builder, input_format, output_format, transcoding_policy)
+  defp plug_transcoding(
+         builder,
+         input_format,
+         output_format,
+         transcoding_policy,
+         use_hardware_acceleration?
+       )
        when Video.is_video_format(input_format) do
     builder
-    |> Video.plug_video_transcoding(input_format, output_format, transcoding_policy)
+    |> Video.plug_video_transcoding(
+      input_format,
+      output_format,
+      transcoding_policy,
+      use_hardware_acceleration?
+    )
   end
 end