Future Shock

The Pion team is very excited to announce the v3.0.0 release of Pion WebRTC. Pion WebRTC is a Go implementation of WebRTC. If you haven't used it before check out awesome-pion or example-webrtc-applications for what people are doing. We maintain a feature list and other helpful resources in our README.md

This release includes 264 commits from 43 authors. We reduced sharp edges in the media API, add performance gains in media and datachannel paths and brought ourselves more in alignment with the browser API.

We do have quite a few breaking changes. Please read them carefully, most of these things can't be caught at compile time. Reading this document could save a lot of time debugging. Each change will have a linked commit. Looking at examples/ in the linked commit should show what code you need to change in your application.

Breaking Changes

Trickle ICE is now enabled by default

Before /v3 Pion WebRTC would gather all candidates before a CreateOffer or CreateAnswer generated a SDP. This would
cause a few issues in real world applications. You can read about the benefits of Trickle ICE here

• Longer call connection times since we blocked for STUN/TURN even if not needed
• This didn't comply with the WebRTC spec
• Made it harder for users to filter/process ICE Candidates

Now you should exchange ICE Candidates that are pushed via the OnICECandidate callback.

Before

  peerConnection, _ := webrtc.NewPeerConnection(webrtc.Configuration{})

  offer, _ := peerConnection.CreateOffer()
  peerConnection.SetLocalDescription(offer)

  // Send `offer` to remote peer
  websocket.Write(offer)

After

  peerConnection, _ := webrtc.NewPeerConnection(webrtc.Configuration{})

  // Set ICE Candidate handler. As soon as a PeerConnection has gathered a candidate
  // send it to the other peer
  peerConnection.OnICECandidate(func(i *webrtc.ICECandidate) {
    // Send ICE Candidate via Websocket/HTTP/$X to remote peer
  })

  // Listen for ICE Candidates from the remote peer
  peerConnection.AddICECandidate(remoteCandidate)

  // You still signal like before, but `CreateOffer` will be much faster
  offer, _ := peerConnection.CreateOffer()
  peerConnection.SetLocalDescription(offer)

  // Send `offer` to remote peer
  websocket.Write(offer)

If you are unable to migrate we have provided a helper function to simulate the pre-v3 behavior.

Helper function to simulate non-trickle ICE

  peerConnection, _ := webrtc.NewPeerConnection(webrtc.Configuration{})

  offer, _ := peerConnection.CreateOffer()

  // Create channel that is blocked until ICE Gathering is complete
  gatherComplete := webrtc.GatheringCompletePromise(peerConnection)
  peerConnection.SetLocalDescription(offer)
  <-gatherComplete

  // Send `LocalDescription` to remote peer
  // This is the offer but populated with all the ICE Candidates
  websocket.Write(*peerConnection.LocalDescription())

This was changed with bb3aa9

A data channel is no longer implicitly created with a PeerConnection

Before /v3 Pion WebRTC would always insert a application Media Section. This means that an offer would work even if
you didn't create a DataChannel or Transceiver, in /v3 you MUST create a DataChannel or track first. To better illustrate
these are two SDPs, each from a different version of Pion WebRTC

/v2 SDP with no CreateDataChannel

v=0
o=- 8334017457074456852 1596089329 IN IP4 0.0.0.0
s=-
t=0 0
a=fingerprint:sha-256 91:B0:3A:6E:9E:43:9A:9D:1B:71:17:7D:FB:D0:5C:81:12:6E:61:D5:6C:BF:92:E8:8D:04:F5:92:EF:62:36:C9
a=group:BUNDLE 0
m=application 9 DTLS/SCTP 5000
c=IN IP4 0.0.0.0
a=setup:actpass
a=mid:0
a=sendrecv
a=sctpmap:5000 webrtc-datachannel 1024
a=ice-ufrag:yBlrlyMmuDdCfawp
a=ice-pwd:RzlouYCNYDNpPLJLdddFtUkMVpKVLYWz
a=candidate:foundation 1 udp 2130706431 192.168.1.8 51147 typ host generation 0
a=candidate:foundation 2 udp 2130706431 192.168.1.8 51147 typ host generation 0
a=end-of-candidates

/v3 SDP with no CreateDataChannel

v=0
o=- 8628031010413059766 1596089396 IN IP4 0.0.0.0
s=-
t=0 0
a=fingerprint:sha-256 64:79:7C:73:6B:8A:CF:34:9D:D0:9C:6B:31:07:44:0A:CD:56:F0:74:62:72:D4:23:D5:BC:B2:C9:46:55:C5:A3
a=group:BUNDLE

To simulate the old functionality, call CreateDataChannel after creating your PeerConnection and before calling anything else.

This was changed with abd6a3

Track is now an interface

The design of the Track API in /v3 has been updated to accommodate more use cases and reduce the sharp edges in the API.
Before we used one structure to represent incoming and outgoing media. This didn't match with how WebRTC actually works.
In WebRTC a track isn't bi-directional. Having Read and Write on the same structure was confusing.

Split Track into TrackLocal and TrackRemote

Now we have TrackLocal and TrackRemote. TrackLocal is used to send media, TrackRemote is used to receive media.

TrackRemote has a similar API to /v2. It has Read and ReadRTP and code will continue to work with just a name change Track -> TrackRemote

TrackLocal is now an interface, and will require more work to port. For existing code you will want to use one of the TrackLocal implementations.
NewLocalTrackStaticSample or NewLocalTrackStaticRTP depending on what type of data you were sending before.

Code that looks like

  videoTrack, err := peerConnection.NewTrack(payloadType, randutil.NewMathRandomGenerator().Uint32(), "video", "pion")

Needs to become like one of the following

  videoTrack, err := webrtc.NewTrackLocalStaticSample(webrtc.RTPCodecCapability{MimeType: "video/vp8"}, "video", "pion")

  videoTrack, err := webrtc.NewTrackLocalStaticRTP(webrtc.RTPCodecCapability{MimeType: "video/vp8"}, "video", "pion")

Users no longer have to manage SSRC/PayloadType

When creating a Track you don't need to know these values. When writing packets you don't need to pull these values either. Internally
we make sure that everything is properly set. This means that mediaengine.PopulateFromSDP has been removed, and you can delete any code that does this.

Other packages can satisfy LocalTrack

pion/mediadevices now can provide an API that feels like getUserMedia in the browser. Before it wasn't able to generate
anything that pion/webrtc could directly call AddTrack on.

A user could also implement LocalTrack and and add custom behavior.

MediaEngine API has changed

We now use data structures from the W3C to configure available codecs and header extensions. You can also define your own MimeTypes, allowing
you to send any codec you wish! pion/webrtc can support for a new codec with just calls to the public API.

Before

  m.RegisterCodec(webrtc.NewRTPOpusCodec(webrtc.DefaultPayloadTypeOpus, 48000))
  m.RegisterCodec(webrtc.NewRTPVP8Codec(webrtc.DefaultPayloadTypeVP8, 90000))

After

  if err := m.RegisterCodec(webrtc.RTPCodecParameters{
    RTPCodecCapability: webrtc.RTPCodecCapability{MimeType: "video/VP8", ClockRate: 90000, Channels: 0, SDPFmtpLine: "", RTCPFeedback: nil},
    PayloadType:        96,
  }, webrtc.RTPCodecTypeVideo); err != nil {
    panic(err)
  }
  if err := m.RegisterCodec(webrtc.RTPCodecParameters{
    RTPCodecCapability: webrtc.RTPCodecCapability{MimeType: "audio/opus", ClockRate: 48000, Channels: 0, SDPFmtpLine: "", RTCPFeedback: nil},
    PayloadType:        111,
  }, webrtc.RTPCodecTypeAudio); err != nil {
    panic(err)
  }

This was changed with 7edfb7

New Features

ICE Restarts

You can now initiate and accept an ICE Restart! This means that if a PeerConnection goes to Disconnected or Failed because of network interruption it is no longer fatal.

To use you just need to pass ICERestart: true in your OfferOptions. The answering PeerConnection will then restart also. This is supported in FireFox/Chrome and Mobile WebRTC Clients.

  peerConn, _ := NewPeerConnection(Configuration{})

  // PeerConnection goes to ICEConnectionStateFailed

  offer, _ := peerConn.CreateOffer(&OfferOptions{ICERestart: true})

This was implemented in f29414

ICE TCP

Pion WebRTC now can act as a passive ICE TCP candidates. This means that a remote ICE Agent that supports TCP active can connect to Pion without using UDP. Before the only way to achieve ICE Connectivity in UDP-less networks was by using a TURN server.

You should still deploy and use a TURN server for NAT traversal.

Since this isn't part of the standard WebRTC API it requires SettingEngine usage. You can see how to use it in examples/ice-tcp

This was implemented in 2236dd

OnNegotationNeeded

onnegotationneeded is now available. You can define a callback and be notified whenever session negotiation needs to done.

OnNegotationNeeded in pion/webrtc will behave differently that in the browser because we are operating in a multi-threaded environment. Make sure to have proper locking around your signaling/S...

v3.0.0-beta.15: Fix RTPSendParameters

RTPSendParameters contains an array of encodings.
RTPSender.GetParameters returns RTPSendParameters.

v3.0.0-beta.11: Add RTPTransceiver.SetSender

This non-standard API allows us to re-use existing transceivers.
The WebRTC API causes SDP bloat right now since it doesn't allow
the re-use of existing media sections.

v3.0.0-beta.10

hold lock for checkNegotiationNeeded transceiver checks

The HUNT Begins

After 5 months of work (and lots of distraction) the Pion team is excited to announce the release of v2.2.0!
This release includes.

New Features

DataChannel Performance Improvements

Thanks to hard work by @enobufs Datachannels have gotten a huge performance improvement. In some cases you will see a 16x improvement in throughput. You can read more about his fantastic work here

Extend SettingEngine to support SFU use cases

Pion WebRTC is seeing lots of usage in building SFUs. To support this the SettingEngine has been extended to add even more options. You now have the following flags you can configure

• SetEphemeralUDPPortRange You can limit the range of UDP ports used to support restrictive networks
• SetInterfaceFilter You can exclude some interfaces from being used.
• SetNAT1To1IPs Allows you to set a static IP to replace all host candidates. Useful if you are behind a DNAT, and don't want to make a STUN request for each PeerConnection.
• SetNetworkTypes You can blacklist TCP, UDP, IPv4 or IPv6. Useful if you know certain configurations will never work.
• SetLite Enables ICE lite, a minimal version of the ICE protocol. Reduces complexity in situations where full ICE isn't needed like a publicly routeable SFU.

Thank you @seppo0010, @AeroNotix, @enobufs and @trivigy for your work on this

TCP TURN Support

Pion WebRTC now supports creating allocations via UDP, TCP and TLS. Implemented by @enobufs

PCM Support

Pion WebRTC now supports sending and receiving PCM.

Renegotiation

You can now Add/Remove tracks at anytime, and renegotiate! We have add a new minimal example called play-from-disk-renegotation that demonstrates this behavior. This example allows you to play a video back from disk multiple times, and you can stop the individual instances at any time!

Add IVFReader

We now have a Go implementation of an .ivf Demuxer. This allows users to easily playback files from disk. Pion also provides an IVFWriter, so you could easily save a file to disk and play it back later. Implemented by @justinokamoto

VP9 Support

You can now send and receive VP9. Implemented by @at-wat

Next Release

The next release will contain lots of bugfixes and other improvements, but the general goals for the next 6 months are.

Better Stats

Pion WebRTC is seeing lots of usage for load testing and measuring WebRTC servers. We are going to work on implement as many webrtc-stats as possible, after that we are going to explore building a framework on top of the PeerConnection API that makes load testing easier. We also want to make it easier to measure things in production, have an application that is easy to build deploy to production that can measure how your service is behaving will help a lot of users.

Better Media

Pion WebRTC lacks a in-tree JitterBuffer and Congestion Control. Users like ion right now have to implement it themselves. In the future Pion WebRTC will allow users to pass their own implementations (because they know their needs best), but provide some default implementations.

Better Performance

We are going to start measuring allocations, create real benchmarks and working on getting them better. We then need to add these benchmarks to CI and make sure they never regress.

Beyond Heretic

The Pion team is excited to announce the v2.1.0 release of Pion WebRTC. This release represents 3 months of feature development and testing across a variety of Pion projects. The headline features are:

TURN Support

Thanks to @enobufs Pion WebRTC now has full TURN support. This has been tested against multiple Open Source and hosted TURN providers.

Stats

@hugoArregui has added support for webrtc-stats. This initial implementation collects stats related to the PeerConnection, DataChannels, ICECandidates and ICECandidatePairs. The status and remaining work is being tracked in #610

mDNS Host Candidates

WebRTC has added mDNS candidates to help with privacy when using WebRTC, you can read the RFC here. We are able to parse and connect to these candidates. Currently we don't generate them, but in the future we will make this controllable by the user.

vnet

Pion WebRTC now implements a virtual network layer. You can read more about it here. This feature allows people to construct networks that only exist in software. This will allow users to simulate real world network conditions simulating NATs, packet loss, bandwidth and jitter without every actually sending a packet. Thanks to this feature written by @enobufs we have fixed multiple bugs in pion/turn and pion/ice already!

Trickle ICE

Trickle ICE is now available! This is controlled by the SettingEngine. We will make this the default in Pion v3 since it is a breaking change, and is not apparent to the user via an API change. Thank you @trivigy and @hugo for all your work on this.

Quest for the Sigil

This is the third public release of pion-WebRTC, thanks for trying it out!

We hope you have as much fun using it and we did making it. Thank you so much to
everyone that contributed, the code and bug reports of the community are what makes it all possible.

---

This release adding the following features

• Raw RTP Input
  You can now supply RTP packets directly. Instead of parsing and rebuilding packets you can just forward.
  This should improve performance for this use case, and will make code simpler. Implemented by Michael MacDonald

• Allow adding Trickle-ICE candidates
  ICE candidates can now be added at any time, making pion-WebRTC compatible with WebRTC implementations that use trickle ICE like Chromium and FireFox. Implement by Michael MacDonald

• Implement RTCP Reception
  The API now provides code to emit and handle RTCP packets, allowing you to build applications that
  interact and emit RTCP packets. Implemented by Woodrow Douglass

• Transport refactor
  The internals of pion-WebRTC have been completely rewritten. This allows us to move subsystems to their own packages, cleaner code and fixed bugs along the way! Soon we should be able to provide ICE, SRTP, SCTP and more libraries for general use. We also now can explore alternative APIs like ORTC. Implemented by Michiel De Backker

• Go native DTLS
  We are now 100% Go, removing our last C dependency (OpenSSL) We also now are able to provide a DTLS implementation to the greater community and are really excited about all the opportunities it opens up. Implemented by Michiel De Backker and Sean DuBois

• Improve SRTP code and add auth tag checking
  Fixed a bug where wrong SRTP keys were used, in some cases video would fail to decode. Also expanded the SRTP code to do tag checking
  Implemented by Tobias Fridén

• Add go-fuzz support to RTCP, and discovered crash in RTP code
  Implemented by Max Hawkins

---

We ship with the following demos you can base your application off of.

• data-channels Shows how to use DataChannels and send/receive data to your browser
• gstreamer-receive Shows how to receive video and play or process it via GStreamer
• gstreamer-send Shows how to generate video via GStreamer and send it to your browser
• janus-gateway/streaming Shows how to use connect to a Janus streaming mountpoint and save to an ivf container
• janus-gateway/video-room Shows how to use connect to a Janus video-room and publish video
• pion-to-pion Shows to communicate between two Pion instance using DataChannels, no browser required!
• save-to-disk Shows how to receive VP8 from your browser and save to an ivf container
• sfu Shows how to broadcast a video to many peers, while only requiring the broadcaster to upload once

To see what features are planned in the future, please see our roadmap

Aliens of Gold

This is the second public release of pion-WebRTC, thanks for trying it out!
Hopefully you have as much fun using it and we did making it

This release adding the following features

• Full ICE. pion-WebRTC is able to be controlling or controlled and can connect to itself.
• DataChannels. pion-WebRTC can now send and receive messages via SCTP DataChannels.
• RTCP. pion-WebRTC now is able to send and receive RTCP, making it a great building block for building things like an SFU.

We also ship with the following demos you can base your application off of.

• data-channels Shows how to use DataChannels and send/receive data to your browser
• gstreamer-receive Shows how to receive video and play or process it via GStreamer
• gstreamer-send Shows how to generate video via GStreamer and send it to your browser
• janus-gateway Shows how to use connect to a Janus streaming mountpoint and save to an ivf container
• pion-to-pion Shows to communicate between two Pion instance using DataChannels, no browser required!
• save-to-disk Shows how to receive VP8 from your browser and save to an ivf container
• sfu Shows how to broadcast a video to many peers, while only requiring the broadcaster to upload once

To see what features are planned in the future, please see our roadmap

Planet Strike

This is the first public release of pion-WebRTC. Thank you for checking it out!

pion-WebRTC is not finished, but ships with the following features

• Send and receiving audio and video
• Go Native SRTP
• DTLS via OpenSSL (we still require Cgo just for this, but will be rewritten soon)
• ICE-lite (requires that pion-WebRTC is run on a public IP, or communicates with in a LAN)

We also ship with the following demos you can base your application off of.

• gstreamer-send Shows how to generate video via GStreamer and send it to your browser
• gstreamer-receive Shows how to receive video and play or process it via GStreamer
• save-to-disk Shows how to receive VP8 from your browser and save to an ivf container

To see what features are planned in the future, please see our roadmap