@type aac_input() ::
  {:aac, location :: String.t()}
  | {:aac, location :: String.t(), [transport_opt()]}

AAC audio codec input endpoint.

location is a file path or HTTP URL.

@type aac_output() ::
  {:aac, location :: String.t()}
  | {:aac, location :: String.t(), [transcoding_policy_opt()]}

AAC audio codec output endpoint.

location is a file path.

@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()}

A common option shared by RTP input and output.

When configuring a track for a media type (video or audio):

• {:audio_encoding | :video_encoding, name} - MUST be provided to configure a given media type. Some options are encoding-specific. Currently supported encodings are: AAC, Opus, H264, H265. The encoding name must match the rtpmap attribute that could be part of an SDP description.

• {:audio_payload_type | :video_payload_type, type}, {:audio_clock_rate | :video_clock_rate, rate} - MAY be provided. If not, an unofficial default will be used, which is registered for the provided encoding by a membrane_rtp_<encoding>_plugin application:

  • AAC - payload_type: 127, clock_rate: 48_000
  • Opus - payload_type: 120, clock_rate: 48_000
  • H264 - payload_type: 96, clock_rate: 90_000
• {:aac_bitrate_mode, mode} - MUST be provided for AAC encoding. Defines which mode should be assumed/set when depayloading/payloading.

@type elixir_input() :: {:stream | :writer | :message, [in_raw_data_opt()]}

Defines an input endpoint for direct Elixir integration.

• {:stream, opts} - an Enumerable of Boombox.Packet.t/0s is expected as the first argument to Boombox.run/2.
• {:writer, opts} - Boombox.run/2 returns a Boombox.Writer.t/0 for writing packets via Boombox.write/2 and finishing via Boombox.close/1.
• {:message, opts} - Boombox.run/2 returns a PID to communicate with. The process accepts:
  • {:boombox_packet, packet} - provides a media packet. The process sends {:boombox_finished, boombox_pid} to the sender when it has finished.
  • :boombox_close - signals no more packets will be provided.

See in_raw_data_opt/0 for available options.

@type elixir_output() :: {:stream | :reader | :message, [out_raw_data_opt()]}

Defines an output endpoint for direct Elixir integration.

• {:stream, opts} - Boombox.run/2 returns a Stream of Boombox.Packet.t/0s.
• {:reader, opts} - Boombox.run/2 returns a Boombox.Reader.t/0 for reading packets via Boombox.read/1 and stopping via Boombox.close/1.
• {:message, opts} - Boombox.run/2 returns a PID to communicate with. The process sends:
  • {:boombox_packet, boombox_pid, packet} - a Boombox.Packet.t/0 produced by Boombox.
  • {:boombox_finished, boombox_pid} - Boombox has finished producing packets and will terminate. No more messages will be sent.

See out_raw_data_opt/0 for available options.

@type h264_input() ::
  {:h264, location :: String.t()}
  | {:h264, location :: String.t(),
     [transport_opt() | {:framerate, Membrane.H264.framerate()}]}

H264 video codec input endpoint in Annex-B format.

location is a file path or HTTP URL. The framerate option defaults to {30, 1}.

@type h264_output() ::
  {:h264, location :: String.t()}
  | {:h264, location :: String.t(), [transcoding_policy_opt()]}

H264 video codec output endpoint in Annex-B format.

location is a file path.

@type h265_input() ::
  {:h265, location :: String.t()}
  | {:h265, location :: String.t(),
     [transport_opt() | {:framerate, Membrane.H265.framerate_t()}]}

H265 video codec input endpoint in Annex-B format.

location is a file path or HTTP URL. The framerate option defaults to {30, 1}.

@type h265_output() ::
  {:h265, location :: String.t()}
  | {:h265, location :: String.t(), [transcoding_policy_opt()]}

H265 video codec output endpoint in Annex-B format.

location is a file path.

@type hls_input() ::
  {:hls, url :: String.t()}
  | {:hls, url :: String.t(), [hls_variant_selection_policy_opt()]}

HLS (HTTP Live Streaming) input endpoint.

url is the location of the HLS playlist.

@type hls_mode_opt() :: {:mode, :live | :vod}

Determines if the HLS session is live or VOD type. Allowed only for HLS output.

Influences the type of metadata inserted into the playlist manifest. Defaults to :vod.

@type hls_output() ::
  {:hls, location :: String.t()}
  | {:hls, location :: String.t(), [hls_mode_opt() | transcoding_policy_opt()]}

HLS (HTTP Live Streaming) output endpoint.

location is the path where the HLS playlist will be created. If it's a directory, an index.m3u8 manifest and segment files will be created there. If a .m3u8 path is provided, the manifest will be created at that location, and all associated HLS files will be stored in the same directory.

@type hls_variant_selection_policy_opt() ::
  {:variant_selection_policy,
   Membrane.HTTPAdaptiveStream.Source.variant_selection_policy()}

Controls the variant selection policy for HLS input.

@type in_raw_data_opt() ::
  {:audio, :binary | boolean()}
  | {:video, :image | boolean()}
  | {:is_live, boolean()}

An option for the raw data input endpoints (:stream, :writer, :message).

• {:audio | :video, value} - Determines if and in what form Boombox will accept audio / video. If not false, Boombox will accept the media encapsulated with Boombox.Packet.t/0 structs in :payload field. Value of this option determines in what form the media has to be:

  • :audio - if this option is set to true, :binary default value is assumed and the audio chunks have to be in form of binary/0 data.
  • :video - if this option is set to true, :image default value is assumed and the video frames have to be in form of Vix.Vips.Image.t/0 structs.
• {:is_live, value} - If true, Boombox assumes that packets are provided in realtime and won't control their pace when passing them to the output. false by default.

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

An option for the rtp_input/0 endpoint.

A receiving {:port, port} MUST be provided and the media to be received MUST be configured. Media configuration is explained in common_rtp_opt/0.

In addition to common_rtp_opt/0, the following encoding-specific options are available for RTP input only:

• {:audio_specific_config, config} - MUST be provided for AAC encoding. Contains crucial information about the stream obtained from a side channel.
• {:vps, vps} (H265 only), {:pps, pps}, {:sps, sps} - MAY be provided for H264 or H265 encodings. Parameter sets obtained from a side channel, containing information about the encoded stream.

@type input() ::
  (path_or_url :: String.t())
  | {path_or_url :: String.t(),
     [
       hls_variant_selection_policy_opt()
       | {:framerate, Membrane.H264.framerate() | Membrane.H265.framerate_t()}
     ]}
  | mp4_input()
  | aac_input()
  | wav_input()
  | mp3_input()
  | ivf_input()
  | ogg_input()
  | h264_input()
  | h265_input()
  | webrtc_input()
  | whip_input()
  | rtmp()
  | rtsp()
  | rtp_input()
  | hls_input()
  | srt_input()

Defines a Boombox input endpoint.

Endpoint can be specified explicitly by providing a tuple with the first element being an atom determining the endpoint type, or implicitly, by providing a string which Boombox will try to interpret based on extension or scheme.

@type ivf_input() ::
  {:ivf, location :: String.t()}
  | {:ivf, location :: String.t(), [transport_opt()]}

IVF container format input endpoint.

location is a file path or HTTP URL.

@type ivf_output() ::
  {:ivf, location :: String.t()}
  | {:ivf, location :: String.t(), [transcoding_policy_opt()]}

IVF container format output endpoint.

location is a file path.

@type mp3_input() ::
  {:mp3, location :: String.t()}
  | {:mp3, location :: String.t(), [transport_opt()]}

MP3 audio format input endpoint.

location is a file path or HTTP URL.

@type mp3_output() ::
  {:mp3, location :: String.t()}
  | {:mp3, location :: String.t(), [transcoding_policy_opt()]}

MP3 audio format output endpoint.

location is a file path.

@type mp4_input() ::
  {:mp4, location :: String.t()}
  | {:mp4, location :: String.t(), [transport_opt()]}

MP4 container input endpoint.

location is a file path or HTTP URL.

@type mp4_output() ::
  {:mp4, location :: String.t()}
  | {:mp4, location :: String.t(), [transcoding_policy_opt()]}

MP4 container output endpoint.

location is a file path.

@type ogg_input() ::
  {:ogg, location :: String.t()}
  | {:ogg, location :: String.t(), [transport_opt()]}

Ogg container format input endpoint.

location is a file path or HTTP URL.

@type ogg_output() ::
  {:ogg, location :: String.t()}
  | {:ogg, location :: String.t(), [transcoding_policy_opt()]}

Ogg container format output endpoint.

location is a file path.

@type out_raw_data_opt() ::
  {: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()}
  | {:pace_control, boolean()}

An option for the raw data output endpoints (:stream, :reader, :message).

• {:audio | :video, value} - Determines if and how Boombox will produce audio / video. If not false, Boombox will produce the media and encapsulate it with Boombox.Packet.t/0 structs in :payload field. Value of this option determines how the media will be stored:

  • :audio - if this option is set to true, :binary default value is assumed and the audio chunks are stored as binary/0 data.
  • :video - if this option is set to true, :image default value is assumed and the video frames are stored as Vix.Vips.Image.t/0 structs.
• {:audio_format, format} - Sample format of the produced audio stream.
• {:audio_rate, rate} - Sample rate of the produced audio stream (samples per second).
• {:audio_channels, channels} - Number of channels in the produced audio stream. Channels are interleaved.
• {:video_width, width}, {:video_height, height} - Dimensions of the produced video stream.
• {:pace_control, value} - If true, the incoming streams are passed to the output according to their timestamps. If false, they are passed as fast as possible. true by default.

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

An option for the rtp_output/0 endpoint.

The target {:port, port} and {:address, address} MUST be provided (alternatively combined as a <address>:<port> string via {:target, target}) and the media to be sent MUST be configured. Media configuration is explained in common_rtp_opt/0.

@type output() ::
  (path_or_url :: String.t())
  | {path_or_url :: String.t(), [transcoding_policy_opt() | hls_mode_opt()]}
  | mp4_output()
  | aac_output()
  | wav_output()
  | mp3_output()
  | ivf_output()
  | ogg_output()
  | h264_output()
  | h265_output()
  | webrtc_output()
  | whip_output()
  | hls_output()
  | rtp_output()
  | srt_output()
  | player()

Defines a Boombox output endpoint.

Endpoint can be specified explicitly by providing a tuple with the first element being an atom determining the endpoint type, or implicitly, by providing a string which Boombox will try to interpret based on extension or scheme.

@type player() :: :player

Plays the output stream with the local SDL2 media player.

@type rtmp() :: {:rtmp, (url :: String.t()) | (client_handler :: pid())}

RTMP (Real-Time Messaging Protocol) input endpoint.

Currently Boombox supports only client-side functionality - receiving streams from a RTMP server. Behavior of this endpoint can be specified in two different ways - by providing a URL of the server or a PID of an already existing RTMP client handler process.

@type rtp_input() :: {:rtp, [in_rtp_opt()]}

RTP (Real-time Transport Protocol) input endpoint.

Since RTP doesn't incorporate any negotiation, media information must be provided manually. See in_rtp_opt/0.

@type rtp_output() :: {:rtp, [out_rtp_opt()]}

RTP (Real-time Transport Protocol) output endpoint.

Since RTP doesn't incorporate any negotiation, media information must be provided manually. See out_rtp_opt/0.

@type rtsp() :: {:rtsp, url :: String.t()}

RTSP (Real-Time Streaming Protocol) input endpoint.

Currently Boombox supports only client-side functionality - receiving media from a RTSP server.

@type srt_auth_opt() :: {:stream_id, String.t()} | {:password, String.t()}

An authentication option for SRT connections.

• {:stream_id, id} - ID of the stream. When using SRT as input, determines the stream ID the server will accept. When using for output, determines the stream ID being sent.
• {:password, password} - Authentication password. When using SRT as input, determines the password required from clients. When using for output, determines the password the client uses to authenticate.

@type srt_input() ::
  {:srt, (url :: String.t()) | (server_awaiting_accept :: ExLibSRT.Server.t())}
  | {:srt, url :: String.t(), [srt_auth_opt()]}

SRT (Secure Reliable Transport) input endpoint.

Boombox acts as an SRT server and expects connections from clients at the provided address. url is an address in the form of <ip>:<port>. Alternatively, an existing ExLibSRT.Server.t() can be passed directly.

@type srt_output() ::
  {:srt, url :: String.t()} | {:srt, url :: String.t(), [srt_auth_opt()]}

SRT (Secure Reliable Transport) output endpoint.

Boombox acts as an SRT client and connects to a server at the provided address. url is an address in the form of <ip>:<port>.

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

Controls the transcoding behavior. Allowed only for output.

The default transcoding behavior is :if_needed, which means that if the format of the media is the same for input and output, the stream is not decoded and re-encoded. This saves resources but in some cases transcoding is necessary. Set to :always to force transcoding regardless of whether formats differ. Set to :never to never transcode, raising if the desired operation can't be done without transcoding.

@type transport_opt() :: {:transport, :file | :http}

Explicitly specifies the transport for storage endpoints.

If not provided, transport is inferred from the location - file paths resolve to :file, HTTP URLs to :http.

@type wav_input() ::
  {:wav, location :: String.t()}
  | {:wav, location :: String.t(), [transport_opt()]}

WAV audio format input endpoint.

location is a file path or HTTP URL.

@type wav_output() ::
  {:wav, location :: String.t()}
  | {:wav, location :: String.t(), [transcoding_policy_opt()]}

WAV audio format output endpoint.

location is a file path.

@type webrtc_input() :: {:webrtc, webrtc_signaling()}

WebRTC input endpoint.

See webrtc_signaling/0 for the signaling argument.

@type webrtc_output() ::
  {:webrtc, webrtc_signaling()}
  | {:webrtc, webrtc_signaling(), [transcoding_policy_opt()]}

WebRTC output endpoint.

See webrtc_signaling/0 for the signaling argument.

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

Signaling channel for a WebRTC connection.

Can be a Membrane.WebRTC.Signaling.t() struct or a WebSocket URL string.

@type whip_input() :: {:whip, url :: String.t(), [{:token, String.t()}]}

WHIP (WebRTC-HTTP Ingestion Protocol) input endpoint.

url is an HTTP URL of the WHIP server. The token is used for authentication and authorization.

@type whip_output() ::
  {:whip, url :: String.t(),
   [
     {:token, String.t()}
     | {bandit_option :: atom(), term()}
     | transcoding_policy_opt()
   ]}

WHIP (WebRTC-HTTP Ingestion Protocol) output endpoint.

url is an HTTP URL for the WHIP server. The token is used for authentication and authorization. Custom Bandit server options can also be provided.