pion

package
v0.0.0-...-3ac212f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 15, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package pion owns the WebRTC peer connection used by a recording capture worker. The package deliberately exposes only provider-neutral signaling and Chalk track identity; Cloudflare and other SFU adapters stay outside it.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidCaptureEpoch   = errors.New("pion capture epoch must be positive")
	ErrPeerClosed            = errors.New("pion peer connection is closed")
	ErrPeerTerminal          = errors.New("pion peer connection is terminal")
	ErrTracksNotRegistered   = errors.New("pion expected tracks are not registered")
	ErrTrackIdentityMutation = errors.New("pion track identity changed for an existing MID")
	ErrUnknownMID            = errors.New("pion received an unknown MID")
	ErrDuplicateMID          = errors.New("pion received a duplicate MID")
	ErrInvalidNegotiation    = errors.New("pion negotiation is invalid")
	ErrStaleNegotiation      = errors.New("pion negotiation is stale")
	ErrNegotiationPending    = errors.New("pion negotiation is already pending")
	ErrTrackBinding          = errors.New("pion track binding failed")
	ErrTrackNotBound         = errors.New("pion capture track is not bound")
	ErrKeyFrameRequest       = errors.New("pion keyframe request failed")
)

Functions

This section is empty.

Types

type Config 

type Config struct {
	CaptureEpoch  captureplane.CaptureEpoch
	Configuration webrtc.Configuration
	API           *webrtc.API
}

Config creates one peer connection for one capture epoch. API is optional; tests can provide a configured Pion API while production uses the defaults.

type MediaTrack 

type MediaTrack struct {
	// contains filtered or unexported fields
}

MediaTrack retains the authenticated Chalk track and exposes only bounded RTP reads from Pion's remote track. It does not buffer packets in memory.

func (*MediaTrack) BoundAt 

func (t *MediaTrack) BoundAt() time.Time

BoundAt is when OnTrack bound this track, which Pion does as the first RTP packet arrives. A reader that starts later can anchor the track's clock here instead of at its own first read.

func (*MediaTrack) CaptureTrack 

func (t *MediaTrack) CaptureTrack() captureplane.PulledCaptureTrack

CaptureTrack returns the identity registered before SDP was applied.

func (*MediaTrack) Codec 

func (t *MediaTrack) Codec() string

Codec returns the normalized codec name negotiated for this remote RTP stream. It is available only after Pion binds the remote track.

func (*MediaTrack) MID 

func (t *MediaTrack) MID() captureplane.ProviderReference

MID is the negotiated transceiver MID used for this binding.

func (*MediaTrack) RID 

func (t *MediaTrack) RID() string

RID is the RTP stream RID observed by Pion. It is empty for a non-simulcast stream and for the primary stream selected by Pion's receiver.

func (*MediaTrack) Read 

func (t *MediaTrack) Read(buffer []byte) (int, interceptor.Attributes, error)

Read reads one RTP packet into the caller-provided bounded buffer.

func (*MediaTrack) ReadRTCP 

func (t *MediaTrack) ReadRTCP() ([]rtcp.Packet, interceptor.Attributes, error)

ReadRTCP reads the sender's clock reports without consuming RTP media.

func (*MediaTrack) ReadRTP 

func (t *MediaTrack) ReadRTP() (*rtp.Packet, interceptor.Attributes, error)

ReadRTP reads one packet from the bounded Pion receiver.

func (*MediaTrack) SetRTCPReadDeadline 

func (t *MediaTrack) SetRTCPReadDeadline(deadline time.Time) error

SetRTCPReadDeadline bounds reads independently of the media deadline.

func (*MediaTrack) SetReadDeadline 

func (t *MediaTrack) SetReadDeadline(deadline time.Time) error

SetReadDeadline bounds a worker's wait for the next RTP packet.

type NegotiationResult 

type NegotiationResult struct {
	LocalDescription *captureplane.Description
	Negotiation      captureplane.Negotiation
}

NegotiationResult carries the local description produced while consuming a provider negotiation. For OfferNeeded, Negotiation is the outbound local offer. For AnswerNeeded, LocalDescription is the answer to send upstream.

type Peer 

type Peer struct {
	// contains filtered or unexported fields
}

Peer owns a single serialized PeerConnection. A reconnect is a worker concern: this object never creates another connection or changes its epoch.

func NewPeer 

func NewPeer(config Config) (*Peer, error)

NewPeer creates exactly one PeerConnection for config.CaptureEpoch.

func NewPeerConnection 

func NewPeerConnection(config Config) (*Peer, error)

NewPeerConnection is an explicit alias for callers that use the Pion terminology while keeping NewPeer convenient for the capture worker.

func (*Peer) AcceptOffer 

func (p *Peer) AcceptOffer(ctx context.Context, negotiation captureplane.Negotiation) (captureplane.Description, error)

AcceptOffer is a vocabulary alias for AnswerRemoteOffer.

func (*Peer) AnswerRemoteOffer 

func (p *Peer) AnswerRemoteOffer(ctx context.Context, negotiation captureplane.Negotiation) (captureplane.Description, error)

AnswerRemoteOffer applies an SFU offer and creates a non-trickle local answer. Expected tracks were registered before SetRemoteDescription.

func (*Peer) ApplyRemoteAnswer 

func (p *Peer) ApplyRemoteAnswer(ctx context.Context, negotiation captureplane.Negotiation) error

ApplyRemoteAnswer applies the terminal remote_answer produced for the pending local offer. It never creates a new capture epoch or SDP offer.

func (*Peer) Close 

func (p *Peer) Close() error

Close closes this epoch's sole PeerConnection. It is idempotent.

func (*Peer) ConnectionState 

func (p *Peer) ConnectionState() webrtc.PeerConnectionState

ConnectionState returns Pion's current connection state.

func (*Peer) CreateLocalOffer 

func (p *Peer) CreateLocalOffer(ctx context.Context, providerNegotiationID ...captureplane.ProviderReference) (captureplane.Negotiation, error)

CreateLocalOffer creates a non-trickle local offer and records one pending answer fence. A second offer cannot replace the pending one on this epoch.

func (*Peer) CreateOffer 

func (p *Peer) CreateOffer(ctx context.Context, providerNegotiationID ...captureplane.ProviderReference) (captureplane.Negotiation, error)

CreateOffer is a short alias used by capture workers.

func (*Peer) Epoch 

func (p *Peer) Epoch() captureplane.CaptureEpoch

Epoch returns the immutable capture epoch owned by this peer.

func (*Peer) Error 

func (p *Peer) Error() error

Error reports asynchronous track-binding or terminal connection failure.

func (*Peer) Handle 

func (p *Peer) Handle(ctx context.Context, negotiation captureplane.Negotiation) (NegotiationResult, error)

Handle applies one provider-neutral negotiation and returns the local description needed by the worker. AnswerNeeded produces a local answer; OfferNeeded produces a fenced local offer; remote_answer is terminal.

func (*Peer) RegisterCaptureTracks 

func (p *Peer) RegisterCaptureTracks(tracks []captureplane.PulledCaptureTrack) error

RegisterCaptureTracks is a vocabulary alias for RegisterTracks.

func (*Peer) RegisterTracks 

func (p *Peer) RegisterTracks(tracks []captureplane.PulledCaptureTrack) error

RegisterTracks replaces the current expected track set before the next SDP operation. A provider may reuse a MID for a replacement publication; in that case the old remote binding is removed so WaitForTrack cannot return it.

func (*Peer) RequestKeyFrame 

func (p *Peer) RequestKeyFrame(mid captureplane.ProviderReference) error

RequestKeyFrame sends a PLI for the currently bound video track. Capture calls this when a source is first bound or replaced so retained RTP does not depend on an arbitrary pre-capture reference frame.

func (*Peer) State 

func (p *Peer) State() PeerState

State projects the Pion state into a provider-neutral bounded vocabulary.

func (*Peer) TerminalState 

func (p *Peer) TerminalState() (webrtc.PeerConnectionState, bool)

TerminalState reports whether this peer has reached a state that requires a worker-level new capture epoch. The peer itself never creates that epoch.

func (*Peer) Track 

func (p *Peer) Track(mid captureplane.ProviderReference) (*MediaTrack, bool)

Track returns a bound track by negotiated MID.

func (*Peer) Tracks 

func (p *Peer) Tracks() []*MediaTrack

Tracks returns a deterministic snapshot of tracks bound by OnTrack.

func (*Peer) WaitForTrack 

func (p *Peer) WaitForTrack(ctx context.Context, mid captureplane.ProviderReference) (*MediaTrack, error)

WaitForTrack waits until OnTrack binds mid, the peer becomes terminal, or ctx expires. The returned wrapper is safe for later RTP reads.

type PeerState 

type PeerState string

PeerState is the provider-neutral projection of Pion's terminal state. 

const (
	PeerStateNew          PeerState = "new"
	PeerStateConnecting   PeerState = "connecting"
	PeerStateConnected    PeerState = "connected"
	PeerStateDisconnected PeerState = "disconnected"
	PeerStateFailed       PeerState = "failed"
	PeerStateClosed       PeerState = "closed"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
⌂ 换网址