RTPSender

Controls how a given Track is encoded and transmitted to a remote peer.

Overview

RTPSender allows an application to control how a given Track is encoded and transmitted to a remote peer. It manages the outbound RTP stream including encoding parameters, SSRC assignment, and RTCP feedback.

Type Definition

type RTPSender struct {
    trackEncodings []*trackEncoding
    transport      *DTLSTransport
    payloadType    PayloadType
    kind           RTPCodecType
    negotiated     bool
    api            *API
    id             string
    rtpTransceiver *RTPTransceiver
    mu             sync.RWMutex
    sendCalled     chan struct{}
    stopCalled     chan struct{}
}

Constructor

NewRTPSender

Constructs a new RTPSender.

func (api *API) NewRTPSender(track TrackLocal, transport *DTLSTransport) (*RTPSender, error)

track · TrackLocal · required

The local track to send

transport · *DTLSTransport · required

The DTLS transport to use for sending

sender · *RTPSender

The newly created RTPSender

error · error

Returns error if track or transport is nil

Methods

Transport

Returns the currently-configured DTLSTransport or nil if one has not yet been configured.

func (r *RTPSender) Transport() *DTLSTransport

transport · *DTLSTransport

The associated DTLS transport

GetParameters

Describes the current configuration for the encoding and transmission of media on the sender’s track.

func (r *RTPSender) GetParameters() RTPSendParameters

parameters · RTPSendParameters

The current send parameters including codecs and encodings

Show RTPSendParameters Structure

type RTPSendParameters struct {
    RTPParameters
    Encodings []RTPEncodingParameters
}

type RTPEncodingParameters struct {
    RTPCodingParameters
    // Additional encoding-specific parameters
}

Track

Returns the RTPSender’s track, or nil.

func (r *RTPSender) Track() TrackLocal

track · TrackLocal

The local track being sent, or nil

ReplaceTrack

Replaces the track currently being used as the sender’s source with a new TrackLocal. The new track must be of the same media kind (audio, video, etc) and switching the track should not require negotiation.

func (r *RTPSender) ReplaceTrack(track TrackLocal) error

track · TrackLocal

The new track to send. Pass nil to stop sending.

error · error

Returns error if:

• New track has incorrect kind
• New track has incorrect envelope (simulcast)
• Track binding fails

Replace Track

// Create new track
newTrack, err := webrtc.NewTrackLocalStaticSample(
    webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeVP8},
    "video",
    "pion",
)
if err != nil {
    panic(err)
}

// Replace the current track
err = sender.ReplaceTrack(newTrack)
if err != nil {
    panic(err)
}

AddEncoding

Adds an encoding to RTPSender. Used by simulcast senders.

func (r *RTPSender) AddEncoding(track TrackLocal) error

track · TrackLocal · required

The additional track encoding to add. Must have a RID set.

error · error

Returns error if:

• Track is nil
• Track RID is empty
• Sender is stopped
• Send already called
• No base encoding exists
• Track properties don’t match base encoding
• RID collision detected

AddEncoding is used for simulcast streaming where multiple encodings of the same track are sent with different quality levels.

Send

Attempts to set the parameters controlling the sending of media.

func (r *RTPSender) Send(parameters RTPSendParameters) error

parameters · RTPSendParameters · required

The send parameters to configure

error · error

Returns error if Send has already been called or track was removed

Stop

Irreversibly stops the RTPSender.

func (r *RTPSender) Stop() error

error · error

Returns error if stopping fails

Read

Reads incoming RTCP for this RTPSender.

func (r *RTPSender) Read(b []byte) (n int, a interceptor.Attributes, err error)

b · []byte · required

Buffer to read RTCP data into

n · int

Number of bytes read

attributes · interceptor.Attributes

Interceptor attributes associated with the RTCP packet

error · error

Returns error if read fails or sender is stopped

ReadRTCP

A convenience method that wraps Read and unmarshals for you.

func (r *RTPSender) ReadRTCP() ([]rtcp.Packet, interceptor.Attributes, error)

packets · []rtcp.Packet

The unmarshaled RTCP packets

attributes · interceptor.Attributes

Interceptor attributes

error · error

Returns error if read or unmarshal fails

Read RTCP Feedback

for {
    packets, _, err := sender.ReadRTCP()
    if err != nil {
        return err
    }
    
    for _, packet := range packets {
        switch p := packet.(type) {
        case *rtcp.PictureLossIndication:
            fmt.Println("Received PLI")
        case *rtcp.ReceiverReport:
            fmt.Printf("Received RR: %+v\n", p)
        }
    }
}

ReadSimulcast

Reads incoming RTCP for this RTPSender for given RID.

func (r *RTPSender) ReadSimulcast(b []byte, rid string) (n int, a interceptor.Attributes, err error)

b · []byte · required

Buffer to read RTCP data into

rid · string · required

The RTP stream identifier to read RTCP for

ReadSimulcastRTCP

A convenience method that wraps ReadSimulcast and unmarshal for you.

func (r *RTPSender) ReadSimulcastRTCP(rid string) ([]rtcp.Packet, interceptor.Attributes, error)

rid · string · required

The RTP stream identifier

SetReadDeadline

Sets the deadline for the Read operation. Setting to zero means no deadline.

func (r *RTPSender) SetReadDeadline(t time.Time) error

t · time.Time · required

The deadline time. Zero value means no deadline.

SetReadDeadlineSimulcast

Sets the max amount of time the RTCP stream for a given RID will block before returning. 0 is forever.

func (r *RTPSender) SetReadDeadlineSimulcast(deadline time.Time, rid string) error

deadline · time.Time · required

The deadline time

rid · string · required

The RTP stream identifier

Usage Examples

Creating and Using an RTPSender

// Create a video track
videoTrack, err := webrtc.NewTrackLocalStaticSample(
    webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeVP8},
    "video",
    "pion",
)
if err != nil {
    panic(err)
}

// Add track to peer connection
rtpSender, err := peerConnection.AddTrack(videoTrack)
if err != nil {
    panic(err)
}

// Read RTCP packets in a separate goroutine
go func() {
    for {
        packets, _, err := rtpSender.ReadRTCP()
        if err != nil {
            return
        }
        
        for _, pkt := range packets {
            // Handle RTCP feedback
            fmt.Printf("Received RTCP: %T\n", pkt)
        }
    }
}()

Simulcast Sending

// Create base track with RID
baseTrack, _ := webrtc.NewTrackLocalStaticSample(
    webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeVP8},
    "video",
    "pion",
)
baseTrack.SetRID("high")

rtpSender, _ := peerConnection.AddTrack(baseTrack)

// Add medium quality encoding
mediumTrack, _ := webrtc.NewTrackLocalStaticSample(
    webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeVP8},
    "video",
    "pion",
)
mediumTrack.SetRID("medium")
rtpSender.AddEncoding(mediumTrack)

// Add low quality encoding
lowTrack, _ := webrtc.NewTrackLocalStaticSample(
    webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeVP8},
    "video",
    "pion",
)
lowTrack.SetRID("low")
rtpSender.AddEncoding(lowTrack)

See Also

• RTPReceiver - Manages inbound RTP streams
• RTPTransceiver - Combines sender and receiver
• TrackLocal - Local media track interface