Boombox (Boombox v0.2.2)

View Source

Boombox is a tool for audio and video streaming.

See run/1 for details and examples.livemd for examples.

Summary

Types

When configuring a track for a media type (video or audio), the following options are used

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 common_rtp_opt/0.

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 common_rtp_opt/0.

Functions

Asynchronous version of run/2.

Runs boombox with given input and output.

Runs boombox with CLI arguments.

Types

common_rtp_opt()

@type common_rtp_opt() ::
  {:video_encoding, Membrane.RTP.encoding_name()}
  | {:video_payload_type, Membrane.RTP.payload_type()}
  | {:video_clock_rate, Membrane.RTP.clock_rate()}
  | {:audio_encoding, Membrane.RTP.encoding_name()}
  | {:audio_payload_type, Membrane.RTP.payload_type()}
  | {:audio_clock_rate, Membrane.RTP.clock_rate()}
  | {:aac_bitrate_mode, Membrane.RTP.AAC.Utils.mode()}

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.

in_rtp_opts()

@type in_rtp_opts() :: [
  common_rtp_opt()
  | {:port, :inet.port_number()}
  | {:audio_specific_config, binary()}
  | {:vps, binary()}
  | {:pps, binary()}
  | {:sps, binary()}
]

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 common_rtp_opt/0.

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.

in_stream_opts()

@type in_stream_opts() :: [audio: :binary | boolean(), video: :image | boolean()]

input()

@type input() ::
  (path_or_uri :: String.t())
  | {:mp4 | :aac | :wav | :mp3 | :ivf | :ogg | :h264 | :h265,
     location :: String.t()}
  | {:mp4 | :aac | :wav | :mp3 | :ivf | :ogg, location :: String.t(),
     [{:transport, :file | :http}]}
  | {:h264, location :: String.t(),
     transport: :file | :http, framerate: Membrane.H264.framerate()}
  | {:h265, location :: String.t(),
     transport: :file | :http, framerate: Membrane.H265.framerate_t()}
  | {:webrtc, webrtc_signaling()}
  | {:whip, uri :: String.t(), [{:token, String.t()}]}
  | {:rtmp, (uri :: String.t()) | (client_handler :: pid())}
  | {:rtsp, url :: String.t()}
  | {:rtp, in_rtp_opts()}
  | {:stream, in_stream_opts()}

out_rtp_opts()

@type out_rtp_opts() :: [
  common_rtp_opt()
  | {:address, :inet.ip_address() | String.t()}
  | {:port, :inet.port_number()}
  | {:target, String.t()}
  | transcoding_policy_opt()
]

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 common_rtp_opt/0.

out_stream_opts()

@type out_stream_opts() :: [
  audio: :binary | boolean(),
  video: :image | boolean(),
  audio_format: Membrane.RawAudio.SampleFormat.t(),
  audio_rate: Membrane.RawAudio.sample_rate_t(),
  audio_channels: Membrane.RawAudio.channels_t(),
  video_width: non_neg_integer(),
  video_height: non_neg_integer()
]

output()

@type output() ::
  (path_or_uri :: String.t())
  | {path_or_uri :: String.t(), [transcoding_policy_opt()]}
  | {:mp4 | :aac | :wav | :mp3 | :ivf | :ogg | :h264 | :h265,
     location :: String.t()}
  | {:mp4 | :aac | :wav | :mp3 | :ivf | :ogg | :h264 | :h265,
     location :: String.t(), [transcoding_policy_opt()]}
  | {:webrtc, webrtc_signaling()}
  | {:webrtc, webrtc_signaling(), [transcoding_policy_opt()]}
  | {:whip, uri :: String.t(),
     [
       {:token, String.t()}
       | {bandit_option :: atom(), term()}
       | transcoding_policy_opt()
     ]}
  | {:hls, location :: String.t()}
  | {:hls, location :: String.t(), [transcoding_policy_opt()]}
  | {:rtp, out_rtp_opts()}
  | {:stream, out_stream_opts()}

transcoding_policy_opt()

@type transcoding_policy_opt() :: {:transcoding_policy, :always | :if_needed | :never}

webrtc_signaling()

@type webrtc_signaling() :: Membrane.WebRTC.Signaling.t() | String.t()

Functions

async(stream \\ nil, opts)

@spec async(Enumerable.t() | nil, input: input(), output: output()) ::
  Task.t() | Enumerable.t()

Asynchronous version of run/2.

Doesn't block the calling process until the termination of the processing.

It returns a Task.t() that can be awaited later.

If the output is a Stream the behaviour is identical to run/2.

run(stream \\ nil, opts)

@spec run(Enumerable.t() | nil, input: input(), output: output()) ::
  :ok | Enumerable.t()

Runs boombox with given input and output.

Example

Boombox.run(input: "rtmp://localhost:5432", output: "index.m3u8")

See input/0 and output/0 for available outputs and examples.livemd for examples.

If the input is {:stream, opts}, a Stream or other Enumerable is expected as the first argument.

Boombox.run(
  input: "path/to/file.mp4",
  output: {:webrtc, "ws://0.0.0.0:1234"}
)

run_cli(argv \\ System.argv())

@spec run_cli([String.t()]) :: :ok

Runs boombox with CLI arguments.

Example

# boombox.exs
Mix.install([:boombox])
Boombox.run_cli()
elixir boombox.exs -i "rtmp://localhost:5432" -o "index.m3u8"