webrtcav

package module
v0.0.0-...-74e1562 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Overview

Package webrtcav moves media between goav and WebRTC peers through Pion. In: a Session accepts remote tracks, TrackReaders expose each track as an RTP packet feed that survives renegotiation, and webrtcav.Track adapts one into a goav source provider for goav.Input(...). Out: LocalTrack sends a stream on a local track. WHEP and WHIP are the whep and whip URL schemes, clients for goav.URIInput and goav.URI, registered with runconfig.Scheme.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrClosed reports a call on a closed session, reader, or track set.
	ErrClosed = errors.New("webrtcav: closed")
	// ErrInvalidCodecUpdate reports a codec update missing the facts a live
	// reader needs to adopt it.
	ErrInvalidCodecUpdate = errors.New("webrtcav: invalid codec update")
	// ErrNilTrack reports a remote track without a Pion track handle.
	ErrNilTrack = errors.New("webrtcav: nil track")
	// ErrNilSession reports a nil session handed to a constructor.
	ErrNilSession = errors.New("webrtcav: nil session")
	// ErrStreamExists reports a second track claiming an existing stream id
	// where a replacement was not requested.
	ErrStreamExists = errors.New("webrtcav: stream already exists")
	// ErrTrackQueueFull reports an accepted track arriving faster than the
	// session consumer drains them.
	ErrTrackQueueFull = errors.New("webrtcav: track queue full")
	// ErrUnknownStream reports an update naming a stream no reader owns.
	ErrUnknownStream = errors.New("webrtcav: unknown stream")
)

WebRTC sentinels, matched with errors.Is.

View Source 
var (
	// ErrWHIPDisconnected reports a WHIP session whose peer connection
	// failed, or never connected, while it published.
	ErrWHIPDisconnected = errors.New("webrtcav: whip session disconnected")
	// ErrWHIPCodecRefused reports a WHIP answer that refuses a stream's
	// codec; encode the stream to one the server takes.
	ErrWHIPCodecRefused = errors.New("webrtcav: whip server refused the codec")
)
View Source 
var ErrWHEPDisconnected = errors.New("webrtcav: whep session disconnected")

ErrWHEPDisconnected reports a WHEP session whose peer connection failed or closed while it played; goav.Reconnect reopens the input after it.

Functions

func LocalTrack 

func LocalTrack(track *webrtc.TrackLocalStaticRTP, sender *webrtc.RTPSender) pipeline.Sink

LocalTrack is a WebRTC egress destination for goav.Sink: the packets routed to it, packetized by rtpav, go out on track, and the keyframe requests and bandwidth estimates sender's RTCP carries reach the encoder feeding the stream. The track's codec is the one it takes, so the planner encodes frames to it. The peer connection's interceptors answer NACK and send reports (Pion's default API registers both). It carries one stream and subscribes to sender's RTCP. One reader belongs to the sender until the caller stops it or closes its peer connection. Closing this sink unsubscribes from feedback, leaves track and sender open, and it opens again when its branch reattaches, continuing the track's RTP sequence and timeline, so the remote peer sees one stream.

func Track 

func Track(track *webrtc.TrackRemote, options ...rtpav.ReceiveOption) *rtpav.Input

Track adapts a remote WebRTC track into an RTP receive provider: the track codec is derived from the negotiated codec parameters and the source node is named after the track stream. Extra options layer on top of the derived ones, so callers can override the name or add jitter, feedback, buffer limits, and decode bounds.

func WHEP 

func WHEP(options ...Option) provider.InputScheme

WHEP is the whep scheme, a WebRTC-HTTP Egress Protocol client (draft-ietf-wish-whep, over the HTTP mechanics of WHIP, RFC 9725), for goav.URIInput: whep://host/path plays over https, whep+http://host/path over plain http. Register it under each name used: 

runconfig.Scheme("whep", webrtcav.WHEP(webrtcav.WithToken(token)))

Opening the input POSTs an SDP offer with receive-only audio and video, applies the answer, and starts once the first negotiated track flows; a track silent until later joins then. ICE candidates found after the offer go out by PATCH when the server accepts trickle, and STUN/TURN servers an answer names (Link rel="ice-server") configure the session: the first to name new ones is re-offered with them, later ones to that host start so. The input is live, one stream per track, and its Close DELETEs the session's resource. A dropped peer connection fails the input with ErrWHEPDisconnected; a refused request is a *StatusError. WHEP is an input scheme: WHIP publishes.

func WHIP 

func WHIP(options ...Option) provider.DestinationScheme

WHIP is the whip scheme, a WebRTC-HTTP Ingestion Protocol client (RFC 9725), for goav.URI: whip://host/path and whips://host/path publish over https, whip+http://host/path over plain http. Register it under each name used: 

runconfig.Scheme("whip", webrtcav.WHIP(webrtcav.WithToken(token)))

The destination takes Opus, VP8, H264, VP9, and AV1 packets, so the planner encodes frames to the first of their media it can encode. When the run opens it, it offers one send-only track per stream routed to it, in that stream's codec, POSTs the offer, applies the answer, and waits for the peer connection to connect. ICE candidates found after the offer go out by PATCH when the server accepts trickle, and STUN/TURN servers the answer names (Link rel="ice-server") configure the session as they do for WHEP. Keyframe requests (PLI, FIR) and bandwidth estimates (REMB, and TWCC through Pion's send-side estimator when WHIP builds the peer connection's API) reach the encoders feeding the streams. Closing it DELETEs the session's resource. A refused request is a *StatusError, a refused codec ErrWHIPCodecRefused, and a dropped peer connection fails the run with ErrWHIPDisconnected. WHIP is a destination scheme: WHEP plays.

Types

type Option 

type Option func(*signalConfig)

Option configures the WHIP and WHEP clients, which share the HTTP mechanics of RFC 9725.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sends the requests through client; the default bounds each request to 15s.

func WithSession 

func WithSession(config SessionConfig) Option

WithSession configures the Pion peer connection the way a receive Session is: its API (media engine, interceptors, setting engine) and Configuration (ICE servers).

func WithToken 

func WithToken(token string) Option

WithToken sends token as the Bearer credential on every request (POST, PATCH, DELETE), so the URL carries none.

type RemoteTrack 

type RemoteTrack struct {
	Track       *webrtc.TrackRemote
	Receiver    *webrtc.RTPReceiver
	Transceiver *webrtc.RTPTransceiver
	Codec       webrtc.RTPCodecParameters
	Stream      av.Stream
	Payloads    rtpav.PayloadMap
	Feedback    rtpav.FeedbackWriter
	Metadata    av.Metadata
}

RemoteTrack bundles one accepted Pion remote track with everything a reader needs: the receiver/transceiver handles, negotiated codec, the goav stream view, payload resolution, and the feedback path.

type Session 

type Session interface {
	PeerConnection() *webrtc.PeerConnection
	AcceptTrack(context.Context) (RemoteTrack, error)
	WriteRTCP(context.Context, []rtcp.Packet) error
	Events() <-chan av.Event
	SetRemoteDescription(context.Context, webrtc.SessionDescription) (webrtc.SessionDescription, error)
	AddICECandidate(context.Context, webrtc.ICECandidateInit) error
	Close() error
}

Session is one WebRTC receive session: accept incoming tracks, exchange SDP/ICE, send RTCP feedback, and observe session events. NewSession returns the Pion-backed implementation.

func NewSession 

func NewSession(ctx context.Context, config SessionConfig) (Session, error)

NewSession creates a Pion-backed WebRTC receive session.

type SessionConfig 

type SessionConfig struct {
	Configuration webrtc.Configuration
	API           *webrtc.API
	Metadata      av.Metadata
	MaxTracks     int
	MaxEvents     int
}

SessionConfig configures a Pion-backed WebRTC receive session.

type StatusError 

type StatusError struct {
	Protocol   string
	Method     string
	StatusCode int
	Status     string
}

StatusError reports a WHIP or WHEP request the server refused: the protocol, the request method, and the HTTP status. It names no URL, which may carry credentials.

func (*StatusError) Error 

func (e *StatusError) Error() string

type TrackAdapter 

type TrackAdapter interface {
	AdaptTrack(context.Context, RemoteTrack) (TrackReader, error)
}

TrackAdapter turns an accepted remote track into a TrackReader; custom adapters can wrap readers with application policy.

type TrackCodecUpdate 

type TrackCodecUpdate struct {
	Codec    webrtc.RTPCodecParameters
	Stream   av.Stream
	Payloads rtpav.PayloadMap
	Metadata av.Metadata
}

TrackCodecUpdate carries a mid-session renegotiation: the new codec parameters, stream view, and payload map a live TrackReader should adopt.

type TrackReader 

type TrackReader interface {
	rtpav.PacketReader
	UpdateCodec(context.Context, TrackCodecUpdate) error
	UpdateTrack(context.Context, RemoteTrack) error
}

TrackReader is an rtpav.PacketReader over one WebRTC track that also accepts live codec and track replacement updates, so renegotiations never rebuild the pipeline.

type TrackRemoteAdapter 

type TrackRemoteAdapter struct{}

TrackRemoteAdapter is the default TrackAdapter: it reads RTP straight from the Pion remote track, deriving the stream identity from the track.

func NewTrackRemoteAdapter 

func NewTrackRemoteAdapter() TrackRemoteAdapter

NewTrackRemoteAdapter returns the stateless default TrackAdapter used when a session declares no custom one; provide your own TrackAdapter to wrap or replace how remote tracks become TrackReaders.

func (TrackRemoteAdapter) AdaptTrack 

func (TrackRemoteAdapter) AdaptTrack(ctx context.Context, remote RemoteTrack) (TrackReader, error)

AdaptTrack wraps the remote track in a TrackReader, filling codec and stream identity from the track when undeclared.

type TrackSet 

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

TrackSet keeps one long-lived TrackReader per logical stream.

It is a cold-path coordinator: callers drive it by calling Accept or AcceptRemote. The session lifecycle remains caller-owned.

func NewTrackSet 

func NewTrackSet(config TrackSetConfig) (*TrackSet, error)

NewTrackSet builds a track set over the session; the session is required.

func (*TrackSet) Accept 

func (s *TrackSet) Accept(ctx context.Context) (TrackUpdate, error)

Accept receives the next session track and either creates or updates a reader.

func (*TrackSet) AcceptRemote 

func (s *TrackSet) AcceptRemote(ctx context.Context, remote RemoteTrack) (TrackUpdate, error)

AcceptRemote applies one remote track without reading from the session queue.

func (*TrackSet) Close 

func (s *TrackSet) Close() error

Close closes every reader; the session stays caller-owned.

func (*TrackSet) Reader 

func (s *TrackSet) Reader(id av.StreamID) (TrackReader, bool)

Reader returns the long-lived reader for a stream id, if one exists.

func (*TrackSet) Readers 

func (s *TrackSet) Readers() []TrackReader

Readers lists every reader in acceptance order.

type TrackSetConfig 

type TrackSetConfig struct {
	Session Session
	Adapter TrackAdapter
}

TrackSetConfig configures a TrackSet: the session to accept from and the adapter that turns remote tracks into readers (defaulting to TrackRemoteAdapter).

type TrackUpdate 

type TrackUpdate struct {
	Kind   TrackUpdateKind
	Reader TrackReader
	Stream av.Stream
}

TrackUpdate reports whether an accepted remote track created a new reader or replaced the underlying track for an existing reader.

type TrackUpdateKind 

type TrackUpdateKind string

TrackUpdateKind says what an accepted track did to the set. 

const (
	TrackAdded    TrackUpdateKind = "added"
	TrackReplaced TrackUpdateKind = "replaced"
)

The track update kinds: a brand-new reader, or a live replacement of an existing reader's underlying track.

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.
⌂ 换网址