interceptor

package module
v0.1.12 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2022 License: MIT Imports: 5 Imported by: 368

README


Pion Interceptor

RTCP and RTCP processors for building real time communications

Pion Interceptor Slack Widget
GoDoc Coverage Status Go Report Card


Interceptor is a framework for building RTP/RTCP communication software. This framework defines a interface that each interceptor must satisfy. These interceptors are then run sequentially. We also then provide common interceptors that will be useful for building RTC software.

This package was built for pion/webrtc, but we designed it to be consumable by anyone. With the following tenets in mind.

  • Useful defaults. Each interceptor will be configured to give you a good default experience.
  • Unblock unique use cases. New use cases are what is driving WebRTC, we want to empower them.
  • Encourage modification. Add your own interceptors without forking. Mixing with the ones we provide.
  • Empower learning. This code base should be useful to read and learn even if you aren't using Pion.

Current Interceptors

Planned Interceptors

Interceptor Public API

The public interface is defined in interceptor.go. The methods you need to satisy are broken up into 4 groups.

  • BindRTCPWriter and BindRTCPReader allow you to inspect/modify RTCP traffic.
  • BindLocalStream and BindRemoteStream notify you of a new SSRC stream and allow you to inspect/modify.
  • UnbindLocalStream and UnbindRemoteStream notify you when a SSRC stream has been removed
  • Close called when the interceptor is closed.

Interceptors also pass Attributes between each other. These are a collection of key/value pairs and are useful for storing metadata or caching.

noop.go is an interceptor that satisfies this interface, but does nothing. You can embed this interceptor as a starting point so you only need to define exactly what you need.

chain.go is used to combine multiple interceptors into one. They are called sequentially as the packet moves through them.

Examples

The examples directory provides some basic examples. If you need more please file an issue! You should also look in pion/webrtc for real world examples.

Community

Pion has an active community on the Golang Slack. Sign up and join the #pion channel for discussions and support. You can also use Pion mailing list.

We are always looking to support your projects. Please reach out if you have something to build!

If you need commercial support or don't want to use public methods you can contact us at team@pion.ly

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible:

License

MIT License - see LICENSE for full text

Documentation

Overview

Package interceptor contains the Interceptor interface, with some useful interceptors that should be safe to use in most cases.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Attributes 

type Attributes map[interface{}]interface{}

Attributes are a generic key/value store used by interceptors

func (Attributes) Get 

func (a Attributes) Get(key interface{}) interface{}

Get returns the attribute associated with key.

func (Attributes) GetRTCPPackets added in v0.1.1 

func (a Attributes) GetRTCPPackets(raw []byte) ([]rtcp.Packet, error)

GetRTCPPackets gets the RTCP packets if present. If the packet slice is not present, it will be unmarshaled from the raw byte slice and stored in the attributes.

func (Attributes) GetRTPHeader added in v0.1.1 

func (a Attributes) GetRTPHeader(raw []byte) (*rtp.Header, error)

GetRTPHeader gets the RTP header if present. If it is not present, it will be unmarshalled from the raw byte slice and stored in the attribtues.

func (Attributes) Set 

func (a Attributes) Set(key interface{}, val interface{})

Set sets the attribute associated with key to the given value.

type Chain 

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

Chain is an interceptor that runs all child interceptors in order.

func NewChain 

func NewChain(interceptors []Interceptor) *Chain

NewChain returns a new Chain interceptor.

func (*Chain) BindLocalStream 

func (i *Chain) BindLocalStream(ctx *StreamInfo, writer RTPWriter) RTPWriter

BindLocalStream lets you modify any outgoing RTP packets. It is called once for per LocalStream. The returned method will be called once per rtp packet.

func (*Chain) BindRTCPReader 

func (i *Chain) BindRTCPReader(reader RTCPReader) RTCPReader

BindRTCPReader lets you modify any incoming RTCP packets. It is called once per sender/receiver, however this might change in the future. The returned method will be called once per packet batch.

func (*Chain) BindRTCPWriter 

func (i *Chain) BindRTCPWriter(writer RTCPWriter) RTCPWriter

BindRTCPWriter lets you modify any outgoing RTCP packets. It is called once per PeerConnection. The returned method will be called once per packet batch.

func (*Chain) BindRemoteStream 

func (i *Chain) BindRemoteStream(ctx *StreamInfo, reader RTPReader) RTPReader

BindRemoteStream lets you modify any incoming RTP packets. It is called once for per RemoteStream. The returned method will be called once per rtp packet.

func (*Chain) Close 

func (i *Chain) Close() error

Close closes the Interceptor, cleaning up any data if necessary.

func (*Chain) UnbindLocalStream 

func (i *Chain) UnbindLocalStream(ctx *StreamInfo)

UnbindLocalStream is called when the Stream is removed. It can be used to clean up any data related to that track.

func (*Chain) UnbindRemoteStream 

func (i *Chain) UnbindRemoteStream(ctx *StreamInfo)

UnbindRemoteStream is called when the Stream is removed. It can be used to clean up any data related to that track.

type Factory added in v0.1.0 

type Factory interface {
	NewInterceptor(id string) (Interceptor, error)
}

Factory provides an interface for constructing interceptors

type Interceptor 

type Interceptor interface {
	// BindRTCPReader lets you modify any incoming RTCP packets. It is called once per sender/receiver, however this might
	// change in the future. The returned method will be called once per packet batch.
	BindRTCPReader(reader RTCPReader) RTCPReader

	// BindRTCPWriter lets you modify any outgoing RTCP packets. It is called once per PeerConnection. The returned method
	// will be called once per packet batch.
	BindRTCPWriter(writer RTCPWriter) RTCPWriter

	// BindLocalStream lets you modify any outgoing RTP packets. It is called once for per LocalStream. The returned method
	// will be called once per rtp packet.
	BindLocalStream(info *StreamInfo, writer RTPWriter) RTPWriter

	// UnbindLocalStream is called when the Stream is removed. It can be used to clean up any data related to that track.
	UnbindLocalStream(info *StreamInfo)

	// BindRemoteStream lets you modify any incoming RTP packets. It is called once for per RemoteStream. The returned method
	// will be called once per rtp packet.
	BindRemoteStream(info *StreamInfo, reader RTPReader) RTPReader

	// UnbindRemoteStream is called when the Stream is removed. It can be used to clean up any data related to that track.
	UnbindRemoteStream(info *StreamInfo)

	io.Closer
}

Interceptor can be used to add functionality to you PeerConnections by modifying any incoming/outgoing rtp/rtcp packets, or sending your own packets as needed.

type NoOp 

type NoOp struct{}

NoOp is an Interceptor that does not modify any packets. It can embedded in other interceptors, so it's possible to implement only a subset of the methods.

func (*NoOp) BindLocalStream 

func (i *NoOp) BindLocalStream(_ *StreamInfo, writer RTPWriter) RTPWriter

BindLocalStream lets you modify any outgoing RTP packets. It is called once for per LocalStream. The returned method will be called once per rtp packet.

func (*NoOp) BindRTCPReader 

func (i *NoOp) BindRTCPReader(reader RTCPReader) RTCPReader

BindRTCPReader lets you modify any incoming RTCP packets. It is called once per sender/receiver, however this might change in the future. The returned method will be called once per packet batch.

func (*NoOp) BindRTCPWriter 

func (i *NoOp) BindRTCPWriter(writer RTCPWriter) RTCPWriter

BindRTCPWriter lets you modify any outgoing RTCP packets. It is called once per PeerConnection. The returned method will be called once per packet batch.

func (*NoOp) BindRemoteStream 

func (i *NoOp) BindRemoteStream(_ *StreamInfo, reader RTPReader) RTPReader

BindRemoteStream lets you modify any incoming RTP packets. It is called once for per RemoteStream. The returned method will be called once per rtp packet.

func (*NoOp) Close 

func (i *NoOp) Close() error

Close closes the Interceptor, cleaning up any data if necessary.

func (*NoOp) UnbindLocalStream 

func (i *NoOp) UnbindLocalStream(_ *StreamInfo)

UnbindLocalStream is called when the Stream is removed. It can be used to clean up any data related to that track.

func (*NoOp) UnbindRemoteStream 

func (i *NoOp) UnbindRemoteStream(_ *StreamInfo)

UnbindRemoteStream is called when the Stream is removed. It can be used to clean up any data related to that track.

type RTCPFeedback 

type RTCPFeedback struct {
	// Type is the type of feedback.
	// see: https://draft.ortc.org/#dom-rtcrtcpfeedback
	// valid: ack, ccm, nack, goog-remb, transport-cc
	Type string

	// The parameter value depends on the type.
	// For example, type="nack" parameter="pli" will send Picture Loss Indicator packets.
	Parameter string
}

RTCPFeedback signals the connection to use additional RTCP packet types. https://draft.ortc.org/#dom-rtcrtcpfeedback

type RTCPReader 

type RTCPReader interface {
	// Read a batch of rtcp packets
	Read([]byte, Attributes) (int, Attributes, error)
}

RTCPReader is used by Interceptor.BindRTCPReader.

type RTCPReaderFunc 

type RTCPReaderFunc func([]byte, Attributes) (int, Attributes, error)

RTCPReaderFunc is an adapter for RTCPReader interface

func (RTCPReaderFunc) Read 

func (f RTCPReaderFunc) Read(b []byte, a Attributes) (int, Attributes, error)

Read a batch of rtcp packets

type RTCPWriter 

type RTCPWriter interface {
	// Write a batch of rtcp packets
	Write(pkts []rtcp.Packet, attributes Attributes) (int, error)
}

RTCPWriter is used by Interceptor.BindRTCPWriter.

type RTCPWriterFunc 

type RTCPWriterFunc func(pkts []rtcp.Packet, attributes Attributes) (int, error)

RTCPWriterFunc is an adapter for RTCPWriter interface

func (RTCPWriterFunc) Write 

func (f RTCPWriterFunc) Write(pkts []rtcp.Packet, attributes Attributes) (int, error)

Write a batch of rtcp packets

type RTPHeaderExtension 

type RTPHeaderExtension struct {
	URI string
	ID  int
}

RTPHeaderExtension represents a negotiated RFC5285 RTP header extension.

type RTPReader 

type RTPReader interface {
	// Read a rtp packet
	Read([]byte, Attributes) (int, Attributes, error)
}

RTPReader is used by Interceptor.BindRemoteStream.

type RTPReaderFunc 

type RTPReaderFunc func([]byte, Attributes) (int, Attributes, error)

RTPReaderFunc is an adapter for RTPReader interface

func (RTPReaderFunc) Read 

func (f RTPReaderFunc) Read(b []byte, a Attributes) (int, Attributes, error)

Read a rtp packet

type RTPWriter 

type RTPWriter interface {
	// Write a rtp packet
	Write(header *rtp.Header, payload []byte, attributes Attributes) (int, error)
}

RTPWriter is used by Interceptor.BindLocalStream.

type RTPWriterFunc 

type RTPWriterFunc func(header *rtp.Header, payload []byte, attributes Attributes) (int, error)

RTPWriterFunc is an adapter for RTPWrite interface

func (RTPWriterFunc) Write 

func (f RTPWriterFunc) Write(header *rtp.Header, payload []byte, attributes Attributes) (int, error)

Write a rtp packet

type Registry added in v0.0.2 

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

Registry is a collector for interceptors.

func (*Registry) Add added in v0.0.2 

func (r *Registry) Add(f Factory)

Add adds a new Interceptor to the registry.

func (*Registry) Build added in v0.0.3 

func (r *Registry) Build(id string) (Interceptor, error)

Build constructs a single Interceptor from a InterceptorRegistry

type StreamInfo 

type StreamInfo struct {
	ID                  string
	Attributes          Attributes
	SSRC                uint32
	PayloadType         uint8
	RTPHeaderExtensions []RTPHeaderExtension
	MimeType            string
	ClockRate           uint32
	Channels            uint16
	SDPFmtpLine         string
	RTCPFeedback        []RTCPFeedback
}

StreamInfo is the Context passed when a StreamLocal or StreamRemote has been Binded or Unbinded

Source Files

View all Source files

Directories

Path Synopsis
examples
nack
internal
cc
Package cc implements common constructs used by Congestion Controllers
 Package cc implements common constructs used by Congestion Controllers
ntp
Package ntp provides conversion methods between time.Time and NTP timestamps stored in uint64
 Package ntp provides conversion methods between time.Time and NTP timestamps stored in uint64
sequencenumber
Package sequencenumber provides a sequence number unwrapper
 Package sequencenumber provides a sequence number unwrapper
test
Package test provides helpers for testing interceptors
 Package test provides helpers for testing interceptors
pkg
cc
Package cc implements an interceptor for bandwidth estimation that can be used with different BandwidthEstimators.
 Package cc implements an interceptor for bandwidth estimation that can be used with different BandwidthEstimators.
gcc
Package gcc implements Google Congestion Control for bandwidth estimation
 Package gcc implements Google Congestion Control for bandwidth estimation
mock
Package mock provides mock Interceptor for testing.
 Package mock provides mock Interceptor for testing.
nack
Package nack provides interceptors to implement sending and receiving negative acknowledgements
 Package nack provides interceptors to implement sending and receiving negative acknowledgements
packetdump
Package packetdump implements RTP & RTCP packet dumpers.
 Package packetdump implements RTP & RTCP packet dumpers.
report
Package report provides interceptors to implement sending sender and receiver reports.
 Package report provides interceptors to implement sending sender and receiver reports.
rfc8888
Package rfc8888 provides an interceptor that generates congestion control feedback reports as defined by RFC 8888.
 Package rfc8888 provides an interceptor that generates congestion control feedback reports as defined by RFC 8888.
stats
Package stats provides an interceptor that records RTP/RTCP stream statistics
 Package stats provides an interceptor that records RTP/RTCP stream statistics
twcc
Package twcc provides interceptors to implement transport wide congestion control.
 Package twcc provides interceptors to implement transport wide congestion control.

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.