Release [email protected]

The Pion team is very excited to announce the v4.0.0 release of Pion WebRTC. Pion WebRTC is a Go implementation of WebRTC. If you aren't sure what WebRTC is we maintain a book WebRTC for the Curious that explains the what, why and how of WebRTC. Now that you have read that, you are ready to build some cool stuff :)

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 205 commits from 42 authors. Media Quality in poor networks has improved. CPU usage in DataChannels and SDP handling has been reduced. In most cases disconnect detection happens instantly now, before it would take 5 seconds. Multiple sharp edges in the API have been removed.

These new features required 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

PeerConnections now respect DTLS Close

Before /v4 Pion WebRTC would ignore DTLS Closes. If a remote client requested a explict close we would ignore it. The connection would then transition to disconnected after 5 seconds. These explict close notifications are no longer ignored, in good networks Pion will notify you immediately and clean up resources.

This means in your PeerConnectionState and ICEConnectionState handles you need to explicitly handle the Closed events. The PeerConnection may never go to Disconnected or Failed now, it could go directly to Closed

Before

peerConnection.OnICEConnectionStateChange(func(connectionState webrtc.ICEConnectionState) {
    if connectionState == webrtc.ICEConnectionStateFailed {
        peerConnection.Close()
        // Business logic when PeerConnection done
    }
})

After

peerConnection.OnICEConnectionStateChange(func(connectionState webrtc.ICEConnectionState) {
    if connectionState == webrtc.ICEConnectionStateFailed {
        peerConnection.Close()
    } else if connectionState == webrtc.ICEConnectionStateClosed {
        // Business logic when PeerConnection done
    }
})

This was changed with 60eea4

Simulcast Extension Headers are enabled by default

Simulcast Extension headers are enabled by default. This makes it easier to send and receive Simulcast traffic. For an explanation on what Simulcast is, and why it matters LiveKit has an excellent write up.

In the majority of cases this shouldn't be impacting. However if you are passing through RTP packets make sure to either clear or update the extension header IDs. Since FireFox/Chrome/Safari use different values this could cause unexpected behavior.

Before

buf := make([]byte, 1500)
for {
        i, _, err := t.Read(buf)
        if err != nil {
                return
        }

       if _, err = trackLocal.Write(buf[:i]); err != nil {
                return
        }
}

After

buf := make([]byte, 1500)
rtpPkt := &rtp.Packet{}

for {
        i, _, err := t.Read(buf)
        if err != nil {
                return
        }

        if err = rtpPkt.Unmarshal(buf[:i]); err != nil {
               log.Println(err)
               return
        }

        rtpPkt.Extension = false
        rtpPkt.Extensions = nil

        if err = trackLocal.WriteRTP(rtpPkt); err != nil {
                return
        }
}

This was changed with b549c9

New Features

DTLS Provides Hooks for Censorship Circumvention

Network operators have been attempting to block Pion by looking for patterns in the DTLS Handshake. Wired wrote an article on the work Tor has been doing to circumvent these blocks.

If you are attempting to get around network blocks check out some of these options in the SettingEngine.

• SetDTLSCertificateRequestMessageHook
• SetDTLSCustomerCipherSuites
• SetDTLSEllipticCurves
• SetDTLSExtendedMasterSecret
• SetDTLSServerHelloMessageHook

RFC 4588 (Retransmissions use a distinct SSRC)

Before /v4 Pion used the same media stream for the original media and retransmissions. We now by default use a different SSRC for sending and receiving media. This provides two major improvements.

• We are able to distinguish between late packets and retransmissions
• We are able to enable Replay Detection, before an attacker could replay old packets and we had to accept them.

SCTP Zero Checksum

SCTP by default runs a checksum for each Chunk. If you are running SCTP over a insecure/lossy transport this is a useful feature. WebRTC runs SCTP over DTLS, which also provides a checksum. This means that each packet was being checksummed twice. Enable the feature via the following SettingEngine flag

• EnableSCTPZeroChecksum

This was implemented in 932b71

NewAPI creates MediaEngine/Interceptor by default

/v4 removes unnecessary boilerplate when creating PeerConnections. You no longer have to call RegisterDefaultCodecs or RegisterDefaultInterceptors if you just want to add a SettingEngine.

Before

m := &webrtc.MediaEngine{}
if err := m.RegisterDefaultCodecs(); err != nil {
        panic(err)
}

i := &interceptor.Registry{}
if err := webrtc.RegisterDefaultInterceptors(m, i); err != nil {
        panic(err)
}

s := webrtc.SettingEngine{}
s.EnableSCTPZeroChecksum(true)

peerConnection, err := webrtc.NewAPI(webrtc.WithMediaEngine(m), webrtc.WithInterceptorRegistry(i), webrtc.WithSettingEngine(s)).NewPeerConnection(config)

After

s := webrtc.SettingEngine{}
s.EnableSCTPZeroChecksum(true)

peerConnection, err := webrtc.NewAPI(webrtc.WithSettingEngine(s)).NewPeerConnection(config)

This was changed with b549c9

WHIP/WHEP Examples

Examples for using the WHIP/WHEP Protocol have been added in examples/whip-whep. WHIP/WHEP allows for WebRTC clients to establish a connection without writing any custom code. This means you can now send OBS/GStreamer/FFmpeg into your WebRTC server!

For an example of a more feature-full WHIP/WHEP server see Broadcast Box. To read more about what WHIP/WHEP enables see the webrtcHacks article on it.

WebRTC for the Curious

The Pion developers started a free book on how WebRTC actually works. It is available at https://webrtcforthecurious.com and is hosted from GitHub. It is A book about WebRTC in depth, not just about the APIs. Learn the full details of ICE, SCTP, DTLS, SRTP, and how they work together to make up the WebRTC stack.

This is also a great resource if you are trying to debug. Learn the tools of the trade and how to approach WebRTC issues.

This book is vendor agnostic and will not have any Pion specific information.

Projects that have been migrated

See https:/pion/webrtc/issues/2557 for a list of projects that have been migrated to v4.0.0 already. If you are confused about what API changes you need these may be helpful