pc

Documentation

Index

• Variables
• type AddTrackParams
• type ConnectionInfo
• type Handler
• type ICESettings
• type NegotiationError
  • func NewNegotiationError(reason string, err error, sfuErr *sfu_models.Error) *NegotiationError
  • func (e *NegotiationError) Error() string
  • func (e *NegotiationError) Unwrap() error
• type NegotiationState
  • func (n NegotiationState) String() string
• type PeerConfig
• type Transport
  • func NewPCTransport(params TransportParams) (*Transport, error)
  • func (t *Transport) AddICECandidate(candidate webrtc.ICECandidateInit)
  • func (t *Transport) AddTrack(track webrtc.TrackLocal, params AddTrackParams) (*webrtc.RTPSender, *webrtc.RTPTransceiver, error)
  • func (t *Transport) Close()
  • func (t *Transport) HandleRemoteDescription(sd webrtc.SessionDescription)
  • func (t *Transport) HandleRemoteDescriptionWithNegotiationID(sd webrtc.SessionDescription, negotiationID uint32)
  • func (t *Transport) ICERestart() error
  • func (t *Transport) IsHealthy() bool
  • func (t *Transport) Negotiate(force bool)
  • func (t *Transport) WriteRTCP(pkts []rtcp.Packet) error
• type TransportParams

Variables

var (
	ErrIceRestartWithoutLocalSDP        = errors.New("ICE restart without local SDP settled")
	ErrIceRestartOnClosedPeerConnection = errors.New("ICE restart on closed peer connection")
)

Types

type AddTrackParams

type AddTrackParams struct {
	Stereo bool
	// Red means the track carries its own redundancy, so NACK is not forced on.
	Red bool
}

AddTrackParams tunes the opus sender of an audio track.

type ConnectionInfo

type ConnectionInfo struct {
	ICEState         webrtc.ICEConnectionState
	DTLSState        webrtc.DTLSTransportState
	Duration         time.Duration
	HasEverConnected bool
	SelectedPair     *webrtc.ICECandidatePair
}

ConnectionInfo is a snapshot of connection state at a significant event (failure, never-connected, close) — it is only ever built on the failure path. The states mirror the last ICE/DTLS transition callbacks.

ICEState/DTLSState localise the failure: ICE not connected => ICE is the culprit; ICE connected but DTLS not => DTLS is the culprit. Duration is the time spent in that failing phase — since ICE connected once ICE has connected, otherwise since ICE checking started. So the states say which layer failed and Duration says how long it was stuck there; the non-failing phase's duration is never interesting, so it is not tracked separately.

SelectedPair is the ICE candidate pair in use at the time of the event, or nil if ICE never selected one (or the transports were already torn down).

type Handler

type Handler interface {
	OnAddIceCandidate(c *webrtc.ICECandidateInit)
	OnAddIceCandidateSuccess()
	OnAnswer(sd webrtc.SessionDescription, negotiationID uint32) error
	OnFailed(info ConnectionInfo)
	OnInitialConnected()
	// OnNeverConnected is called when the peer connection is closed while still in the
	// connecting state, without ever reaching connected or failed. This covers abrupt
	// closes before ICE/DTLS failure detection fires — e.g. client drops the signaling
	// connection before failure timeout or an SFU-side timer expires.
	OnNeverConnected(info ConnectionInfo)
	OnICECandidateSender(c *webrtc.ICECandidate, target models.PeerType) error
	OnNegotiationFailed(err *NegotiationError)
	OnNegotiationStateChanged(state NegotiationState)
	OnOffer(sd webrtc.SessionDescription, negotiationID uint32) error
	// Pion standard callbacks
	OnConnectionStateChange(state webrtc.PeerConnectionState)
	OnICECandidate(c *webrtc.ICECandidate)
	OnICEConnectionStateChange(state webrtc.ICEConnectionState)
	OnICEGatheringStateChange(state webrtc.ICEGatheringState)
	OnNegotiationNeeded()
	OnSetLocalDescription(desc webrtc.SessionDescription)
	OnSetLocalDescriptionSuccess()
	OnSetRemoteDescription(desc webrtc.SessionDescription)
	OnSetRemoteDescriptionSuccess()
	OnSignalingStateChange(state webrtc.SignalingState)
	OnTrack(track *webrtc.TrackRemote, rtpReceiver *webrtc.RTPReceiver)
}

Handler receives a Transport's signalling work and connection events. The signalling methods run on the transport's event loop, one at a time.

type ICESettings

type ICESettings struct {
	// UDPPortRange restricts host candidate gathering to [min, max] when it
	// holds exactly two ports.
	UDPPortRange []uint16
	// InterfaceFilter selects which local interfaces to gather candidates on.
	// A nil filter gathers on all of them.
	InterfaceFilter func(name string) bool
}

ICESettings are the ICE knobs a client can usefully set.

type NegotiationError

type NegotiationError struct {
	// Reason is a human-readable description of what went wrong
	Reason string
	// Code is the error code from the SFU response (if available)
	Code sfu_models.ErrorCode
	// Message is the detailed error message from the SFU (if available)
	Message string
	// Underlying error (if any)
	Err error
}

NegotiationError represents a structured error from negotiation failures

func NewNegotiationError

func NewNegotiationError(reason string, err error, sfuErr *sfu_models.Error) *NegotiationError

NewNegotiationError creates a negotiation error with optional error details. If sfuErr is provided, it extracts the error code and message. Otherwise, if err is provided, it stores it as the underlying error.

func (*NegotiationError) Error

func (e *NegotiationError) Error() string

func (*NegotiationError) Unwrap

func (e *NegotiationError) Unwrap() error

type NegotiationState

type NegotiationState int

NegotiationState is where the offering side is in its offer/answer exchange.

const (
	// NegotiationStateIdle means no offer is outstanding.
	NegotiationStateIdle NegotiationState = iota
	// NegotiationStateAwaitingAnswer means an offer is out and unanswered.
	NegotiationStateAwaitingAnswer
	// NegotiationStateRenegotiatePending means another offer goes out as soon
	// as the outstanding one is answered.
	NegotiationStateRenegotiatePending
)

func (NegotiationState) String

func (n NegotiationState) String() string

type PeerConfig

type PeerConfig struct {
	Config        webrtc.Configuration
	MediaEngine   *webrtc.MediaEngine
	SettingEngine webrtc.SettingEngine
	Registry      *interceptor.Registry
	*ICESettings
}

type Transport

type Transport struct {
	Params TransportParams
	PC     *webrtc.PeerConnection
	// contains filtered or unexported fields
}

Transport runs one peer connection to the SFU. It negotiates as the offerer or the answerer, trickles candidates and restarts ICE, all on one event loop, and reports connection failures to its Handler.

func NewPCTransport

func NewPCTransport(params TransportParams) (*Transport, error)

NewPCTransport creates the peer connection and starts its event loop.

func (*Transport) AddICECandidate

func (t *Transport) AddICECandidate(candidate webrtc.ICECandidateInit)

AddICECandidate adds a candidate trickled by the SFU.

func (*Transport) AddTrack

func (t *Transport) AddTrack(track webrtc.TrackLocal, params AddTrackParams) (*webrtc.RTPSender, *webrtc.RTPTransceiver, error)

AddTrack adds a send-only transceiver for the track.

func (*Transport) Close

func (t *Transport) Close()

Close stops the event loop, dropping whatever it had not run yet, and closes the peer connection. It is safe to call from a Handler method.

func (*Transport) HandleRemoteDescription

func (t *Transport) HandleRemoteDescription(sd webrtc.SessionDescription)

HandleRemoteDescription applies an offer or answer that carries no negotiation id.

func (*Transport) HandleRemoteDescriptionWithNegotiationID

func (t *Transport) HandleRemoteDescriptionWithNegotiationID(sd webrtc.SessionDescription, negotiationID uint32)

HandleRemoteDescriptionWithNegotiationID applies an offer, answering it with the same id, or an answer, dropping it unless the id is the outstanding offer's.

func (*Transport) ICERestart

func (t *Transport) ICERestart() error

ICERestart restarts ICE by renegotiating. Only the offerer can.

func (*Transport) IsHealthy

func (t *Transport) IsHealthy() bool

IsHealthy reports whether the transport is in a state an ICE restart could still repair. A failed or closed transport cannot be, so callers deciding between a fast reconnect and a full rejoin treat it as unusable.

func (*Transport) Negotiate

func (t *Transport) Negotiate(force bool)

Negotiate schedules an offer. Calls within negotiationDebounce of each other share one offer; force sends it without waiting.

func (*Transport) WriteRTCP

func (t *Transport) WriteRTCP(pkts []rtcp.Packet) error

WriteRTCP sends RTCP on the peer connection.

type TransportParams

type TransportParams struct {
	Handler   Handler
	Transport models.PeerType
	Logger    logger.ILogger
	IsOfferer bool
	PeerConfig
	// contains filtered or unexported fields
}