Boombox (Boombox v0.2.0)
View SourceBoombox 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
.
Types
@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.
@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.
@type input() :: (path_or_uri :: String.t()) | {:mp4, 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()} | {:aac, location :: String.t(), [{:transport, :file | :http}]} | {:wav, location :: String.t(), [{:transport, :file | :http}]} | {:mp3, location :: String.t(), [{:transport, :file | :http}]} | {:ivf, location :: String.t(), [{:transport, :file | :http}]} | {:ogg, location :: String.t(), [{:transport, :file | :http}]} | {: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()}
@type out_rtp_opts() :: [ common_rtp_opt() | {:address, :inet.ip_address() | String.t()} | {:port, :inet.port_number()} | {:target, String.t()} | transcoding_policy() ]
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
.
@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() ]
@type output() :: (path_or_uri :: String.t()) | {path_or_uri :: String.t(), [transcoding_policy()]} | {:mp4, location :: String.t()} | {:h264, location :: String.t()} | {:h265, location :: String.t()} | {:aac, location :: String.t()} | {:wav, location :: String.t()} | {:mp3, location :: String.t()} | {:ivf, location :: String.t()} | {:ogg, location :: String.t()} | {:mp4, location :: String.t(), [transcoding_policy()]} | {:webrtc, webrtc_signaling()} | {:webrtc, webrtc_signaling(), [transcoding_policy()]} | {:whip, uri :: String.t(), [{:token, String.t()} | {bandit_option :: atom(), term()}]} | {:hls, location :: String.t()} | {:hls, location :: String.t(), [transcoding_policy()]} | {:rtp, out_rtp_opts()} | {:stream, out_stream_opts()}
@type transcoding_policy() :: {:transcoding_policy, :always | :if_needed | :never}
@type webrtc_signaling() :: Membrane.WebRTC.Signaling.t() | String.t()
Functions
@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"}
)
@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"