aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-02-16 06:56:58 +0100
committerOnur Gündüz <ogunduz@gmail.com>2026-02-16 06:56:58 +0100
commit1034f4d97732e3788dc67edae97ca6030b2934c8 (patch)
tree3270deaf4d7fa89ea0cb763ac9d0d7e9b258fd80
parent7366f91c9a735b16c70dfc2c5c65ba6651497ecc (diff)
downloadmp4-1034f4d97732e3788dc67edae97ca6030b2934c8.tar.gz
mp4-1034f4d97732e3788dc67edae97ca6030b2934c8.zip
Improve documentation
-rw-r--r--box.go4
-rw-r--r--cmd/mp4dump/README.md (renamed from cmd/mfdump/README.md)8
-rw-r--r--cmd/mp4dump/main.go (renamed from cmd/mfdump/main.go)118
-rw-r--r--descriptor.go2
-rw-r--r--go.mod2
-rw-r--r--iter.go2
-rw-r--r--reader.go45
-rw-r--r--scanner.go21
-rw-r--r--writer.go20
9 files changed, 140 insertions, 82 deletions
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/mp4dump/README.md
index 770e468..ce25882 100644
--- a/cmd/mfdump/README.md
+++ b/cmd/mp4dump/README.md
@@ -1,13 +1,13 @@
-# mfdump
+# mp4dump
-`mfdump` reads a media file (e.g., MP4) and dumps its box structure in a human-readable format.
+`mp4dump` reads an MP4 file 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:
+Pipe the output of `mp4dump` to [`indentree`](https://github.com/tetsuo/indentree) to visualize the box hierarchy:
```
-mfdump "big-buck-bunny-1080p-60fps-30sec.mp4" | indentree
+mp4dump "big-buck-bunny-1080p-60fps-30sec.mp4" | indentree
```
Output:
diff --git a/cmd/mfdump/main.go b/cmd/mp4dump/main.go
index 0c813d5..ee7a577 100644
--- a/cmd/mfdump/main.go
+++ b/cmd/mp4dump/main.go
@@ -1,4 +1,4 @@
-// Command mfdump reads a media file and prints its box structure.
+// Command mp4dump reads an MP4 file and prints its box structure.
package main
import (
@@ -6,7 +6,7 @@ import (
"os"
"strings"
- mf "github.com/tetsuo/bmff"
+ "github.com/tetsuo/mp4"
)
func main() {
@@ -22,27 +22,27 @@ func main() {
}
defer f.Close()
- sc := mf.NewScanner(f)
+ 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 == mf.TypeMoov || e.Type == mf.TypeMoof {
+ 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 := mf.NewReader(buf)
+ r := mp4.NewReader(buf)
walk(&r, 1)
- } else if e.Type == mf.TypeFtyp {
+ } 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 := mf.ReadFtyp(buf)
+ f := mp4.ReadFtyp(buf)
fmt.Printf(" brand=%s ver=%d", string(f.MajorBrand[:]), f.MinorVersion)
if len(f.Compatible) > 0 {
fmt.Printf(" compat=[")
@@ -55,7 +55,7 @@ func main() {
fmt.Printf("]")
}
fmt.Println()
- } else if e.Type == mf.TypeMdat {
+ } else if e.Type == mp4.TypeMdat {
fmt.Printf(" dataLen=%d\n", e.DataSize())
}
}
@@ -65,13 +65,13 @@ func main() {
}
}
-func walk(r *mf.Reader, depth int) {
+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 mf.IsFullBox(r.Type()) {
+ if mp4.IsFullBox(r.Type()) {
fmt.Printf(" v=%d flags=0x%06x", r.Version(), r.Flags())
}
@@ -79,7 +79,7 @@ func walk(r *mf.Reader, depth int) {
fmt.Println()
// Descend into containers
- if mf.IsContainerBox(r.Type()) {
+ if mp4.IsContainerBox(r.Type()) {
r.Enter()
walk(r, depth+1)
r.Exit()
@@ -87,7 +87,7 @@ func walk(r *mf.Reader, depth int) {
}
// Handle stsd: entry count + sub-boxes
- if r.Type() == mf.TypeStsd {
+ if r.Type() == mp4.TypeStsd {
r.Enter()
r.Skip(4) // skip entry count
for r.Next() {
@@ -99,46 +99,46 @@ func walk(r *mf.Reader, depth int) {
}
}
-func printSampleEntry(r *mf.Reader, depth int) {
+func printSampleEntry(r *mp4.Reader, depth int) {
indent := strings.Repeat(" ", depth)
switch r.Type() {
- case mf.TypeAvc1:
- v := mf.ReadVisualSampleEntry(r.Data())
+ 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 mf.IsFullBox(r.Type()) {
+ 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() == mf.TypeAvcC {
- codec := mf.ReadAvcC(r.Data())
+ if r.Type() == mp4.TypeAvcC {
+ codec := mp4.ReadAvcC(r.Data())
fmt.Printf(" codec=%s", codec)
}
fmt.Println()
}
r.Exit()
- case mf.TypeMp4a:
- a := mf.ReadAudioSampleEntry(r.Data())
+ 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 mf.IsFullBox(r.Type()) {
+ 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() == mf.TypeEsds {
- codec := mf.ReadEsdsCodec(r.Data())
+ if r.Type() == mp4.TypeEsds {
+ codec := mp4.ReadEsdsCodec(r.Data())
fmt.Printf(" codec=%s", codec)
}
fmt.Println()
@@ -147,17 +147,17 @@ func printSampleEntry(r *mf.Reader, depth int) {
default:
fmt.Printf("%s[%s] size=%d", indent, r.Type(), r.Size())
- if mf.IsFullBox(r.Type()) {
+ 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 *mf.Reader) {
+func printBoxInfo(r *mp4.Reader) {
switch r.Type() {
- case mf.TypeFtyp:
- f := mf.ReadFtyp(r.Data())
+ 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=[")
@@ -170,97 +170,97 @@ func printBoxInfo(r *mf.Reader) {
fmt.Printf("]")
}
- case mf.TypeMvhd:
+ case mp4.TypeMvhd:
ts, dur, ntid := r.ReadMvhd()
fmt.Printf(" timescale=%d duration=%d nextTrackId=%d", ts, dur, ntid)
- case mf.TypeTkhd:
+ 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 mf.TypeMdhd:
+ case mp4.TypeMdhd:
ts, dur, lang := r.ReadMdhd()
fmt.Printf(" timescale=%d duration=%d lang=%d", ts, dur, lang)
- case mf.TypeHdlr:
+ case mp4.TypeHdlr:
ht := r.ReadHdlr()
name := r.ReadHdlrName()
fmt.Printf(" type=%s name=%q", string(ht[:]), name)
- case mf.TypeStsd:
+ case mp4.TypeStsd:
if len(r.Data()) >= 4 {
fmt.Printf(" entries=%d", r.EntryCount())
}
- case mf.TypeStsz:
- it := mf.NewStszIter(r.Data())
+ case mp4.TypeStsz:
+ it := mp4.NewStszIter(r.Data())
fmt.Printf(" entries=%d", it.Count())
- case mf.TypeStco, mf.TypeStss:
- it := mf.NewUint32Iter(r.Data())
+ case mp4.TypeStco, mp4.TypeStss:
+ it := mp4.NewUint32Iter(r.Data())
fmt.Printf(" entries=%d", it.Count())
- case mf.TypeCo64:
- it := mf.NewCo64Iter(r.Data())
+ case mp4.TypeCo64:
+ it := mp4.NewCo64Iter(r.Data())
fmt.Printf(" entries=%d", it.Count())
- case mf.TypeStts:
- it := mf.NewSttsIter(r.Data())
+ case mp4.TypeStts:
+ it := mp4.NewSttsIter(r.Data())
fmt.Printf(" entries=%d", it.Count())
- case mf.TypeCtts:
- it := mf.NewCttsIter(r.Data(), r.Version())
+ case mp4.TypeCtts:
+ it := mp4.NewCttsIter(r.Data(), r.Version())
fmt.Printf(" entries=%d", it.Count())
- case mf.TypeStsc:
- it := mf.NewStscIter(r.Data())
+ case mp4.TypeStsc:
+ it := mp4.NewStscIter(r.Data())
fmt.Printf(" entries=%d", it.Count())
- case mf.TypeElst:
- it := mf.NewElstIter(r.Data(), r.Version())
+ case mp4.TypeElst:
+ it := mp4.NewElstIter(r.Data(), r.Version())
fmt.Printf(" entries=%d", it.Count())
- case mf.TypeDref:
+ case mp4.TypeDref:
if len(r.Data()) >= 4 {
fmt.Printf(" entries=%d", r.EntryCount())
}
- case mf.TypeMehd:
+ case mp4.TypeMehd:
dur := r.ReadMehd()
fmt.Printf(" fragmentDuration=%d", dur)
- case mf.TypeTrex:
+ case mp4.TypeTrex:
tid, _, _, _, _ := r.ReadTrex()
fmt.Printf(" trackId=%d", tid)
- case mf.TypeMfhd:
+ case mp4.TypeMfhd:
seq := r.ReadMfhd()
fmt.Printf(" seq=%d", seq)
- case mf.TypeTfhd:
+ case mp4.TypeTfhd:
tid := r.ReadTfhd()
fmt.Printf(" trackId=%d", tid)
- case mf.TypeTfdt:
+ case mp4.TypeTfdt:
bt := r.ReadTfdt()
fmt.Printf(" baseMediaDecodeTime=%d", bt)
- case mf.TypeTrun:
- it := mf.NewTrunIter(r.Data(), r.Flags())
+ case mp4.TypeTrun:
+ it := mp4.NewTrunIter(r.Data(), r.Flags())
fmt.Printf(" entries=%d", it.Count())
- if r.Flags()&mf.TrunDataOffsetPresent != 0 {
+ if r.Flags()&mp4.TrunDataOffsetPresent != 0 {
fmt.Printf(" dataOffset=%d", it.DataOffset())
}
- case mf.TypeMdat:
+ case mp4.TypeMdat:
fmt.Printf(" dataLen=%d", len(r.Data()))
- case mf.TypeVmhd:
+ case mp4.TypeVmhd:
// graphicsMode and opcolor
- case mf.TypeSmhd:
+ case mp4.TypeSmhd:
// balance
default:
- if !mf.IsContainerBox(r.Type()) {
+ 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()
}