interceptor

README

Pion Interceptor

RTCP and RTCP processors for building real time communications

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:

• Adam Kiss - Original Author
• Sean DuBois - Original Author
• Atsushi Watanabe

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

• type Attributes
  • func (a Attributes) Get(key interface{}) interface{}
  • func (a Attributes) Set(key interface{}, val interface{})
• type Chain
  • func NewChain(interceptors []Interceptor) *Chain
  • func (i *Chain) BindLocalStream(ctx *StreamInfo, writer RTPWriter) RTPWriter
  • func (i *Chain) BindRTCPReader(reader RTCPReader) RTCPReader
  • func (i *Chain) BindRTCPWriter(writer RTCPWriter) RTCPWriter
  • func (i *Chain) BindRemoteStream(ctx *StreamInfo, reader RTPReader) RTPReader
  • func (i *Chain) Close() error
  • func (i *Chain) UnbindLocalStream(ctx *StreamInfo)
  • func (i *Chain) UnbindRemoteStream(ctx *StreamInfo)
• type Interceptor
• type NoOp
  • func (i *NoOp) BindLocalStream(_ *StreamInfo, writer RTPWriter) RTPWriter
  • func (i *NoOp) BindRTCPReader(reader RTCPReader) RTCPReader
  • func (i *NoOp) BindRTCPWriter(writer RTCPWriter) RTCPWriter
  • func (i *NoOp) BindRemoteStream(_ *StreamInfo, reader RTPReader) RTPReader
  • func (i *NoOp) Close() error
  • func (i *NoOp) UnbindLocalStream(_ *StreamInfo)
  • func (i *NoOp) UnbindRemoteStream(_ *StreamInfo)
• type RTCPFeedback
• type RTCPReader
• type RTCPReaderFunc
  • func (f RTCPReaderFunc) Read(b []byte, a Attributes) (int, Attributes, error)
• type RTCPWriter
• type RTCPWriterFunc
  • func (f RTCPWriterFunc) Write(pkts []rtcp.Packet, attributes Attributes) (int, error)
• type RTPHeaderExtension
• type RTPReader
• type RTPReaderFunc
  • func (f RTPReaderFunc) Read(b []byte, a Attributes) (int, Attributes, error)
• type RTPWriter
• type RTPWriterFunc
  • func (f RTPWriterFunc) Write(header *rtp.Header, payload []byte, attributes Attributes) (int, error)
• type Registry
  • func (i *Registry) Add(icpr Interceptor)
  • func (i *Registry) Build() Interceptor
• type StreamInfo

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

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

Registry is a collector for interceptors.

func (*Registry) Add

func (i *Registry) Add(icpr Interceptor)

Add adds a new Interceptor to the registry.

func (*Registry) Build

func (i *Registry) Build() Interceptor

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