a GLib ICE implementation

libnice

…is a library that implements the Interactive Connectivity Establishment (ICE) standard (RFC 5245 & RFC 8445)!

It provides a GLib-based library, libnice, as well as GStreamer elements to use it.

libnice is sponsored by Collabora.

Why

Traverse NATs and Interop

ICE is useful for applications that want to establish peer-to-peer UDP data streams. It automates the process of traversing NATs and provides security against some attacks. It also allows applications to create reliable streams using a TCP over UDP layer.

Existing standards that use ICE include Session Initiation Protocol (SIP), XMPP Jingle and WebRTC.

libnice has been tested to interop with other major ICE implementations. In particular, it is widely used to interop with Google’s WebRTC library used to implement the WebRTC specifications in all major browers, Chrome, Firefox & Safari. It also implements some of the Microsoft variants used by Microsoft Office Communicator, Microsoft Lync & Microsoft Skype for Business.

standards

libnice implements a number of current standards:

  • RFC 8445: Interactive Connectivity Establishment (ICE) itself
  • RFC 5766: TURN relay client
  • RFC 5389: Full STUN implementation
  • RFC 6544: TCP Candidates with ICE (ICE-TCP)
    • Partial support, only passive and active candidates are supported
  • Trickle ICE: Incremental Provisioning of Candidates
  • Compatible with IPv4 & IPv6

It also implements a number of older version with appropriate compatibility flags:

  • RFC 5242: The original ICE RFC
    • Also implements Draft 6 as used by older programs.
  • RFC 3489: The original STUN RFC

There is also compatibility mode with non-standard implemenations:

  • Microsoft’s implementations, both compatible with Windows Live Messenger 2009, Office Communicator 2007, Office Communicator 2007R2, Lync, Skype for Business. - Those are mostly documented in MS-ICE2
  • Compatibility with the old variant used by Google Talk
download

You can get libnice from our GitLab repository.

You can also download release tarballs:

docs

Reference manual

The generated documentation for the latest released version is available online.

GStreamer

libnice has been designed to nice integrate with GStreamer, two GStreamer element are provided nicesrc and nicesink to help with that.

libnice works with both GStreamer 0.10 and GStreamer 1.x.

Steps to use:

  • Create a NiceAgent
  • Create a stream with nice_agent_add_stream()
  • Create a nicesrc GStreamer element for each component
  • Set the NiceAgent, stream_id and component_id on each nicesrc
  • Put the nicesrc elements inside a GstPipeline and connect them to the elements that will receive the packets, most likely rtpbin
  • Set the GstPipeline to the PLAYING state
  • libnice can now receive packets.
  • Use the nice_agent_gather_candidates() API to gather candidates
  • Use the libnice APIs to exchange candidates and credentials, this will cause establish connectivity, be aware that as soon as connectivity is established (component state is CONNECTED), nicesrc may start producing data packets. Don’t forget to monitor the state of each component.

At any time after the libnice Stream has been created, you can create nicesink elements and add them to your pipeline to send packets, you can do that at the same time as the nicesrc elements or later. b

contributing

Support requests and general discussions should on the mailing list, a full archive is available.

Contributions are welcome! Please reports bugs using freedesktop.org GitLab.

Patches can also be submitted as merge requests on our GitLab.

Merge requests are NOT accepted on the GitHub or GitLab.com mirrors.

Code of Conduct

libnice is hosted by freedesktop.org and as such applies its Code of Conduct. This applies to all of our forums, including GitLab and the mailing list. Please be excellent to each other.