aboutsummaryrefslogtreecommitdiff
path: root/fragment
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-09-15 00:07:06 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-09-15 00:07:06 +0200
commitd2b3cde2cff3cdfc0cf435e91fad6d40cbc8e85e (patch)
treee4293a705a3151646bff7a849ebff6b4583fa31f /fragment
parent6216b2ed1fcd0b06a9e0b3ae74e5373a8cccd114 (diff)
downloadmp4-d2b3cde2cff3cdfc0cf435e91fad6d40cbc8e85e.tar.gz
mp4-d2b3cde2cff3cdfc0cf435e91fad6d40cbc8e85e.zip
fragment: parse packaged media segments
Diffstat (limited to 'fragment')
-rw-r--r--fragment/parse.go169
-rw-r--r--fragment/parse_test.go142
2 files changed, 311 insertions, 0 deletions
diff --git a/fragment/parse.go b/fragment/parse.go
new file mode 100644
index 0000000..0276852
--- /dev/null
+++ b/fragment/parse.go
@@ -0,0 +1,169 @@
+package fragment
+
+import (
+ "encoding/binary"
+ "errors"
+ "fmt"
+
+ "github.com/tetsuo/mp4"
+ "github.com/tetsuo/mp4/track"
+)
+
+// ErrNoSamples is returned by ParseSegment when the data holds no moof with
+// samples.
+var ErrNoSamples = errors.New("fragment: segment has no samples")
+
+// sampleIsNonSync is the bit in a sample's flags that marks it as not a sync
+// sample (ISO/IEC 14496-12, sample_is_non_sync_sample).
+const sampleIsNonSync = 0x00010000
+
+// ParseSegment reads a packaged CMAF media segment back into its samples: any
+// leading boxes (styp, sidx) are skipped and every moof's track runs are
+// decoded, so a segment holding several moof+mdat pairs (low-latency parts)
+// parses as one flat sample list. Each sample's Offset is its absolute byte
+// position in data, so data itself serves as the [Writer]'s source when the
+// samples are re-packaged. The returned sequence number is the first moof's.
+//
+// The parser covers the layout this package's [Writer] produces (per-traf
+// tfdt, data offsets relative to the moof start or an explicit base) and
+// validates that every sample's bytes lie inside data.
+func ParseSegment(data []byte) ([]track.Sample, uint32, error) {
+ var (
+ samples []track.Sample
+ seq uint32
+ seqSet bool
+ )
+ r := mp4.NewReader(data)
+ for r.Next() {
+ if r.Type() != mp4.TypeMoof {
+ continue
+ }
+ moofStart := int64(r.Offset())
+ r.Enter()
+ for r.Next() {
+ switch r.Type() {
+ case mp4.TypeMfhd:
+ if !seqSet {
+ seq = r.ReadMfhd()
+ seqSet = true
+ }
+ case mp4.TypeTraf:
+ var err error
+ samples, err = parseTraf(&r, len(data), moofStart, samples)
+ if err != nil {
+ return nil, 0, err
+ }
+ }
+ }
+ r.Exit()
+ }
+ if len(samples) == 0 {
+ return nil, 0, ErrNoSamples
+ }
+ return samples, seq, nil
+}
+
+// parseTraf decodes one traf's samples and appends them to samples. r is
+// positioned on the traf box; dataLen bounds the sample byte ranges.
+func parseTraf(r *mp4.Reader, dataLen int, moofStart int64, samples []track.Sample) ([]track.Sample, error) {
+ var (
+ trackID uint32
+ baseOffset = moofStart
+ defDuration uint32
+ defSize uint32
+ defFlags uint32
+ dts int64
+ )
+ r.Enter()
+ defer r.Exit()
+ for r.Next() {
+ switch r.Type() {
+ case mp4.TypeTfhd:
+ d := r.Data()
+ fl := r.Flags()
+ if len(d) < 4 {
+ return nil, errors.New("fragment: short tfhd")
+ }
+ trackID = binary.BigEndian.Uint32(d)
+ p := 4
+ if fl&mp4.TfhdBaseDataOffsetPresent != 0 {
+ if len(d) < p+8 {
+ return nil, errors.New("fragment: short tfhd")
+ }
+ baseOffset = int64(binary.BigEndian.Uint64(d[p:]))
+ p += 8
+ }
+ if fl&mp4.TfhdSampleDescriptionIndexPresent != 0 {
+ p += 4
+ }
+ if fl&mp4.TfhdDefaultSampleDurationPresent != 0 {
+ if len(d) < p+4 {
+ return nil, errors.New("fragment: short tfhd")
+ }
+ defDuration = binary.BigEndian.Uint32(d[p:])
+ p += 4
+ }
+ if fl&mp4.TfhdDefaultSampleSizePresent != 0 {
+ if len(d) < p+4 {
+ return nil, errors.New("fragment: short tfhd")
+ }
+ defSize = binary.BigEndian.Uint32(d[p:])
+ p += 4
+ }
+ if fl&mp4.TfhdDefaultSampleFlagsPresent != 0 {
+ if len(d) < p+4 {
+ return nil, errors.New("fragment: short tfhd")
+ }
+ defFlags = binary.BigEndian.Uint32(d[p:])
+ }
+ case mp4.TypeTfdt:
+ dts = int64(r.ReadTfdt())
+ case mp4.TypeTrun:
+ flags := r.Flags()
+ if flags&mp4.TrunDataOffsetPresent == 0 {
+ return nil, errors.New("fragment: trun without data offset")
+ }
+ it := mp4.NewTrunIter(r.Data(), flags)
+ off := baseOffset + int64(it.DataOffset())
+ first := true
+ for {
+ e, ok := it.Next()
+ if !ok {
+ break
+ }
+ dur := e.Duration
+ if flags&mp4.TrunSampleDurationPresent == 0 {
+ dur = defDuration
+ }
+ size := e.Size
+ if flags&mp4.TrunSampleSizePresent == 0 {
+ size = defSize
+ }
+ sflags := e.Flags
+ if flags&mp4.TrunSampleFlagsPresent == 0 {
+ sflags = defFlags
+ if first && flags&mp4.TrunFirstSampleFlagsPresent != 0 {
+ sflags = it.FirstSampleFlags()
+ }
+ }
+ if off < 0 || off+int64(size) > int64(dataLen) {
+ return nil, fmt.Errorf("fragment: sample bytes [%d, %d) outside segment of %d bytes",
+ off, off+int64(size), dataLen)
+ }
+ sm := track.Sample{
+ Offset: off,
+ DTS: dts,
+ TrackID: trackID,
+ Duration: dur,
+ PresentationOffset: e.CompositionTimeOffset,
+ }
+ sm.SetSize(size, sflags&sampleIsNonSync == 0)
+ samples = append(samples, sm)
+ off += int64(size)
+ dts += int64(dur)
+ first = false
+ }
+ }
+ }
+ return samples, nil
+}
diff --git a/fragment/parse_test.go b/fragment/parse_test.go
new file mode 100644
index 0000000..80f3f62
--- /dev/null
+++ b/fragment/parse_test.go
@@ -0,0 +1,142 @@
+package fragment
+
+import (
+ "bytes"
+ "testing"
+
+ "github.com/tetsuo/mp4"
+ "github.com/tetsuo/mp4/track"
+)
+
+// buildSamples returns a two-track sample set laid over a synthetic data
+// buffer: four video samples (a sync sample, then three with composition
+// offsets) and five audio samples. Offsets index into the returned data.
+func buildSamples() ([]track.Sample, []byte) {
+ var data []byte
+ var samples []track.Sample
+ add := func(trackID uint32, dts int64, dur uint32, cts int32, sync bool, size int) {
+ sm := track.Sample{
+ Offset: int64(len(data)),
+ DTS: dts,
+ TrackID: trackID,
+ Duration: dur,
+ PresentationOffset: cts,
+ }
+ sm.SetSize(uint32(size), sync)
+ samples = append(samples, sm)
+ for range size {
+ data = append(data, byte(len(data)))
+ }
+ }
+ add(1, 9000, 3000, 0, true, 500)
+ add(1, 12000, 3000, 6000, false, 120)
+ add(1, 15000, 3000, 3000, false, 80)
+ add(1, 18000, 3000, 0, false, 90)
+ for i := range 5 {
+ add(2, 4800+int64(i)*1024, 1024, 0, true, 60+i)
+ }
+ return samples, data
+}
+
+// sampleBytes returns the sample's bytes out of src.
+func sampleBytes(src []byte, s track.Sample) []byte {
+ return src[s.Offset : s.Offset+int64(s.Size())]
+}
+
+// TestParseSegmentRoundTrip writes a fragment with the Writer and parses it
+// back, proving every field and every sample byte survives, including when a
+// styp box precedes the moof as in a packaged segment.
+func TestParseSegmentRoundTrip(t *testing.T) {
+ samples, src := buildSamples()
+
+ var seg bytes.Buffer
+ hdr := mp4.NewWriter(make([]byte, 64))
+ hdr.WriteStyp([4]byte{'m', 's', 'd', 'h'}, 0, [][4]byte{{'m', 's', 'd', 'h'}})
+ seg.Write(hdr.Bytes())
+
+ w := NewWriter(&seg)
+ if err := w.WriteFragment(&Fragment{Samples: samples, SequenceNum: 7}, bytes.NewReader(src)); err != nil {
+ t.Fatal(err)
+ }
+
+ got, seq, err := ParseSegment(seg.Bytes())
+ if err != nil {
+ t.Fatal(err)
+ }
+ if seq != 7 {
+ t.Fatalf("sequence %d, want 7", seq)
+ }
+ if len(got) != len(samples) {
+ t.Fatalf("%d samples, want %d", len(got), len(samples))
+ }
+ // The writer groups samples by track in first-appearance order, which is
+ // already the order buildSamples emits, so the lists align index by index.
+ for i, want := range samples {
+ g := got[i]
+ if g.TrackID != want.TrackID || g.DTS != want.DTS || g.Duration != want.Duration ||
+ g.PresentationOffset != want.PresentationOffset || g.Size() != want.Size() || g.IsSync() != want.IsSync() {
+ t.Fatalf("sample %d: got %+v (size %d sync %v), want %+v (size %d sync %v)",
+ i, g, g.Size(), g.IsSync(), want, want.Size(), want.IsSync())
+ }
+ if !bytes.Equal(sampleBytes(seg.Bytes(), g), sampleBytes(src, want)) {
+ t.Fatalf("sample %d bytes differ", i)
+ }
+ }
+}
+
+// TestParseSegmentMultiMoof proves a segment holding several moof+mdat pairs
+// (the low-latency parts layout) parses into the concatenated sample list.
+func TestParseSegmentMultiMoof(t *testing.T) {
+ samples, src := buildSamples()
+ var seg bytes.Buffer
+ w := NewWriter(&seg)
+ if err := w.WriteFragment(&Fragment{Samples: samples[:4], SequenceNum: 1}, bytes.NewReader(src)); err != nil {
+ t.Fatal(err)
+ }
+ w.Reset(&seg)
+ if err := w.WriteFragment(&Fragment{Samples: samples[4:], SequenceNum: 2}, bytes.NewReader(src)); err != nil {
+ t.Fatal(err)
+ }
+
+ got, seq, err := ParseSegment(seg.Bytes())
+ if err != nil {
+ t.Fatal(err)
+ }
+ if seq != 1 {
+ t.Fatalf("sequence %d, want the first moof's 1", seq)
+ }
+ if len(got) != len(samples) {
+ t.Fatalf("%d samples, want %d", len(got), len(samples))
+ }
+ for i, want := range samples {
+ g := got[i]
+ if g.TrackID != want.TrackID || g.DTS != want.DTS || g.Size() != want.Size() {
+ t.Fatalf("sample %d: got %+v, want %+v", i, g, want)
+ }
+ if !bytes.Equal(sampleBytes(seg.Bytes(), g), sampleBytes(src, want)) {
+ t.Fatalf("sample %d bytes differ", i)
+ }
+ }
+}
+
+// TestParseSegmentRejectsGarbage proves the parser reports empty and
+// truncated inputs rather than fabricating samples.
+func TestParseSegmentRejectsGarbage(t *testing.T) {
+ if _, _, err := ParseSegment(nil); err == nil {
+ t.Fatal("nil input parsed")
+ }
+ if _, _, err := ParseSegment([]byte("not an mp4 segment")); err == nil {
+ t.Fatal("garbage parsed")
+ }
+
+ samples, src := buildSamples()
+ var seg bytes.Buffer
+ w := NewWriter(&seg)
+ if err := w.WriteFragment(&Fragment{Samples: samples, SequenceNum: 1}, bytes.NewReader(src)); err != nil {
+ t.Fatal(err)
+ }
+ // Truncating the mdat leaves trun entries pointing past the end.
+ if _, _, err := ParseSegment(seg.Bytes()[:seg.Len()-40]); err == nil {
+ t.Fatal("truncated segment parsed")
+ }
+}