Improve API and API docs (#57)

Author: mickel8

README.md

@@ -3,7 +3,7 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/elixir-webrtc/ex_webrtc/ci.yml?logo=github&label=CI)](https://github.com/elixir-webrtc/ex_webrtc/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/elixir-webrtc/ex_webrtc/graph/badge.svg?token=PdnXfnnmNw)](https://codecov.io/gh/elixir-webrtc/ex_webrtc)
 
-Implementation of WebRTC in Elixir.
+Implementation of [the W3C WebRTC API](https://www.w3.org/TR/webrtc/) in Elixir.
 
 ## Installation
 

examples/echo/example.exs

@@ -9,7 +9,7 @@ defmodule Peer do
   require Logger
 
   alias ExWebRTC.{
-    IceCandidate,
+    ICECandidate,
     PeerConnection,
     MediaStreamTrack,
     SessionDescription,
@@ -129,7 +129,7 @@ defmodule Peer do
   defp handle_ws_message(%{"type" => "ice", "data" => data}, state) do
     Logger.info("Received remote ICE candidate: #{inspect(data)}")
 
-    candidate = %IceCandidate{
+    candidate = %ICECandidate{
       candidate: data["candidate"],
       sdp_mid: data["sdpMid"],
       sdp_m_line_index: data["sdpMLineIndex"],

examples/save_to_file/example.exs

@@ -9,7 +9,7 @@ defmodule Peer do
   require Logger
 
   alias ExWebRTC.{
-    IceCandidate,
+    ICECandidate,
     MediaStreamTrack,
     PeerConnection,
     SessionDescription,
@@ -123,7 +123,7 @@ defmodule Peer do
   defp handle_ws_message(%{"type" => "ice", "data" => data}, state) do
     Logger.info("Received remote ICE candidate: #{inspect(data)}")
 
-    candidate = %IceCandidate{
+    candidate = %ICECandidate{
       candidate: data["candidate"],
       sdp_mid: data["sdpMid"],
       sdp_m_line_index: data["sdpMLineIndex"],

examples/send_from_file/example.exs

@@ -11,7 +11,7 @@ defmodule Peer do
   import Bitwise
 
   alias ExWebRTC.{
-    IceCandidate,
+    ICECandidate,
     MediaStreamTrack,
     Media.IVF,
     Media.Ogg,
@@ -220,7 +220,7 @@ defmodule Peer do
   defp handle_ws_message(%{"type" => "ice", "data" => data}, state) do
     Logger.info("Received remote ICE candidate: #{inspect(data)}")
 
-    candidate = %IceCandidate{
+    candidate = %ICECandidate{
       candidate: data["candidate"],
       sdp_mid: data["sdpMid"],
       sdp_m_line_index: data["sdpMLineIndex"],

lib/ex_webrtc/dtls_transport.ex

@@ -1,7 +1,5 @@
 defmodule ExWebRTC.DTLSTransport do
-  @moduledoc """
-  DTLSTransport
-  """
+  @moduledoc false
 
   use GenServer
 
@@ -11,25 +9,30 @@ defmodule ExWebRTC.DTLSTransport do
 
   @type dtls_transport() :: pid()
 
-  # Messages sent by the DTLSTransport
-  @typedoc false
-  @type signal() :: {:dtls_transport, pid(), state_change() | rtp_data()}
+  @typedoc """
+  Messages sent by the DTLSTransport.
+  """
+  @type signal() :: {:dtls_transport, pid(), state_change() | rtp_rtcp()}
 
-  # Message sent when DTLSTransport changes its state
-  @typedoc false
+  @typedoc """
+  Message sent when DTLSTransport changes its state.
+  """
   @type state_change() :: {:state_change, dtls_state()}
 
-  # Message sent when a new RTP packet arrives.
-  # Packet is decrypted.
-  @typedoc false
-  @type rtp_data() :: {:rtp_data, binary()}
+  @typedoc """
+  Message sent when a new RTP/RTCP packet arrives.
 
-  # Possible DTLSTransport states.
-  # For the exact meaning, refer to the [WebRTC W3C, sec. 5.5.1](https://www.w3.org/TR/webrtc/#rtcdtlstransportstate-enum)
-  @typedoc false
+  Packet is decrypted.
+  """
+  @type rtp_rtcp() :: {:rtp | :rtcp, binary()}
+
+  @typedoc """
+  Possible DTLSTransport states.
+
+  For the exact meaning, refer to the [WebRTC W3C, sec. 5.5.1](https://www.w3.org/TR/webrtc/#rtcdtlstransportstate-enum)
+  """
   @type dtls_state() :: :new | :connecting | :connected | :closed | :failed
 
-  @doc false
   @spec start_link(ICETransport.t(), pid()) :: GenServer.on_start()
   def start_link(ice_transport \\ DefaultICETransport, ice_pid) do
     behaviour = ice_transport.__info__(:attributes)[:behaviour] || []
@@ -41,38 +44,32 @@ defmodule ExWebRTC.DTLSTransport do
     GenServer.start_link(__MODULE__, [ice_transport, ice_pid, self()])
   end
 
-  @doc false
   @spec set_ice_connected(dtls_transport()) :: :ok
   def set_ice_connected(dtls_transport) do
     GenServer.call(dtls_transport, :set_ice_connected)
   end
 
-  @doc false
   @spec get_fingerprint(dtls_transport()) :: binary()
   def get_fingerprint(dtls_transport) do
     GenServer.call(dtls_transport, :get_fingerprint)
   end
 
-  @doc false
   @spec start_dtls(dtls_transport(), :active | :passive, binary()) ::
           :ok | {:error, :already_started}
   def start_dtls(dtls_transport, mode, peer_fingerprint) do
     GenServer.call(dtls_transport, {:start_dtls, mode, peer_fingerprint})
   end
 
-  @doc false
   @spec send_rtp(dtls_transport(), binary()) :: :ok
   def send_rtp(dtls_transport, data) do
     GenServer.cast(dtls_transport, {:send_rtp, data})
   end
 
-  @doc false
   @spec send_rtcp(dtls_transport(), binary()) :: :ok
   def send_rtcp(dtls_transport, data) do
     GenServer.cast(dtls_transport, {:send_rtcp, data})
   end
 
-  @doc false
   @spec stop(dtls_transport()) :: :ok
   def stop(dtls_transport) do
     GenServer.stop(dtls_transport)

lib/ex_webrtc/ice_candidate.ex

@@ -1,14 +1,13 @@
-defmodule ExWebRTC.IceCandidate do
+defmodule ExWebRTC.ICECandidate do
   @moduledoc """
-  ICE candidate
+  Implementation of the [RTCIceCandidate](https://www.w3.org/TR/webrtc/#rtcicecandidate-interface).
   """
 
-  # not exacly the same as W3 IceCandidate
   @type t() :: %__MODULE__{
-          candidate: term() | nil,
-          sdp_mid: term() | nil,
-          sdp_m_line_index: term() | nil,
-          username_fragment: term() | nil
+          candidate: binary(),
+          sdp_mid: non_neg_integer() | nil,
+          sdp_m_line_index: non_neg_integer() | nil,
+          username_fragment: binary() | nil
         }
 
   defstruct [:candidate, :username_fragment, :sdp_mid, :sdp_m_line_index]

lib/ex_webrtc/media_stream_track.ex

@@ -1,21 +1,23 @@
 defmodule ExWebRTC.MediaStreamTrack do
   @moduledoc """
-  MediaStreamTrack
+  Mimics [MediaStreamTrack](https://www.w3.org/TR/mediacapture-streams/#dom-mediastreamtrack).
   """
 
   alias ExWebRTC.Utils
 
   @type id() :: integer()
+  @type kind() :: :audio | :video
 
   @type t() :: %__MODULE__{
-          kind: :audio | :video,
+          kind: kind(),
           id: id()
         }
 
   @enforce_keys [:id, :kind]
   defstruct @enforce_keys
 
-  def new(kind) do
+  @spec new(kind()) :: t()
+  def new(kind) when kind in [:audio, :video] do
     %__MODULE__{kind: kind, id: Utils.generate_id()}
   end
 end

lib/ex_webrtc/peer_connection.ex

@@ -1,6 +1,6 @@
 defmodule ExWebRTC.PeerConnection do
   @moduledoc """
-  PeerConnection
+  Implementation of the [RTCPeerConnection](https://www.w3.org/TR/webrtc/#dom-rtcpeerconnection).
   """
 
   use GenServer
@@ -14,7 +14,7 @@ defmodule ExWebRTC.PeerConnection do
   alias ExWebRTC.{
     DefaultICETransport,
     DTLSTransport,
-    IceCandidate,
+    ICECandidate,
     MediaStreamTrack,
     RTPTransceiver,
     RTPSender,
@@ -36,7 +36,7 @@ defmodule ExWebRTC.PeerConnection do
   @type signal() ::
           {:ex_webrtc, pid(),
            :negotiation_needed
-           | {:ice_candidate, IceCandidate.t()}
+           | {:ice_candidate, ICECandidate.t()}
            | {:signaling_state_change, signaling_state()}
            | {:connection_state_change, connection_state()}
            | {:track, MediaStreamTrack.t()}
@@ -72,19 +72,19 @@ defmodule ExWebRTC.PeerConnection do
   end
 
   @spec create_offer(peer_connection(), offer_options()) ::
-          {:ok, SessionDescription.t()} | {:error, :TODO}
+          {:ok, SessionDescription.t()} | {:error, :invalid_state}
   def create_offer(peer_connection, options \\ []) do
     GenServer.call(peer_connection, {:create_offer, options})
   end
 
   @spec create_answer(peer_connection(), answer_options()) ::
-          {:ok, SessionDescription.t()} | {:error, :TODO}
+          {:ok, SessionDescription.t()} | {:error, :invalid_state}
   def create_answer(peer_connection, options \\ []) do
     GenServer.call(peer_connection, {:create_answer, options})
   end
 
   @spec set_local_description(peer_connection(), SessionDescription.t()) ::
-          :ok | {:error, :TODO}
+          :ok | {:error, atom()}
   def set_local_description(peer_connection, description) do
     GenServer.call(peer_connection, {:set_local_description, description})
   end
@@ -95,7 +95,7 @@ defmodule ExWebRTC.PeerConnection do
   end
 
   @spec set_remote_description(peer_connection(), SessionDescription.t()) ::
-          :ok | {:error, :TODO}
+          :ok | {:error, atom()}
   def set_remote_description(peer_connection, description) do
     GenServer.call(peer_connection, {:set_remote_description, description})
   end
@@ -105,8 +105,8 @@ defmodule ExWebRTC.PeerConnection do
     GenServer.call(peer_connection, :get_current_remote_description)
   end
 
-  @spec add_ice_candidate(peer_connection(), IceCandidate.t()) ::
-          :ok | {:error, :TODO}
+  @spec add_ice_candidate(peer_connection(), ICECandidate.t()) ::
+          :ok | {:error, :no_remote_description}
   def add_ice_candidate(peer_connection, candidate) do
     GenServer.call(peer_connection, {:add_ice_candidate, candidate})
   end
@@ -157,16 +157,16 @@ defmodule ExWebRTC.PeerConnection do
     GenServer.call(peer_connection, {:remove_track, sender_id})
   end
 
-  @spec close(peer_connection()) :: :ok
-  def close(peer_connection) do
-    GenServer.stop(peer_connection)
-  end
-
   @spec send_rtp(peer_connection(), String.t(), ExRTP.Packet.t()) :: :ok
   def send_rtp(peer_connection, track_id, packet) do
     GenServer.cast(peer_connection, {:send_rtp, track_id, packet})
   end
 
+  @spec close(peer_connection()) :: :ok
+  def close(peer_connection) do
+    GenServer.stop(peer_connection)
+  end
+
   #### CALLBACKS ####
 
   @impl true
@@ -617,7 +617,7 @@ defmodule ExWebRTC.PeerConnection do
 
   @impl true
   def handle_info({:ex_ice, _from, {:new_candidate, candidate}}, state) do
-    candidate = %IceCandidate{
+    candidate = %ICECandidate{
       candidate: "candidate:" <> candidate,
       sdp_mid: 0,
       sdp_m_line_index: 0
@@ -795,7 +795,7 @@ defmodule ExWebRTC.PeerConnection do
 
   defp apply_local_description(%SessionDescription{type: type}, _state)
        when type in [:rollback, :pranswer],
-       do: {:error, :not_implemented}
+       do: {:error, :"#{type}_not_implemented"}
 
   defp apply_local_description(%SessionDescription{type: type, sdp: raw_sdp}, state) do
     with {:ok, next_sig_state} <- next_signaling_state(state.signaling_state, :local, type),
@@ -829,7 +829,7 @@ defmodule ExWebRTC.PeerConnection do
 
   defp apply_remote_description(%SessionDescription{type: type}, _state)
        when type in [:rollback, :pranswer],
-       do: {:error, :not_implemented}
+       do: {:error, :"#{type}_not_implemented"}
 
   defp apply_remote_description(%SessionDescription{type: type, sdp: raw_sdp}, state) do
     with {:ok, next_sig_state} <- next_signaling_state(state.signaling_state, :remote, type),

lib/ex_webrtc/peer_connection/configuration.ex

@@ -1,6 +1,6 @@
 defmodule ExWebRTC.PeerConnection.Configuration do
   @moduledoc """
-  PeerConnection configuration
+  `ExWebRTC.PeerConnection` configuration.
   """
 
   alias ExWebRTC.{RTPCodecParameters, SDPUtils}

lib/ex_webrtc/rtp/opus_depayloader.ex

@@ -1,6 +1,8 @@
 defmodule ExWebRTC.RTP.OpusDepayloader do
   @moduledoc """
   Decapsualtes Opus audio out of RTP packet.
+
+  Based on [RFC 7587: RTP Payload Format for the Opus Speech and Audio Codec](https://datatracker.ietf.org/doc/html/rfc7587).
   """
 
   alias ExRTP.Packet

lib/ex_webrtc/rtp/opus_payloader.ex

@@ -1,6 +1,8 @@
 defmodule ExWebRTC.RTP.OpusPayloader do
   @moduledoc """
   Encapsulates Opus audio packet into an RTP packet.
+
+  Based on [RFC 7587: RTP Payload Format for the Opus Speech and Audio Codec](https://datatracker.ietf.org/doc/html/rfc7587).
   """
 
   @doc """

lib/ex_webrtc/rtp/vp8_depayloader.ex

@@ -2,7 +2,7 @@ defmodule ExWebRTC.RTP.VP8Depayloader do
   @moduledoc """
   Reassembles VP8 frames from RTP packets.
 
-  Based on [RFC 7741: RTP Payload Format for VP8 Video](https://datatracker.ietf.org/doc/html/rfc7741)
+  Based on [RFC 7741: RTP Payload Format for VP8 Video](https://datatracker.ietf.org/doc/html/rfc7741).
   """
   require Logger
 

lib/ex_webrtc/rtp/vp8_payload.ex

@@ -2,7 +2,7 @@ defmodule ExWebRTC.RTP.VP8Payload do
   @moduledoc """
   Defines VP8 payload structure stored in RTP packet payload.
 
-  Based on [RFC 7741: RTP Payload Format for VP8 Video](https://datatracker.ietf.org/doc/html/rfc7741)
+  Based on [RFC 7741: RTP Payload Format for VP8 Video](https://datatracker.ietf.org/doc/html/rfc7741).
   """
 
   @type t() :: %__MODULE__{

lib/ex_webrtc/rtp/vp8_payloader.ex

@@ -2,7 +2,7 @@ defmodule ExWebRTC.RTP.VP8Payloader do
   @moduledoc """
   Encapsulates VP8 video frames into RTP packets.
 
-  Based on [RFC 7741: RTP Payload Format for VP8 Video](https://datatracker.ietf.org/doc/html/rfc7741)
+  Based on [RFC 7741: RTP Payload Format for VP8 Video](https://datatracker.ietf.org/doc/html/rfc7741).
 
   It does not support `X` bit right now, in particular it
   does not pay attention to VP8 partion boundaries (see RFC 7741 sec. 4.4).

lib/ex_webrtc/rtp_codec_parameters.ex

@@ -1,8 +1,10 @@
 defmodule ExWebRTC.RTPCodecParameters do
   @moduledoc """
-  RTPCodecParameters
+  Implementation of the [RTCRtpCodecParameters](https://www.w3.org/TR/webrtc/#rtcrtpcodecparameters).
   """
 
+  alias ExSDP.Attribute.{FMTP, RTPMapping, RTCPFeedback}
+
   @type t() :: %__MODULE__{
           payload_type: non_neg_integer(),
           mime_type: binary(),
@@ -15,6 +17,7 @@ defmodule ExWebRTC.RTPCodecParameters do
   @enforce_keys [:payload_type, :mime_type, :clock_rate]
   defstruct @enforce_keys ++ [:channels, :sdp_fmtp_line, rtcp_fbs: []]
 
+  @spec new(:audio | :video, RTPMapping.t(), FMTP.t() | nil, [RTCPFeedback.t()]) :: t()
   def new(type, rtp_mapping, fmtp, rtcp_fbs) do
     %__MODULE__{
       payload_type: rtp_mapping.payload_type,