webrtc (webrtc v0.1.0)

View Source

WebRTC peer connections in pure Erlang.

A peer connection is a process. The process that creates it (or the owner option) receives every event as {webrtc, Pc, Event}: signaling and ICE (negotiation_needed, {ice_candidate, Candidate, Mid}, ...), connection state, data channels ({channel_message, Id, Type, Data}, ...), media ({rtp, Mid, Packet}, {frame, Mid, Frame}, ...) and congestion ({bandwidth_estimate, Bps}, ...).

Signaling is the application's business: exchange the SDP returned by create_offer/2 and create_answer/2 and the candidates of ice_candidate events by any means, and pass the mid of each candidate to add_ice_candidate/3 on the other side.

This module and the webrtc_media_codec behaviour are the public API. See docs/REFERENCE.md for every option and event.

Summary

Functions

Add a trickled remote candidate (<<"candidate:...">>) or end_of_candidates.

The same for the transport of m= section Mid (the sdpMid of the candidate): needed when the sections are not all bundled, every transport having its own candidates.

Add a transceiver. Opts: direction (default sendrecv), stream_id, track_id, the simulcast layers send_encodings and recv_rids, frames, codec_plugin, priority and interactive. See docs/REFERENCE.md ("Transceiver options").

Close the peer connection. Returns ok if it is already gone.

Close data channel Id.

The connection state, as in {connection_state, State} events.

Make Pid the owner: it receives every event from now on, and the peer connection closes when it exits.

Create an answer (SDP binary) to the remote offer. Opts is not read yet.

Create a data channel. Opts: ordered, max_retransmits, max_packet_life_time, protocol, negotiated, id and priority (see docs/REFERENCE.md, "Data channel options"). Returns {ok, Id} when the id is known (association up, or a negotiated channel); otherwise ok, and the datachannel_open event carries the id.

Create an offer (SDP binary). Opts is not read yet.

Internal statistics; see get_stats/2 for the W3C ones.

Statistics. #{format => w3c} gives the W3C WebRTC statistics (webrtc_stats): a map from stats id to a map of the dictionary's members; #{format => internal} is get_stats/1.

The current local description, or undefined.

Create a peer connection. Every option is optional: owner, the ICE servers (stun_servers, turn_servers, ice_servers), local addresses, DTLS, codecs and extensions, congestion control, frames and codec_plugins, and more. See docs/REFERENCE.md ("Peer connection options") for every key, its type and default.

The current remote description, or undefined.

Report W3C statistics of media you code yourself: inbound (decoder members of the transceiver's received streams, such as framesDecoded or totalDecodeTime), outbound (encoder members such as framesEncoded or qualityLimitationReason), source (the media-source object: audioLevel, width, frames, ...) or playout (the media-playout object of received audio). Keys are W3C member names; counters add up across reports, other members replace the previous value; an unknown member or a value of the wrong type is dropped. Any process can call it; it does not wait.

Ask the remote sender of a transceiver for a keyframe (PLI on every stream it sends).

Opts: rid to ask for a keyframe on one simulcast layer only. Returns ok and sends nothing while the SSRC of that layer is unknown.

Ask the remote sender of a transceiver to keep its streams under Bps bits per second, RTP headers and payload, with TMMBR (RFC 5104 §4.2.1), or to lift the limit with infinity. Needs ccm tmmbr negotiated on both sides, {error, not_negotiated} otherwise. The request is repeated until the sender acknowledges it.

Ask the remote sender of a transceiver to pause its stream (RFC 7728 PAUSE), when both sides negotiated ccm pause. The answer comes as {remote_paused, Mid} or {pause_refused, Mid} (with the rid for a simulcast layer); the request is repeated until then.

Opts: rid to pause one simulcast layer only.

Ask the remote sender to resume a paused stream (RFC 7728 RESUME). {remote_resumed, Mid} follows with its first packet.

New ICE credentials; renegotiate to complete the restart.

Restart the streams of a transceiver that a circuit breaker halted ({circuit_breaker, Mid, Reason} event). RFC 8083 §4.5 asks for a human or a sign that the congestion is gone before restarting; the call is refused with {error, {retry_after, Ms}} during the hold time (circuit_breaker_hold, default 15 s).

Send a text or binary message on data channel Id.

Send an encoded frame on a transceiver: split into RTP payloads by the codec's payload format, the marker bit on the last. Frame is a VP8 or VP9 frame, an H.264 access unit in Annex B, an AV1 temporal unit, or an audio payload. Opts: timestamp, keyframe (VP9 and AV1 signal it in the payload), codec, rid.

Encode raw media with the transceiver's codec plugin (codec_plugin, see webrtc_media_codec) and send the frames. Opts: rid.

Ask the remote encoder of a transceiver to use a reference picture the decoder has (RPSI, RFC 4585 §6.3.3, RFC 8834 §5.1.4). Bits is the codec's native RPSI bit string for payload type Pt. Needs nack rpsi negotiated.

Opts: rid for one simulcast layer.

Send an RTP payload on a transceiver. Opts: timestamp, marker, codec (name) or pt, rid to send on one simulcast layer of the transceiver, and audio_level ({Voice, Level}, RFC 6464, level in -dBov 0..127) added when the extension is negotiated, encrypted when negotiated so (RFC 6904).

Forward an RTP packet (#rtp{}) on a transceiver: SSRC and sequence number are replaced by the transceiver's.

Forward an RTP packet. Opts: rid to send it on one simulcast layer, with that layer's SSRC and sequence numbers.

Tell the remote encoder of a transceiver that slices were lost (SLI, RFC 4585 §6.3.2, RFC 8834 §5.1.3): Entries are {First, Number, PictureId} (13, 13 and 6 bits). Needs nack sli negotiated, {error, not_negotiated} otherwise.

Opts: rid for one simulcast layer.

Configure congestion control of the connection's media, once the transport exists (after the first description is set). Opts: pacing (boolean, default true; false sends every packet at once), pacing_factor (default 2.5), min_bitrate and max_bitrate (bits per second).

Change the direction of transceiver Id; renegotiate to apply it.

Apply a local description (rollback takes undefined).

Apply the peer's description (rollback takes undefined).

The JSEP signaling state, as in {signaling_state, State} events.

Stop transceiver Id; renegotiate to apply it.

Transceivers with their mid, directions and SSRCs.

Types

pc/0

-type pc() :: pid().

sdp_type/0

-type sdp_type() :: offer | answer | pranswer | rollback.

Functions

add_ice_candidate(Pc, Cand)

-spec add_ice_candidate(pc(), binary() | end_of_candidates) -> ok | {error, term()}.

Add a trickled remote candidate (<<"candidate:...">>) or end_of_candidates.

add_ice_candidate(Pc, Cand, Mid)

-spec add_ice_candidate(pc(), binary() | end_of_candidates, binary() | undefined) ->
                           ok | {error, term()}.

The same for the transport of m= section Mid (the sdpMid of the candidate): needed when the sections are not all bundled, every transport having its own candidates.

add_transceiver(Pc, Kind, Opts)

-spec add_transceiver(pc(), audio | video, map()) -> {ok, pos_integer()} | {error, term()}.

Add a transceiver. Opts: direction (default sendrecv), stream_id, track_id, the simulcast layers send_encodings and recv_rids, frames, codec_plugin, priority and interactive. See docs/REFERENCE.md ("Transceiver options").

close(Pc)

-spec close(pc()) -> ok.

Close the peer connection. Returns ok if it is already gone.

close_data_channel(Pc, Id)

-spec close_data_channel(pc(), non_neg_integer()) -> ok | {error, term()}.

Close data channel Id.

connection_state(Pc)

-spec connection_state(pc()) -> atom().

The connection state, as in {connection_state, State} events.

controlling_process(Pc, Pid)

-spec controlling_process(pc(), pid()) -> ok | {error, term()}.

Make Pid the owner: it receives every event from now on, and the peer connection closes when it exits.

create_answer(Pc, Opts)

-spec create_answer(pc(), map()) -> {ok, binary()} | {error, term()}.

Create an answer (SDP binary) to the remote offer. Opts is not read yet.

create_data_channel(Pc, Label, Opts)

-spec create_data_channel(pc(), binary(), map()) -> ok | {ok, non_neg_integer()} | {error, term()}.

Create a data channel. Opts: ordered, max_retransmits, max_packet_life_time, protocol, negotiated, id and priority (see docs/REFERENCE.md, "Data channel options"). Returns {ok, Id} when the id is known (association up, or a negotiated channel); otherwise ok, and the datachannel_open event carries the id.

create_offer(Pc, Opts)

-spec create_offer(pc(), map()) -> {ok, binary()} | {error, term()}.

Create an offer (SDP binary). Opts is not read yet.

get_stats(Pc)

-spec get_stats(pc()) -> map().

Internal statistics; see get_stats/2 for the W3C ones.

get_stats(Pc, _)

-spec get_stats(pc(), #{format => w3c | internal}) -> map().

Statistics. #{format => w3c} gives the W3C WebRTC statistics (webrtc_stats): a map from stats id to a map of the dictionary's members; #{format => internal} is get_stats/1.

local_description(Pc)

-spec local_description(pc()) -> binary() | undefined.

The current local description, or undefined.

new_peer_connection()

-spec new_peer_connection() -> {ok, pc()} | {error, term()}.

Equivalent to new_peer_connection(#{}).

new_peer_connection(Opts)

-spec new_peer_connection(map()) -> {ok, pc()} | {error, term()}.

Create a peer connection. Every option is optional: owner, the ICE servers (stun_servers, turn_servers, ice_servers), local addresses, DTLS, codecs and extensions, congestion control, frames and codec_plugins, and more. See docs/REFERENCE.md ("Peer connection options") for every key, its type and default.

remote_description(Pc)

-spec remote_description(pc()) -> binary() | undefined.

The current remote description, or undefined.

report_media_stats(Pc, Mid, Dir, Report)

-spec report_media_stats(pc(), binary(), inbound | outbound | source | playout, map()) -> ok.

Report W3C statistics of media you code yourself: inbound (decoder members of the transceiver's received streams, such as framesDecoded or totalDecodeTime), outbound (encoder members such as framesEncoded or qualityLimitationReason), source (the media-source object: audioLevel, width, frames, ...) or playout (the media-playout object of received audio). Keys are W3C member names; counters add up across reports, other members replace the previous value; an unknown member or a value of the wrong type is dropped. Any process can call it; it does not wait.

request_keyframe(Pc, Mid)

-spec request_keyframe(pc(), binary()) -> ok | {error, term()}.

Ask the remote sender of a transceiver for a keyframe (PLI on every stream it sends).

request_keyframe(Pc, Mid, Opts)

-spec request_keyframe(pc(), binary(), map()) -> ok | {error, term()}.

Opts: rid to ask for a keyframe on one simulcast layer only. Returns ok and sends nothing while the SSRC of that layer is unknown.

request_max_bitrate(Pc, Mid, Bps)

-spec request_max_bitrate(pc(), binary(), pos_integer() | infinity) -> ok | {error, term()}.

Ask the remote sender of a transceiver to keep its streams under Bps bits per second, RTP headers and payload, with TMMBR (RFC 5104 §4.2.1), or to lift the limit with infinity. Needs ccm tmmbr negotiated on both sides, {error, not_negotiated} otherwise. The request is repeated until the sender acknowledges it.

request_pause(Pc, Mid)

-spec request_pause(pc(), binary()) -> ok | {error, term()}.

Ask the remote sender of a transceiver to pause its stream (RFC 7728 PAUSE), when both sides negotiated ccm pause. The answer comes as {remote_paused, Mid} or {pause_refused, Mid} (with the rid for a simulcast layer); the request is repeated until then.

request_pause(Pc, Mid, Opts)

-spec request_pause(pc(), binary(), map()) -> ok | {error, term()}.

Opts: rid to pause one simulcast layer only.

request_resume(Pc, Mid)

-spec request_resume(pc(), binary()) -> ok | {error, term()}.

Ask the remote sender to resume a paused stream (RFC 7728 RESUME). {remote_resumed, Mid} follows with its first packet.

request_resume(Pc, Mid, Opts)

-spec request_resume(pc(), binary(), map()) -> ok | {error, term()}.

restart_ice(Pc)

-spec restart_ice(pc()) -> ok.

New ICE credentials; renegotiate to complete the restart.

resume_stream(Pc, Mid)

-spec resume_stream(pc(), binary()) -> ok | {error, term()}.

Restart the streams of a transceiver that a circuit breaker halted ({circuit_breaker, Mid, Reason} event). RFC 8083 §4.5 asks for a human or a sign that the congestion is gone before restarting; the call is refused with {error, {retry_after, Ms}} during the hold time (circuit_breaker_hold, default 15 s).

send_data(Pc, Id, Type, Data)

-spec send_data(pc(), non_neg_integer(), text | binary, iodata()) -> ok | {error, term()}.

Send a text or binary message on data channel Id.

send_frame(Pc, Mid, Frame, Opts)

-spec send_frame(pc(), binary(), binary(), map()) -> ok | {error, term()}.

Send an encoded frame on a transceiver: split into RTP payloads by the codec's payload format, the marker bit on the last. Frame is a VP8 or VP9 frame, an H.264 access unit in Annex B, an AV1 temporal unit, or an audio payload. Opts: timestamp, keyframe (VP9 and AV1 signal it in the payload), codec, rid.

send_media(Pc, Mid, Raw)

-spec send_media(pc(), binary(), term()) -> ok | {error, term()}.

Equivalent to send_media(Pc, Mid, Raw, #{}).

send_media(Pc, Mid, Raw, Opts)

-spec send_media(pc(), binary(), term(), map()) -> ok | {error, term()}.

Encode raw media with the transceiver's codec plugin (codec_plugin, see webrtc_media_codec) and send the frames. Opts: rid.

send_reference_picture(Pc, Mid, Pt, Bits)

-spec send_reference_picture(pc(), binary(), 0..127, bitstring()) -> ok | {error, term()}.

Ask the remote encoder of a transceiver to use a reference picture the decoder has (RPSI, RFC 4585 §6.3.3, RFC 8834 §5.1.4). Bits is the codec's native RPSI bit string for payload type Pt. Needs nack rpsi negotiated.

send_reference_picture(Pc, Mid, Pt, Bits, Opts)

-spec send_reference_picture(pc(), binary(), 0..127, bitstring(), map()) -> ok | {error, term()}.

Opts: rid for one simulcast layer.

send_rtp(Pc, Mid, Payload, Opts)

-spec send_rtp(pc(), binary(), binary(), map()) -> ok | {error, term()}.

Send an RTP payload on a transceiver. Opts: timestamp, marker, codec (name) or pt, rid to send on one simulcast layer of the transceiver, and audio_level ({Voice, Level}, RFC 6464, level in -dBov 0..127) added when the extension is negotiated, encrypted when negotiated so (RFC 6904).

send_rtp_packet(Pc, Mid, Pkt)

-spec send_rtp_packet(pc(), binary(), tuple()) -> ok | {error, term()}.

Forward an RTP packet (#rtp{}) on a transceiver: SSRC and sequence number are replaced by the transceiver's.

send_rtp_packet(Pc, Mid, Pkt, Opts)

-spec send_rtp_packet(pc(), binary(), tuple(), map()) -> ok | {error, term()}.

Forward an RTP packet. Opts: rid to send it on one simulcast layer, with that layer's SSRC and sequence numbers.

send_slice_loss(Pc, Mid, Entries)

-spec send_slice_loss(pc(), binary(), [{0..8191, 0..8191, 0..63}, ...]) -> ok | {error, term()}.

Tell the remote encoder of a transceiver that slices were lost (SLI, RFC 4585 §6.3.2, RFC 8834 §5.1.3): Entries are {First, Number, PictureId} (13, 13 and 6 bits). Needs nack sli negotiated, {error, not_negotiated} otherwise.

send_slice_loss(Pc, Mid, Entries, Opts)

-spec send_slice_loss(pc(), binary(), [{0..8191, 0..8191, 0..63}, ...], map()) -> ok | {error, term()}.

Opts: rid for one simulcast layer.

set_congestion_control(Pc, Opts)

-spec set_congestion_control(pc(), map()) -> ok | {error, term()}.

Configure congestion control of the connection's media, once the transport exists (after the first description is set). Opts: pacing (boolean, default true; false sends every packet at once), pacing_factor (default 2.5), min_bitrate and max_bitrate (bits per second).

set_direction(Pc, Id, Dir)

-spec set_direction(pc(), pos_integer(), sendrecv | sendonly | recvonly | inactive) ->
                       ok | {error, term()}.

Change the direction of transceiver Id; renegotiate to apply it.

set_local_description(Pc, Type, Sdp)

-spec set_local_description(pc(), sdp_type(), binary() | undefined) -> ok | {error, term()}.

Apply a local description (rollback takes undefined).

set_remote_description(Pc, Type, Sdp)

-spec set_remote_description(pc(), sdp_type(), binary() | undefined) -> ok | {error, term()}.

Apply the peer's description (rollback takes undefined).

signaling_state(Pc)

-spec signaling_state(pc()) -> atom().

The JSEP signaling state, as in {signaling_state, State} events.

stop_transceiver(Pc, Id)

-spec stop_transceiver(pc(), pos_integer()) -> ok | {error, term()}.

Stop transceiver Id; renegotiate to apply it.

transceivers(Pc)

-spec transceivers(pc()) -> [map()].

Transceivers with their mid, directions and SSRCs.