@spec async(Enumerable.t() | nil,
  input: Boombox.Endpoints.input() | Boombox.Endpoints.elixir_input(),
  output: Boombox.Endpoints.output() | Boombox.Endpoints.elixir_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, :reader or :message endpoint, or the input is a :writer or :message endpoint, the behaviour is identical to run/2.

@spec child_spec(
  [input: Boombox.Endpoints.input(), output: Boombox.Endpoints.output()]
  | [
      Enumerable.t()
      | [
          input: {:stream, [Boombox.Endpoints.in_raw_data_opt()]},
          output: Boombox.Endpoints.output()
        ]
    ]
) :: Supervisor.child_spec()

Returns a child specification for running Boombox under a supervisor.

Boombox processes are one-shot: they process media and exit normally when done. The restart: :temporary configuration means they will not be restarted after finishing.

Example

children = [
  {Boombox, input: "rtmp://localhost:5432", output: "output.mp4"}
]

Supervisor.start_link(children, strategy: :one_for_one)

Example with :stream input

audio_packets_stream = ...

children = [
  {Boombox, [audio_packets_stream, input: {:stream, audio: :binary, video: false} output: "output.mp4"]}
]

Supervisor.start_link(children, strategy: :one_for_one)

@spec close(Boombox.Writer.t() | Boombox.Reader.t()) ::
  :ok | {:error, :incompatible_mode | :already_finished}

Gracefully terminates Boombox when using :reader or :writer endpoints before a response of type :finished has been received.

When using :reader endpoint on output informs Boombox that no more packets will be read from it with read/1 and that it should terminate accordingly.

When using :writer endpoint on input informs Boombox that it will not be provided any more packets with write/2 and should terminate accordingly.

@spec play(
  Enumerable.t() | nil,
  Boombox.Endpoints.input() | Boombox.Endpoints.elixir_input()
) :: :ok

Runs boombox with given input and plays audio and video streams on your computer.

Boombox.play(input) is idiomatic to Boombox.run(input: input, output: :player).

Example

Boombox.play("rtmp://localhost:5432")

@spec read(Boombox.Reader.t()) ::
  {:ok, Boombox.Packet.t()} | :finished | {:error, :incompatible_mode}

Reads a packet from Boombox.

If returned with :ok, then this function can be called again to request the next packet, and if returned with :finished, then Boombox finished it's operation and will not produce any more packets.

Can be called only when using :reader endpoint on output.

@spec run(Enumerable.t() | nil,
  input: Boombox.Endpoints.input() | Boombox.Endpoints.elixir_input(),
  output: Boombox.Endpoints.output() | Boombox.Endpoints.elixir_output()
) :: :ok | Enumerable.t() | Boombox.Writer.t() | Boombox.Reader.t() | pid()

Runs boombox with given input and output.

Example

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

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

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

Calling this function results in it blocking until the media flow is finished and then returning :ok, except for when an endpoint with special behavior is used.

Input endpoints with special behaviours:

• :stream - a Stream or other Enumerable containing Boombox.Packets is expected as the first argument.
• :writer - this function will return a Boombox.Writer struct, which is used to write media packets to boombox with write/2 and to finish writing with close/1.
• :message - this function returns a PID of a process to communicate with. The process accepts the following types of messages:
  • {:boombox_packet, packet :: Boombox.Packet.t()} - provides boombox with a media packet. The process will a {:boombox_finished, boombox_pid :: pid()} message to sender_pid if it has finished processing packets and should not be provided any more.
  • :boombox_close - tells boombox that no more packets will be provided and that it should terminate.

Output endpoints with special behaviours:

• :stream - this function will return a Stream that contains Boombox.Packets
• :reader - this function will return a Boombox.Reader struct, which is used to read media packets from boombox with read/1 and to stop reading with close/1.
• :message - this function returns a PID of a process to communicate with. The process will send the following types of messages to the process that called this function:
  • {:boombox_packet, boombox_pid :: pid(), packet :: Boombox.Packet.t()} - contains a packet produced by boombox.
  • {:boombox_finished, boombox_pid :: pid()} - informs that boombox has finished producing packets and will begin terminating. No more messages will be sent.

@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"

@spec start_link(Enumerable.t() | nil,
  input:
    Boombox.Endpoints.input() | {:stream, [Boombox.Endpoints.in_raw_data_opt()]},
  output: Boombox.Endpoints.output()
) :: {:ok, pid()} | {:error, term()}

Starts Boombox and links it to the calling process.

This function is suitable for supervision tree integration — see child_spec/1. Otherwise, use run/1 or async/1.

Returns {:ok, pid} once Boombox is ready to process media. For protocols that require a server socket (RTMP, RTSP, RTP, SRT), this function blocks until the server is bound and ready to accept connections. For all other protocols it returns immediately after the pipeline starts.

The returned pid is the pipeline supervisor. You can monitor it to detect when processing finishes or if Boombox crashes.

:message and :reader endpoints are not supported as input, and :stream, :message and :writer endpoints are not supported as output — always use run/1 or async/1 for those.

@spec write(Boombox.Writer.t(), Boombox.Packet.t()) ::
  :ok | :finished | {:error, :incompatible_mode}

Writes provided packet to Boombox.

Returns :ok if more packets can be provided, and :finished when Boombox finished consuming and will not accept any more packets. Returns synchronously once the packet has been ingested and Boombox is ready for more packets.

Can be called only when using :writer endpoint on input.