Caracola.Siprec (Caracola v0.1.0-rc.1)

Copy Markdown View Source

Session recording (SIPREC, RFC 7866): a session recording client (SRC) records a call by starting a recording session with a session recording server (SRS): an INVITE whose body has the SDP of the media streams sent to the SRS and the recording metadata (RFC 7865, application/rs-metadata+xml), that says who the participants are and which stream each one sends.

As SRC, record/4 starts a recording session:

recording = %{
  call_id: "the Call-ID of the recorded call",
  participants: [
    %{aor: "sip:alice@example.com", name: "Alice", send: [1]},
    %{aor: "sip:bob@example.com", send: [2]}
  ],
  sdp: sdp
}

{:ok, 200, [dialog: dialog]} = Caracola.Siprec.record(MySRC, "sip:srs@rec.example.com", recording)
# ...
Caracola.UAC.bye(dialog)

sdp has one media for each stream (send: [1] is the first one), with the address where the media of that stream is sent from: copying the RTP of the call to the SRS is up to the application (usually, a media server or relay). The medias get a label attribute with their number and are sendonly. With Caracola.B2BUA, bridge/2 builds the recording of a bridged call.

As SRS, a service with this plugin accepts Require: siprec; recording_session?/1 tells if an INVITE is a recording session (its Contact has the +sip.src feature tag), and decode/1 returns its SDP and metadata. Recording the media is up to the application.

Not yet: updating the metadata during the session, pausing and resuming, and the +sip.srs and recording-aware UA indications.

Summary

Types

The metadata of a recording session, as returned by decode_metadata/1.

A participant of a recording: its address (and optional name), and the numbers (from 1) of the medias of the SDP it sends.

A recording, for record/4: the participants, the SDP with one media per stream, the Call-ID of the recorded call (optional) and the session id of the recording (optional, generated by default).

Functions

The recording of a call bridged by Caracola.B2BUA: the remote party of the A leg sends the first media of sdp, and the one of the B leg the second one.

The SDP and the metadata of the body of a recording session request.

Parses recording metadata. The streams sent and received by each participant are given by their labels (the media numbers).

Encodes the metadata of a recording (RFC 7865), with the time of now as start time.

Starts a recording session with the SRS at uri: an INVITE with the SDP and the metadata of the recording (see the module documentation), Require: siprec and the +sip.src feature tag. opts are options of Caracola.UAC.invite/3; the ACK is sent automatically. End it with Caracola.UAC.bye/2.

Returns true if a request comes from an SRC (its Contact has +sip.src).

Types

metadata()

@type metadata() :: %{
  session_id: String.t() | nil,
  call_id: String.t() | nil,
  start_time: String.t() | nil,
  participants: [
    %{
      id: String.t(),
      aor: String.t() | nil,
      name: String.t() | nil,
      send: [String.t()],
      recv: [String.t()]
    }
  ],
  streams: [%{id: String.t(), label: String.t() | nil}]
}

The metadata of a recording session, as returned by decode_metadata/1.

participant()

@type participant() :: %{
  :aor => String.t(),
  optional(:name) => String.t() | nil,
  send: [pos_integer()]
}

A participant of a recording: its address (and optional name), and the numbers (from 1) of the medias of the SDP it sends.

recording()

@type recording() :: %{
  :participants => [participant()],
  :sdp => Caracola.SDP.t(),
  optional(:call_id) => String.t() | nil,
  optional(:session_id) => String.t()
}

A recording, for record/4: the participants, the SDP with one media per stream, the Call-ID of the recorded call (optional) and the session id of the recording (optional, generated by default).

Functions

bridge(bridge, sdp)

@spec bridge(Caracola.B2BUA.t(), Caracola.SDP.t()) ::
  {:ok, recording()} | {:error, term()}

The recording of a call bridged by Caracola.B2BUA: the remote party of the A leg sends the first media of sdp, and the one of the B leg the second one.

decode(message)

@spec decode(Caracola.Message.t()) ::
  {:ok, %{sdp: Caracola.SDP.t() | nil, metadata: metadata()}} | :error

The SDP and the metadata of the body of a recording session request.

decode_metadata(xml)

@spec decode_metadata(binary()) :: {:ok, metadata()} | :error

Parses recording metadata. The streams sent and received by each participant are given by their labels (the media numbers).

encode_metadata(recording)

@spec encode_metadata(recording()) :: binary()

Encodes the metadata of a recording (RFC 7865), with the time of now as start time.

record(service, uri, recording, opts \\ [])

@spec record(module(), String.t() | Caracola.URI.t(), recording(), list()) ::
  Caracola.UAC.result()

Starts a recording session with the SRS at uri: an INVITE with the SDP and the metadata of the recording (see the module documentation), Require: siprec and the +sip.src feature tag. opts are options of Caracola.UAC.invite/3; the ACK is sent automatically. End it with Caracola.UAC.bye/2.

recording_session?(message)

@spec recording_session?(Caracola.Message.t()) :: boolean()

Returns true if a request comes from an SRC (its Contact has +sip.src).