zishuo/webrtc
1
0
Fork 0
mirror of https://github.com/pion/webrtc.git synced 2025-10-05 15:16:52 +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
import (
@@ -6,11 +6,9 @@ import (
"github.com/pion/webrtc/v2/pkg/media"
)
// SampleBuilder contains all packets
// 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
// SampleBuilder buffers packets until media frames are complete.
type SampleBuilder struct {
maxLate uint16
maxLate uint16 // how many packets to wait until we get a valid Sample
buffer [65536]*rtp.Packet
// Interface that allows us to take RTP packets to samples
@@ -30,7 +28,12 @@ type SampleBuilder struct {
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 {
s := &SampleBuilder{maxLate: maxLate, depacketizer: depacketizer}
for _, o := range opts {
@@ -39,7 +42,7 @@ func New(maxLate uint16, depacketizer rtp.Depacketizer, opts ...Option) *SampleB
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) {
s.buffer[p.SequenceNumber] = p
s.lastPush = p.SequenceNumber
@@ -94,14 +97,15 @@ func seqnumDistance(x, y uint16) uint16 {
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 {
sample, _ := s.PopWithTimestamp()
return sample
}
// PopWithTimestamp scans buffer for valid samples and its RTP timestamp,
// returns nil, 0 when no valid samples have been found
// PopWithTimestamp scans s's buffer for a valid sample and its RTP timestamp.
// It returns nil, 0 when no valid samples have been found.
func (s *SampleBuilder) PopWithTimestamp() (*media.Sample, uint32) {
var i uint16
if !s.isContiguous {
@@ -142,10 +146,11 @@ func (s *SampleBuilder) PopWithTimestamp() (*media.Sample, uint32) {
return nil, 0
}
// Option configures SampleBuilder
// An Option configures a 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 {
return func(o *SampleBuilder) {
o.partitionHeadChecker = checker