Boombox.Bin (Boombox v0.2.0)

View Source

Boombox.Bin is a Membrane Bin for audio and video streaming. It can be used as a Sink or Source in your Membrane Pipeline.

If you use it as a Membrane Source and link :output pad, you have to specify :input option, e.g.

child(:boombox, %Boombox.Bin{
  input: "path/to/input/file.mp4"
})
|> via_out(:output, options: [kind: :audio])
|> child(:my_audio_sink, My.Audio.Sink)

If you use it as a Membrane Sink and link :input pad, you have to specify :output option, e.g.

child(:my_video_source, My.Video.Source)
|> via_in(:input, options: [kind: :video])
|> child(:boombox, %Boombox.Bin{
  output: "path/to/output/file.mp4"
})

Boombox.Bin cannot have :input and :output pads linked at the same time.

Boombox.Bin cannot have :input and :output options set at the same time.

If you use Boombox.Bin as a source, you can either:

  • link output pads in the same spec where you spawn it
  • or wait until Boombox.Bin returns a notification {:new_tracks, [:audio | :video]} and then link the pads according to the notification.

Bin options

Passed via struct Boombox.Bin.t/0

  • input

    input() | nil

    Default value: nil

  • output

    output() | nil

    Default value: nil

Pads

:input

Accepted formats:

format when Transcoder.Audio.is_audio_format(format) or Transcoder.Video.is_video_format(format)
Direction::input
Availability::on_request

Pad options:

  • kind

    :video | :audio

    Required
    Specifies, if the input pad is for audio or video.

    There might be up to one pad of each kind at the time.

:output

Accepted formats:

format when Transcoder.Audio.is_audio_format(format) or Transcoder.Video.is_video_format(format)
Direction::output
Availability::on_request

Pad options:

  • kind

    :video | :audio

    Required
    Specifies, if the output pad is for audio or video.

    There might be up to one pad of each kind at the time.

  • codec

    H264
    | VP8
    | VP9
    | AAC
    | Opus
    | RawVideo
    | RawAudio
    | [H264 | VP8 | VP9 | AAC | Opus | RawVideo | RawAudio]
    | nil

    Default value: nil
    Specifies the codec of the stream flowing through the pad.

    Can be either a single codec or a list of codecs.

    If a list is provided

    • and the stream matches one of the codecs, the matching codec will be used,
    • and the stream doesn't match any of the codecs, it will be transcoded to the first codec in the list.

    If the codec is not specified, it will be resolved to:

  • transcoding_policy

    :always | :if_needed | :never

    Default value: :if_needed
    Specifies the transcoding policy for the stream flowing through the pad.

    Can be either :always, :if_needed, or :never.

    If set to :always, the media stream will be decoded and/or encoded, even if the format of the stream arriving at the Boombox.Bin endpoint matches the output pad codec. This option is useful when you want to make sure keyframe request events going upstream the output pad are handled in Boombox when the Boombox input itself cannot handle them (i.e. when the input is not WebRTC).

    If set to :if_needed, the media stream will be transcoded only if the format of the stream arriving at the Boombox.Bin endpoint doesn't match the output pad codec. This is the default behavior.

    If set to :never, the input media stream won't be decoded or encoded. Changing alignment, encapsulation, or stream structure is still possible. This option is helpful when you want to ensure that Boombox.Bin will not use too many resources, e.g., CPU or memory.

    If the stream arriving at the Boombox.Bin endpoint doesn't match the output pad codec, an error will be raised.

Summary

Types

Value passed via :input option.

Options for pad :input

Type of notification sent to the parent of Boombox.Bin when new tracks arrive.

Value passed via :output option.

Options for pad :output

t()

Struct containing options for Boombox.Bin

Functions

Returns description of options available for this module

Types

input()

@type input() ::
  (path_or_uri :: String.t())
  | {:mp4, location :: String.t(), [{:transport, :file | :http}]}
  | {:webrtc, Boombox.webrtc_signaling()}
  | {:whip, uri :: String.t(), [{:token, String.t()}]}
  | {:rtmp, (uri :: String.t()) | (client_handler :: pid())}
  | {:rtsp, url :: String.t()}
  | {:rtp, Boombox.in_rtp_opts()}

Value passed via :input option.

Specifies the input endpoint of Boombox.Bin.

Similar to Boombox.input/0, but without :stream option.

input_pad_opts()

@type input_pad_opts() :: [{:kind, :video | :audio}]

Options for pad :input

new_tracks()

@type new_tracks() :: {:new_tracks, [:video | :audio]}

Type of notification sent to the parent of Boombox.Bin when new tracks arrive.

It is sent only when Boombox.Bin is used as a source (the :input option is set).

This notification is sent by Boombox.Bin only if its pads weren't linked before handle_playing/2 callback.

output()

@type output() ::
  (path_or_uri :: String.t())
  | {path_or_uri :: String.t(), [Boombox.transcoding_policy()]}
  | {:mp4, location :: String.t()}
  | {:mp4, location :: String.t(), [Boombox.transcoding_policy()]}
  | {:webrtc, Boombox.webrtc_signaling()}
  | {:webrtc, Boombox.webrtc_signaling(), [Boombox.transcoding_policy()]}
  | {:whip, uri :: String.t(),
     [{:token, String.t()} | {bandit_option :: atom(), term()}]}
  | {:hls, location :: String.t()}
  | {:hls, location :: String.t(), [Boombox.transcoding_policy()]}
  | {:rtp, Boombox.out_rtp_opts()}

Value passed via :output option.

Specifies the output endpoint of Boombox.Bin.

Similar to Boombox.output/0, but without :stream option.

output_pad_opts()

@type output_pad_opts() :: [
  kind: :video | :audio,
  codec:
    Membrane.H264
    | Membrane.VP8
    | Membrane.VP9
    | Membrane.AAC
    | Membrane.Opus
    | Membrane.RawVideo
    | Membrane.RawAudio
    | [
        Membrane.H264
        | Membrane.VP8
        | Membrane.VP9
        | Membrane.AAC
        | Membrane.Opus
        | Membrane.RawVideo
        | Membrane.RawAudio
      ]
    | nil,
  transcoding_policy: :always | :if_needed | :never
]

Options for pad :output

t()

@type t() :: %Boombox.Bin{input: input() | nil, output: output() | nil}

Struct containing options for Boombox.Bin

Functions

options()

@spec options() :: keyword()

Returns description of options available for this module