ExWebRTC.Recorder (ex_webrtc_recorder v0.2.1)

Saves received RTP packets to a file for later processing/analysis.

Dumps raw RTP packets fed to it in a custom format. Use ExWebRTC.Recorder.Converter to process them.

Can optionally upload the saved files to S3-compatible storage. See ExWebRTC.Recorder.S3 and options/0 for more info.

Summary

Types

end_tracks_ok_result()

Tuple returned on successful call to end_tracks/2.

message()

Messages sent by the ExWebRTC.Recorder process to its controlling process.

option()

Options that can be passed to start_link/1.

options()

recorder()

Functions

add_tracks(recorder, tracks)

Adds new tracks to the recording.

controlling_process(recorder, controlling_process)

Changes the controlling process of this recorder process.

end_tracks(recorder, track_ids)

Finishes the recording for the given tracks and optionally uploads the result files.

record(recorder, track_id, rid, packet)

Records a received packet on the given track.

start(recorder_opts \\ [], gen_server_opts \\ [])

Starts a new ExWebRTC.Recorder process.

start_link(recorder_opts \\ [], gen_server_opts \\ [])

Starts a new ExWebRTC.Recorder process.

Types

end_tracks_ok_result()

@type end_tracks_ok_result() ::
  {:ok, ExWebRTC.Recorder.Manifest.t(),
   ExWebRTC.Recorder.S3.upload_task_ref() | nil}

Tuple returned on successful call to end_tracks/2.

Contains the part of the recording manifest that's relevant to the freshly ended tracks. See ExWebRTC.Recorder.Manifest.t/0 for more info.

If uploads are configured:

Contains the reference to the upload task that was spawned.
Recorder will send the :upload_complete/:upload_failed message with this reference to its controlling process when the task finishes.

Note that the manifest returned by end_tracks/2 always contains local paths to files. The updated manifest with s3:// scheme URLs is sent in the aforementioned message.

message()

@type message() ::
  {:ex_webrtc_recorder, pid(),
   {:upload_complete, ExWebRTC.Recorder.S3.upload_task_ref(),
    ExWebRTC.Recorder.Manifest.t()}
   | {:upload_failed, ExWebRTC.Recorder.S3.upload_task_ref(),
      ExWebRTC.Recorder.Manifest.t()}}

Messages sent by the ExWebRTC.Recorder process to its controlling process.

:upload_complete, :upload_failed - Sent after the completion of the upload task, identified by its reference. Contains the updated manifest with s3:// scheme URLs to uploaded files.

option()

@type option() ::
  {:base_dir, String.t()}
  | {:on_start, (-> [ExWebRTC.MediaStreamTrack.t()])}
  | {:controlling_process, Process.dest()}
  | {:s3_upload_config, ExWebRTC.Recorder.S3.upload_config()}

Options that can be passed to start_link/1.

:base_dir - Base directory where Recorder will save its artifacts. ./recordings by default.
:on_start - Callback that will be executed just after the Recorder is (re)started. It should return the initial list of tracks to be added.
:controlling_process - PID of a process where all messages will be sent. self() by default.
:s3_upload_config - If passed, finished recordings will be uploaded to S3-compatible storage. See ExWebRTC.Recorder.S3.upload_config/0 for more info.

options()

@type options() :: [option()]

recorder()

@type recorder() :: GenServer.server()

Functions

add_tracks(recorder, tracks)

@spec add_tracks(recorder(), [ExWebRTC.MediaStreamTrack.t()]) ::
  {:ok, ExWebRTC.Recorder.Manifest.t()}

Adds new tracks to the recording.

Returns the part of the recording manifest that's relevant to the freshly added tracks. See ExWebRTC.Recorder.Manifest.t/0 for more info.

controlling_process(recorder, controlling_process)

@spec controlling_process(recorder(), Process.dest()) :: :ok

Changes the controlling process of this recorder process.

Controlling process is a process that receives all of the messages (described by message/0) from this Recorder.

end_tracks(recorder, track_ids)

@spec end_tracks(recorder(), [ExWebRTC.MediaStreamTrack.id()]) ::
  end_tracks_ok_result() | {:error, :tracks_not_found}

Finishes the recording for the given tracks and optionally uploads the result files.

See end_tracks_ok_result/0 for the success typing.

record(recorder, track_id, rid, packet)

@spec record(
  recorder(),
  ExWebRTC.MediaStreamTrack.id(),
  ExWebRTC.MediaStreamTrack.rid() | nil,
  ExRTP.Packet.t()
) :: :ok

Records a received packet on the given track.

start(recorder_opts \\ [], gen_server_opts \\ [])

@spec start(options(), GenServer.options()) :: GenServer.on_start()

Starts a new ExWebRTC.Recorder process.

ExWebRTC.Recorder is a GenServer under the hood, thus this function allows for passing the generic GenServer.options/0 as an argument.

start_link(recorder_opts \\ [], gen_server_opts \\ [])

@spec start_link(options(), GenServer.options()) :: GenServer.on_start()

Starts a new ExWebRTC.Recorder process.

Works identically to start/2, but links to the calling process.