Specter is a method for managing data structures and entities provided by webrtc.rs. It is intended as a low-level library with some small set of opinions, which can composed into more complex behaviors by higher-level libraries and applications.

Key points

Specter wraps webrtc.rs, which heavily utilizes async Rust. For this reason, many functions cannot be automatically awaited by the caller—the NIF functions send messages across channels to separate threads managed by Rust, which send messages back to Elixir that can be caught by receive or handle_info.

Usage

A process initializes Specter via the init/1 function, which registers the current process for callbacks that may be triggered via webrtc entities.

iex> ## Initialize the library. Register messages to the current pid.
iex> {:ok, specter} = Specter.init(ice_servers: ["stun:stun.l.google.com:19302"])
...>
iex> ## Create a peer connection's dependencies
iex> {:ok, media_engine} = Specter.new_media_engine(specter)
iex> {:ok, registry} = Specter.new_registry(specter, media_engine)
...>
iex> Specter.media_engine_exists?(specter, media_engine)
true
iex> Specter.registry_exists?(specter, registry)
true
...>
iex> {:ok, api} = Specter.new_api(specter, media_engine, registry)
...>
iex> Specter.media_engine_exists?(specter, media_engine)
false
iex> Specter.registry_exists?(specter, registry)
false
...>
iex> ## Create a peer connection
iex> {:ok, pc_1} = Specter.PeerConnection.new(specter, api)
iex> assert_receive {:peer_connection_ready, ^pc_1}
iex> Specter.PeerConnection.exists?(specter, pc_1)
true
iex> ## Add a thing to be negotiated
iex> :ok = Specter.PeerConnection.create_data_channel(specter, pc_1, "data")
iex> assert_receive {:data_channel_created, ^pc_1}
...>
iex> ## Create an offer
iex> :ok = Specter.PeerConnection.create_offer(specter, pc_1)
iex> assert_receive {:offer, ^pc_1, offer}
iex> :ok = Specter.PeerConnection.set_local_description(specter, pc_1, offer)
iex> assert_receive {:ok, ^pc_1, :set_local_description}
...>
iex> ## Create a second peer connection, to answer back
iex> {:ok, media_engine} = Specter.new_media_engine(specter)
iex> {:ok, registry} = Specter.new_registry(specter, media_engine)
iex> {:ok, api} = Specter.new_api(specter, media_engine, registry)
iex> {:ok, pc_2} = Specter.PeerConnection.new(specter, api)
iex> assert_receive {:peer_connection_ready, ^pc_2}
...>
iex> ## Begin negotiating offer/answer
iex> :ok = Specter.PeerConnection.set_remote_description(specter, pc_2, offer)
iex> assert_receive {:ok, ^pc_2, :set_remote_description}
iex> :ok = Specter.PeerConnection.create_answer(specter, pc_2)
iex> assert_receive {:answer, ^pc_2, answer}
iex> :ok = Specter.PeerConnection.set_local_description(specter, pc_2, answer)
iex> assert_receive {:ok, ^pc_2, :set_local_description}
...>
iex> ## Receive ice candidates
iex> assert_receive {:ice_candidate, ^pc_1, _candidate}
iex> assert_receive {:ice_candidate, ^pc_2, _candidate}
...>
iex> ## Shut everything down
iex> Specter.PeerConnection.close(specter, pc_1)
:ok
iex> assert_receive {:peer_connection_closed, ^pc_1}
...>
iex> :ok = Specter.PeerConnection.close(specter, pc_2)
iex> assert_receive {:peer_connection_closed, ^pc_2}

Thoughts

During development of the library, it can be assumed that callers will implement handle_info/2 function heads appropriate to the underlying implementation. Once these are more solid, it would be nice to use Specter, which will inject a handle_info/2 callback, and send the messages to other callback functions defined by a behaviour. handle_ice_candidate, and so on.

Some things are returned from the NIF as UUIDs. These are declared as @opaque, to indicate that users of the library should not rely of them being in a particular format. They could change later to be references, for instance.