# `Boombox.Endpoints`
[🔗](https://github.com/membraneframework/boombox/blob/v0.2.11/lib/boombox/endpoints.ex#L1)

Definitions of all available Boombox endpoints.

Endpoints define possible inputs and outputs of Boombox. Each endpoint
represents a different media format or protocol. See `t:input/0` and
`t:output/0` for available inputs and outputs.

# `aac_input`

```elixir
@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.

# `aac_output`

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

AAC audio codec output endpoint.

`location` is a file path.

# `common_rtp_opt`

```elixir
@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.

# `elixir_input`

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

Defines an input endpoint for direct Elixir integration.

* `{:stream, opts}` - an `Enumerable` of `t:Boombox.Packet.t/0`s is expected
  as the first argument to `Boombox.run/2`.
* `{:writer, opts}` - `Boombox.run/2` returns a `t: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 `t:in_raw_data_opt/0` for available options.

# `elixir_output`

```elixir
@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
  `t:Boombox.Packet.t/0`s.
* `{:reader, opts}` - `Boombox.run/2` returns a `t: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 `t: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 `t:out_raw_data_opt/0` for available options.

# `h264_input`

```elixir
@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}`.

# `h264_output`

```elixir
@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.

# `h265_input`

```elixir
@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}`.

# `h265_output`

```elixir
@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.

# `hls_input`

```elixir
@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.

# `hls_mode_opt`

```elixir
@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`.

# `hls_output`

```elixir
@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.

# `hls_variant_selection_policy_opt`

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

Controls the variant selection policy for HLS input.

# `in_raw_data_opt`

```elixir
@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
  `t: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 `t: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 `t: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.

# `in_rtp_opt`

```elixir
@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 `t: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 `t:common_rtp_opt/0`.

In addition to `t: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.

# `input`

```elixir
@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.

# `ivf_input`

```elixir
@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.

# `ivf_output`

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

IVF container format output endpoint.

`location` is a file path.

# `mp3_input`

```elixir
@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.

# `mp3_output`

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

MP3 audio format output endpoint.

`location` is a file path.

# `mp4_input`

```elixir
@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.

# `mp4_output`

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

MP4 container output endpoint.

`location` is a file path.

# `ogg_input`

```elixir
@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.

# `ogg_output`

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

Ogg container format output endpoint.

`location` is a file path.

# `out_raw_data_opt`

```elixir
@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
  `t: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 `t:binary/0` data.
  - `:video` - if this option is set to `true`, `:image` default value is assumed
    and the video frames are stored as `t: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.

# `out_rtp_opt`

```elixir
@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 `t: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 `t:common_rtp_opt/0`.

# `output`

```elixir
@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.

# `player`

```elixir
@type player() :: :player
```

Plays the output stream with the local SDL2 media player.

# `rtmp`

```elixir
@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.

# `rtp_input`

```elixir
@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 `t:in_rtp_opt/0`.

# `rtp_output`

```elixir
@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 `t:out_rtp_opt/0`.

# `rtsp`

```elixir
@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.

# `srt_auth_opt`

```elixir
@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.

# `srt_input`

```elixir
@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.

# `srt_output`

```elixir
@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>`.

# `transcoding_policy_opt`

```elixir
@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.

# `transport_opt`

```elixir
@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`.

# `wav_input`

```elixir
@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.

# `wav_output`

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

WAV audio format output endpoint.

`location` is a file path.

# `webrtc_input`

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

WebRTC input endpoint.

See `t:webrtc_signaling/0` for the `signaling` argument.

# `webrtc_output`

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

WebRTC output endpoint.

See `t:webrtc_signaling/0` for the `signaling` argument.

# `webrtc_signaling`

```elixir
@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.

# `whip_input`

```elixir
@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.

# `whip_output`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*