# `Caracola.Siprec`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/siprec.ex#L1)

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.

# `metadata`

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

```elixir
@type participant() :: %{
  :aor =&gt; String.t(),
  optional(:name) =&gt; 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`

```elixir
@type recording() :: %{
  :participants =&gt; [participant()],
  :sdp =&gt; Caracola.SDP.t(),
  optional(:call_id) =&gt; String.t() | nil,
  optional(:session_id) =&gt; 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).

# `bridge`

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

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

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

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

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

# `record`

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

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

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

---

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