Simulcast

Accept and demux simulcast streams into separate tracks for adaptive bitrate streaming

The simulcast example demonstrates how to receive a single WebRTC track containing multiple simulcast streams (different quality levels) and demux them into separate tracks. This is essential for implementing adaptive bitrate streaming, bandwidth-adaptive video conferencing, and multi-quality broadcasting.

Overview

Simulcast allows a sender to transmit the same video at multiple quality levels (resolutions/bitrates) within a single track. The receiver can then select which quality to display based on available bandwidth, screen size, or user preference. This example receives all three simulcast layers and sends them back as independent tracks.

Key Features

• Receives single track with 3 simulcast streams (low, medium, high quality)
• Demultiplexes streams by RID (Restriction Identifier)
• Returns each quality as a separate independent track
• Periodic PLI (Picture Loss Indication) for keyframe requests
• Real-time quality switching capability

Simulcast Stream Naming

The example uses standard simulcast naming:

• “q” (quarter): Low quality/resolution stream
• “h” (half): Medium quality/resolution stream
• “f” (full): High quality/resolution stream

How It Works

1. Create Output Tracks

   Prepare three local tracks for the demuxed streams:

   outputTracks := map[string]*webrtc.TrackLocalStaticRTP{}
   
   // Low quality track
   outputTrack, err := webrtc.NewTrackLocalStaticRTP(
       webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeVP8},
       "video_q",
       "pion_q",
   )
   if err != nil {
       panic(err)
   }
   outputTracks["q"] = outputTrack
   
   // Medium quality track
   outputTrack, err = webrtc.NewTrackLocalStaticRTP(
       webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeVP8},
       "video_h",
       "pion_h",
   )
   if err != nil {
       panic(err)
   }
   outputTracks["h"] = outputTrack
   
   // High quality track
   outputTrack, err = webrtc.NewTrackLocalStaticRTP(
       webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeVP8},
       "video_f",
       "pion_f",
   )
   if err != nil {
       panic(err)
   }
   outputTracks["f"] = outputTrack
   
2. Add Transceivers

   Configure transceivers for receiving and sending:

   // Add receive-only transceiver for incoming simulcast
   if _, err = peerConnection.AddTransceiverFromKind(
       webrtc.RTPCodecTypeVideo,
       webrtc.RTPTransceiverInit{
           Direction: webrtc.RTPTransceiverDirectionRecvonly,
       },
   ); err != nil {
       panic(err)
   }
   
   // Add send-only transceivers for each output track
   for _, track := range outputTracks {
       if _, err = peerConnection.AddTransceiverFromTrack(
           track,
           webrtc.RTPTransceiverInit{
               Direction: webrtc.RTPTransceiverDirectionSendonly,
           },
       ); err != nil {
           panic(err)
       }
   }
   
3. Setup RTCP Processing

   Read RTCP packets for all senders:

   processRTCP := func(rtpSender *webrtc.RTPSender) {
       rtcpBuf := make([]byte, 1500)
       for {
           if _, _, rtcpErr := rtpSender.Read(rtcpBuf); rtcpErr != nil {
               return
           }
       }
   }
   
   for _, rtpSender := range peerConnection.GetSenders() {
       go processRTCP(rtpSender)
   }
   
4. Handle Incoming Track

   Demux based on RID and forward to appropriate output track:

   peerConnection.OnTrack(func(
       track *webrtc.TrackRemote,
       receiver *webrtc.RTPReceiver,
   ) {
       fmt.Println("Track has started")
   
       // Get the RID (restriction identifier) for this stream
       rid := track.RID()
       
       // Send PLI every 3 seconds for keyframes
       if track.Kind() == webrtc.RTPCodecTypeVideo {
           go func() {
               ticker := time.NewTicker(3 * time.Second)
               defer ticker.Stop()
               for range ticker.C {
                   fmt.Printf(
                       "Sending PLI for stream with rid: %q, ssrc: %d\n",
                       track.RID(),
                       track.SSRC(),
                   )
                   if writeErr := peerConnection.WriteRTCP([]rtcp.Packet{
                       &rtcp.PictureLossIndication{
                           MediaSSRC: uint32(track.SSRC()),
                       },
                   }); writeErr != nil {
                       fmt.Println(writeErr)
                   }
               }
           }()
       }
       
       // Forward packets to the appropriate output track
       for {
           packet, _, readErr := track.ReadRTP()
           if readErr != nil {
               panic(readErr)
           }
   
           if writeErr := outputTracks[rid].WriteRTP(packet); writeErr != nil &&
              !errors.Is(writeErr, io.ErrClosedPipe) {
               panic(writeErr)
           }
       }
   })
   

Complete Source Code

Track Setup

package main

import (
    "errors"
    "fmt"
    "io"
    "os"
    "time"

    "github.com/pion/rtcp"
    "github.com/pion/webrtc/v4"
)

func main() {
    config := webrtc.Configuration{
        ICEServers: []webrtc.ICEServer{
            {
                URLs: []string{"stun:stun.l.google.com:19302"},
            },
        },
    }

    peerConnection, err := webrtc.NewPeerConnection(config)
    if err != nil {
        panic(err)
    }
    defer peerConnection.Close()

    outputTracks := map[string]*webrtc.TrackLocalStaticRTP{}

    // Create output tracks for each quality level
    qualities := []struct {
        rid   string
        label string
    }{
        {"q", "video_q"},
        {"h", "video_h"},
        {"f", "video_f"},
    }

    for _, quality := range qualities {
        track, err := webrtc.NewTrackLocalStaticRTP(
            webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeVP8},
            quality.label,
            "pion_"+quality.rid,
        )
        if err != nil {
            panic(err)
        }
        outputTracks[quality.rid] = track
    }

    // Add receive-only transceiver
    if _, err = peerConnection.AddTransceiverFromKind(
        webrtc.RTPCodecTypeVideo,
        webrtc.RTPTransceiverInit{
            Direction: webrtc.RTPTransceiverDirectionRecvonly,
        },
    ); err != nil {
        panic(err)
    }

    // Add send-only transceivers for output tracks
    for _, track := range outputTracks {
        if _, err = peerConnection.AddTransceiverFromTrack(
            track,
            webrtc.RTPTransceiverInit{
                Direction: webrtc.RTPTransceiverDirectionSendonly,
            },
        ); err != nil {
            panic(err)
        }
    }

    // Process RTCP packets
    processRTCP := func(rtpSender *webrtc.RTPSender) {
        rtcpBuf := make([]byte, 1500)
        for {
            if _, _, rtcpErr := rtpSender.Read(rtcpBuf); rtcpErr != nil {
                return
            }
        }
    }
    for _, rtpSender := range peerConnection.GetSenders() {
        go processRTCP(rtpSender)
    }

    // Handle incoming tracks
    peerConnection.OnTrack(handleTrack(peerConnection, outputTracks))

    // ... signaling code continues
}

Important Implementation Details

RID (Restriction Identifier)

RID identifies which simulcast stream a packet belongs to:

rid := track.RID()

Common RID values:

• “q” or “0”: Lowest quality (quarter resolution)
• “h” or “1”: Medium quality (half resolution)
• “f” or “2”: Highest quality (full resolution)

The RID maps incoming packets to the correct output track for demuxing.

PLI (Picture Loss Indication)

The example sends PLI every 3 seconds to request keyframes:

peerConnection.WriteRTCP([]rtcp.Packet{
    &rtcp.PictureLossIndication{
        MediaSSRC: uint32(track.SSRC()),
    },
})

Why this matters:

• Ensures each stream has recent keyframes
• Enables quick quality switching
• Helps with error recovery

For production, adjust PLI frequency based on:

• Network conditions
• Available bandwidth
• Quality switching patterns

Transceiver Direction

The example explicitly sets transceiver directions:

// Receive simulcast from browser
webrtc.RTPTransceiverDirectionRecvonly

// Send demuxed streams back to browser
webrtc.RTPTransceiverDirectionSendonly

This ensures proper negotiation and prevents unnecessary media pipelines.

Quality Selection

While this example sends all three qualities back, in production you would:

1. Monitor bandwidth using RTCP feedback
2. Select appropriate quality based on:
   • Available bandwidth
   • Screen size/viewport
   • CPU capabilities
   • User preferences
3. Switch dynamically between qualities

Example quality selection logic:

func selectQuality(bandwidth int) string {
    switch {
    case bandwidth > 2000000: // 2 Mbps
        return "f" // Full quality
    case bandwidth > 500000:  // 500 Kbps
        return "h" // Half quality
    default:
        return "q" // Quarter quality
    }
}

Browser Configuration

To enable simulcast in the browser, configure the sender:

const sender = pc.addTrack(videoTrack, stream);

const params = sender.getParameters();
if (!params.encodings) {
    params.encodings = [
        { rid: 'f', maxBitrate: 2000000 },  // Full: 2 Mbps
        { rid: 'h', maxBitrate: 500000, scaleResolutionDownBy: 2 },  // Half: 500 Kbps, 1/2 res
        { rid: 'q', maxBitrate: 150000, scaleResolutionDownBy: 4 },  // Quarter: 150 Kbps, 1/4 res
    ];
}
await sender.setParameters(params);

Running the Example

1. Start the application

   cd examples/simulcast
   go run main.go
   
2. Configure browser for simulcast

   Open the simulcast example page which automatically configures three encoding layers

3. Complete handshake

   Exchange SDP offer/answer through the copy-paste signaling

4. Observe streams

   You should see:

   • Terminal logs showing PLI requests for each RID
   • Three separate video elements in the browser showing different qualities
   • All three streams playing simultaneously

Use Cases

Adaptive Streaming

Automatically switch quality based on network conditions for smooth playback

Video Conferencing

Show active speaker in high quality, thumbnails in low quality

Broadcasting

Serve different qualities to viewers with varying bandwidth

Recording

Record multiple qualities simultaneously for later transcoding

Performance Considerations

Bandwidth Usage: Simulcast increases upload bandwidth by 2-3x compared to single stream. Ensure the sender has sufficient bandwidth:

• Single stream: ~1-2 Mbps
• Simulcast (3 layers): ~2.5-3.5 Mbps

The benefit is that each receiver can choose their quality, reducing download bandwidth.

For optimal results:

• Use simulcast when you have multiple viewers with varying bandwidth
• Consider SVC (Scalable Video Coding) as an alternative with lower upload requirements
• Implement adaptive bitrate switching on the receiver side
• Monitor RTCP feedback for quality decisions

Related Examples

• Broadcast - Forward streams to multiple viewers
• Save to Disk - Record specific quality levels
• RTP Forwarder - Forward selected quality via RTP