interceptor

package module
Version: v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Sep 17, 2021 License: MIT Imports: 5 Imported by: 44

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

  • NACK Generator/Responder

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) 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

Directories

Path Synopsis
examples
pkg
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
report
Package report provides interceptors to implement sending sender and receiver reports.
Package report provides interceptors to implement sending sender and receiver reports.
twcc
Package twcc provides interceptors to implement transport wide congestion control.
Package twcc provides interceptors to implement transport wide congestion control.
internal
test
Package test provides helpers for testing interceptors
Package test provides helpers for testing interceptors

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL