zishuo/webrtc
1
0
Fork 0
mirror of https://github.com/pion/webrtc.git synced 2025-10-05 23:26:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

Overhaul the samplebuilder docs

Browse Source 
Use complete sentences, with periods.
Explain all parameters.
Cross-reference other useful packages.
This commit is contained in:
Josh Bleecher Snyder
2020-06-07 13:50:09 -07:00
committed by Sean DuBois
parent 30f2dbd150
commit feed5e66cb
1 changed files with 17 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
pkg/media/samplebuilder/samplebuilder.go
View File

@@ -1,4 +1,4 @@
// Package samplebuilder provides functionality to reconstruct media frame from RTP packets // Package samplebuilder provides functionality to reconstruct media frames from RTP packets.
package samplebuilder package samplebuilder
import ( import (
@@ -6,11 +6,9 @@ import (
"github.com/pion/webrtc/v2/pkg/media" "github.com/pion/webrtc/v2/pkg/media"
) )
// SampleBuilder contains all packets // SampleBuilder buffers packets until media frames are complete.
// maxLate determines how long we should wait until we get a valid Sample
// The larger the value the less packet loss you will see, but higher latency
type SampleBuilder struct { type SampleBuilder struct {
maxLate uint16 maxLate uint16 // how many packets to wait until we get a valid Sample
buffer [65536]*rtp.Packet buffer [65536]*rtp.Packet
// Interface that allows us to take RTP packets to samples // Interface that allows us to take RTP packets to samples
@@ -30,7 +28,12 @@ type SampleBuilder struct {
partitionHeadChecker rtp.PartitionHeadChecker partitionHeadChecker rtp.PartitionHeadChecker
} }
// New constructs a new SampleBuilder // New constructs a new SampleBuilder.
// maxLate is how long to wait until we can construct a completed media.Sample.
// maxLate is measured in RTP packet sequence numbers.
// A large maxLate will result in less packet loss but higher latency.
// The depacketizer extracts media samples from RTP packets.
// Several depacketizers are available in package github.com/pion/rtp/codecs.
func New(maxLate uint16, depacketizer rtp.Depacketizer, opts ...Option) *SampleBuilder { func New(maxLate uint16, depacketizer rtp.Depacketizer, opts ...Option) *SampleBuilder {
s := &SampleBuilder{maxLate: maxLate, depacketizer: depacketizer} s := &SampleBuilder{maxLate: maxLate, depacketizer: depacketizer}
for _, o := range opts { for _, o := range opts {
@@ -39,7 +42,7 @@ func New(maxLate uint16, depacketizer rtp.Depacketizer, opts ...Option) *SampleB
return s return s
} }
// Push adds a RTP Packet to the sample builder // Push adds an RTP Packet to s's buffer.
func (s *SampleBuilder) Push(p *rtp.Packet) { func (s *SampleBuilder) Push(p *rtp.Packet) {
s.buffer[p.SequenceNumber] = p s.buffer[p.SequenceNumber] = p
s.lastPush = p.SequenceNumber s.lastPush = p.SequenceNumber
@@ -94,14 +97,15 @@ func seqnumDistance(x, y uint16) uint16 {
return uint16(diff) return uint16(diff)
} }
// Pop scans buffer for valid samples, returns nil when no valid samples have been found // Pop scans s's buffer for a valid sample.
// It returns nil if no valid samples have been found.
func (s *SampleBuilder) Pop() *media.Sample { func (s *SampleBuilder) Pop() *media.Sample {
sample, _ := s.PopWithTimestamp() sample, _ := s.PopWithTimestamp()
return sample return sample
} }
// PopWithTimestamp scans buffer for valid samples and its RTP timestamp, // PopWithTimestamp scans s's buffer for a valid sample and its RTP timestamp.
// returns nil, 0 when no valid samples have been found // It returns nil, 0 when no valid samples have been found.
func (s *SampleBuilder) PopWithTimestamp() (*media.Sample, uint32) { func (s *SampleBuilder) PopWithTimestamp() (*media.Sample, uint32) {
var i uint16 var i uint16
if !s.isContiguous { if !s.isContiguous {
@@ -142,10 +146,11 @@ func (s *SampleBuilder) PopWithTimestamp() (*media.Sample, uint32) {
return nil, 0 return nil, 0
} }
// Option configures SampleBuilder // An Option configures a SampleBuilder.
type Option func(o *SampleBuilder) type Option func(o *SampleBuilder)
// WithPartitionHeadChecker assigns codec specific PartitionHeadChecker to SampleBuilder // WithPartitionHeadChecker assigns a codec-specific PartitionHeadChecker to SampleBuilder.
// Several PartitionHeadCheckers are available in package github.com/pion/rtp/codecs.
func WithPartitionHeadChecker(checker rtp.PartitionHeadChecker) Option { func WithPartitionHeadChecker(checker rtp.PartitionHeadChecker) Option {
return func(o *SampleBuilder) { return func(o *SampleBuilder) {
o.partitionHeadChecker = checker o.partitionHeadChecker = checker