webrtc_jsep (webrtc v0.1.0)

View Source

JSEP (RFC 9429) negotiation on structured SDP.

A pure state machine: it creates offers and answers, applies local and remote descriptions with the signaling state transitions of RFC 9429 §3.2 (including pranswer and rollback), associates transceivers with m= sections (§5.10) and computes the negotiated parameters the transport needs.

  J0 = webrtc_jsep:new(#{ice_ufrag => U, ice_pwd => P, fingerprints => [FP]}),
  {ok, _Id, J1} = webrtc_jsep:add_transceiver(audio, #{}, J0),
  {ok, Offer, J2} = webrtc_jsep:create_offer(#{}, J1),
  {ok, J3} = webrtc_jsep:set_local_description(offer, Offer, J2),
  {ok, J4} = webrtc_jsep:set_remote_description(answer, Answer, J3),
  #{media := [_ | _]} = webrtc_jsep:negotiated(J4).

Each BUNDLE group (RFC 9143) and each section outside a group gets its own transport, with its own ICE credentials and candidates; the bundle option set to false offers every section on its own.

negotiated/1 is the contract between negotiation and the transport process, available once both descriptions are set:

  • ice: local and remote credentials, remote candidates, ICE lite, end of candidates; read by the transport for its ICE agent.
  • dtls: our role, the remote fingerprints and tls-id; read by webrtc_transport_secure for the DTLS association.
  • media: one map per active section (mid, kind, direction, send and receive codecs and extensions, SSRCs, RTX and FEC SSRCs, simulcast layers, feedback, cryptex, frames, codec plugin, priority, and the transport it belongs to); read by webrtc_media:configure/2.
  • data: the SCTP ports and message size of the data section; read by the transport for SCTP and the data channels.
  • bundle and transports: the groups, and the parameters of each transport; read by webrtc_pc to start one transport per group and route calls by mid.

Offers and answers are built in webrtc_jsep_build, the negotiated parameters in webrtc_jsep_params, codecs, extensions and feedback in webrtc_jsep_caps, simulcast in webrtc_jsep_simulcast, and the grouping of sections into transports in webrtc_jsep_transport.

Summary

Functions

Ask for an SCTP m= section (the first createDataChannel call).

Add a transceiver (RTCPeerConnection.addTransceiver). Returns a handle that stays valid for the life of the connection.

RFC 9143 §6, RFC 9429 §5.2.1: with the max-bundle policy an offerer gives every bundled m= section except the tagged one a zero port and a=bundle-only. Such a section is part of the BUNDLE group, not rejected: give it the port of the tagged section so the offer and answer rules treat it as accepted. Sections with port 0 and no bundle-only, or outside every BUNDLE group, stay rejected.

A sender changed SSRC after a collision seen in the media: later descriptions carry the new one.

The mid of the data channel section, once it has one.

Check the frames option: false, true, or the buffer delays.

The local ICE ufrag and password.

Negotiated parameters from the current (or provisional) descriptions, or undefined before the first answer.

Options: ice_ufrag, ice_pwd and fingerprints (required); ice_lite, ice_pacing (our Ta in ms, default 50), sctp_port, max_message_size, codecs and extensions (maps keyed by audio and video; an extension with encrypt => true is offered encrypted, RFC 6904), and encrypt_header_extensions: accept (default) answers an offered encrypted extension encrypted but offers none, offer also offers the encrypted forms, false neither offers nor accepts them.

Check the codec_plugin option: {Module, Opts}, on frames.

New local ICE credentials for an ICE restart; used by the next offer or answer (RFC 9429 §5.2.1, RFC 8445 §9).

Candidates to include in descriptions created from now on.

Candidates of the transport Key (see transports/1) to include in descriptions created from now on.

New local ICE credentials for a transport after the first (an ICE restart of that transport); used by the next offer or answer.

Stop a transceiver. Its m= section is rejected (port 0) in the next offer.

The transports of the local description (current or pending, else the offer to be created), first one first: #{key, mids, ufrag, pwd}. A BUNDLE group is one transport (RFC 9143); an unbundled section has its own.

Types

sdp_type/0

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

state/0

-opaque state()

Functions

add_data_channel(J)

-spec add_data_channel(state()) -> state().

Ask for an SCTP m= section (the first createDataChannel call).

add_transceiver(Kind, Opts, J)

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

Add a transceiver (RTCPeerConnection.addTransceiver). Returns a handle that stays valid for the life of the connection.

send_encodings is a list of #{rid => Rid, restrictions => [{Name, Value}]} maps, one per simulcast layer (RFC 8853), most preferred first. Rids are offered as given, or generated when missing (RFC 9429 §5.2.1); restrictions are RFC 8851 §5 restrictions such as {<<"max-width">>, <<"640">>}. recv_rids lists the simulcast layers to ask for, as rids or #{rid => Rid, paused => true} for a layer to start paused.

A transceiver without send_encodings that answers an offer asking to receive simulcast sends the offered layers (RFC 9429 §5.10).

frames: true, or #{min_delay => Ms, max_delay => Ms}, delivers assembled frames instead of packets (see webrtc_frame_buffer).

priority (very_low, low (default), medium, high), also per encoding in send_encodings, and interactive (default true; set false for video nobody answers live) pick the DSCP the packets are marked with (RFC 8837).

bundle_view(T)

-spec bundle_view(T) -> T
                     when
                         T ::
                             #sdp{version :: non_neg_integer(),
                                  origin ::
                                      #sdp_origin{username :: binary(),
                                                  sess_id :: non_neg_integer(),
                                                  sess_version :: non_neg_integer(),
                                                  nettype :: binary(),
                                                  addrtype :: binary(),
                                                  address :: binary()},
                                  session_name :: binary(),
                                  information :: binary() | undefined,
                                  uri :: binary() | undefined,
                                  emails :: [binary()],
                                  phones :: [binary()],
                                  connection ::
                                      #sdp_connection{nettype :: binary(),
                                                      addrtype :: binary(),
                                                      address :: binary()} |
                                      undefined,
                                  bandwidths :: [{binary(), non_neg_integer()}],
                                  times ::
                                      [#sdp_time{start :: non_neg_integer(),
                                                 stop :: non_neg_integer(),
                                                 repeats :: [[binary(), ...]],
                                                 zones :: [{non_neg_integer(), binary()}]},
                                       ...],
                                  key :: binary() | undefined,
                                  attributes :: [webrtc_sdp:attribute()],
                                  media ::
                                      [#sdp_media{media :: binary(),
                                                  port :: inet:port_number(),
                                                  port_count :: pos_integer() | undefined,
                                                  proto :: binary(),
                                                  fmts :: [binary()],
                                                  information :: binary() | undefined,
                                                  connections ::
                                                      [#sdp_connection{nettype :: binary(),
                                                                       addrtype :: binary(),
                                                                       address :: binary()}],
                                                  bandwidths :: [{binary(), non_neg_integer()}],
                                                  key :: binary() | undefined,
                                                  attributes :: [webrtc_sdp:attribute()]}]} |
                             term().

RFC 9143 §6, RFC 9429 §5.2.1: with the max-bundle policy an offerer gives every bundled m= section except the tagged one a zero port and a=bundle-only. Such a section is part of the BUNDLE group, not rejected: give it the port of the tagged section so the offer and answer rules treat it as accepted. Sections with port 0 and no bundle-only, or outside every BUNDLE group, stay rejected.

change_ssrc(Mid, Old, New, Jsep)

-spec change_ssrc(binary(), 0..4294967295, 0..4294967295, state()) -> state().

A sender changed SSRC after a collision seen in the media: later descriptions carry the new one.

close(J)

-spec close(state()) -> state().

create_answer(Opts, Jsep)

-spec create_answer(map(), state()) ->
                       {ok,
                        #sdp{version :: non_neg_integer(),
                             origin ::
                                 #sdp_origin{username :: binary(),
                                             sess_id :: non_neg_integer(),
                                             sess_version :: non_neg_integer(),
                                             nettype :: binary(),
                                             addrtype :: binary(),
                                             address :: binary()},
                             session_name :: binary(),
                             information :: binary() | undefined,
                             uri :: binary() | undefined,
                             emails :: [binary()],
                             phones :: [binary()],
                             connection ::
                                 #sdp_connection{nettype :: binary(),
                                                 addrtype :: binary(),
                                                 address :: binary()} |
                                 undefined,
                             bandwidths :: [{binary(), non_neg_integer()}],
                             times ::
                                 [#sdp_time{start :: non_neg_integer(),
                                            stop :: non_neg_integer(),
                                            repeats :: [[binary(), ...]],
                                            zones :: [{non_neg_integer(), binary()}]},
                                  ...],
                             key :: binary() | undefined,
                             attributes :: [webrtc_sdp:attribute()],
                             media ::
                                 [#sdp_media{media :: binary(),
                                             port :: inet:port_number(),
                                             port_count :: pos_integer() | undefined,
                                             proto :: binary(),
                                             fmts :: [binary()],
                                             information :: binary() | undefined,
                                             connections ::
                                                 [#sdp_connection{nettype :: binary(),
                                                                  addrtype :: binary(),
                                                                  address :: binary()}],
                                             bandwidths :: [{binary(), non_neg_integer()}],
                                             key :: binary() | undefined,
                                             attributes :: [webrtc_sdp:attribute()]}]},
                        state()} |
                       {error, term()}.

create_offer(Opts, Jsep)

-spec create_offer(map(), state()) ->
                      {ok,
                       #sdp{version :: non_neg_integer(),
                            origin ::
                                #sdp_origin{username :: binary(),
                                            sess_id :: non_neg_integer(),
                                            sess_version :: non_neg_integer(),
                                            nettype :: binary(),
                                            addrtype :: binary(),
                                            address :: binary()},
                            session_name :: binary(),
                            information :: binary() | undefined,
                            uri :: binary() | undefined,
                            emails :: [binary()],
                            phones :: [binary()],
                            connection ::
                                #sdp_connection{nettype :: binary(),
                                                addrtype :: binary(),
                                                address :: binary()} |
                                undefined,
                            bandwidths :: [{binary(), non_neg_integer()}],
                            times ::
                                [#sdp_time{start :: non_neg_integer(),
                                           stop :: non_neg_integer(),
                                           repeats :: [[binary(), ...]],
                                           zones :: [{non_neg_integer(), binary()}]},
                                 ...],
                            key :: binary() | undefined,
                            attributes :: [webrtc_sdp:attribute()],
                            media ::
                                [#sdp_media{media :: binary(),
                                            port :: inet:port_number(),
                                            port_count :: pos_integer() | undefined,
                                            proto :: binary(),
                                            fmts :: [binary()],
                                            information :: binary() | undefined,
                                            connections ::
                                                [#sdp_connection{nettype :: binary(),
                                                                 addrtype :: binary(),
                                                                 address :: binary()}],
                                            bandwidths :: [{binary(), non_neg_integer()}],
                                            key :: binary() | undefined,
                                            attributes :: [webrtc_sdp:attribute()]}]},
                       state()} |
                      {error, term()}.

data_mid(Jsep)

-spec data_mid(state()) -> binary() | undefined.

The mid of the data channel section, once it has one.

frames_opts(O)

-spec frames_opts(term()) -> {ok, false | map()} | {error, {badarg, {frames, term()}}}.

Check the frames option: false, true, or the buffer delays.

local_description(Jsep)

-spec local_description(state()) ->
                           #sdp{version :: non_neg_integer(),
                                origin ::
                                    #sdp_origin{username :: binary(),
                                                sess_id :: non_neg_integer(),
                                                sess_version :: non_neg_integer(),
                                                nettype :: binary(),
                                                addrtype :: binary(),
                                                address :: binary()},
                                session_name :: binary(),
                                information :: binary() | undefined,
                                uri :: binary() | undefined,
                                emails :: [binary()],
                                phones :: [binary()],
                                connection ::
                                    #sdp_connection{nettype :: binary(),
                                                    addrtype :: binary(),
                                                    address :: binary()} |
                                    undefined,
                                bandwidths :: [{binary(), non_neg_integer()}],
                                times ::
                                    [#sdp_time{start :: non_neg_integer(),
                                               stop :: non_neg_integer(),
                                               repeats :: [[binary(), ...]],
                                               zones :: [{non_neg_integer(), binary()}]},
                                     ...],
                                key :: binary() | undefined,
                                attributes :: [webrtc_sdp:attribute()],
                                media ::
                                    [#sdp_media{media :: binary(),
                                                port :: inet:port_number(),
                                                port_count :: pos_integer() | undefined,
                                                proto :: binary(),
                                                fmts :: [binary()],
                                                information :: binary() | undefined,
                                                connections ::
                                                    [#sdp_connection{nettype :: binary(),
                                                                     addrtype :: binary(),
                                                                     address :: binary()}],
                                                bandwidths :: [{binary(), non_neg_integer()}],
                                                key :: binary() | undefined,
                                                attributes :: [webrtc_sdp:attribute()]}]} |
                           undefined.

local_ice(Jsep)

-spec local_ice(state()) -> {binary(), binary()}.

The local ICE ufrag and password.

negotiated(Jsep)

-spec negotiated(state()) -> map() | undefined.

Negotiated parameters from the current (or provisional) descriptions, or undefined before the first answer.

new(Opts)

-spec new(map()) -> state().

Options: ice_ufrag, ice_pwd and fingerprints (required); ice_lite, ice_pacing (our Ta in ms, default 50), sctp_port, max_message_size, codecs and extensions (maps keyed by audio and video; an extension with encrypt => true is offered encrypted, RFC 6904), and encrypt_header_extensions: accept (default) answers an offered encrypted extension encrypted but offers none, offer also offers the encrypted forms, false neither offers nor accepts them.

plugin_opts(P, Frames)

-spec plugin_opts(term(), false | map()) -> {ok, undefined | {module(), term()}} | {error, term()}.

Check the codec_plugin option: {Module, Opts}, on frames.

remote_description(Jsep)

-spec remote_description(state()) ->
                            #sdp{version :: non_neg_integer(),
                                 origin ::
                                     #sdp_origin{username :: binary(),
                                                 sess_id :: non_neg_integer(),
                                                 sess_version :: non_neg_integer(),
                                                 nettype :: binary(),
                                                 addrtype :: binary(),
                                                 address :: binary()},
                                 session_name :: binary(),
                                 information :: binary() | undefined,
                                 uri :: binary() | undefined,
                                 emails :: [binary()],
                                 phones :: [binary()],
                                 connection ::
                                     #sdp_connection{nettype :: binary(),
                                                     addrtype :: binary(),
                                                     address :: binary()} |
                                     undefined,
                                 bandwidths :: [{binary(), non_neg_integer()}],
                                 times ::
                                     [#sdp_time{start :: non_neg_integer(),
                                                stop :: non_neg_integer(),
                                                repeats :: [[binary(), ...]],
                                                zones :: [{non_neg_integer(), binary()}]},
                                      ...],
                                 key :: binary() | undefined,
                                 attributes :: [webrtc_sdp:attribute()],
                                 media ::
                                     [#sdp_media{media :: binary(),
                                                 port :: inet:port_number(),
                                                 port_count :: pos_integer() | undefined,
                                                 proto :: binary(),
                                                 fmts :: [binary()],
                                                 information :: binary() | undefined,
                                                 connections ::
                                                     [#sdp_connection{nettype :: binary(),
                                                                      addrtype :: binary(),
                                                                      address :: binary()}],
                                                 bandwidths :: [{binary(), non_neg_integer()}],
                                                 key :: binary() | undefined,
                                                 attributes :: [webrtc_sdp:attribute()]}]} |
                            undefined.

restart_ice(U, P, J)

-spec restart_ice(binary(), binary(), state()) -> state().

New local ICE credentials for an ICE restart; used by the next offer or answer (RFC 9429 §5.2.1, RFC 8445 §9).

set_direction(Id, Dir, J)

-spec set_direction(pos_integer(), webrtc_sdp_rtp:direction(), state()) ->
                       {ok, state()} | {error, term()}.

set_local_candidates(Cands, EndOfCandidates, J)

-spec set_local_candidates([#sdp_candidate{foundation :: binary(),
                                           component :: 1..256,
                                           transport :: binary(),
                                           priority :: 1..2147483647,
                                           address :: webrtc_sdp_lex:address(),
                                           port :: inet:port_number(),
                                           type :: host | srflx | prflx | relay | binary(),
                                           raddr :: webrtc_sdp_lex:address() | undefined,
                                           rport :: inet:port_number() | undefined,
                                           tcptype :: active | passive | so | undefined,
                                           extensions :: [{binary(), binary()}]}],
                           boolean(),
                           state()) ->
                              state().

Candidates to include in descriptions created from now on.

set_local_candidates(Key, Cands, EndOfCandidates, J)

-spec set_local_candidates(binary(),
                           [#sdp_candidate{foundation :: binary(),
                                           component :: 1..256,
                                           transport :: binary(),
                                           priority :: 1..2147483647,
                                           address :: webrtc_sdp_lex:address(),
                                           port :: inet:port_number(),
                                           type :: host | srflx | prflx | relay | binary(),
                                           raddr :: webrtc_sdp_lex:address() | undefined,
                                           rport :: inet:port_number() | undefined,
                                           tcptype :: active | passive | so | undefined,
                                           extensions :: [{binary(), binary()}]}],
                           boolean(),
                           state()) ->
                              state().

Candidates of the transport Key (see transports/1) to include in descriptions created from now on.

set_local_description(Type, Sdp, Jsep)

-spec set_local_description(sdp_type(),
                            #sdp{version :: non_neg_integer(),
                                 origin ::
                                     #sdp_origin{username :: binary(),
                                                 sess_id :: non_neg_integer(),
                                                 sess_version :: non_neg_integer(),
                                                 nettype :: binary(),
                                                 addrtype :: binary(),
                                                 address :: binary()},
                                 session_name :: binary(),
                                 information :: binary() | undefined,
                                 uri :: binary() | undefined,
                                 emails :: [binary()],
                                 phones :: [binary()],
                                 connection ::
                                     #sdp_connection{nettype :: binary(),
                                                     addrtype :: binary(),
                                                     address :: binary()} |
                                     undefined,
                                 bandwidths :: [{binary(), non_neg_integer()}],
                                 times ::
                                     [#sdp_time{start :: non_neg_integer(),
                                                stop :: non_neg_integer(),
                                                repeats :: [[binary(), ...]],
                                                zones :: [{non_neg_integer(), binary()}]},
                                      ...],
                                 key :: binary() | undefined,
                                 attributes :: [webrtc_sdp:attribute()],
                                 media ::
                                     [#sdp_media{media :: binary(),
                                                 port :: inet:port_number(),
                                                 port_count :: pos_integer() | undefined,
                                                 proto :: binary(),
                                                 fmts :: [binary()],
                                                 information :: binary() | undefined,
                                                 connections ::
                                                     [#sdp_connection{nettype :: binary(),
                                                                      addrtype :: binary(),
                                                                      address :: binary()}],
                                                 bandwidths :: [{binary(), non_neg_integer()}],
                                                 key :: binary() | undefined,
                                                 attributes :: [webrtc_sdp:attribute()]}]} |
                            undefined,
                            state()) ->
                               {ok, state()} | {error, term()}.

set_remote_description(Type, Sdp0, Jsep)

-spec set_remote_description(sdp_type(),
                             #sdp{version :: non_neg_integer(),
                                  origin ::
                                      #sdp_origin{username :: binary(),
                                                  sess_id :: non_neg_integer(),
                                                  sess_version :: non_neg_integer(),
                                                  nettype :: binary(),
                                                  addrtype :: binary(),
                                                  address :: binary()},
                                  session_name :: binary(),
                                  information :: binary() | undefined,
                                  uri :: binary() | undefined,
                                  emails :: [binary()],
                                  phones :: [binary()],
                                  connection ::
                                      #sdp_connection{nettype :: binary(),
                                                      addrtype :: binary(),
                                                      address :: binary()} |
                                      undefined,
                                  bandwidths :: [{binary(), non_neg_integer()}],
                                  times ::
                                      [#sdp_time{start :: non_neg_integer(),
                                                 stop :: non_neg_integer(),
                                                 repeats :: [[binary(), ...]],
                                                 zones :: [{non_neg_integer(), binary()}]},
                                       ...],
                                  key :: binary() | undefined,
                                  attributes :: [webrtc_sdp:attribute()],
                                  media ::
                                      [#sdp_media{media :: binary(),
                                                  port :: inet:port_number(),
                                                  port_count :: pos_integer() | undefined,
                                                  proto :: binary(),
                                                  fmts :: [binary()],
                                                  information :: binary() | undefined,
                                                  connections ::
                                                      [#sdp_connection{nettype :: binary(),
                                                                       addrtype :: binary(),
                                                                       address :: binary()}],
                                                  bandwidths :: [{binary(), non_neg_integer()}],
                                                  key :: binary() | undefined,
                                                  attributes :: [webrtc_sdp:attribute()]}]} |
                             undefined,
                             state()) ->
                                {ok, state()} | {error, term()}.

set_transport_credentials(Key, U, P, J)

-spec set_transport_credentials(binary(), binary(), binary(), state()) -> state().

New local ICE credentials for a transport after the first (an ICE restart of that transport); used by the next offer or answer.

signaling_state(Jsep)

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

stop_transceiver(Id, J)

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

Stop a transceiver. Its m= section is rejected (port 0) in the next offer.

transceivers(Jsep)

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

transports(J)

-spec transports(state()) -> [map()].

The transports of the local description (current or pending, else the offer to be created), first one first: #{key, mids, ufrag, pwd}. A BUNDLE group is one transport (RFC 9143); an unbundled section has its own.