media

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Jan 20, 2025 License: MPL-2.0 Imports: 17 Imported by: 1

README

media

Implemented:

Everything is io.Reader and io.Writer

We follow GO std lib and providing interface for Reader/Writer when it comes reading and writing media.
This optimized and made easier usage of RTP framework, by providing end user standard library io.Reader io.Writer to pass his media.

In other words chaining reader or writer allows to build interceptors, encoders, decoders without introducing overhead of contention or many memory allocations

Features:

  • Simple SDP build with formats alaw,ulaw,dtmf
  • RTP/RTCP receiving and logging
  • Extendable MediaSession handling for RTP/RTCP handling (ex microphone,speaker)
  • DTMF encoder, decoder via RFC4733
  • Minimal SDP package for audio
  • Media Session, RTP Session handling
  • RTCP monitoring
  • SDP codec fields manipulating
  • ... who knows

Concepts

  • Media Session represents mapping between SDP media description and creates session based on local/remote addr
  • RTP Session is creating RTP/RTCP session. It is using media session underneath to add networking layer.
  • RTP Packet Reader is depackatizing RTP packets and providing payload as io.Reader. Normally it should be chained to RTP Session
  • RTP Packet Writer is packatizing payload to RTP packets as io.Writer. Normally it should be chained to RTP Session

IO flow

Reader: AudioDecoder<->RTPPacketReader<->RTPSession<->MediaSession

Writer: AudioEncoder<->RTPPackerWriter<->RTPSession<->MediaSession

more docs...

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Here are some codec constants that can be reused
	CodecAudioUlaw          = Codec{PayloadType: 0, SampleRate: 8000, SampleDur: 20 * time.Millisecond, NumChannels: 1}
	CodecAudioAlaw          = Codec{PayloadType: 8, SampleRate: 8000, SampleDur: 20 * time.Millisecond, NumChannels: 1}
	CodecAudioOpus          = Codec{PayloadType: 96, SampleRate: 48000, SampleDur: 20 * time.Millisecond, NumChannels: 2}
	CodecTelephoneEvent8000 = Codec{PayloadType: 101, SampleRate: 8000, SampleDur: 20 * time.Millisecond, NumChannels: 1}
)
View Source 
var (
	// RTPPortStart and RTPPortEnd allows defining rtp port range for media
	RTPPortStart = 0
	RTPPortEnd   = 0

	// When reading RTP use at least MTU size. Increase this
	RTPBufSize = 1500

	RTPDebug  = false
	RTCPDebug = false
)
View Source 
var (
	ErrRTPSequenceOutOfOrder = errors.New("out of order")
	ErrRTPSequenceBad        = errors.New("bad sequence")
	ErrRTPSequnceDuplicate   = errors.New("sequence duplicate")
)
View Source 
var (
	DefaultOnReadRTCP  func(pkt rtcp.Packet, rtpStats RTPReadStats)  = nil
	DefaultOnWriteRTCP func(pkt rtcp.Packet, rtpStats RTPWriteStats) = nil
)

Functions

func Copy added in v0.4.0 

func Copy(reader io.Reader, writer io.Writer) (int64, error)

Copy is like io.Copy but it uses buffer size needed for RTP

func CopyWithBuf 

func CopyWithBuf(reader io.Reader, writer io.Writer, payloadBuf []byte) (int64, error)

CopyWithBuf is simple and strict compared to io.CopyBuffer. ReadFrom and WriteTo is not considered and due to RTP buf requirement it can lead to different buffer size passing

func DTMFDecode 

func DTMFDecode(payload []byte, d *DTMFEvent) error

DecodeRTPPayload decodes an RTP payload into a DTMF event

func DTMFEncode 

func DTMFEncode(d DTMFEvent) []byte

func DTMFToRune 

func DTMFToRune(dtmf uint8) rune

func ErrorIsTimeout 

func ErrorIsTimeout(err error) bool

func FractionLostFloat 

func FractionLostFloat(f uint8) float64

func GetCurrentNTPTimestamp 

func GetCurrentNTPTimestamp() uint64

func NTPTimestamp 

func NTPTimestamp(t time.Time) uint64

func NTPToTime 

func NTPToTime(ntpTimestamp uint64) time.Time

func RTCPUnmarshal 

func RTCPUnmarshal(data []byte, packets []rtcp.Packet) (n int, err error)

RTCPUnmarshal is improved version based on pion/rtcp where we allow caller to define and control buffer of rtcp packets. This also reduces one allocation NOTE: data is still referenced in packet buffer

func RTPUnmarshal 

func RTPUnmarshal(buf []byte, p *rtp.Packet) error

Experimental

RTPUnmarshal temporarly solution to provide more optimized unmarshal version based on pion/rtp it does not preserve any buffer reference which allows reusage

TODO build RTP header unmarshaller for VOIP needs

func ReadAll added in v0.13.0 

func ReadAll(reader io.Reader, sampleSize int) ([]byte, error)

func SendDummyRTP 

func SendDummyRTP(rtpConn *net.UDPConn, raddr net.Addr)

func StringRTCP added in v0.2.0 

func StringRTCP(p rtcp.Packet) string

func WriteAll added in v0.13.0 

func WriteAll(w io.Writer, data []byte, sampleSize int) (int64, error)

Types

type Codec 

type Codec struct {
	PayloadType uint8
	SampleRate  uint32
	SampleDur   time.Duration
	NumChannels int // 1 or 2
}

func CodecAudioFromPayloadType added in v0.12.0 

func CodecAudioFromPayloadType(payloadType uint8) (Codec, error)

func CodecFromPayloadType deprecated 

func CodecFromPayloadType(payloadType uint8) Codec

Deprecated: Use CodecAudioFromPayloadType

func CodecFromSession 

func CodecFromSession(s *MediaSession) Codec

func (*Codec) SampleTimestamp 

func (c *Codec) SampleTimestamp() uint32

func (*Codec) Samples16 added in v0.12.0 

func (c *Codec) Samples16() int

func (*Codec) SamplesPCM added in v0.12.0 

func (c *Codec) SamplesPCM(bitSize int) int

Samples is samples in pcm

func (*Codec) String added in v0.2.0 

func (c *Codec) String() string

type DTMFEvent 

type DTMFEvent struct {
	Event      uint8
	EndOfEvent bool
	Volume     uint8
	Duration   uint16
}

DTMFEvent represents a DTMF event

func RTPDTMFEncode 

func RTPDTMFEncode(char rune) []DTMFEvent

RTPDTMFEncode creates series of DTMF redudant events which should be encoded as payload It is currently only 8000 sample rate considered for telophone event

func (*DTMFEvent) String 

func (ev *DTMFEvent) String() string

type MediaSession 

type MediaSession struct {
	// SDP stuff
	// Depending of negotiation this can change.
	// Formats will always try to match remote, to avoid different codec matching
	// TODO:
	// 1. make this list of codecs as we need to match also sample rate and ptime
	// 2. rtp session when matching incoming packet sample rate for RTCP should use this
	Formats sdp.Formats
	Mode    sdp.Mode
	// Laddr our local address which has full IP and port after media session creation
	Laddr net.UDPAddr

	// Raddr is our target remote address. Normally it is resolved by SDP parsing.
	// Checkout SetRemoteAddr
	Raddr net.UDPAddr

	// ExternalIP that should be used for building SDP
	ExternalIP net.IP
	// contains filtered or unexported fields
}

MediaSession represents active media session with RTP/RTCP TODO: multiple media descriptions. Consider https://datatracker.ietf.org/doc/rfc3388/ for grouping multiple media

Design: - It identfies single session Laddr <-> Raddr - With multi descriptions, or reinvites it should be forked and create new media Session

NOTE: Not thread safe, read only after SDP negotiation or have locking in place

func NewMediaSession 

func NewMediaSession(ip net.IP, port int) (s *MediaSession, e error)

func (*MediaSession) Close 

func (s *MediaSession) Close()

func (*MediaSession) Fork 

func (s *MediaSession) Fork() *MediaSession

Fork is special call to be used in case when there is session update It preserves pointer to same conneciton but rest is remobed After this call it still expected that

func (*MediaSession) Init added in v0.7.0 

func (s *MediaSession) Init() error

Init should be called if session is created manually Use NewMediaSession for default building

func (*MediaSession) InitWithListeners added in v0.13.0 

func (s *MediaSession) InitWithListeners(lRTP net.PacketConn, lRTCP net.PacketConn, raddr *net.UDPAddr)

func (*MediaSession) LocalSDP 

func (s *MediaSession) LocalSDP() []byte

func (*MediaSession) ReadRTCP 

func (m *MediaSession) ReadRTCP(buf []byte, pkts []rtcp.Packet) (n int, err error)

ReadRTCP is optimized reads and unmarshals RTCP packets. Buffers is only used for unmarshaling. Caller needs to be aware of size this buffer and allign with MTU

func (*MediaSession) ReadRTCPRaw 

func (m *MediaSession) ReadRTCPRaw(buf []byte) (int, error)

func (*MediaSession) ReadRTCPRawDeadline 

func (m *MediaSession) ReadRTCPRawDeadline(buf []byte, t time.Time) (int, error)

func (*MediaSession) ReadRTP 

func (m *MediaSession) ReadRTP(buf []byte, pkt *rtp.Packet) (int, error)

ReadRTP reads data from network and parses to pkt buffer is passed in order to avoid extra allocs

func (*MediaSession) ReadRTPRaw 

func (m *MediaSession) ReadRTPRaw(buf []byte) (int, error)

func (*MediaSession) ReadRTPRawDeadline 

func (m *MediaSession) ReadRTPRawDeadline(buf []byte, t time.Time) (int, error)

func (*MediaSession) RemoteSDP 

func (s *MediaSession) RemoteSDP(sdpReceived []byte) error

func (*MediaSession) SetLogger 

func (s *MediaSession) SetLogger(log zerolog.Logger)

func (*MediaSession) SetRemoteAddr 

func (s *MediaSession) SetRemoteAddr(raddr *net.UDPAddr)

SetRemoteAddr is helper to set Raddr and rtcp address. It is not thread safe

func (*MediaSession) StartRTP 

func (s *MediaSession) StartRTP(rw int8) error

func (*MediaSession) StopRTP 

func (s *MediaSession) StopRTP(rw int8, dur time.Duration) error

func (*MediaSession) WriteRTCP 

func (m *MediaSession) WriteRTCP(p rtcp.Packet) error

func (*MediaSession) WriteRTCPDeadline 

func (m *MediaSession) WriteRTCPDeadline(p rtcp.Packet, deadline time.Time) error

func (*MediaSession) WriteRTCPRaw 

func (m *MediaSession) WriteRTCPRaw(data []byte) (int, error)

func (*MediaSession) WriteRTCPs 

func (m *MediaSession) WriteRTCPs(pkts []rtcp.Packet) error

Use this to write Multi RTCP packets if they can fit in MTU=1500

func (*MediaSession) WriteRTP 

func (m *MediaSession) WriteRTP(p *rtp.Packet) error

func (*MediaSession) WriteRTPRaw 

func (m *MediaSession) WriteRTPRaw(data []byte) (n int, err error)

type MediaStreamer 

type MediaStreamer interface {
	MediaStream(s *MediaSession) error
}

type OnRTPReadStats added in v0.10.0 

type OnRTPReadStats func(stats RTPReadStats)

type OnRTPWriteStats added in v0.10.0 

type OnRTPWriteStats func(stats RTPWriteStats)

type RTCPReader 

type RTCPReader interface {
	ReadRTCP(buf []byte, pkts []rtcp.Packet) (n int, err error)
}

type RTCPWriter 

type RTCPWriter interface {
	WriteRTCP(p rtcp.Packet) error
}

type RTCPWriterRaw 

type RTCPWriterRaw interface {
	WriteRTCPRaw(buf []byte) (int, error) // -> io.Writer
}

type RTPCReaderRaw 

type RTPCReaderRaw interface {
	ReadRTCPRaw(buf []byte) (int, error)
}

type RTPDtmfReader 

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

func NewRTPDTMFReader 

func NewRTPDTMFReader(codec Codec, packetReader *RTPPacketReader, reader io.Reader) *RTPDtmfReader

RTP DTMF writer is midleware for reading DTMF events It reads from io Reader and checks packet Reader

func (*RTPDtmfReader) Read 

func (w *RTPDtmfReader) Read(b []byte) (int, error)

Write is RTP io.Writer which adds more sync mechanism

func (*RTPDtmfReader) ReadDTMF 

func (w *RTPDtmfReader) ReadDTMF() (rune, bool)

type RTPDtmfWriter 

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

func NewRTPDTMFWriter 

func NewRTPDTMFWriter(codec Codec, rtpPacketizer *RTPPacketWriter, writer io.Writer) *RTPDtmfWriter

RTP DTMF writer is midleware for passing RTP DTMF event. If it is chained it uses to block writer while writing DTFM events

func (*RTPDtmfWriter) Write 

func (w *RTPDtmfWriter) Write(b []byte) (int, error)

Write is RTP io.Writer which adds more sync mechanism

func (*RTPDtmfWriter) WriteDTMF 

func (w *RTPDtmfWriter) WriteDTMF(dtmf rune) error

type RTPExtendedSequenceNumber 

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

RTPExtendedSequenceNumber is embedable/ replacable sequnce number generator For thread safety you should wrap it

func NewRTPSequencer 

func NewRTPSequencer() RTPExtendedSequenceNumber

func (*RTPExtendedSequenceNumber) InitSeq 

func (sn *RTPExtendedSequenceNumber) InitSeq(seq uint16)

func (*RTPExtendedSequenceNumber) NextSeqNumber 

func (s *RTPExtendedSequenceNumber) NextSeqNumber() uint16

func (*RTPExtendedSequenceNumber) ReadExtendedSeq 

func (sn *RTPExtendedSequenceNumber) ReadExtendedSeq() uint64

func (*RTPExtendedSequenceNumber) UpdateSeq 

func (sn *RTPExtendedSequenceNumber) UpdateSeq(seq uint16) error

Based on https://datatracker.ietf.org/doc/html/rfc1889#appendix-A.2

type RTPPacketReader 

type RTPPacketReader struct {

	// PacketHeader is stored after calling Read
	// Safe to read only in same goroutine as Read
	PacketHeader rtp.Header
	// contains filtered or unexported fields
}

RTPPacketReader reads RTP packet and extracts payload and header

func NewRTPPacketReader 

func NewRTPPacketReader(reader RTPReader, codec Codec) *RTPPacketReader

func NewRTPPacketReaderSession 

func NewRTPPacketReaderSession(sess *RTPSession) *RTPPacketReader

NewRTPPacketReaderSession just helper constructor

func (*RTPPacketReader) Read 

func (r *RTPPacketReader) Read(b []byte) (int, error)

Read Implements io.Reader and extracts Payload from RTP packet has no input queue or sorting control of packets Buffer is used for reading headers and Headers are stored in PacketHeader

NOTE: Consider that if you are passsing smaller buffer than RTP header+payload, io.ErrShortBuffer is returned

func (*RTPPacketReader) Reader 

func (r *RTPPacketReader) Reader() RTPReader

func (*RTPPacketReader) UpdateRTPSession 

func (r *RTPPacketReader) UpdateRTPSession(rtpSess *RTPSession)

func (*RTPPacketReader) UpdateReader added in v0.2.0 

func (r *RTPPacketReader) UpdateReader(reader RTPReader)

type RTPPacketWriter 

type RTPPacketWriter struct {

	// After each write packet header is saved for more reading
	PacketHeader rtp.Header

	// SSRC is readOnly and it is not changed
	SSRC uint32
	// contains filtered or unexported fields
}

RTPPacketWriter packetize any payload before pushing to active media session It creates SSRC as identifier and all packets sent will be with this SSRC For multiple streams, multiple RTP Writer needs to be created

func NewRTPPacketWriter 

func NewRTPPacketWriter(writer RTPWriter, codec Codec) *RTPPacketWriter

RTPPacketWriter packetize payload in RTP packet before passing on media session Not having: - random Timestamp - allow different clock rate - CSRC contribution source - Silence detection and marker set updateClockRate- Padding and encryyption

func NewRTPPacketWriterSession 

func NewRTPPacketWriterSession(sess *RTPSession) *RTPPacketWriter

NewRTPPacketWriterSession creates RTPPacketWriter and attaches RTP Session expected values

func (*RTPPacketWriter) UpdateRTPSession 

func (w *RTPPacketWriter) UpdateRTPSession(rtpSess *RTPSession)

UpdateRTPSession updates rtp writer from current rtp session due to REINVITE It is expected that this is now new RTP Session and it is expected tha: - Statistics will be reset (SSRC=0) -> Fresh Start of Quality monitoring - Should not lead inacurate reporting - In case CODEC change than RTP should reset stats anyway

func (*RTPPacketWriter) Write 

func (p *RTPPacketWriter) Write(b []byte) (int, error)

Write implements io.Writer and does payload RTP packetization Media clock rate is determined For more control or dynamic payload WriteSamples can be used It is not thread safe and order of payload frames is required

func (*RTPPacketWriter) WriteSamples 

func (p *RTPPacketWriter) WriteSamples(payload []byte, sampleRateTimestamp uint32, marker bool, payloadType uint8) (int, error)

WriteSamples allows to skip default packet rate. This is useful if you need to write different payload but keeping same SSRC

func (*RTPPacketWriter) Writer 

func (w *RTPPacketWriter) Writer() RTPWriter

type RTPReadStats 

type RTPReadStats struct {
	SSRC                   uint32
	FirstPktSequenceNumber uint16
	LastSequenceNumber     uint16

	// tracks first pkt seq in this interval to calculate loss of packets
	IntervalFirstPktSeqNum uint16
	IntervalPacketsCount   uint16

	PacketsCount uint64
	OctetCount   uint64

	// RTP reading stats
	SampleRate uint32

	// Round TRIP Time based on LSR and DLSR
	RTT time.Duration
	// contains filtered or unexported fields
}

Some of fields here are exported (as readonly) intentionally

type RTPReader 

type RTPReader interface {
	ReadRTP(buf []byte, p *rtp.Packet) (int, error)
}

type RTPReaderRaw 

type RTPReaderRaw interface {
	ReadRTPRaw(buf []byte) (int, error)
}

type RTPSession 

type RTPSession struct {
	// Keep pointers at top to reduce GC
	Sess *MediaSession

	// Experimental
	// this intercepts reading or writing rtcp packet. Allows manipulation
	OnReadRTCP  func(pkt rtcp.Packet, rtpStats RTPReadStats)
	OnWriteRTCP func(pkt rtcp.Packet, rtpStats RTPWriteStats)
	// contains filtered or unexported fields
}

func NewRTPSession 

func NewRTPSession(sess *MediaSession) *RTPSession

RTP session creates new RTP reader/writer from session

func (*RTPSession) Close 

func (s *RTPSession) Close() error

func (*RTPSession) Monitor 

func (s *RTPSession) Monitor() error

Monitor starts reading RTCP and monitoring media quality

func (*RTPSession) MonitorBackground 

func (s *RTPSession) MonitorBackground() error

MonitorBackground is helper to keep monitoring in background MUST Be called after session REMOTE SDP is parsed

func (*RTPSession) ReadRTP 

func (s *RTPSession) ReadRTP(b []byte, readPkt *rtp.Packet) (n int, err error)

func (*RTPSession) ReadRTPRaw 

func (s *RTPSession) ReadRTPRaw(buf []byte) (int, error)

func (*RTPSession) ReadStats added in v0.10.0 

func (s *RTPSession) ReadStats() RTPReadStats

func (*RTPSession) WriteRTP 

func (s *RTPSession) WriteRTP(pkt *rtp.Packet) error

func (*RTPSession) WriteRTPRaw 

func (s *RTPSession) WriteRTPRaw(buf []byte) (int, error)

func (*RTPSession) WriteStats added in v0.10.0 

func (s *RTPSession) WriteStats() RTPWriteStats

type RTPStatsReader added in v0.10.0 

type RTPStatsReader struct {
	// Reader should be your AudioReade or any other interceptor RTP reader that is reading audio stream
	Reader     io.Reader
	RTPSession *RTPSession
	// OnRTPReadStats is fired each time on Read RTP. Must not block
	OnRTPReadStats OnRTPReadStats
}

func (*RTPStatsReader) Read added in v0.10.0 

func (i *RTPStatsReader) Read(b []byte) (int, error)

type RTPStatsWriter added in v0.10.0 

type RTPStatsWriter struct {
	// Writer should be your Writer or any other interceptor RTP writer that is reading audio stream
	Writer     io.Writer
	RTPSession *RTPSession
	// ONRTPWriteStats is fired each time on Read RTP. Must not block
	OnRTPWriteStats OnRTPWriteStats
}

func (*RTPStatsWriter) Write added in v0.10.0 

func (i *RTPStatsWriter) Write(b []byte) (int, error)

type RTPWriteStats 

type RTPWriteStats struct {
	SSRC uint32

	// RTCP stats
	PacketsCount uint64
	OctetCount   uint64
	// contains filtered or unexported fields
}

Some of fields here are exported (as readonly) intentionally

type RTPWriter 

type RTPWriter interface {
	WriteRTP(p *rtp.Packet) error
}

type RTPWriterRaw 

type RTPWriterRaw interface {
	WriteRTPRaw(buf []byte) (int, error) // -> io.Writer
}

Source Files

View all Source files

Directories

Path Synopsis

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.