From 1034f4d97732e3788dc67edae97ca6030b2934c8 Mon Sep 17 00:00:00 2001 From: Onur Gündüz Date: Mon, 16 Feb 2026 06:56:58 +0100 Subject: Improve documentation --- box.go | 4 +- cmd/mfdump/README.md | 68 ------------- cmd/mfdump/main.go | 269 -------------------------------------------------- cmd/mp4dump/README.md | 68 +++++++++++++ cmd/mp4dump/main.go | 269 ++++++++++++++++++++++++++++++++++++++++++++++++++ descriptor.go | 2 +- go.mod | 2 +- iter.go | 2 +- reader.go | 45 ++++++++- scanner.go | 21 ++-- writer.go | 20 +++- 11 files changed, 414 insertions(+), 356 deletions(-) delete mode 100644 cmd/mfdump/README.md delete mode 100644 cmd/mfdump/main.go create mode 100644 cmd/mp4dump/README.md create mode 100644 cmd/mp4dump/main.go diff --git a/box.go b/box.go index 9b56423..464cdc1 100644 --- a/box.go +++ b/box.go @@ -1,5 +1,5 @@ -// Package bmff implements encoding and decoding of ISO Base Media File Format (ISOBMFF) boxes. -package bmff +// Package mp4 implements encoding and decoding of ISO Base Media File Format (ISOBMFF) boxes. +package mp4 // BoxType is a 4-byte box type identifier. type BoxType [4]byte diff --git a/cmd/mfdump/README.md b/cmd/mfdump/README.md deleted file mode 100644 index 770e468..0000000 --- a/cmd/mfdump/README.md +++ /dev/null @@ -1,68 +0,0 @@ -# mfdump - -`mfdump` reads a media file (e.g., MP4) and dumps its box structure in a human-readable format. - -**Example:** - -Pipe the output of `mfdump` to [`indentree`](https://github.com/tetsuo/indentree) to visualize the box hierarchy: - -``` -mfdump "big-buck-bunny-1080p-60fps-30sec.mp4" | indentree -``` - -Output: - -``` -. -├─ [ftyp] size=32 -│ └─ brand=isom ver=512 compat=[isom,iso2,avc1,mp41] -├─ [free] size=8 -├─ [mdat] size=14373924 -│ └─ dataLen=14373916 -└─ [moov] size=49061 - ├─ [mvhd] size=108 v=0 flags=0x000000 timescale=1000 duration=30022 nextTrackId=3 - ├─ [trak] size=36795 - │ ├─ [tkhd] size=92 v=0 flags=0x000003 trackId=1 duration=30000 size=1920x1080 - │ ├─ [edts] size=36 - │ │ └─ [elst] size=28 v=0 flags=0x000000 entries=1 - │ └─ [mdia] size=36659 - │ ├─ [mdhd] size=32 v=0 flags=0x000000 timescale=15360 duration=460800 lang=21956 - │ ├─ [hdlr] size=45 v=0 flags=0x000000 type=vide name="VideoHandler" - │ └─ [minf] size=36574 - │ ├─ [vmhd] size=20 v=0 flags=0x000001 - │ ├─ [dinf] size=36 - │ │ └─ [dref] size=28 v=0 flags=0x000000 entries=1 - │ └─ [stbl] size=36510 - │ ├─ [stsd] size=154 v=0 flags=0x000000 entries=1 - │ │ └─ [avc1] size=138 1920x1080 compressor="" - │ │ └─ [avcC] size=52 codec=64002a - │ ├─ [stts] size=24 v=0 flags=0x000000 entries=1 - │ ├─ [stss] size=48 v=0 flags=0x000000 entries=8 - │ ├─ [ctts] size=13944 v=0 flags=0x000000 entries=1741 - │ ├─ [stsc] size=9472 v=0 flags=0x000000 entries=788 - │ ├─ [stsz] size=7220 v=0 flags=0x000000 entries=1800 - │ └─ [stco] size=5640 v=0 flags=0x000000 entries=1406 - ├─ [trak] size=11756 - │ ├─ [tkhd] size=92 v=0 flags=0x000003 trackId=2 duration=30022 size=0x0 - │ ├─ [edts] size=36 - │ │ └─ [elst] size=28 v=0 flags=0x000000 entries=1 - │ └─ [mdia] size=11620 - │ ├─ [mdhd] size=32 v=0 flags=0x000000 timescale=48000 duration=1441024 lang=21956 - │ ├─ [hdlr] size=45 v=0 flags=0x000000 type=soun name="SoundHandler" - │ └─ [minf] size=11535 - │ ├─ [smhd] size=16 v=0 flags=0x000000 - │ ├─ [dinf] size=36 - │ │ └─ [dref] size=28 v=0 flags=0x000000 entries=1 - │ └─ [stbl] size=11475 - │ ├─ [stsd] size=103 v=0 flags=0x000000 entries=1 - │ │ └─ [mp4a] size=87 ch=2 sampleSize=16 sampleRate=48000 - │ │ └─ [esds] size=51 v=0 flags=0x000000 codec=40.2 - │ ├─ [stts] size=32 v=0 flags=0x000000 entries=2 - │ ├─ [stsc] size=40 v=0 flags=0x000000 entries=2 - │ ├─ [stsz] size=5652 v=0 flags=0x000000 entries=1408 - │ └─ [stco] size=5640 v=0 flags=0x000000 entries=1406 - └─ [udta] size=394 - └─ [meta] size=386 v=0 flags=0x000000 - ├─ [hdlr] size=33 v=0 flags=0x000000 type=mdir name="" - └─ [ilst] size=341 (333 bytes) -``` diff --git a/cmd/mfdump/main.go b/cmd/mfdump/main.go deleted file mode 100644 index 0c813d5..0000000 --- a/cmd/mfdump/main.go +++ /dev/null @@ -1,269 +0,0 @@ -// Command mfdump reads a media file and prints its box structure. -package main - -import ( - "fmt" - "os" - "strings" - - mf "github.com/tetsuo/bmff" -) - -func main() { - if len(os.Args) < 2 { - fmt.Fprintf(os.Stderr, "usage: %s \n", os.Args[0]) - os.Exit(1) - } - - f, err := os.Open(os.Args[1]) - if err != nil { - fmt.Fprintf(os.Stderr, "error opening file: %v\n", err) - os.Exit(1) - } - defer f.Close() - - sc := mf.NewScanner(f) - for sc.Next() { - e := sc.Entry() - fmt.Printf("[%s] size=%d\n", e.Type, e.Size) - - // Only load metadata boxes into memory for deep parsing - if e.Type == mf.TypeMoov || e.Type == mf.TypeMoof { - buf := make([]byte, e.DataSize()) - if err := sc.ReadBody(buf); err != nil { - fmt.Fprintf(os.Stderr, "error reading %s: %v\n", e.Type, err) - continue - } - r := mf.NewReader(buf) - walk(&r, 1) - } else if e.Type == mf.TypeFtyp { - buf := make([]byte, e.DataSize()) - if err := sc.ReadBody(buf); err != nil { - fmt.Fprintf(os.Stderr, "error reading ftyp: %v\n", err) - continue - } - f := mf.ReadFtyp(buf) - fmt.Printf(" brand=%s ver=%d", string(f.MajorBrand[:]), f.MinorVersion) - if len(f.Compatible) > 0 { - fmt.Printf(" compat=[") - for i, c := range f.Compatible { - if i > 0 { - fmt.Printf(",") - } - fmt.Printf("%s", string(c[:])) - } - fmt.Printf("]") - } - fmt.Println() - } else if e.Type == mf.TypeMdat { - fmt.Printf(" dataLen=%d\n", e.DataSize()) - } - } - if err := sc.Err(); err != nil { - fmt.Fprintf(os.Stderr, "scan error: %v\n", err) - os.Exit(1) - } -} - -func walk(r *mf.Reader, depth int) { - for r.Next() { - indent := strings.Repeat(" ", depth) - - fmt.Printf("%s[%s] size=%d", indent, r.Type(), r.Size()) - - if mf.IsFullBox(r.Type()) { - fmt.Printf(" v=%d flags=0x%06x", r.Version(), r.Flags()) - } - - printBoxInfo(r) - fmt.Println() - - // Descend into containers - if mf.IsContainerBox(r.Type()) { - r.Enter() - walk(r, depth+1) - r.Exit() - continue - } - - // Handle stsd: entry count + sub-boxes - if r.Type() == mf.TypeStsd { - r.Enter() - r.Skip(4) // skip entry count - for r.Next() { - printSampleEntry(r, depth+1) - } - r.Exit() - continue - } - } -} - -func printSampleEntry(r *mf.Reader, depth int) { - indent := strings.Repeat(" ", depth) - - switch r.Type() { - case mf.TypeAvc1: - v := mf.ReadVisualSampleEntry(r.Data()) - fmt.Printf("%s[%s] size=%d %dx%d compressor=%q\n", indent, r.Type(), r.Size(), v.Width, v.Height, v.CompressorName) - // Enter to find avcC and other children - r.Enter() - r.Skip(v.ChildOffset) - for r.Next() { - childIndent := strings.Repeat(" ", depth+1) - if mf.IsFullBox(r.Type()) { - fmt.Printf("%s[%s] size=%d v=%d flags=0x%06x", childIndent, r.Type(), r.Size(), r.Version(), r.Flags()) - } else { - fmt.Printf("%s[%s] size=%d", childIndent, r.Type(), r.Size()) - } - if r.Type() == mf.TypeAvcC { - codec := mf.ReadAvcC(r.Data()) - fmt.Printf(" codec=%s", codec) - } - fmt.Println() - } - r.Exit() - - case mf.TypeMp4a: - a := mf.ReadAudioSampleEntry(r.Data()) - fmt.Printf("%s[%s] size=%d ch=%d sampleSize=%d sampleRate=%d\n", indent, r.Type(), r.Size(), a.ChannelCount, a.SampleSize, a.SampleRate>>16) - // Enter to find esds and other children - r.Enter() - r.Skip(a.ChildOffset) - for r.Next() { - childIndent := strings.Repeat(" ", depth+1) - if mf.IsFullBox(r.Type()) { - fmt.Printf("%s[%s] size=%d v=%d flags=0x%06x", childIndent, r.Type(), r.Size(), r.Version(), r.Flags()) - } else { - fmt.Printf("%s[%s] size=%d", childIndent, r.Type(), r.Size()) - } - if r.Type() == mf.TypeEsds { - codec := mf.ReadEsdsCodec(r.Data()) - fmt.Printf(" codec=%s", codec) - } - fmt.Println() - } - r.Exit() - - default: - fmt.Printf("%s[%s] size=%d", indent, r.Type(), r.Size()) - if mf.IsFullBox(r.Type()) { - fmt.Printf(" v=%d flags=0x%06x", r.Version(), r.Flags()) - } - fmt.Printf(" (raw %d bytes)\n", len(r.Data())) - } -} - -func printBoxInfo(r *mf.Reader) { - switch r.Type() { - case mf.TypeFtyp: - f := mf.ReadFtyp(r.Data()) - fmt.Printf(" brand=%s ver=%d", string(f.MajorBrand[:]), f.MinorVersion) - if len(f.Compatible) > 0 { - fmt.Printf(" compat=[") - for i, c := range f.Compatible { - if i > 0 { - fmt.Printf(",") - } - fmt.Printf("%s", string(c[:])) - } - fmt.Printf("]") - } - - case mf.TypeMvhd: - ts, dur, ntid := r.ReadMvhd() - fmt.Printf(" timescale=%d duration=%d nextTrackId=%d", ts, dur, ntid) - - case mf.TypeTkhd: - tid, dur, w, h := r.ReadTkhd() - fmt.Printf(" trackId=%d duration=%d size=%dx%d", tid, dur, w>>16, h>>16) - - case mf.TypeMdhd: - ts, dur, lang := r.ReadMdhd() - fmt.Printf(" timescale=%d duration=%d lang=%d", ts, dur, lang) - - case mf.TypeHdlr: - ht := r.ReadHdlr() - name := r.ReadHdlrName() - fmt.Printf(" type=%s name=%q", string(ht[:]), name) - - case mf.TypeStsd: - if len(r.Data()) >= 4 { - fmt.Printf(" entries=%d", r.EntryCount()) - } - - case mf.TypeStsz: - it := mf.NewStszIter(r.Data()) - fmt.Printf(" entries=%d", it.Count()) - - case mf.TypeStco, mf.TypeStss: - it := mf.NewUint32Iter(r.Data()) - fmt.Printf(" entries=%d", it.Count()) - - case mf.TypeCo64: - it := mf.NewCo64Iter(r.Data()) - fmt.Printf(" entries=%d", it.Count()) - - case mf.TypeStts: - it := mf.NewSttsIter(r.Data()) - fmt.Printf(" entries=%d", it.Count()) - - case mf.TypeCtts: - it := mf.NewCttsIter(r.Data(), r.Version()) - fmt.Printf(" entries=%d", it.Count()) - - case mf.TypeStsc: - it := mf.NewStscIter(r.Data()) - fmt.Printf(" entries=%d", it.Count()) - - case mf.TypeElst: - it := mf.NewElstIter(r.Data(), r.Version()) - fmt.Printf(" entries=%d", it.Count()) - - case mf.TypeDref: - if len(r.Data()) >= 4 { - fmt.Printf(" entries=%d", r.EntryCount()) - } - - case mf.TypeMehd: - dur := r.ReadMehd() - fmt.Printf(" fragmentDuration=%d", dur) - - case mf.TypeTrex: - tid, _, _, _, _ := r.ReadTrex() - fmt.Printf(" trackId=%d", tid) - - case mf.TypeMfhd: - seq := r.ReadMfhd() - fmt.Printf(" seq=%d", seq) - - case mf.TypeTfhd: - tid := r.ReadTfhd() - fmt.Printf(" trackId=%d", tid) - - case mf.TypeTfdt: - bt := r.ReadTfdt() - fmt.Printf(" baseMediaDecodeTime=%d", bt) - - case mf.TypeTrun: - it := mf.NewTrunIter(r.Data(), r.Flags()) - fmt.Printf(" entries=%d", it.Count()) - if r.Flags()&mf.TrunDataOffsetPresent != 0 { - fmt.Printf(" dataOffset=%d", it.DataOffset()) - } - - case mf.TypeMdat: - fmt.Printf(" dataLen=%d", len(r.Data())) - - case mf.TypeVmhd: - // graphicsMode and opcolor - case mf.TypeSmhd: - // balance - default: - if !mf.IsContainerBox(r.Type()) { - if len(r.Data()) > 0 { - fmt.Printf(" (%d bytes)", len(r.Data())) - } - } - } -} diff --git a/cmd/mp4dump/README.md b/cmd/mp4dump/README.md new file mode 100644 index 0000000..ce25882 --- /dev/null +++ b/cmd/mp4dump/README.md @@ -0,0 +1,68 @@ +# mp4dump + +`mp4dump` reads an MP4 file and dumps its box structure in a human-readable format. + +**Example:** + +Pipe the output of `mp4dump` to [`indentree`](https://github.com/tetsuo/indentree) to visualize the box hierarchy: + +``` +mp4dump "big-buck-bunny-1080p-60fps-30sec.mp4" | indentree +``` + +Output: + +``` +. +├─ [ftyp] size=32 +│ └─ brand=isom ver=512 compat=[isom,iso2,avc1,mp41] +├─ [free] size=8 +├─ [mdat] size=14373924 +│ └─ dataLen=14373916 +└─ [moov] size=49061 + ├─ [mvhd] size=108 v=0 flags=0x000000 timescale=1000 duration=30022 nextTrackId=3 + ├─ [trak] size=36795 + │ ├─ [tkhd] size=92 v=0 flags=0x000003 trackId=1 duration=30000 size=1920x1080 + │ ├─ [edts] size=36 + │ │ └─ [elst] size=28 v=0 flags=0x000000 entries=1 + │ └─ [mdia] size=36659 + │ ├─ [mdhd] size=32 v=0 flags=0x000000 timescale=15360 duration=460800 lang=21956 + │ ├─ [hdlr] size=45 v=0 flags=0x000000 type=vide name="VideoHandler" + │ └─ [minf] size=36574 + │ ├─ [vmhd] size=20 v=0 flags=0x000001 + │ ├─ [dinf] size=36 + │ │ └─ [dref] size=28 v=0 flags=0x000000 entries=1 + │ └─ [stbl] size=36510 + │ ├─ [stsd] size=154 v=0 flags=0x000000 entries=1 + │ │ └─ [avc1] size=138 1920x1080 compressor="" + │ │ └─ [avcC] size=52 codec=64002a + │ ├─ [stts] size=24 v=0 flags=0x000000 entries=1 + │ ├─ [stss] size=48 v=0 flags=0x000000 entries=8 + │ ├─ [ctts] size=13944 v=0 flags=0x000000 entries=1741 + │ ├─ [stsc] size=9472 v=0 flags=0x000000 entries=788 + │ ├─ [stsz] size=7220 v=0 flags=0x000000 entries=1800 + │ └─ [stco] size=5640 v=0 flags=0x000000 entries=1406 + ├─ [trak] size=11756 + │ ├─ [tkhd] size=92 v=0 flags=0x000003 trackId=2 duration=30022 size=0x0 + │ ├─ [edts] size=36 + │ │ └─ [elst] size=28 v=0 flags=0x000000 entries=1 + │ └─ [mdia] size=11620 + │ ├─ [mdhd] size=32 v=0 flags=0x000000 timescale=48000 duration=1441024 lang=21956 + │ ├─ [hdlr] size=45 v=0 flags=0x000000 type=soun name="SoundHandler" + │ └─ [minf] size=11535 + │ ├─ [smhd] size=16 v=0 flags=0x000000 + │ ├─ [dinf] size=36 + │ │ └─ [dref] size=28 v=0 flags=0x000000 entries=1 + │ └─ [stbl] size=11475 + │ ├─ [stsd] size=103 v=0 flags=0x000000 entries=1 + │ │ └─ [mp4a] size=87 ch=2 sampleSize=16 sampleRate=48000 + │ │ └─ [esds] size=51 v=0 flags=0x000000 codec=40.2 + │ ├─ [stts] size=32 v=0 flags=0x000000 entries=2 + │ ├─ [stsc] size=40 v=0 flags=0x000000 entries=2 + │ ├─ [stsz] size=5652 v=0 flags=0x000000 entries=1408 + │ └─ [stco] size=5640 v=0 flags=0x000000 entries=1406 + └─ [udta] size=394 + └─ [meta] size=386 v=0 flags=0x000000 + ├─ [hdlr] size=33 v=0 flags=0x000000 type=mdir name="" + └─ [ilst] size=341 (333 bytes) +``` diff --git a/cmd/mp4dump/main.go b/cmd/mp4dump/main.go new file mode 100644 index 0000000..ee7a577 --- /dev/null +++ b/cmd/mp4dump/main.go @@ -0,0 +1,269 @@ +// Command mp4dump reads an MP4 file and prints its box structure. +package main + +import ( + "fmt" + "os" + "strings" + + "github.com/tetsuo/mp4" +) + +func main() { + if len(os.Args) < 2 { + fmt.Fprintf(os.Stderr, "usage: %s \n", os.Args[0]) + os.Exit(1) + } + + f, err := os.Open(os.Args[1]) + if err != nil { + fmt.Fprintf(os.Stderr, "error opening file: %v\n", err) + os.Exit(1) + } + defer f.Close() + + sc := mp4.NewScanner(f) + for sc.Next() { + e := sc.Entry() + fmt.Printf("[%s] size=%d\n", e.Type, e.Size) + + // Only load metadata boxes into memory for deep parsing + if e.Type == mp4.TypeMoov || e.Type == mp4.TypeMoof { + buf := make([]byte, e.DataSize()) + if err := sc.ReadBody(buf); err != nil { + fmt.Fprintf(os.Stderr, "error reading %s: %v\n", e.Type, err) + continue + } + r := mp4.NewReader(buf) + walk(&r, 1) + } else if e.Type == mp4.TypeFtyp { + buf := make([]byte, e.DataSize()) + if err := sc.ReadBody(buf); err != nil { + fmt.Fprintf(os.Stderr, "error reading ftyp: %v\n", err) + continue + } + f := mp4.ReadFtyp(buf) + fmt.Printf(" brand=%s ver=%d", string(f.MajorBrand[:]), f.MinorVersion) + if len(f.Compatible) > 0 { + fmt.Printf(" compat=[") + for i, c := range f.Compatible { + if i > 0 { + fmt.Printf(",") + } + fmt.Printf("%s", string(c[:])) + } + fmt.Printf("]") + } + fmt.Println() + } else if e.Type == mp4.TypeMdat { + fmt.Printf(" dataLen=%d\n", e.DataSize()) + } + } + if err := sc.Err(); err != nil { + fmt.Fprintf(os.Stderr, "scan error: %v\n", err) + os.Exit(1) + } +} + +func walk(r *mp4.Reader, depth int) { + for r.Next() { + indent := strings.Repeat(" ", depth) + + fmt.Printf("%s[%s] size=%d", indent, r.Type(), r.Size()) + + if mp4.IsFullBox(r.Type()) { + fmt.Printf(" v=%d flags=0x%06x", r.Version(), r.Flags()) + } + + printBoxInfo(r) + fmt.Println() + + // Descend into containers + if mp4.IsContainerBox(r.Type()) { + r.Enter() + walk(r, depth+1) + r.Exit() + continue + } + + // Handle stsd: entry count + sub-boxes + if r.Type() == mp4.TypeStsd { + r.Enter() + r.Skip(4) // skip entry count + for r.Next() { + printSampleEntry(r, depth+1) + } + r.Exit() + continue + } + } +} + +func printSampleEntry(r *mp4.Reader, depth int) { + indent := strings.Repeat(" ", depth) + + switch r.Type() { + case mp4.TypeAvc1: + v := mp4.ReadVisualSampleEntry(r.Data()) + fmt.Printf("%s[%s] size=%d %dx%d compressor=%q\n", indent, r.Type(), r.Size(), v.Width, v.Height, v.CompressorName) + // Enter to find avcC and other children + r.Enter() + r.Skip(v.ChildOffset) + for r.Next() { + childIndent := strings.Repeat(" ", depth+1) + if mp4.IsFullBox(r.Type()) { + fmt.Printf("%s[%s] size=%d v=%d flags=0x%06x", childIndent, r.Type(), r.Size(), r.Version(), r.Flags()) + } else { + fmt.Printf("%s[%s] size=%d", childIndent, r.Type(), r.Size()) + } + if r.Type() == mp4.TypeAvcC { + codec := mp4.ReadAvcC(r.Data()) + fmt.Printf(" codec=%s", codec) + } + fmt.Println() + } + r.Exit() + + case mp4.TypeMp4a: + a := mp4.ReadAudioSampleEntry(r.Data()) + fmt.Printf("%s[%s] size=%d ch=%d sampleSize=%d sampleRate=%d\n", indent, r.Type(), r.Size(), a.ChannelCount, a.SampleSize, a.SampleRate>>16) + // Enter to find esds and other children + r.Enter() + r.Skip(a.ChildOffset) + for r.Next() { + childIndent := strings.Repeat(" ", depth+1) + if mp4.IsFullBox(r.Type()) { + fmt.Printf("%s[%s] size=%d v=%d flags=0x%06x", childIndent, r.Type(), r.Size(), r.Version(), r.Flags()) + } else { + fmt.Printf("%s[%s] size=%d", childIndent, r.Type(), r.Size()) + } + if r.Type() == mp4.TypeEsds { + codec := mp4.ReadEsdsCodec(r.Data()) + fmt.Printf(" codec=%s", codec) + } + fmt.Println() + } + r.Exit() + + default: + fmt.Printf("%s[%s] size=%d", indent, r.Type(), r.Size()) + if mp4.IsFullBox(r.Type()) { + fmt.Printf(" v=%d flags=0x%06x", r.Version(), r.Flags()) + } + fmt.Printf(" (raw %d bytes)\n", len(r.Data())) + } +} + +func printBoxInfo(r *mp4.Reader) { + switch r.Type() { + case mp4.TypeFtyp: + f := mp4.ReadFtyp(r.Data()) + fmt.Printf(" brand=%s ver=%d", string(f.MajorBrand[:]), f.MinorVersion) + if len(f.Compatible) > 0 { + fmt.Printf(" compat=[") + for i, c := range f.Compatible { + if i > 0 { + fmt.Printf(",") + } + fmt.Printf("%s", string(c[:])) + } + fmt.Printf("]") + } + + case mp4.TypeMvhd: + ts, dur, ntid := r.ReadMvhd() + fmt.Printf(" timescale=%d duration=%d nextTrackId=%d", ts, dur, ntid) + + case mp4.TypeTkhd: + tid, dur, w, h := r.ReadTkhd() + fmt.Printf(" trackId=%d duration=%d size=%dx%d", tid, dur, w>>16, h>>16) + + case mp4.TypeMdhd: + ts, dur, lang := r.ReadMdhd() + fmt.Printf(" timescale=%d duration=%d lang=%d", ts, dur, lang) + + case mp4.TypeHdlr: + ht := r.ReadHdlr() + name := r.ReadHdlrName() + fmt.Printf(" type=%s name=%q", string(ht[:]), name) + + case mp4.TypeStsd: + if len(r.Data()) >= 4 { + fmt.Printf(" entries=%d", r.EntryCount()) + } + + case mp4.TypeStsz: + it := mp4.NewStszIter(r.Data()) + fmt.Printf(" entries=%d", it.Count()) + + case mp4.TypeStco, mp4.TypeStss: + it := mp4.NewUint32Iter(r.Data()) + fmt.Printf(" entries=%d", it.Count()) + + case mp4.TypeCo64: + it := mp4.NewCo64Iter(r.Data()) + fmt.Printf(" entries=%d", it.Count()) + + case mp4.TypeStts: + it := mp4.NewSttsIter(r.Data()) + fmt.Printf(" entries=%d", it.Count()) + + case mp4.TypeCtts: + it := mp4.NewCttsIter(r.Data(), r.Version()) + fmt.Printf(" entries=%d", it.Count()) + + case mp4.TypeStsc: + it := mp4.NewStscIter(r.Data()) + fmt.Printf(" entries=%d", it.Count()) + + case mp4.TypeElst: + it := mp4.NewElstIter(r.Data(), r.Version()) + fmt.Printf(" entries=%d", it.Count()) + + case mp4.TypeDref: + if len(r.Data()) >= 4 { + fmt.Printf(" entries=%d", r.EntryCount()) + } + + case mp4.TypeMehd: + dur := r.ReadMehd() + fmt.Printf(" fragmentDuration=%d", dur) + + case mp4.TypeTrex: + tid, _, _, _, _ := r.ReadTrex() + fmt.Printf(" trackId=%d", tid) + + case mp4.TypeMfhd: + seq := r.ReadMfhd() + fmt.Printf(" seq=%d", seq) + + case mp4.TypeTfhd: + tid := r.ReadTfhd() + fmt.Printf(" trackId=%d", tid) + + case mp4.TypeTfdt: + bt := r.ReadTfdt() + fmt.Printf(" baseMediaDecodeTime=%d", bt) + + case mp4.TypeTrun: + it := mp4.NewTrunIter(r.Data(), r.Flags()) + fmt.Printf(" entries=%d", it.Count()) + if r.Flags()&mp4.TrunDataOffsetPresent != 0 { + fmt.Printf(" dataOffset=%d", it.DataOffset()) + } + + case mp4.TypeMdat: + fmt.Printf(" dataLen=%d", len(r.Data())) + + case mp4.TypeVmhd: + // graphicsMode and opcolor + case mp4.TypeSmhd: + // balance + default: + if !mp4.IsContainerBox(r.Type()) { + if len(r.Data()) > 0 { + fmt.Printf(" (%d bytes)", len(r.Data())) + } + } + } +} diff --git a/descriptor.go b/descriptor.go index 8e82769..746bec1 100644 --- a/descriptor.go +++ b/descriptor.go @@ -1,4 +1,4 @@ -package bmff +package mp4 import "strconv" diff --git a/go.mod b/go.mod index 08daf7d..4b0b7a2 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,3 @@ -module github.com/tetsuo/bmff +module github.com/tetsuo/mp4 go 1.25.5 diff --git a/iter.go b/iter.go index 8389156..2ec0e1f 100644 --- a/iter.go +++ b/iter.go @@ -1,4 +1,4 @@ -package bmff +package mp4 import ( "encoding/binary" diff --git a/reader.go b/reader.go index d7f6b3f..c197882 100644 --- a/reader.go +++ b/reader.go @@ -1,4 +1,4 @@ -package bmff +package mp4 // maxDepth limits the reader/writer nesting stack. const maxDepth = 16 @@ -9,7 +9,48 @@ type readerFrame struct { boxEnd int // position to resume after exiting this container } -// Reader provides streaming parsing of ISOBMFF boxes. +// Reader provides hierarchical, in-memory parsing of box data. After loading +// a box's bytes (e.g., from Scanner), create a Reader to iterate children, +// descend into containers, and extract typed fields. +// +// Iterating over top-level boxes: +// +// r := mp4.NewReader(buf) +// for r.Next() { +// fmt.Printf("box: %s size: %d\n", r.Type(), r.Size()) +// } +// +// For container boxes, use Enter/Exit to descend into children: +// +// for r.Next() { +// if r.Type() == mp4.TypeMoov { +// r.Enter() // descend into moov +// for r.Next() { // iterate moov children +// // process trak, mvhd, etc. +// } +// r.Exit() // return to top level +// } +// } +// +// Some boxes have an entry count before child boxes (stsd, dref). +// Use Skip(4) after Enter to skip past the count field: +// +// r.Enter() +// r.Skip(4) // skip entry count +// for r.Next() { +// // process entries +// } +// r.Exit() +// +// Sample entry boxes have fixed-size headers before child boxes. +// Use Skip with the header size (avc1=78, mp4a=28): +// +// r.Enter() +// r.Skip(78) // skip avc1 fixed header +// for r.Next() { +// // process avcC, pasp, etc. +// } +// r.Exit() type Reader struct { buf []byte pos int // next position to parse from diff --git a/scanner.go b/scanner.go index 30c3098..4169f1f 100644 --- a/scanner.go +++ b/scanner.go @@ -1,4 +1,4 @@ -package bmff +package mp4 import "io" @@ -15,21 +15,26 @@ func (e ScanEntry) DataSize() int64 { return e.Size - int64(e.HeaderSize) } -// Scanner reads top-level box headers from an io.ReadSeeker without -// loading box contents into memory. This lets callers discover box -// positions and sizes, then selectively read only the boxes they need -// (e.g. moov) into a buffer for parsing with NewReader. +// DataOffset returns the byte offset where the box data begins (after the header). +// Use it with [io.ReaderAt.ReadAt] to read box data without seeking. +func (e ScanEntry) DataOffset() int64 { + return e.Offset + int64(e.HeaderSize) +} + +// Scanner reads top-level box headers from an [io.ReadSeeker] without loading +// box contents into memory. Use it to discover box positions and sizes, then +// selectively read only the boxes you need. // // Typical usage: // // f, _ := os.Open("video.mp4") -// sc := bmff.NewScanner(f) +// sc := mp4.NewScanner(f) // for sc.Next() { // e := sc.Entry() -// if e.Type == bmff.TypeMoov { +// if e.Type == mp4.TypeMoov { // buf := make([]byte, e.DataSize()) // sc.ReadBody(buf) -// r := bmff.NewReader(buf) +// r := mp4.NewReader(buf) // // parse moov contents... // } // } diff --git a/writer.go b/writer.go index 8c57e19..3bb111d 100644 --- a/writer.go +++ b/writer.go @@ -1,4 +1,4 @@ -package bmff +package mp4 import "errors" @@ -10,6 +10,21 @@ type writerFrame struct { // ErrBoxTooLarge is returned by [Writer.Err] when a box exceeds the 4 GB // limit for standard (32-bit) box sizes. var ErrBoxTooLarge = errors.New("mp4: box size exceeds 4GB limit") + +// Writer encodes ISOBMFF boxes into the provided buffer. +// +// The buffer must be large enough to hold all written data; writes beyond +// the buffer boundary will panic. +// +// Use [Writer.StartBox] and [Writer.EndBox] to write nested boxes: +// +// w := mp4.NewWriter(buf) +// w.StartBox(mp4.TypeMoov) +// w.WriteMvhd(1000, 30000, 3) +// w.EndBox() +// output := w.Bytes() +// +// After all writes, check [Writer.Err] for errors. type Writer struct { buf []byte pos int @@ -414,9 +429,6 @@ func (w *Writer) WriteTfdt(baseMediaDecodeTime uint64) { w.StartFullBox(TypeTfdt, 0, 0) w.putUint32(uint32(baseMediaDecodeTime)) } - // TODO: maybe always use version 1 (64-bit)? - // w.StartFullBox(TypeTfdt, 1, 0) - // w.putUint64(baseMediaDecodeTime) w.EndBox() } -- cgit v1.3.1