Rework RTP API (#58)

* Flatten RTP API

* Support more values in the CLI, add more docs

* Add IP parsing

Author: Noarkhh

README.md

@@ -100,16 +100,35 @@ Make sure you have [Elixir](https://elixir-lang.org/) installed. The first call
 
 ## CLI
 
-The CLI API is similar to the Elixir API, for example:
+The CLI API is a direct mapping of the Elixir API:
+  * `:input` and `:output` options of `Boombox.run/2` are mapped to `-i` and `-o` CLI arguments respectively.
+  * Option names, like `:some_option`, are mapped to CLI arguments by removing the colon, adding a leading double hyphen and replacing all underscores with hyphens, like `--some-option`.
+  * Option values mappings depend on the option's type:
+    - String values, like `"some_value"`, are mapped to CLI arguments by stripping the quotes, like `some_value`.
+    - Atom values, like `:some_value`, are mapped to CLI arguments by stripping the leading colon, like `some_value`.
+    - Integer values are identical in elixir and CLI.
+    - Binary values, like `<<161, 63>>`, are represented in CLI as their representation in base 16, like `a13f`.
+
+For example:
 
 ```elixir
 Boombox.run(input: "file.mp4", output: {:webrtc, "ws://localhost:8830"})
+Boombox.run(
+  input:
+    {:rtp,
+     port: 50001,
+     audio_encoding: :AAC,
+     audio_specific_config: <<161, 63>>,
+     aac_bitrate_mode: :hbr},
+  output: "index.m3u8"
+)
 ```
 
-is equivalent to:
+are equivalent to:
 
 ```sh
 ./boombox -i file.mp4 -o --webrtc ws://localhost:8830
+./boombox -i --rtp --port 50001 --audio-encoding AAC --audio-specific-config a13f --aac-bitrate-mode hbr -o index.m3u8
 ```
 
 It's also possible to pass an `.exs` script:

examples.livemd

@@ -542,7 +542,7 @@ rtp_port = 50001
 t =
   Task.async(fn ->
     Boombox.run(
-      input: {:rtp, port: rtp_port, track_configs: [audio: [encoding: :OPUS], video: [encoding: :H264]]},
+      input: {:rtp, port: rtp_port, audio_encoding: :OPUS, video_encoding: :H264},
       output: "#{out_dir}/index.m3u8"
     )
   end)

lib/boombox.ex

@@ -22,54 +22,47 @@ defmodule Boombox do
         ]
 
   @typedoc """
-  Some encodings can/must be accompanied with encoding specific parameters:
-    * AAC:
-      - bitrate_mode - MUST be provided for both RTP input and output. Defines which mode should be assumed/set when depayloading/payloading.
-      - audio_specific_config - MUST be provided for RTP input. Contains crucial information about the stream and has to be obtained from a side channel.
-    * H264 and H265:
-      - vpss (H265 only), ppss, spss - MAY be provided for RTP input. picture and sequence parameter sets, could be obtained from a side channel. They contain information about the encoded stream.
+  When configuring a track for a media type (video or audio), the following options are used:
+    * <media_type>_encoding - MUST be provided to configure given media type. Some options are encoding-specific. Currently supported encodings are: AAC, Opus, H264, H265.
+    * <media_type>_payload_type, <media_type>_clock rate - MAY be provided. If not, an unofficial default will be used.
+  The following encoding-specific parameters are available for both RTP input and output:
+    * aac_bitrate_mode - MUST be provided for AAC encoding. Defines which mode should be assumed/set when depayloading/payloading.
   """
-  @type rtp_encoding_specific_params ::
-          {:AAC, [{:bitrate_mode, RTP.AAC.Utils.mode()} | {:audio_specific_config, binary()}]}
-          | {:H264, [{:ppss, [binary()]} | {:spss, [binary()]}]}
-          | {:H265, [{:vpss, [binary()]} | {:ppss, [binary()]} | {:spss, [binary()]}]}
+  @type common_rtp_opt ::
+          {:video_encoding, RTP.encoding_name()}
+          | {:video_payload_type, RTP.payload_type()}
+          | {:video_clock_rate, RTP.clock_rate()}
+          | {:audio_encoding, RTP.encoding_name()}
+          | {:audio_payload_type, RTP.payload_type()}
+          | {:audio_clock_rate, RTP.clock_rate()}
+          | {:aac_bitrate_mode, RTP.AAC.Utils.mode()}
 
   @typedoc """
-  For each media type the following parameters are specified:
-    * encoding - MUST be provided for both RTP input and output, some encodings require additional parameters, see `rtp_encoding_specific_params/0`.
-    * payload_type, clock rate - MAY be provided for both RTP input and output, if not, then an unofficial default will be used.
-  """
-  @type rtp_track_config :: [
-          {:encoding, RTP.encoding_name() | rtp_encoding_specific_params()}
-          | {:payload_type, RTP.payload_type()}
-          | {:clock_rate, RTP.clock_rate()}
-        ]
+  In order to configure a RTP input a receiving port MUST be provided and the media that will be received
+  MUST be configured. Media configuration is explained further in `t:common_rtp_opt/0`.
 
-  @typedoc """
-  In order to configure RTP input both a receiving port and media configurations must be provided.
-  At least one media type needs to be configured.
+  The following encoding-specific parameters are available for RTP input:
+    * audio_specific_config - MUST be provided for AAC encoding. Contains crucial information about the stream and has to be obtained from a side channel.
+    * vps (H265 only), pps, sps - MAY be provided for H264 or H265 encodings. Parameter sets, could be obtained from a side channel. They contain information about the encoded stream.
   """
   @type in_rtp_opts :: [
-          {:port, :inet.port_number()}
-          | {:track_configs,
-             [
-               {:audio, rtp_track_config()}
-               | {:video, rtp_track_config()}
-             ]}
+          common_rtp_opt()
+          | {:port, :inet.port_number()}
+          | {:audio_specific_config, binary()}
+          | {:vps, binary()}
+          | {:pps, binary()}
+          | {:sps, binary()}
         ]
 
   @typedoc """
-  In order to configure RTP output the destination and media configurations must be provided.
-  At least one media type needs to be configured.
+  In order to configure a RTP output the target port and address MUST be provided (can be provided in `:target` option as a `<address>:<port>` string)
+  and the media that will be sent MUST be configured. Media configuration is explained further in `t:common_rtp_opt/0`.
   """
   @type out_rtp_opts :: [
-          {:address, :inet.ip_address()}
+          common_rtp_opt()
+          | {:address, :inet.ip_address() | String.t()}
           | {:port, :inet.port_number()}
-          | {:track_configs,
-             [
-               {:audio, rtp_track_config()}
-               | {:video, rtp_track_config()}
-             ]}
+          | {:target, String.t()}
         ]
 
   @type input ::

lib/boombox/rtp.ex

@@ -7,34 +7,31 @@ defmodule Boombox.RTP do
   alias Boombox.Pipeline.Ready
   alias Membrane.RTP
 
-  @required_opts %{
-    input: [:port, :track_configs],
-    output: [:address, :port, :track_configs]
-  }
+  @supported_encodings [audio: [:AAC, :Opus], video: [:H264, :H265]]
 
-  @required_encoding_specific_params %{
+  @encoding_specific_params_specs %{
     input: %{
-      AAC: [bitrate_mode: [require?: true], audio_specific_config: [require?: true]],
-      H264: [ppss: [require?: false, default: []], spss: [require?: false, default: []]],
+      AAC: [aac_bitrate_mode: [require?: true], audio_specific_config: [require?: true]],
+      H264: [pps: [require?: false, default: nil], sps: [require?: false, default: nil]],
       H265: [
-        vpss: [require?: false, default: []],
-        ppss: [require?: false, default: []],
-        spss: [require?: false, default: []]
+        vps: [require?: false, default: nil],
+        pps: [require?: false, default: nil],
+        sps: [require?: false, default: nil]
       ]
     },
     output: %{
-      AAC: [bitrate_mode: [require?: true]]
+      AAC: [aac_bitrate_mode: [require?: true]]
     }
   }
 
   @type parsed_input_encoding_specific_params ::
-          %{bitrate_mode: RTP.AAC.Utils.mode(), audio_specific_config: binary()}
-          | %{:ppss => [binary()], :spss => [binary()]}
-          | %{:vpss => [binary()], :ppss => [binary()], :spss => [binary()]}
+          %{aac_bitrate_mode: RTP.AAC.Utils.mode(), audio_specific_config: binary()}
+          | %{vps: binary() | nil, pps: binary() | nil, sps: binary() | nil}
+          | %{pps: binary() | nil, sps: binary() | nil}
           | %{}
 
   @type parsed_output_encoding_specific_params ::
-          %{bitrate_mode: RTP.AAC.Utils.mode()}
+          %{aac_bitrate_mode: RTP.AAC.Utils.mode()}
           | %{}
 
   @type parsed_input_track_config :: %{
@@ -84,13 +81,13 @@ defmodule Boombox.RTP do
         {depayloader, parser} =
           case track_config.encoding_name do
             :H264 ->
-              ppss = track_config.encoding_specific_params.ppss
-              spss = track_config.encoding_specific_params.spss
+              ppss = List.wrap(track_config.encoding_specific_params.pps)
+              spss = List.wrap(track_config.encoding_specific_params.sps)
               {Membrane.RTP.H264.Depayloader, %Membrane.H264.Parser{ppss: ppss, spss: spss}}
 
             :AAC ->
               audio_specific_config = track_config.encoding_specific_params.audio_specific_config
-              bitrate_mode = track_config.encoding_specific_params.bitrate_mode
+              bitrate_mode = track_config.encoding_specific_params.aac_bitrate_mode
 
               {%Membrane.RTP.AAC.Depayloader{mode: bitrate_mode},
                %Membrane.AAC.Parser{audio_specific_config: audio_specific_config}}
@@ -99,9 +96,9 @@ defmodule Boombox.RTP do
               {Membrane.RTP.Opus.Depayloader, Membrane.Opus.Parser}
 
             :H265 ->
-              vpss = Map.get(track_config.encoding_specific_params, :vpss, [])
-              ppss = Map.get(track_config.encoding_specific_params, :ppss, [])
-              spss = Map.get(track_config.encoding_specific_params, :spss, [])
+              vpss = List.wrap(track_config.encoding_specific_params.vps)
+              ppss = List.wrap(track_config.encoding_specific_params.pps)
+              spss = List.wrap(track_config.encoding_specific_params.sps)
 
               {Membrane.RTP.H265.Depayloader,
                %Membrane.H265.Parser{vpss: vpss, ppss: ppss, spss: spss}}
@@ -151,7 +148,7 @@ defmodule Boombox.RTP do
               {%Membrane.AAC{encapsulation: :none},
                %Membrane.AAC.Parser{out_encapsulation: :none},
                %Membrane.RTP.AAC.Payloader{
-                 mode: track_config.encoding_specific_params.bitrate_mode,
+                 mode: track_config.encoding_specific_params.aac_bitrate_mode,
                  frames_per_packet: 1
                }}
 
@@ -189,42 +186,85 @@ defmodule Boombox.RTP do
   @spec validate_and_parse_options(:input, Boombox.in_rtp_opts()) :: parsed_in_opts()
   @spec validate_and_parse_options(:output, Boombox.out_rtp_opts()) :: parsed_out_opts()
   defp validate_and_parse_options(direction, opts) do
-    Enum.each(@required_opts[direction], fn required_option ->
-      unless Keyword.has_key?(opts, required_option) do
-        raise "Required option #{inspect(required_option)} not present in passed RTP options"
-      end
-    end)
+    transport_opts =
+      case direction do
+        :input ->
+          if Keyword.has_key?(opts, :port) do
+            %{port: opts[:port]}
+          else
+            raise "Receiving port not specified in RTP options"
+          end
 
-    if opts[:track_configs] == [] do
-      raise "No RTP media configured"
-    end
+        :output ->
+          parse_output_target(opts)
+      end
 
     parsed_track_configs =
-      Map.new(opts[:track_configs], fn {media_type, track_config} ->
-        {media_type, validate_and_parse_track_config!(direction, track_config)}
+      [:audio, :video]
+      |> Enum.filter(fn
+        :video -> opts[:video_encoding] != nil
+        :audio -> opts[:audio_encoding] != nil
+      end)
+      |> Map.new(fn media_type ->
+        {media_type, validate_and_parse_track_config(direction, media_type, opts)}
       end)
 
-    case direction do
-      :input ->
-        %{port: opts[:port], track_configs: parsed_track_configs}
+    if parsed_track_configs == %{} do
+      raise "No RTP media configured"
+    end
+
+    Map.put(transport_opts, :track_configs, parsed_track_configs)
+  end
 
-      :output ->
-        %{address: opts[:address], port: opts[:port], track_configs: parsed_track_configs}
+  @spec parse_output_target(
+          target: String.t(),
+          address: :inet.ip4_address() | String.t(),
+          port: :inet.port_number()
+        ) :: %{address: :inet.ip4_address(), port: :inet.port_number()}
+  defp parse_output_target(opts) do
+    case Map.new(opts) do
+      %{target: target} ->
+        [address_string, port_string] = String.split(target, ":")
+        {:ok, address} = :inet.parse_ipv4_address(String.to_charlist(address_string))
+        %{address: address, port: String.to_integer(port_string)}
+
+      %{address: address, port: port} when is_binary(address) ->
+        {:ok, address} = :inet.parse_ipv4_address(String.to_charlist(address))
+        %{address: address, port: port}
+
+      %{address: address, port: port} when is_tuple(address) ->
+        %{address: address, port: port}
+
+      _invalid_target ->
+        raise "RTP output target address and port not specified"
     end
   end
 
-  @spec validate_and_parse_track_config!(:input, Boombox.rtp_track_config()) ::
+  @spec validate_and_parse_track_config(:input, :video | :audio, Boombox.in_rtp_opts()) ::
           parsed_input_track_config()
-  @spec validate_and_parse_track_config!(:output, Boombox.rtp_track_config()) ::
+  @spec validate_and_parse_track_config(:output, :video | :audio, Boombox.out_rtp_opts()) ::
           parsed_output_track_config()
-  defp validate_and_parse_track_config!(direction, track_config) do
-    {encoding_name, encoding_specific_params} =
-      validate_and_parse_encoding!(direction, track_config[:encoding])
+  defp validate_and_parse_track_config(direction, media_type, opts) do
+    {encoding_name, payload_type, clock_rate} =
+      case media_type do
+        :audio -> {opts[:audio_encoding], opts[:audio_payload_type], opts[:audio_clock_rate]}
+        :video -> {opts[:video_encoding], opts[:video_payload_type], opts[:video_clock_rate]}
+      end
 
-    track_config = Keyword.put(track_config, :encoding_name, encoding_name)
+    if encoding_name not in @supported_encodings[media_type] do
+      raise "Encoding #{inspect(encoding_name)} for #{inspect(media_type)} media type not supported"
+    end
 
-    %{payload_type: payload_type, clock_rate: clock_rate} =
-      RTP.PayloadFormat.resolve(track_config)
+    %{
+      payload_format: %RTP.PayloadFormat{encoding_name: encoding_name},
+      payload_type: payload_type,
+      clock_rate: clock_rate
+    } =
+      RTP.PayloadFormat.resolve(
+        encoding_name: encoding_name,
+        payload_type: payload_type,
+        clock_rate: clock_rate
+      )
 
     if payload_type == nil do
       raise "payload_type for encoding #{inspect(encoding_name)} not provided with no default value registered"
@@ -234,6 +274,13 @@ defmodule Boombox.RTP do
       raise "clock_rate for encoding #{inspect(encoding_name)} and payload_type #{inspect(payload_type)} not provided with no default value registered"
     end
 
+    encoding_specific_params_specs =
+      Map.get(@encoding_specific_params_specs[direction], encoding_name, [])
+
+    {:ok, encoding_specific_params} =
+      Keyword.intersect(encoding_specific_params_specs, opts)
+      |> Bunch.Config.parse(encoding_specific_params_specs)
+
     %{
       encoding_name: encoding_name,
       encoding_specific_params: encoding_specific_params,
@@ -242,29 +289,6 @@ defmodule Boombox.RTP do
     }
   end
 
-  @spec validate_and_parse_encoding!(
-          :input,
-          RTP.encoding_name() | Boombox.rtp_encoding_specific_params()
-        ) :: {RTP.encoding_name(), parsed_input_encoding_specific_params()}
-  @spec validate_and_parse_encoding!(
-          :output,
-          RTP.encoding_name() | Boombox.rtp_encoding_specific_params()
-        ) :: {RTP.encoding_name(), parsed_output_encoding_specific_params()}
-  defp validate_and_parse_encoding!(direction, encoding) do
-    case encoding do
-      nil ->
-        raise "Encoding name not provided"
-
-      encoding when is_atom(encoding) ->
-        validate_and_parse_encoding!(direction, {encoding, []})
-
-      {encoding, encoding_params} when is_atom(encoding) ->
-        field_specs = Map.get(@required_encoding_specific_params[direction], encoding, [])
-        {:ok, encoding_params} = Bunch.Config.parse(encoding_params, field_specs)
-        {encoding, encoding_params}
-    end
-  end
-
   @spec get_payload_type_mapping(%{audio: parsed_track_config(), video: parsed_track_config()}) ::
           RTP.PayloadFormat.payload_type_mapping()
   defp get_payload_type_mapping(track_configs) do