Add mulaw encoder and decoder (#8)

samrat · web-flow · commit c48cf0593d23 · 2025-04-29T14:34:26.000+02:00
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 
 This package provides G.711 audio decoder, encoder and parser. The decoder and encoder are based on [ffmpeg](https://www.ffmpeg.org).
 
-At the moment, only G.711 A-law is supported.
+Both G.711 A-law (PCMA) and μ-law (PCMU) formats are supported.
 
 It is part of [Membrane Multimedia Framework](https://membrane.stream).
 
diff --git a/c_src/membrane_g711_ffmpeg_plugin/decoder.c b/c_src/membrane_g711_ffmpeg_plugin/decoder.c
@@ -8,7 +8,7 @@ void handle_destroy_state(UnifexEnv *env, State *state) {
   }
 }
 
-UNIFEX_TERM create(UnifexEnv *env) {
+UNIFEX_TERM create(UnifexEnv *env, char *encoding) {
   UNIFEX_TERM res;
   State *state = unifex_alloc_state(env);
   state->codec_ctx = NULL;
@@ -18,7 +18,18 @@ UNIFEX_TERM create(UnifexEnv *env) {
 #if (LIBAVCODEC_VERSION_MAJOR < 58)
   avcodec_register_all();
 #endif
-  const AVCodec *codec = avcodec_find_decoder(AV_CODEC_ID_PCM_ALAW);
+
+  enum AVCodecID codec_id;
+  if (strcmp(encoding, "PCMA") == 0) {
+    codec_id = AV_CODEC_ID_PCM_ALAW;
+  } else if (strcmp(encoding, "PCMU") == 0) {
+    codec_id = AV_CODEC_ID_PCM_MULAW;
+  } else {
+    res = create_result_error(env, "encoding");
+    goto exit_create;
+  }
+
+  const AVCodec *codec = avcodec_find_decoder(codec_id);
   if (!codec) {
     res = create_result_error(env, "nocodec");
     goto exit_create;
diff --git a/c_src/membrane_g711_ffmpeg_plugin/decoder.spec.exs b/c_src/membrane_g711_ffmpeg_plugin/decoder.spec.exs
@@ -2,7 +2,7 @@ module Membrane.G711.FFmpeg.Decoder.Native
 
 state_type "State"
 
-spec create() :: {:ok :: label, state} | {:error :: label, reason :: atom}
+spec create(encoding :: atom) :: {:ok :: label, state} | {:error :: label, reason :: atom}
 
 spec decode(payload, state) ::
        {:ok :: label, frames :: [payload]}
diff --git a/c_src/membrane_g711_ffmpeg_plugin/encoder.c b/c_src/membrane_g711_ffmpeg_plugin/encoder.c
@@ -8,7 +8,7 @@ void handle_destroy_state(UnifexEnv *env, State *state) {
   }
 }
 
-UNIFEX_TERM create(UnifexEnv *env, char *sample_fmt) {
+UNIFEX_TERM create(UnifexEnv *env, char *sample_fmt, char *encoding) {
   UNIFEX_TERM res;
   State *state = unifex_alloc_state(env);
   state->codec_ctx = NULL;
@@ -18,7 +18,18 @@ UNIFEX_TERM create(UnifexEnv *env, char *sample_fmt) {
 #if (LIBAVCODEC_VERSION_MAJOR < 58)
   avcodec_register_all();
 #endif
-  const AVCodec *codec = avcodec_find_encoder(AV_CODEC_ID_PCM_ALAW);
+
+  enum AVCodecID codec_id;
+  if (strcmp(encoding, "PCMA") == 0) {
+    codec_id = AV_CODEC_ID_PCM_ALAW;
+  } else if (strcmp(encoding, "PCMU") == 0) {
+    codec_id = AV_CODEC_ID_PCM_MULAW;
+  } else {
+    res = create_result_error(env, "encoding");
+    goto exit_create;
+  }
+
+  const AVCodec *codec = avcodec_find_encoder(codec_id);
   if (!codec) {
     res = create_result_error(env, "nocodec");
     goto exit_create;
diff --git a/c_src/membrane_g711_ffmpeg_plugin/encoder.spec.exs b/c_src/membrane_g711_ffmpeg_plugin/encoder.spec.exs
@@ -2,7 +2,7 @@ module Membrane.G711.FFmpeg.Encoder.Native
 
 state_type "State"
 
-spec create(sample_fmt :: atom) ::
+spec create(sample_fmt :: atom, encoding :: atom) ::
        {:ok :: label, state} | {:error :: label, reason :: atom}
 
 spec encode(payload, state) ::
diff --git a/examples/README.md b/examples/README.md
@@ -1,3 +1,11 @@
 # Membrane G.711 FFmpeg plugin examples
 
 To run, execute `elixir <example>`, e.g. `elixir decode_example.exs`.
+
+## A-law examples
+- `encode_example.exs` - Encodes a raw audio file to G.711 A-law format
+- `decode_example.exs` - Decodes a G.711 A-law file to raw audio
+
+## μ-law examples
+- `encode_mulaw_example.exs` - Encodes a raw audio file to G.711 μ-law format
+- `decode_mulaw_example.exs` - Decodes a G.711 μ-law file to raw audio
diff --git a/examples/decode_mulaw_example.exs b/examples/decode_mulaw_example.exs
@@ -0,0 +1,49 @@
+# Decoding example (μ-law)
+#
+# The following pipeline takes a G.711 μ-law file and decodes it to the raw audio.
+
+Logger.configure(level: :info)
+
+Mix.install([
+  {:membrane_g711_ffmpeg_plugin,
+   path: __DIR__ |> Path.join("..") |> Path.expand(), override: true},
+  :membrane_file_plugin,
+  :req
+])
+
+# For this example, we'll use a local file created by encode_mulaw_example.exs
+# Alternatively, you could download a μ-law sample file from a URL
+
+defmodule DecodingMulaw.Pipeline do
+  use Membrane.Pipeline
+
+  @impl true
+  def handle_init(_ctx, _opts) do
+    structure =
+      child(:source, %Membrane.File.Source{chunk_size: 40_960, location: "output.ul"})
+      |> child(:decoder, %Membrane.G711.FFmpeg.Decoder{encoding: :PCMU})
+      |> child(:sink, %Membrane.File.Sink{location: "output_from_mulaw.raw"})
+
+    {[spec: structure], %{}}
+  end
+
+  @impl true
+  def handle_element_end_of_stream(:sink, _pad, _ctx, state) do
+    {[terminate: :shutdown], state}
+  end
+
+  @impl true
+  def handle_element_end_of_stream(_child, _pad, _ctx, state) do
+    {[], state}
+  end
+end
+
+# Start and monitor the pipeline
+{:ok, _supervisor_pid, pipeline_pid} = Membrane.Pipeline.start_link(DecodingMulaw.Pipeline)
+ref = Process.monitor(pipeline_pid)
+
+# Wait for the pipeline to finish
+receive do
+  {:DOWN, ^ref, :process, _pipeline_pid, _reason} ->
+    System.stop()
+end
diff --git a/examples/encode_mulaw_example.exs b/examples/encode_mulaw_example.exs
@@ -0,0 +1,62 @@
+# Encoding example (μ-law)
+#
+# The following pipeline takes a raw audio file and encodes it as G.711 μ-law.
+
+Logger.configure(level: :info)
+
+Mix.install([
+  {:membrane_g711_ffmpeg_plugin,
+   path: __DIR__ |> Path.join("..") |> Path.expand(), override: true},
+  :membrane_raw_audio_parser_plugin,
+  :membrane_raw_audio_format,
+  :membrane_file_plugin,
+  :req
+])
+
+raw_audio =
+  Req.get!(
+    "https://raw.githubusercontent.com/membraneframework/static/gh-pages/samples/beep-s16le-8kHz-mono.raw"
+  ).body
+
+File.write!("input.raw", raw_audio)
+
+defmodule EncodingMulaw.Pipeline do
+  use Membrane.Pipeline
+
+  @impl true
+  def handle_init(_ctx, _opts) do
+    structure =
+      child(:source, %Membrane.File.Source{chunk_size: 40_960, location: "input.raw"})
+      |> child(:parser, %Membrane.RawAudioParser{
+        stream_format: %Membrane.RawAudio{
+          sample_format: :s16le,
+          sample_rate: 8000,
+          channels: 1
+        }
+      })
+      |> child(:encoder, %Membrane.G711.FFmpeg.Encoder{encoding: :PCMU})
+      |> child(:sink, %Membrane.File.Sink{location: "output.ul"})
+
+    {[spec: structure], %{}}
+  end
+
+  @impl true
+  def handle_element_end_of_stream(:sink, _pad, _ctx, state) do
+    {[terminate: :shutdown], state}
+  end
+
+  @impl true
+  def handle_element_end_of_stream(_child, _pad, _ctx, state) do
+    {[], state}
+  end
+end
+
+# Start and monitor the pipeline
+{:ok, _supervisor_pid, pipeline_pid} = Membrane.Pipeline.start_link(EncodingMulaw.Pipeline)
+ref = Process.monitor(pipeline_pid)
+
+# Wait for the pipeline to finish
+receive do
+  {:DOWN, ^ref, :process, _pipeline_pid, _reason} ->
+    System.stop()
+end
diff --git a/lib/membrane_g711_ffmpeg/decoder.ex b/lib/membrane_g711_ffmpeg/decoder.ex
@@ -2,7 +2,7 @@ defmodule Membrane.G711.FFmpeg.Decoder do
   @moduledoc """
   Membrane element that decodes audio in G711 format. It is backed by decoder from FFmpeg.
 
-  At the moment, only A-law is supported.
+  A-law and μ-law encoding formats are supported.
   """
 
   use Membrane.Filter
@@ -14,20 +14,34 @@ defmodule Membrane.G711.FFmpeg.Decoder do
   alias Membrane.G711.FFmpeg.Common
   alias Membrane.{G711, RawAudio, RemoteStream}
 
-  def_input_pad :input,
+  def_options(
+    encoding: [
+      spec: :PCMA | :PCMU,
+      description: "G.711 encoding to decode (A-law or μ-law)",
+      default: :PCMA
+    ]
+  )
+
+  def_input_pad(:input,
     flow_control: :auto,
-    accepted_format: any_of(%RemoteStream{}, %G711{encoding: :PCMA})
+    accepted_format:
+      any_of(%RemoteStream{}, %G711{encoding: encoding} when encoding in [:PCMA, :PCMU])
+  )
 
-  def_output_pad :output,
+  def_output_pad(:output,
     flow_control: :auto,
     accepted_format: %RawAudio{
       channels: G711.num_channels(),
       sample_rate: G711.sample_rate()
     }
+  )
 
   @impl true
-  def handle_init(_ctx, _opts) do
-    state = %{decoder_ref: nil}
+  def handle_init(_ctx, opts) do
+    state = %{
+      decoder_ref: nil,
+      encoding: opts.encoding
+    }
 
     {[], state}
   end
@@ -44,9 +58,15 @@ defmodule Membrane.G711.FFmpeg.Decoder do
   end
 
   @impl true
-  def handle_stream_format(:input, _stream_format, _ctx, state) do
+  def handle_stream_format(:input, stream_format, _ctx, state) do
+    encoding =
+      case stream_format do
+        %G711{encoding: encoding} -> encoding
+        %RemoteStream{} -> state.encoding
+      end
+
     with buffers <- flush_decoder_if_exists(state),
-         {:ok, new_decoder_ref} <- Native.create() do
+         {:ok, new_decoder_ref} <- Native.create(encoding) do
       stream_format = generate_stream_format(new_decoder_ref)
       actions = buffers ++ [stream_format: {:output, stream_format}]
       {actions, %{state | decoder_ref: new_decoder_ref}}
diff --git a/lib/membrane_g711_ffmpeg/encoder.ex b/lib/membrane_g711_ffmpeg/encoder.ex
@@ -1,6 +1,6 @@
 defmodule Membrane.G711.FFmpeg.Encoder do
   @moduledoc """
-  Membrane element that encodes raw audio frames to G711 format (only A-law is supported).
+  Membrane element that encodes raw audio frames to G711 format (A-law and μ-law are supported).
   It is backed by encoder from FFmpeg.
 
   The element expects that each received buffer has whole samples, so the parser
@@ -19,21 +19,34 @@ defmodule Membrane.G711.FFmpeg.Encoder do
   alias Membrane.G711.FFmpeg.Common
   alias Membrane.{G711, RawAudio}
 
-  def_input_pad :input,
+  def_options(
+    encoding: [
+      spec: :PCMA | :PCMU,
+      description: "G.711 encoding to use (A-law or μ-law)",
+      default: :PCMA
+    ]
+  )
+
+  def_input_pad(:input,
     flow_control: :auto,
     accepted_format: %RawAudio{
       channels: G711.num_channels(),
       sample_rate: G711.sample_rate(),
       sample_format: :s16le
     }
+  )
 
-  def_output_pad :output,
+  def_output_pad(:output,
     flow_control: :auto,
-    accepted_format: %G711{encoding: :PCMA}
+    accepted_format: %G711{encoding: encoding} when encoding in [:PCMA, :PCMU]
+  )
 
   @impl true
-  def handle_init(_ctx, _opts) do
-    state = %{encoder_ref: nil}
+  def handle_init(_ctx, opts) do
+    state = %{
+      encoder_ref: nil,
+      encoding: opts.encoding
+    }
 
     {[], state}
   end
@@ -52,7 +65,8 @@ defmodule Membrane.G711.FFmpeg.Encoder do
   @impl true
   def handle_stream_format(:input, stream_format, _ctx, state) do
     with buffers <- flush_encoder_if_exists(state),
-         {:ok, new_encoder_ref} <- Native.create(stream_format.sample_format) do
+         {:ok, new_encoder_ref} <-
+           Native.create(stream_format.sample_format, state.encoding) do
       stream_format = generate_stream_format(state)
       actions = buffers ++ [stream_format: {:output, stream_format}]
       {actions, %{state | encoder_ref: new_encoder_ref}}
@@ -78,7 +92,7 @@ defmodule Membrane.G711.FFmpeg.Encoder do
     end
   end
 
-  defp generate_stream_format(_state) do
-    %G711{encoding: :PCMA}
+  defp generate_stream_format(%{encoding: encoding}) do
+    %G711{encoding: encoding}
   end
 end
diff --git a/lib/membrane_g711_ffmpeg/parser.ex b/lib/membrane_g711_ffmpeg/parser.ex
