relay

README

Relay

ion-sfu supports relaying tracks to other ion-SFUs or other services using the ORTC API.

Using this api allows to quickly send the stream to other services by signaling a single request, after that all the following negotiations are handled internally.

API

Relay Peer

The relay peer shares common methods with the Webrtc PeerConnection, so it should be straight forward to use. To create a new relay peer follow below example :

 // Meta holds all the related information of the peer you want to relay.
 meta := PeerMeta{
	      PeerID : "super-villain-1",
	      SessionID : "world-domination",
        } 
 // config will hold pion/webrtc related structs required for the connection. 
 // you should fill according your requirements or leave the defaults.
 config := &PeerConfig{} 
 peer, err := NewPeer(meta, config)
 handleErr(err)
 
 // Now before working with the peer you need to signal the peer to 
 // your remote sever, the signaling can be whatever method you want (gRPC, RESt, pubsub, etc..)
 signalFunc= func (meta PeerMeta, signal []byte) ([]byte, error){
   if meta.session== "world-domination"{
      	return RelayToLegionOfDoom(meta, signal)
   }	
   return nil, errors.New("not supported")
 }
 
 // The remote peer should create a new Relay Peer with the metadata and call Answer.
 if err:= peer.Offer(signalFunc); err!=nil{
 	handleErr(err)
 }
 
 // If there are no errors, relay peer offer some convenience methods to communicate with
 // Relayed peer.
 
 // Emit will fire and forget to the request event
 peer.Emit("evil-plan-1", data)
 // Request will wait for a remote answer, use a time cancelled
 // context to not block forever if peer does not answer
 ans,err:= peer.Request(ctx, "evil-plan-2", data)
 // To listen to remote event just attach the callback to peer
 peer.OnRequest( func (event string, msg Message){
 	// to access to request data
 	msg.Paylod()
 	// to reply the request
 	msg.Reply(...)
 })
 
 // The Relay Peer also has some convenience callbacks to manage the peer lifespan.
 
 // Peer OnClose is called when the remote peer connection is closed, or the Close method is called
 peer.OnClose(func())
 // Peer OnReady is called when the relay peer is ready to start negotiating tracks, data channels and request
 // is highly recommended to attach all the initialization logic to this callback
 peer.OnReady(func())
 
 // To add or receive tracks or data channels the API is similar to webrtc Peer Connection, just listen
 // to the required callbacks
 peer.OnDataChannel(f func(channel *webrtc.DataChannel))
 peer.OnTrack(f func(track *webrtc.TrackRemote, receiver *webrtc.RTPReceiver))
 // Make sure to call below methods after the OnReady callback fired.
 peer.CreateDataChannel(label string)
 peer.AddTrack(receiver *webrtc.RTPReceiver, remoteTrack *webrtc.TrackRemote,
localTrack webrtc.TrackLocal) (*webrtc.RTPSender, error)

ION-SFU integration

ION-SFU offers some convenience methods for relaying peers in a very simple way.

To relay a peer just call Peer.Publisher().Relay(...) then signal the data to the remote SFU and ingest the data using:

session.AddRelayPeer(peerID string, signalData []byte) ([]byte, error)

set the []byte response from the method as the response of the signaling. And is ready, everytime a peer joins to the new SFU will negotiate the relayed stream.

Documentation

Index

• Variables
• type Message
  • func (m *Message) Payload() []byte
  • func (m *Message) Reply(msg []byte) error
• type Options
• type Peer
  • func NewPeer(meta PeerMeta, conf *PeerConfig) (*Peer, error)
  • func (p *Peer) AddTrack(receiver *webrtc.RTPReceiver, remoteTrack *webrtc.TrackRemote, ...) (*webrtc.RTPSender, error)
  • func (p *Peer) Answer(request []byte) ([]byte, error)
  • func (p *Peer) Close() error
  • func (p *Peer) CreateDataChannel(label string) (*webrtc.DataChannel, error)
  • func (p *Peer) Emit(event string, data []byte) error
  • func (p *Peer) ID() string
  • func (p *Peer) LocalTracks() []webrtc.TrackLocal
  • func (p *Peer) Offer(signalFn func(meta PeerMeta, signal []byte) ([]byte, error)) error
  • func (p *Peer) OnClose(fn func())
  • func (p *Peer) OnDataChannel(f func(channel *webrtc.DataChannel))
  • func (p *Peer) OnReady(f func())
  • func (p *Peer) OnRequest(f func(event string, msg Message))
  • func (p *Peer) OnTrack(...)
  • func (p *Peer) Request(ctx context.Context, event string, data []byte) ([]byte, error)
  • func (p *Peer) WriteRTCP(pkts []rtcp.Packet) error
• type PeerConfig
• type PeerMeta
• type TrackMeta

Variables

var (
	ErrRelayPeerNotReady     = errors.New("relay Peer is not ready")
	ErrRelayPeerSignalDone   = errors.New("relay Peer signal already called")
	ErrRelaySignalDCNotReady = errors.New("relay Peer data channel is not ready")
)

Types

type Message

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

func (*Message) Payload

func (m *Message) Payload() []byte

func (*Message) Reply

func (m *Message) Reply(msg []byte) error

type Options

type Options struct {
	// RelayMiddlewareDC if set to true middleware data channels will be created and forwarded
	// to the relayed peer
	RelayMiddlewareDC bool
	// RelaySessionDC if set to true fanout data channels will be created and forwarded to the
	// relayed peer
	RelaySessionDC bool
}

type Peer

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

func NewPeer

func NewPeer(meta PeerMeta, conf *PeerConfig) (*Peer, error)

func (*Peer) AddTrack

func (p *Peer) AddTrack(receiver *webrtc.RTPReceiver, remoteTrack *webrtc.TrackRemote,
	localTrack webrtc.TrackLocal) (*webrtc.RTPSender, error)

AddTrack is used to negotiate a track to the remote peer

func (*Peer) Answer

func (p *Peer) Answer(request []byte) ([]byte, error)

Answer answers the remote Peer signal signalRequest

func (*Peer) Close

func (p *Peer) Close() error

Close ends the relay Peer

func (*Peer) CreateDataChannel

func (p *Peer) CreateDataChannel(label string) (*webrtc.DataChannel, error)

CreateDataChannel creates a new DataChannel object with the given label

func (*Peer) Emit

func (p *Peer) Emit(event string, data []byte) error

Emit emits the data argument to remote peer.

func (*Peer) ID

func (p *Peer) ID() string

func (*Peer) LocalTracks

func (p *Peer) LocalTracks() []webrtc.TrackLocal

func (*Peer) Offer

func (p *Peer) Offer(signalFn func(meta PeerMeta, signal []byte) ([]byte, error)) error

Offer is used for establish the connection of the local relay Peer with the remote relay Peer.

If connection is successful OnReady handler will be called

func (*Peer) OnClose

func (p *Peer) OnClose(fn func())

OnClose sets a callback that is called when relay Peer is closed.

func (*Peer) OnDataChannel

func (p *Peer) OnDataChannel(f func(channel *webrtc.DataChannel))

OnDataChannel sets an event handler which is invoked when a data channel message arrives from a remote Peer.

func (*Peer) OnReady

func (p *Peer) OnReady(f func())

OnReady calls the callback when relay Peer is ready to start sending/receiving and creating DC

func (*Peer) OnRequest

func (p *Peer) OnRequest(f func(event string, msg Message))

OnRequest calls the callback when Peer gets a request message from remote Peer

func (*Peer) OnTrack

func (p *Peer) OnTrack(f func(track *webrtc.TrackRemote, receiver *webrtc.RTPReceiver, meta *TrackMeta))

OnTrack sets an event handler which is called when remote track arrives from a remote Peer

func (*Peer) Request

func (p *Peer) Request(ctx context.Context, event string, data []byte) ([]byte, error)

func (*Peer) WriteRTCP

func (p *Peer) WriteRTCP(pkts []rtcp.Packet) error

WriteRTCP sends a user provided RTCP packet to the connected Peer. If no Peer is connected the packet is discarded. It also runs any configured interceptors.

type PeerConfig

type PeerConfig struct {
	SettingEngine webrtc.SettingEngine
	ICEServers    []webrtc.ICEServer
	Logger        logr.Logger
}

type PeerMeta

type PeerMeta struct {
	PeerID    string `json:"peerId"`
	SessionID string `json:"sessionId"`
}

type TrackMeta

type TrackMeta struct {
	StreamID        string                     `json:"streamId"`
	TrackID         string                     `json:"trackId"`
	CodecParameters *webrtc.RTPCodecParameters `json:"codecParameters,omitempty"`
}