jitterbuffer

Documentation

Overview

Package jitterbuffer implements a buffer for RTP packets designed to help counteract non-deterministic sources of latency

Index

• Constants
• Variables
• type Event
• type EventListener
• type JitterBuffer
  • func New(opts ...Option) *JitterBuffer
  • func (jb *JitterBuffer) Listen(event Event, cb EventListener)
  • func (jb *JitterBuffer) Peek(playoutHead bool) (*rtp.Packet, error)
  • func (jb *JitterBuffer) PeekAtSequence(sq uint16) (*rtp.Packet, error)
  • func (jb *JitterBuffer) PlayoutHead() uint16
  • func (jb *JitterBuffer) Pop() (*rtp.Packet, error)
  • func (jb *JitterBuffer) PopAtSequence(sq uint16) (*rtp.Packet, error)
  • func (jb *JitterBuffer) PopAtTimestamp(ts uint32) (*rtp.Packet, error)
  • func (jb *JitterBuffer) Push(packet *rtp.Packet)
  • func (jb *JitterBuffer) SetPlayoutHead(playoutHead uint16)
• type Option
  • func WithMinimumPacketCount(count uint16) Option
• type PriorityQueue
  • func NewQueue() *PriorityQueue
  • func (q *PriorityQueue) Find(sqNum uint16) (*rtp.Packet, error)
  • func (q *PriorityQueue) Length() uint16
  • func (q *PriorityQueue) Pop() (*rtp.Packet, error)
  • func (q *PriorityQueue) PopAt(sqNum uint16) (*rtp.Packet, error)
  • func (q *PriorityQueue) PopAtTimestamp(timestamp uint32) (*rtp.Packet, error)
  • func (q *PriorityQueue) Push(val *rtp.Packet, priority uint16)
• type State
  • func (jbs State) String() string
• type Stats

Constants

const (
	// StartBuffering is emitted when the buffer receives its first packet
	StartBuffering Event = "startBuffering"
	// BeginPlayback is emitted when the buffer has satisfied its buffer length
	BeginPlayback = "playing"
	// BufferUnderflow is emitted when the buffer does not have enough packets to Pop
	BufferUnderflow = "underflow"
	// BufferOverflow is emitted when the buffer has exceeded its limit
	BufferOverflow = "overflow"
)

Variables

var (
	// ErrBufferUnderrun is returned when the buffer has no items
	ErrBufferUnderrun = errors.New("invalid Peek: Empty jitter buffer")
	// ErrPopWhileBuffering is returned if a jitter buffer is not in a playback state
	ErrPopWhileBuffering = errors.New("attempt to pop while buffering")
)

var (
	// ErrInvalidOperation may be returned if a Pop or Find operation is performed on an empty queue
	ErrInvalidOperation = errors.New("attempt to find or pop on an empty list")
	// ErrNotFound will be returned if the packet cannot be found in the queue
	ErrNotFound = errors.New("priority not found")
)

Types

type Event

type Event string

Event represents all events a JitterBuffer can emit

type EventListener

type EventListener func(event Event, jb *JitterBuffer)

EventListener will be called when the corresponding Event occurs

type JitterBuffer

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

A JitterBuffer will accept Pushed packets, put them in sequence number order, and allows removing in either sequence number order or via a provided timestamp

func New

func New(opts ...Option) *JitterBuffer

New will initialize a jitter buffer and its associated statistics

func (*JitterBuffer) Listen

func (jb *JitterBuffer) Listen(event Event, cb EventListener)

Listen will register an event listener The jitter buffer may emit events correspnding, interested listerns should look at Event for available events

func (*JitterBuffer) Peek

func (jb *JitterBuffer) Peek(playoutHead bool) (*rtp.Packet, error)

Peek at the packet which is either:

At the playout head when we are emitting, and the playoutHead flag is true

or else

At the last sequence received

func (*JitterBuffer) PeekAtSequence

func (jb *JitterBuffer) PeekAtSequence(sq uint16) (*rtp.Packet, error)

PeekAtSequence will return an RTP packet from the jitter buffer at the specified Sequence without removing it from the buffer

func (*JitterBuffer) PlayoutHead

func (jb *JitterBuffer) PlayoutHead() uint16

PlayoutHead returns the SequenceNumber that will be attempted to Pop next

func (*JitterBuffer) Pop

func (jb *JitterBuffer) Pop() (*rtp.Packet, error)

Pop an RTP packet from the jitter buffer at the current playout head

func (*JitterBuffer) PopAtSequence

func (jb *JitterBuffer) PopAtSequence(sq uint16) (*rtp.Packet, error)

PopAtSequence will pop an RTP packet from the jitter buffer at the specified Sequence

func (*JitterBuffer) PopAtTimestamp

func (jb *JitterBuffer) PopAtTimestamp(ts uint32) (*rtp.Packet, error)

PopAtTimestamp pops an RTP packet from the jitter buffer with the provided timestamp Call this method repeatedly to drain the buffer at the timestamp

func (*JitterBuffer) Push

func (jb *JitterBuffer) Push(packet *rtp.Packet)

Push an RTP packet into the jitter buffer, this does not clone the data so if the memory is expected to be reused, the caller should take this in to account and pass a copy of the packet they wish to buffer

func (*JitterBuffer) SetPlayoutHead

func (jb *JitterBuffer) SetPlayoutHead(playoutHead uint16)

SetPlayoutHead allows you to manually specify the packet you wish to pop next If you have encountered a packet that hasn't resolved you can skip it

type Option

type Option func(jb *JitterBuffer)

Option will Override JitterBuffer's defaults

func WithMinimumPacketCount

func WithMinimumPacketCount(count uint16) Option

WithMinimumPacketCount will set the required number of packets to be received before any attempt to pop a packet can succeed

type PriorityQueue

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

PriorityQueue provides a linked list sorting of RTP packets by SequenceNumber

func NewQueue

func NewQueue() *PriorityQueue

NewQueue will create a new PriorityQueue whose order relies on monotonically increasing Sequence Number, wrapping at MaxUint16, so a packet with sequence number MaxUint16 - 1 will be after 0

func (*PriorityQueue) Find

func (q *PriorityQueue) Find(sqNum uint16) (*rtp.Packet, error)

Find a packet in the queue with the provided sequence number, regardless of position (the packet is retained in the queue)

func (*PriorityQueue) Length

func (q *PriorityQueue) Length() uint16

Length will get the total length of the queue

func (*PriorityQueue) Pop

func (q *PriorityQueue) Pop() (*rtp.Packet, error)

Pop removes the first element from the queue, regardless sequence number

func (*PriorityQueue) PopAt

func (q *PriorityQueue) PopAt(sqNum uint16) (*rtp.Packet, error)

PopAt removes an element at the specified sequence number (priority)

func (*PriorityQueue) PopAtTimestamp

func (q *PriorityQueue) PopAtTimestamp(timestamp uint32) (*rtp.Packet, error)

PopAtTimestamp removes and returns a packet at the given RTP Timestamp, regardless sequence number order

func (*PriorityQueue) Push

func (q *PriorityQueue) Push(val *rtp.Packet, priority uint16)

Push will insert a packet in to the queue in order of sequence number

type State

type State uint16

State tracks a JitterBuffer as either Buffering or Emitting

const (
	// Buffering is the state when the jitter buffer has not started emitting yet, or has hit an underflow and needs to re-buffer packets
	Buffering State = iota
	//  Emitting is the state when the jitter buffer is operating nominally
	Emitting
)

func (State) String

func (jbs State) String() string

type Stats

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

Stats Track interesting statistics for the life of this JitterBuffer outOfOrderCount will provide the number of times a packet was Pushed

without its predecessor being present

underflowCount will provide the count of attempts to Pop an empty buffer overflowCount will track the number of times the jitter buffer exceeds its limit