aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-06-30 17:12:12 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-06-30 17:12:12 +0200
commitc56d4fa173d3a851a1ebb4a2d27684669e699630 (patch)
treeb176914225419cb4f708f5fc352af16d50b408b8
parent0f5c3761970cdf122da63a2454dfcce545ab357c (diff)
downloadmp4-c56d4fa173d3a851a1ebb4a2d27684669e699630.tar.gz
mp4-c56d4fa173d3a851a1ebb4a2d27684669e699630.zip
fragment: add streaming MP4 fragmentation
-rw-r--r--fragment/benchmark_test.go128
-rw-r--r--fragment/reader.go656
-rw-r--r--fragment/reader_test.go320
-rw-r--r--fragment/writer.go362
-rw-r--r--track/track.go9
5 files changed, 1474 insertions, 1 deletions
diff --git a/fragment/benchmark_test.go b/fragment/benchmark_test.go
new file mode 100644
index 0000000..b3ca832
--- /dev/null
+++ b/fragment/benchmark_test.go
@@ -0,0 +1,128 @@
+package fragment_test
+
+import (
+ "io"
+ "testing"
+
+ "github.com/tetsuo/mp4/fragment"
+ "github.com/tetsuo/mp4/track"
+)
+
+func BenchmarkNewReader(b *testing.B) {
+ f := openTestFile(b)
+ defer f.Close()
+
+ b.ReportAllocs()
+ for b.Loop() {
+ f.Seek(0, io.SeekStart)
+ if _, _, err := fragment.NewReader(f); err != nil {
+ b.Fatal(err)
+ }
+ }
+}
+
+func BenchmarkReaderReset(b *testing.B) {
+ f := openTestFile(b)
+ defer f.Close()
+
+ r, _, err := fragment.NewReader(f)
+ if err != nil {
+ b.Fatal(err)
+ }
+
+ b.ReportAllocs()
+ for b.Loop() {
+ f.Seek(0, io.SeekStart)
+ if _, err := r.Reset(f); err != nil {
+ b.Fatal(err)
+ }
+ }
+}
+
+func BenchmarkReadWriteFragments(b *testing.B) {
+ f := openTestFile(b)
+ defer f.Close()
+
+ info, err := f.Stat()
+ if err != nil {
+ b.Fatal(err)
+ }
+
+ w := fragment.NewWriter(io.Discard)
+
+ b.SetBytes(info.Size())
+ b.ReportAllocs()
+ for b.Loop() {
+ f.Seek(0, io.SeekStart)
+ frag, initSeg, err := fragment.NewReader(f)
+ if err != nil {
+ b.Fatal(err)
+ }
+
+ w.Reset(io.Discard)
+ if err := w.WriteInit(initSeg); err != nil {
+ b.Fatal(err)
+ }
+
+ for {
+ fr, err := frag.ReadFragment()
+ if err == io.EOF {
+ break
+ }
+ if err != nil {
+ b.Fatal(err)
+ }
+ if err := w.WriteFragment(fr, f); err != nil {
+ b.Fatal(err)
+ }
+ }
+ }
+}
+
+func BenchmarkWriteFragmentsOnly(b *testing.B) {
+ f := openTestFile(b)
+ defer f.Close()
+
+ info, err := f.Stat()
+ if err != nil {
+ b.Fatal(err)
+ }
+
+ frag, initSeg, err := fragment.NewReader(f)
+ if err != nil {
+ b.Fatal(err)
+ }
+
+ var frags []*fragment.Fragment
+ for {
+ fr, err := frag.ReadFragment()
+ if err == io.EOF {
+ break
+ }
+ if err != nil {
+ b.Fatal(err)
+ }
+ samples := make([]track.Sample, len(fr.Samples))
+ copy(samples, fr.Samples)
+ frags = append(frags, &fragment.Fragment{
+ Samples: samples,
+ SequenceNum: fr.SequenceNum,
+ })
+ }
+
+ w := fragment.NewWriter(io.Discard)
+
+ b.SetBytes(info.Size())
+ b.ReportAllocs()
+ for b.Loop() {
+ w.Reset(io.Discard)
+ if err := w.WriteInit(initSeg); err != nil {
+ b.Fatal(err)
+ }
+ for _, fr := range frags {
+ if err := w.WriteFragment(fr, f); err != nil {
+ b.Fatal(err)
+ }
+ }
+ }
+}
diff --git a/fragment/reader.go b/fragment/reader.go
new file mode 100644
index 0000000..ee12524
--- /dev/null
+++ b/fragment/reader.go
@@ -0,0 +1,656 @@
+// Package fragment provides streaming MP4 fragmentation.
+//
+// It reads a standard MP4 file and produces fragmented MP4 (fMP4)
+// segments suitable for adaptive streaming protocols like HLS and DASH.
+//
+// Basic usage:
+//
+// reader, initSeg, err := fragment.NewReader(file)
+// if err != nil { ... }
+//
+// writer := fragment.NewWriter(output)
+// writer.WriteInit(initSeg)
+//
+// for {
+// frag, err := reader.ReadFragment()
+// if err == io.EOF { break }
+// if err != nil { ... }
+// writer.WriteFragment(frag, file)
+// }
+//
+// The [Reader] parses the moov box on construction and produces
+// an [InitSegment] containing the ftyp+moov.
+// Subsequent calls to [Reader.ReadFragment] produce fragments
+// containing moof+mdat box pairs.
+//
+// Use [Reader.SetTimeRange] to limit output to a specific time window,
+// or [Reader.Seek] to reposition to a different time.
+package fragment
+
+import (
+ "errors"
+ "io"
+ "sort"
+
+ "github.com/tetsuo/mp4"
+ "github.com/tetsuo/mp4/track"
+)
+
+var (
+ // ErrNoMoov is returned when the input file has no moov box.
+ ErrNoMoov = errors.New("moov box not found")
+ // ErrNoPlayableTracks is returned when no video or audio tracks are found.
+ ErrNoPlayableTracks = errors.New("no playable tracks found")
+ // ErrMoovTooLarge is returned when the moov box exceeds the size limit.
+ ErrMoovTooLarge = errors.New("moov box exceeds size limit")
+ // ErrInvalidTimeRange is returned when an invalid time range is specified.
+ ErrInvalidTimeRange = errors.New("invalid time range")
+ // ErrReaderNotInitialized is returned when ReadFragment or Seek is called before initialization.
+ ErrReaderNotInitialized = errors.New("reader not initialized")
+ // ErrNoVideoTrack is returned when no video track is found in the init segment.
+ ErrNoVideoTrack = errors.New("no video track")
+ // ErrInvalidDuration is returned when a non-positive target duration is set.
+ ErrInvalidDuration = errors.New("invalid target duration")
+)
+
+const (
+ // DefaultMaxMoovSize is the default limit for moov box size (50 MB).
+ DefaultMaxMoovSize = 50 << 20
+
+ // minFragmentDuration is the minimum fragment duration in seconds.
+ // Fragments shorter than this will be merged with the next fragment
+ // (unless a sync point forces a break).
+ minFragmentDuration = 1
+
+ // maxTracks is the maximum number of concurrent tracks supported.
+ // Limited to 4 to keep per-track arrays on the stack and avoid
+ // heap allocations in the hot path.
+ maxTracks = 4
+
+ // movieTimescale is the timescale written into the init segment's mvhd.
+ movieTimescale = 1000
+)
+
+// InitSegment holds parsed initialization data (ftyp+moov) for a fragmented MP4.
+type InitSegment struct {
+ Tracks []*track.Track
+ Duration uint64
+ buf []byte
+}
+
+// VideoTrack returns the first video track, or nil.
+func (s *InitSegment) VideoTrack() *track.Track {
+ for _, t := range s.Tracks {
+ if t.Kind == track.TrackVideo {
+ return t
+ }
+ }
+ return nil
+}
+
+// AudioTrack returns the first audio track, or nil.
+func (s *InitSegment) AudioTrack() *track.Track {
+ for _, t := range s.Tracks {
+ if t.Kind == track.TrackAudio {
+ return t
+ }
+ }
+ return nil
+}
+
+// Bytes returns the serialized init segment (ftyp+moov).
+func (s *InitSegment) Bytes() []byte {
+ return s.buf
+}
+
+// Fragment represents samples for one moof+mdat pair.
+//
+// Returned by [Reader.ReadFragment]; valid until the next ReadFragment call.
+// Copy Samples if you need to retain the data.
+type Fragment struct {
+ Samples []track.Sample
+ SequenceNum uint32
+}
+
+// Reader reads a standard MP4 file and produces fragmented MP4 segments.
+type Reader struct {
+ rs io.ReadSeeker
+ sc mp4.Scanner
+ initSeg *InitSegment // points to initSegStorage once initialized
+
+ trackIdx [maxTracks]int
+ dtsBase [maxTracks]int64
+ dtsBaseSet [maxTracks]bool
+ trackCount int
+ videoTrackID uint32
+
+ videoRun [2]int // last fragment's video sample range [start, end)
+ audioRun [2]int // last fragment's audio sample range [start, end)
+
+ sequenceNum uint32
+ startTime float64
+ endTime float64
+ targetDuration float64
+
+ frag Fragment
+ fragSamples []track.Sample
+
+ allTracks []*track.Track
+ moovBuf []byte
+ initBuf []byte
+
+ initSegStorage InitSegment // reused backing for the returned init segment
+ filtered []*track.Track // reused backing for initSegStorage.Tracks
+}
+
+// NewReader creates a new fragment reader. It parses the moov box from
+// the provided reader and builds the init segment for fragmented MP4 output.
+// The returned [InitSegment] contains the serialized ftyp+moov and the parsed
+// track information.
+func NewReader(rs io.ReadSeeker) (*Reader, *InitSegment, error) {
+ f := &Reader{rs: rs, targetDuration: minFragmentDuration}
+ initSeg, err := f.readInit()
+ if err != nil {
+ return nil, nil, err
+ }
+ return f, initSeg, nil
+}
+
+// Reset reinitializes the Reader to read from rs, keeping the moov, init, and
+// sample-window buffers allocated for a previous file. It parses the moov box
+// and returns a fresh init segment, like NewReader. The InitSegment and
+// Fragment returned by an earlier call must not be used after Reset.
+func (f *Reader) Reset(rs io.ReadSeeker) (*InitSegment, error) {
+ *f = Reader{
+ rs: rs,
+ allTracks: f.allTracks,
+ moovBuf: f.moovBuf[:0],
+ initBuf: f.initBuf[:0],
+ fragSamples: f.fragSamples[:0],
+ filtered: f.filtered[:0],
+ targetDuration: f.targetDuration,
+ }
+ return f.readInit()
+}
+
+// SetTimeRange sets the start and end time (in seconds) for reading.
+// An end time of 0 means read to the end of the file.
+//
+// Returns [ErrInvalidTimeRange] if start or end are negative, or if
+// end is non-zero and less than or equal to start.
+//
+// SetTimeRange may be called at any time to change the range; it
+// reinitializes the internal track positions.
+func (f *Reader) SetTimeRange(startTime, endTime float64) error {
+ if startTime < 0 || endTime < 0 {
+ return ErrInvalidTimeRange
+ }
+ if endTime > 0 && startTime >= endTime {
+ return ErrInvalidTimeRange
+ }
+ f.startTime = startTime
+ f.endTime = endTime
+ f.initTrackIndices()
+ return nil
+}
+
+// SetTargetDuration sets the minimum segment duration in seconds. Each call to
+// ReadFragment runs until the first sync sample at or after this duration. The
+// default is one second.
+func (f *Reader) SetTargetDuration(seconds float64) error {
+ if seconds <= 0 {
+ return ErrInvalidDuration
+ }
+ f.targetDuration = seconds
+ return nil
+}
+
+// readInit parses the moov box and builds the init segment.
+func (f *Reader) readInit() (*InitSegment, error) {
+ if f.initSeg != nil {
+ return f.initSeg, nil
+ }
+
+ moovBuf, err := f.findMoov()
+ if err != nil {
+ return nil, err
+ }
+
+ tracks, duration, err := track.ParseTracksInto(f.allTracks, moovBuf)
+ if err != nil {
+ return nil, err
+ }
+ f.allTracks = tracks
+
+ // Filter to first video + first audio only.
+ f.filtered = f.filtered[:0]
+ hasVideo, hasAudio := false, false
+ for _, t := range tracks {
+ if t.Kind == track.TrackVideo && !hasVideo {
+ f.filtered = append(f.filtered, t)
+ hasVideo = true
+ } else if t.Kind == track.TrackAudio && !hasAudio {
+ f.filtered = append(f.filtered, t)
+ hasAudio = true
+ }
+ }
+ if len(f.filtered) == 0 {
+ return nil, ErrNoPlayableTracks
+ }
+
+ initSeg := &f.initSegStorage
+ initSeg.Tracks = f.filtered
+ initSeg.Duration = duration
+ initSeg.buf = f.buildInitSegment(initSeg.Tracks, initSeg.Duration)
+
+ f.initSeg = initSeg
+ f.trackCount = len(initSeg.Tracks)
+ f.sequenceNum = 1
+
+ if vt := initSeg.VideoTrack(); vt != nil {
+ f.videoTrackID = vt.ID
+ }
+
+ f.initTrackIndices()
+ return initSeg, nil
+}
+
+func (f *Reader) initTrackIndices() {
+ f.dtsBaseSet = [maxTracks]bool{}
+ f.dtsBase = [maxTracks]int64{}
+
+ videoTrack := f.initSeg.VideoTrack()
+ var videoStartPTS int64
+
+ for i, t := range f.initSeg.Tracks {
+ if t.Kind == track.TrackVideo && f.startTime > 0 {
+ idx := f.findSampleAfter(t, f.startTime)
+ n := len(t.Samples)
+
+ if f.endTime > 0 && idx < n {
+ endTimeScaled := int64(f.endTime * float64(t.TimeScale))
+ if t.Samples[idx].PTS() >= endTimeScaled {
+ idx = f.findSampleBefore(t, f.startTime)
+ }
+ }
+
+ f.trackIdx[i] = idx
+ if idx < n {
+ videoStartPTS = t.Samples[idx].PTS()
+ }
+ } else if t.Kind == track.TrackVideo {
+ f.trackIdx[i] = 0
+ }
+ }
+
+ for i, t := range f.initSeg.Tracks {
+ if t.Kind == track.TrackVideo {
+ continue
+ }
+ if f.startTime > 0 && videoTrack != nil {
+ audioStartTicks := videoStartPTS * int64(t.TimeScale) / int64(videoTrack.TimeScale)
+ idx := sort.Search(len(t.Samples), func(j int) bool {
+ return t.Samples[j].PTS() >= audioStartTicks
+ })
+ f.trackIdx[i] = idx
+ } else {
+ f.trackIdx[i] = 0
+ }
+ }
+}
+
+func (f *Reader) findSampleAfter(track *track.Track, timeSeconds float64) int {
+ scaledTime := int64(timeSeconds * float64(track.TimeScale))
+ n := len(track.Samples)
+ idx := sort.Search(n, func(i int) bool {
+ return track.Samples[i].PTS() >= scaledTime
+ })
+ if idx >= n {
+ return n - 1
+ }
+ for idx < n && !track.Samples[idx].IsSync() {
+ idx++
+ }
+ if idx >= n {
+ return n - 1
+ }
+ return idx
+}
+
+func (f *Reader) findSampleBefore(track *track.Track, timeSeconds float64) int {
+ scaledTime := int64(timeSeconds * float64(track.TimeScale))
+ n := len(track.Samples)
+ idx := max(sort.Search(n, func(i int) bool {
+ return track.Samples[i].PTS() > scaledTime
+ })-1, 0)
+ for idx > 0 && !track.Samples[idx].IsSync() {
+ idx--
+ }
+ return idx
+}
+
+func (f *Reader) getTrackIndex(trackID uint32) int {
+ for i, track := range f.initSeg.Tracks {
+ if track.ID == trackID {
+ return i
+ }
+ }
+ return -1
+}
+
+// appendSample adds a sample with DTS rebased relative to the first sample per track.
+func (f *Reader) appendSample(trackIdx int, s track.Sample) {
+ if !f.dtsBaseSet[trackIdx] {
+ f.dtsBase[trackIdx] = s.DTS
+ f.dtsBaseSet[trackIdx] = true
+ }
+ s.DTS -= f.dtsBase[trackIdx]
+ f.fragSamples = append(f.fragSamples, s)
+}
+
+// ReadFragment returns the next fragment.
+// Returns [io.EOF] when there are no more fragments to read.
+func (f *Reader) ReadFragment() (*Fragment, error) {
+ if f.initSeg == nil {
+ return nil, ErrReaderNotInitialized
+ }
+
+ videoTrack := f.initSeg.VideoTrack()
+ if videoTrack == nil {
+ return nil, ErrNoVideoTrack
+ }
+
+ videoTrackIdx := f.getTrackIndex(videoTrack.ID)
+ videoSampleIdx := f.trackIdx[videoTrackIdx]
+
+ if videoSampleIdx >= len(videoTrack.Samples) {
+ return nil, io.EOF
+ }
+
+ var endTimeScaled int64
+ if f.endTime > 0 {
+ endTimeScaled = int64(f.endTime * float64(videoTrack.TimeScale))
+ }
+
+ if endTimeScaled > 0 && videoTrack.Samples[videoSampleIdx].PTS() >= endTimeScaled {
+ return nil, io.EOF
+ }
+
+ startDTS := videoTrack.Samples[videoSampleIdx].DTS
+ threshold := int64(f.targetDuration * float64(videoTrack.TimeScale))
+ lastVideoIdx := videoSampleIdx
+
+ for lastVideoIdx < len(videoTrack.Samples) {
+ s := videoTrack.Samples[lastVideoIdx]
+ if endTimeScaled > 0 && s.PTS() >= endTimeScaled {
+ break
+ }
+ if endTimeScaled == 0 && lastVideoIdx > videoSampleIdx && s.IsSync() {
+ if s.DTS-startDTS >= threshold {
+ break
+ }
+ }
+ lastVideoIdx++
+ }
+
+ if lastVideoIdx == videoSampleIdx {
+ return nil, io.EOF
+ }
+
+ f.videoRun = [2]int{videoSampleIdx, lastVideoIdx}
+ f.audioRun = [2]int{}
+
+ var audioStart [maxTracks]int
+ var audioEnd [maxTracks]int
+ need := lastVideoIdx - videoSampleIdx
+
+ fragStartPTS := videoTrack.Samples[videoSampleIdx].PTS()
+ var fragEndPTS int64
+ if lastVideoIdx < len(videoTrack.Samples) {
+ fragEndPTS = videoTrack.Samples[lastVideoIdx].PTS()
+ } else {
+ lastSample := videoTrack.Samples[lastVideoIdx-1]
+ fragEndPTS = lastSample.DTS + int64(lastSample.Duration)
+ }
+
+ for i, t := range f.initSeg.Tracks {
+ if t.Kind == track.TrackVideo {
+ continue
+ }
+ startTicks := fragStartPTS * int64(t.TimeScale) / int64(videoTrack.TimeScale)
+ endTicks := fragEndPTS * int64(t.TimeScale) / int64(videoTrack.TimeScale)
+ idx := f.trackIdx[i]
+ n := len(t.Samples)
+ for idx < n && t.Samples[idx].PTS() < startTicks {
+ idx++
+ }
+ audioStart[i] = idx
+ for idx < n && t.Samples[idx].PTS() < endTicks {
+ idx++
+ }
+ audioEnd[i] = idx
+ if t.Kind == track.TrackAudio {
+ f.audioRun = [2]int{audioStart[i], audioEnd[i]}
+ }
+ need += idx - audioStart[i]
+ }
+
+ if cap(f.fragSamples) < need {
+ f.fragSamples = make([]track.Sample, 0, need)
+ }
+ f.fragSamples = f.fragSamples[:0]
+
+ // Append video samples
+ for i := videoSampleIdx; i < lastVideoIdx; i++ {
+ f.appendSample(videoTrackIdx, videoTrack.Samples[i])
+ }
+ f.trackIdx[videoTrackIdx] = lastVideoIdx
+
+ for i, t := range f.initSeg.Tracks {
+ if t.Kind == track.TrackVideo {
+ continue
+ }
+ // Append audio samples
+ for j := audioStart[i]; j < audioEnd[i]; j++ {
+ f.appendSample(i, t.Samples[j])
+ }
+ f.trackIdx[i] = audioEnd[i]
+ }
+
+ f.frag.Samples = f.fragSamples
+ f.frag.SequenceNum = f.sequenceNum
+ f.sequenceNum++
+ return &f.frag, nil
+}
+
+// VideoRun returns the video track's sample range [start, end) in the most
+// recent fragment returned by ReadFragment.
+func (f *Reader) VideoRun() (start, end int) {
+ return f.videoRun[0], f.videoRun[1]
+}
+
+// AudioRun returns the audio track's sample range [start, end) in the most
+// recent fragment, or (0, 0) when there is no audio track.
+func (f *Reader) AudioRun() (start, end int) {
+ return f.audioRun[0], f.audioRun[1]
+}
+
+// Seek repositions reading to the given time (in seconds).
+// The next ReadFragment call will produce a fragment starting at or
+// near the requested time (snapped to the nearest sync point).
+func (f *Reader) Seek(timeSeconds float64) error {
+ if f.initSeg == nil {
+ return ErrReaderNotInitialized
+ }
+ f.startTime = timeSeconds
+ f.initTrackIndices()
+ return nil
+}
+
+// findMoov scans for the moov box and returns its raw bytes.
+func (f *Reader) findMoov() ([]byte, error) {
+ maxSize := int64(DefaultMaxMoovSize)
+
+ if _, err := f.rs.Seek(0, io.SeekStart); err != nil {
+ return nil, err
+ }
+
+ f.sc.Reset(f.rs)
+ for f.sc.Next() {
+ e := f.sc.Entry()
+ if e.Type != mp4.TypeMoov {
+ continue
+ }
+ if e.Size > maxSize {
+ return nil, ErrMoovTooLarge
+ }
+ if e.Size > int64(^uint(0)>>1) {
+ return nil, ErrMoovTooLarge
+ }
+ needed := int(e.Size)
+ if cap(f.moovBuf) < needed {
+ f.moovBuf = make([]byte, needed)
+ }
+ buf := f.moovBuf[:needed]
+ if err := f.sc.ReadBox(buf); err != nil {
+ return nil, err
+ }
+ return buf, nil
+ }
+
+ if err := f.sc.Err(); err != nil {
+ return nil, err
+ }
+ return nil, ErrNoMoov
+}
+
+// buildInitSegment constructs ftyp+moov for fragmented MP4.
+func (f *Reader) buildInitSegment(tracks []*track.Track, duration uint64) []byte {
+ estSize := 256
+ for _, track := range tracks {
+ estSize += 256 + len(track.HdlrRaw()) + len(track.DinfRaw()) + len(track.StsdRaw()) + len(track.TkhdRaw()) + len(track.MdhdRaw())
+ }
+
+ if cap(f.initBuf) < estSize {
+ f.initBuf = make([]byte, estSize)
+ }
+ buf := f.initBuf[:estSize]
+ w := mp4.NewWriter(buf)
+
+ w.WriteFtyp([4]byte{'i', 's', 'o', '5'}, 0,
+ [][4]byte{{'i', 's', 'o', '5'}, {'a', 'v', 'c', '1'}})
+
+ w.StartBox(mp4.TypeMoov)
+ {
+ w.WriteMvhd(movieTimescale, 0, uint32(len(tracks)+1))
+
+ for _, track := range tracks {
+ writeInitTrak(&w, track)
+ }
+
+ w.StartBox(mp4.TypeMvex)
+ {
+ w.WriteMehd(duration)
+ for _, track := range tracks {
+ w.WriteTrex(track.ID, track.SampleDescIdx, 0, 0, 0)
+ }
+ }
+ w.EndBox()
+ }
+ w.EndBox()
+
+ return w.Bytes()
+}
+
+func writeInitTrak(w *mp4.Writer, track *track.Track) {
+ w.StartBox(mp4.TypeTrak)
+ {
+ writeTkhdZeroDuration(w, track)
+
+ if mt, ok := track.EditMediaTime(); ok && track.TimeScale > 0 {
+ segDur := track.Duration * movieTimescale / uint64(track.TimeScale)
+ w.StartBox(mp4.TypeEdts)
+ w.WriteElst([]mp4.ElstEntry{{
+ SegmentDuration: segDur,
+ MediaTime: mt,
+ MediaRateInt: 1,
+ }})
+ w.EndBox()
+ }
+
+ w.StartBox(mp4.TypeMdia)
+ {
+ writeMdhdZeroDuration(w, track)
+
+ if track.HdlrRaw() != nil {
+ w.Write(track.HdlrRaw())
+ }
+
+ w.StartBox(mp4.TypeMinf)
+ {
+ if track.HasVmhd() {
+ w.WriteVmhd()
+ } else {
+ w.WriteSmhd()
+ }
+
+ if track.HasDinf() && track.DinfRaw() != nil {
+ w.Write(track.DinfRaw())
+ } else {
+ w.StartBox(mp4.TypeDinf)
+ w.WriteDref()
+ w.EndBox()
+ }
+
+ w.StartBox(mp4.TypeStbl)
+ {
+ if track.StsdRaw() != nil {
+ w.Write(track.StsdRaw())
+ }
+ w.WriteStts(nil)
+ w.WriteStsc(nil)
+ w.WriteStsz(0, nil)
+ w.WriteStco(nil)
+ }
+ w.EndBox()
+ }
+ w.EndBox()
+ }
+ w.EndBox()
+ }
+ w.EndBox()
+}
+
+func writeTkhdZeroDuration(w *mp4.Writer, track *track.Track) {
+ data := track.TkhdRaw()
+ if data == nil {
+ return
+ }
+ w.StartFullBox(mp4.TypeTkhd, track.TkhdVersion(), track.TkhdFlags())
+ start := w.Len()
+ w.Write(data)
+ out := w.Bytes()[start : start+len(data)]
+ if track.TkhdVersion() == 1 {
+ clear(out[24:32])
+ } else {
+ clear(out[16:20])
+ }
+ w.EndBox()
+}
+
+func writeMdhdZeroDuration(w *mp4.Writer, track *track.Track) {
+ data := track.MdhdRaw()
+ if data == nil {
+ return
+ }
+ w.StartFullBox(mp4.TypeMdhd, track.MdhdVersion(), 0)
+ start := w.Len()
+ w.Write(data)
+ out := w.Bytes()[start : start+len(data)]
+ if track.MdhdVersion() == 1 {
+ clear(out[20:28])
+ } else {
+ clear(out[12:16])
+ }
+ w.EndBox()
+}
diff --git a/fragment/reader_test.go b/fragment/reader_test.go
new file mode 100644
index 0000000..96dddaf
--- /dev/null
+++ b/fragment/reader_test.go
@@ -0,0 +1,320 @@
+package fragment_test
+
+import (
+ "io"
+ "os"
+ "reflect"
+ "testing"
+
+ "github.com/tetsuo/mp4"
+ "github.com/tetsuo/mp4/fragment"
+)
+
+const testFile = "../video-media-samples/big-buck-bunny-480p-30sec.mp4"
+
+func openTestFile(t testing.TB) *os.File {
+ t.Helper()
+ f, err := os.Open(testFile)
+ if err != nil {
+ t.Skipf("test file not available: %v", err)
+ }
+ return f
+}
+
+func TestNewReader(t *testing.T) {
+ f := openTestFile(t)
+ defer f.Close()
+
+ _, initSeg, err := fragment.NewReader(f)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ if len(initSeg.Tracks) != 2 {
+ t.Fatalf("expected 2 tracks, got %d", len(initSeg.Tracks))
+ }
+
+ vt := initSeg.VideoTrack()
+ if vt == nil {
+ t.Fatal("no video track")
+ }
+ if vt.Codec() != "avc1.64001e" {
+ t.Errorf("video codec = %q, want avc1.64001e", vt.Codec())
+ }
+ if vt.Width != 854 || vt.Height != 480 {
+ t.Errorf("video size = %dx%d, want 854x480", vt.Width, vt.Height)
+ }
+ if vt.TimeScale != 12288 {
+ t.Errorf("video timescale = %d, want 12288", vt.TimeScale)
+ }
+
+ at := initSeg.AudioTrack()
+ if at == nil {
+ t.Fatal("no audio track")
+ }
+ if at.Codec() != "mp4a.40.2" {
+ t.Errorf("audio codec = %q, want mp4a.40.2", at.Codec())
+ }
+ if at.SampleRate != 48000 {
+ t.Errorf("audio sample rate = %d, want 48000", at.SampleRate)
+ }
+
+ buf := initSeg.Bytes()
+ if len(buf) < 8 {
+ t.Fatal("init segment too small")
+ }
+ mr := mp4.NewReader(buf)
+ if !mr.Next() {
+ t.Fatal("expected ftyp in init segment")
+ }
+ if mr.Type() != mp4.TypeFtyp {
+ t.Errorf("first box = %s, want ftyp", mr.Type())
+ }
+ if !mr.Next() {
+ t.Fatal("expected moov in init segment")
+ }
+ if mr.Type() != mp4.TypeMoov {
+ t.Errorf("second box = %s, want moov", mr.Type())
+ }
+}
+
+func TestReadFragments(t *testing.T) {
+ f := openTestFile(t)
+ defer f.Close()
+
+ frag, initSeg, err := fragment.NewReader(f)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ fragCount := 0
+ totalSamples := 0
+ for {
+ fr, err := frag.ReadFragment()
+ if err == io.EOF {
+ break
+ }
+ if err != nil {
+ t.Fatal(err)
+ }
+ fragCount++
+ totalSamples += len(fr.Samples)
+ }
+
+ if fragCount == 0 {
+ t.Fatal("expected at least one fragment")
+ }
+
+ vt := initSeg.VideoTrack()
+ if totalSamples < len(vt.Samples) {
+ t.Errorf("total samples = %d, want at least %d (video samples)", totalSamples, len(vt.Samples))
+ }
+
+ t.Logf("fragments=%d totalSamples=%d", fragCount, totalSamples)
+}
+
+func TestWriteFragment(t *testing.T) {
+ f := openTestFile(t)
+ defer f.Close()
+
+ frag, initSeg, err := fragment.NewReader(f)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := frag.SetTimeRange(5, 10); err != nil {
+ t.Fatal(err)
+ }
+
+ out, err := os.CreateTemp("", "fragment-test-*.mp4")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer os.Remove(out.Name())
+ defer out.Close()
+
+ w := fragment.NewWriter(out)
+ if err := w.WriteInit(initSeg); err != nil {
+ t.Fatal(err)
+ }
+
+ fragCount := 0
+ for {
+ fr, err := frag.ReadFragment()
+ if err == io.EOF {
+ break
+ }
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := w.WriteFragment(fr, f); err != nil {
+ t.Fatal(err)
+ }
+ fragCount++
+ }
+
+ if fragCount == 0 {
+ t.Fatal("expected at least one fragment")
+ }
+
+ out.Seek(0, io.SeekStart)
+ verifyOutputBoxes(t, out)
+}
+
+func TestSeek(t *testing.T) {
+ f := openTestFile(t)
+ defer f.Close()
+
+ frag, _, err := fragment.NewReader(f)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ frag1, err := frag.ReadFragment()
+ if err != nil {
+ t.Fatal(err)
+ }
+ frag1Len := len(frag1.Samples)
+
+ if err := frag.Seek(0); err != nil {
+ t.Fatal(err)
+ }
+
+ frag2, err := frag.ReadFragment()
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ if len(frag2.Samples) != frag1Len {
+ t.Errorf("after seek, fragment has %d samples, want %d", len(frag2.Samples), frag1Len)
+ }
+}
+
+func TestReset(t *testing.T) {
+ f := openTestFile(t)
+ defer f.Close()
+
+ // A separate reader gives ground-truth samples from a fresh parse.
+ g := openTestFile(t)
+ defer g.Close()
+ _, fresh, err := fragment.NewReader(g)
+ if err != nil {
+ t.Fatal(err)
+ }
+ want := fresh.VideoTrack().Samples
+
+ r, _, err := fragment.NewReader(f)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ if _, err := f.Seek(0, io.SeekStart); err != nil {
+ t.Fatal(err)
+ }
+ init2, err := r.Reset(f)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ got := init2.VideoTrack().Samples
+ if !reflect.DeepEqual(got, want) {
+ t.Errorf("video samples after Reset differ from a fresh parse (got %d, want %d)", len(got), len(want))
+ }
+
+ fragCount := 0
+ for {
+ if _, err := r.ReadFragment(); err == io.EOF {
+ break
+ } else if err != nil {
+ t.Fatal(err)
+ }
+ fragCount++
+ }
+ if fragCount == 0 {
+ t.Fatal("no fragments after Reset")
+ }
+}
+
+func TestSetTimeRangeValidation(t *testing.T) {
+ f := openTestFile(t)
+ defer f.Close()
+
+ frag, _, err := fragment.NewReader(f)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ tests := []struct {
+ start, end float64
+ wantErr bool
+ }{
+ {0, 0, false}, // valid: entire file
+ {5, 10, false}, // valid: normal range
+ {0, 10, false}, // valid: from start
+ {-1, 10, true}, // invalid: negative start
+ {0, -1, true}, // invalid: negative end
+ {10, 5, true}, // invalid: end before start
+ {10, 10, true}, // invalid: zero-length range
+ }
+
+ for _, tt := range tests {
+ err := frag.SetTimeRange(tt.start, tt.end)
+ if (err != nil) != tt.wantErr {
+ t.Errorf("SetTimeRange(%v, %v): err=%v, wantErr=%v", tt.start, tt.end, err, tt.wantErr)
+ }
+ }
+}
+
+func verifyOutputBoxes(t *testing.T, f *os.File) {
+ t.Helper()
+ stat, _ := f.Stat()
+ data := make([]byte, stat.Size())
+ f.ReadAt(data, 0)
+
+ moofCount := 0
+ mdatCount := 0
+ hasFtyp := false
+ hasMoov := false
+
+ mr := mp4.NewReader(data)
+ for mr.Next() {
+ switch mr.Type() {
+ case mp4.TypeFtyp:
+ hasFtyp = true
+ case mp4.TypeMoov:
+ hasMoov = true
+ case mp4.TypeMoof:
+ moofCount++
+ mr.Enter()
+ trafCount := 0
+ for mr.Next() {
+ if mr.Type() == mp4.TypeTraf {
+ trafCount++
+ }
+ }
+ mr.Exit()
+ if trafCount == 0 {
+ t.Error("moof has no traf children")
+ }
+ case mp4.TypeMdat:
+ mdatCount++
+ }
+ }
+
+ if !hasFtyp {
+ t.Error("missing ftyp")
+ }
+ if !hasMoov {
+ t.Error("missing moov")
+ }
+ if moofCount == 0 {
+ t.Error("no moof boxes")
+ }
+ if mdatCount == 0 {
+ t.Error("no mdat boxes")
+ }
+ if moofCount != mdatCount {
+ t.Errorf("moof count (%d) != mdat count (%d)", moofCount, mdatCount)
+ }
+
+ t.Logf("output: ftyp=%v moov=%v moof=%d mdat=%d", hasFtyp, hasMoov, moofCount, mdatCount)
+}
diff --git a/fragment/writer.go b/fragment/writer.go
new file mode 100644
index 0000000..a992a0d
--- /dev/null
+++ b/fragment/writer.go
@@ -0,0 +1,362 @@
+package fragment
+
+import (
+ "encoding/binary"
+ "io"
+
+ "github.com/tetsuo/mp4"
+)
+
+// Writer writes fragmented MP4 segments.
+type Writer struct {
+ w io.Writer
+ buf []byte // moof build buffer
+ copyBuf [131072]byte // sample data copy buffer
+ mdatHdr [8]byte // mdat box header (size + 'mdat'), reused per fragment
+
+ // State carried from Prepare to the body writers. moof points into buf and
+ // holds the finished moof bytes; mdatPayload is the sum of the sample sizes,
+ // so the body size is known before any media byte is read.
+ moof []byte
+ mdatPayload int64
+
+ // Per-track scratch buffers.
+ sampleIdx [maxTracks][]int
+ trunBuf [maxTracks][]mp4.TrunEntry
+ ranges []byteRange
+}
+
+type byteRange struct {
+ offset int64
+ size int64
+}
+
+// NewWriter creates a fragment writer which writes to the provided [io.Writer].
+func NewWriter(w io.Writer) *Writer {
+ wr := &Writer{
+ w: w,
+ buf: make([]byte, 65536),
+ ranges: make([]byteRange, 0, 1024),
+ }
+ for i := range wr.sampleIdx {
+ wr.sampleIdx[i] = make([]int, 0, 512)
+ }
+ for i := range wr.trunBuf {
+ wr.trunBuf[i] = make([]mp4.TrunEntry, 0, 512)
+ }
+ return wr
+}
+
+// Reset prepares the [Writer] for reuse with a new [io.Writer].
+func (w *Writer) Reset(dst io.Writer) {
+ w.w = dst
+}
+
+// WriteInit writes the init segment (ftyp+moov).
+func (w *Writer) WriteInit(s *InitSegment) error {
+ _, err := w.w.Write(s.buf)
+ return err
+}
+
+// WriteFragment writes a single moof+mdat fragment.
+// src is used to read sample data at the offsets specified in fragment samples.
+func (w *Writer) WriteFragment(frag *Fragment, src io.ReaderAt) error {
+ if err := w.Prepare(frag); err != nil {
+ return err
+ }
+ return w.WriteBodyRange(w.w, src, 0, w.BodySize())
+}
+
+// BodySize returns the byte size of the body (moof + mdat) of the fragment last
+// passed to [Writer.Prepare]. It is moofSize + 8 + sum(sample sizes), all known
+// from sample metadata, so the size is available before any media is read.
+func (w *Writer) BodySize() int64 {
+ return int64(len(w.moof)) + 8 + w.mdatPayload
+}
+
+// Prepare builds the moof for frag from sample metadata alone, reading no media.
+// It records the moof bytes and the mdat payload size so [Writer.BodySize] and
+// [Writer.WriteBodyRange] can write the body, or a byte window of it, afterward.
+// The recorded state is valid until the next call to Prepare on this writer.
+func (w *Writer) Prepare(frag *Fragment) error {
+ // Group samples by track
+ var trackIDs [maxTracks]uint32
+ groupCount := 0
+
+ for i := range w.sampleIdx {
+ w.sampleIdx[i] = w.sampleIdx[i][:0]
+ }
+
+ for i := range frag.Samples {
+ s := &frag.Samples[i]
+ found := false
+ for g := 0; g < groupCount; g++ {
+ if trackIDs[g] == s.TrackID {
+ w.sampleIdx[g] = append(w.sampleIdx[g], i)
+ found = true
+ break
+ }
+ }
+ if !found {
+ if groupCount >= maxTracks {
+ continue
+ }
+ trackIDs[groupCount] = s.TrackID
+ w.sampleIdx[groupCount] = append(w.sampleIdx[groupCount], i)
+ groupCount++
+ }
+ }
+
+ // Build byte ranges for mdat (contiguous runs of sample data)
+ w.ranges = w.ranges[:0]
+ for g := 0; g < groupCount; g++ {
+ for _, idx := range w.sampleIdx[g] {
+ s := &frag.Samples[idx]
+ sz := int64(s.Size())
+ if len(w.ranges) > 0 {
+ last := &w.ranges[len(w.ranges)-1]
+ if last.offset+last.size == s.Offset {
+ last.size += sz
+ continue
+ }
+ }
+ w.ranges = append(w.ranges, byteRange{offset: s.Offset, size: sz})
+ }
+ }
+
+ // Total mdat payload size
+ var mdatPayload int64
+ for i := range w.ranges {
+ mdatPayload += w.ranges[i].size
+ }
+
+ mdatHeaderSize := int32(8)
+
+ // Build trun entries per track group
+ type trafInfo struct {
+ trackID uint32
+ baseDTS int64
+ hasCtts bool
+ }
+ var trafs [maxTracks]trafInfo
+
+ for g := 0; g < groupCount; g++ {
+ ti := &trafs[g]
+ ti.trackID = trackIDs[g]
+ w.trunBuf[g] = w.trunBuf[g][:0]
+
+ indices := w.sampleIdx[g]
+ if len(indices) > 0 {
+ ti.baseDTS = frag.Samples[indices[0]].DTS
+ }
+
+ for _, idx := range indices {
+ s := &frag.Samples[idx]
+ entry := mp4.TrunEntry{
+ Duration: s.Duration,
+ Size: s.Size(),
+ Flags: sampleFlags(s.IsSync()),
+ }
+ if s.PresentationOffset != 0 {
+ entry.CompositionTimeOffset = s.PresentationOffset
+ ti.hasCtts = true
+ }
+ w.trunBuf[g] = append(w.trunBuf[g], entry)
+ }
+ }
+
+ // Track data layout in mdat
+ var trackDataOffsets [maxTracks]int32
+ var accum int32
+ for g := 0; g < groupCount; g++ {
+ trackDataOffsets[g] = accum
+ for _, idx := range w.sampleIdx[g] {
+ accum += int32(frag.Samples[idx].Size())
+ }
+ }
+
+ // Build moof, recording trun data_offset positions for backpatching
+ type trunPatch struct {
+ pos int
+ dataStart int32
+ }
+ var patches [maxTracks]trunPatch
+ patchCount := 0
+
+ mw := mp4.NewWriter(w.buf)
+ mw.Reset()
+
+ mw.StartBox(mp4.TypeMoof)
+ mw.WriteMfhd(frag.SequenceNum)
+
+ for g := 0; g < groupCount; g++ {
+ ti := &trafs[g]
+ entries := w.trunBuf[g]
+ n := len(entries)
+
+ // Move constant fields into tfhd defaults so the trun only carries what
+ // varies. Sample sizes always differ, so they stay per-sample. Sample
+ // flags differ only at the first sample (a keyframe) unless the segment
+ // holds interior keyframes, in which case they stay per-sample.
+ var defaultDuration, defaultFlags uint32
+ sameDuration, sameFlags, firstDiffers := true, true, false
+ if n > 0 {
+ defaultDuration = entries[0].Duration
+ ref := 0
+ if n > 1 {
+ ref = 1
+ }
+ defaultFlags = entries[ref].Flags
+ for i := 1; i < n; i++ {
+ if entries[i].Duration != defaultDuration {
+ sameDuration = false
+ }
+ if entries[i].Flags != defaultFlags {
+ sameFlags = false
+ }
+ }
+ firstDiffers = entries[0].Flags != defaultFlags
+ }
+
+ tfhdFlags := uint32(mp4.TfhdDefaultBaseIsMoof | mp4.TfhdDefaultSampleFlagsPresent)
+ if sameDuration {
+ tfhdFlags |= mp4.TfhdDefaultSampleDurationPresent
+ }
+
+ trunFlags := uint32(mp4.TrunDataOffsetPresent | mp4.TrunSampleSizePresent)
+ if !sameDuration {
+ trunFlags |= mp4.TrunSampleDurationPresent
+ }
+ if !sameFlags {
+ trunFlags |= mp4.TrunSampleFlagsPresent
+ } else if firstDiffers {
+ trunFlags |= mp4.TrunFirstSampleFlagsPresent
+ }
+ if ti.hasCtts {
+ trunFlags |= mp4.TrunSampleCompositionTimeOffsetPresent
+ }
+
+ var firstSampleFlags uint32
+ if n > 0 {
+ firstSampleFlags = entries[0].Flags
+ }
+
+ mw.StartBox(mp4.TypeTraf)
+
+ mw.WriteTfhd(tfhdFlags, ti.trackID, defaultDuration, 0, defaultFlags)
+ mw.WriteTfdt(uint64(ti.baseDTS))
+
+ trunStart := mw.Len()
+ if patchCount < maxTracks {
+ patches[patchCount] = trunPatch{
+ pos: trunStart + 16, // offset to data_offset field
+ dataStart: trackDataOffsets[g],
+ }
+ patchCount++
+ }
+ mw.WriteTrun(trunFlags, 0, firstSampleFlags, entries)
+
+ mw.EndBox() // traf
+ }
+
+ mw.EndBox() // moof
+
+ moofSize := int32(mw.Len())
+
+ // Backpatch data_offset fields
+ moofBytes := mw.Bytes()
+ for i := 0; i < patchCount; i++ {
+ p := patches[i]
+ dataOffset := moofSize + mdatHeaderSize + p.dataStart
+ binary.BigEndian.PutUint32(moofBytes[p.pos:], uint32(dataOffset))
+ }
+
+ w.moof = moofBytes
+ w.mdatPayload = mdatPayload
+ return nil
+}
+
+// WriteBodyRange writes the body bytes in [start, end) to dst, reading sample
+// bytes from src only for the portion of the window that overlaps the sample
+// data. Offsets are relative to the start of the body: the moof occupies
+// [0, moofSize), the 8-byte mdat header [moofSize, moofSize+8), and the sample
+// data the remainder up to [Writer.BodySize]. It must be called after
+// [Writer.Prepare]. start and end must satisfy 0 <= start <= end <= BodySize.
+func (w *Writer) WriteBodyRange(dst io.Writer, src io.ReaderAt, start, end int64) error {
+ moofSize := int64(len(w.moof))
+
+ // moof region [0, moofSize)
+ if start < moofSize {
+ e := min(end, moofSize)
+ if _, err := dst.Write(w.moof[start:e]); err != nil {
+ return err
+ }
+ }
+
+ // mdat header region [moofSize, moofSize+8)
+ const mdatHdrSize = 8
+ dataStart := moofSize + mdatHdrSize
+ if start < dataStart && end > moofSize {
+ hdr := w.mdatHdr[:]
+ binary.BigEndian.PutUint32(hdr[:4], uint32(w.mdatPayload+mdatHdrSize))
+ copy(hdr[4:], "mdat")
+ s := max(start, moofSize) - moofSize
+ e := min(end, dataStart) - moofSize
+ if _, err := dst.Write(hdr[s:e]); err != nil {
+ return err
+ }
+ }
+
+ // sample data region [dataStart, dataStart+mdatPayload)
+ if end <= dataStart {
+ return nil
+ }
+ return w.writeDataRange(dst, src, max(start, dataStart)-dataStart, end-dataStart)
+}
+
+// writeDataRange writes the sample-data bytes in [lo, hi) to dst, where the
+// offsets are relative to the start of the concatenated sample data. It maps the
+// window onto the source byte ranges recorded by Prepare and reads only the
+// overlapping source bytes, in fixed-size chunks through the reused copy buffer.
+func (w *Writer) writeDataRange(dst io.Writer, src io.ReaderAt, lo, hi int64) error {
+ var pos int64 // running start of the current range within the data region
+ for i := range w.ranges {
+ rng := &w.ranges[i]
+ rEnd := pos + rng.size
+ if rEnd <= lo {
+ pos = rEnd
+ continue
+ }
+ if pos >= hi {
+ break
+ }
+ from := max(lo, pos)
+ to := min(hi, rEnd)
+ off := rng.offset + (from - pos)
+ remaining := to - from
+ for remaining > 0 {
+ n := min(int64(len(w.copyBuf)), remaining)
+ nr, err := src.ReadAt(w.copyBuf[:n], off)
+ if err != nil && err != io.EOF {
+ return err
+ }
+ if nr == 0 {
+ break
+ }
+ if _, err := dst.Write(w.copyBuf[:nr]); err != nil {
+ return err
+ }
+ off += int64(nr)
+ remaining -= int64(nr)
+ }
+ pos = rEnd
+ }
+ return nil
+}
+
+func sampleFlags(isSync bool) uint32 {
+ if isSync {
+ return 0x02000000
+ }
+ return 0x01010000
+}
diff --git a/track/track.go b/track/track.go
index 6397268..f80abcd 100644
--- a/track/track.go
+++ b/track/track.go
@@ -400,8 +400,15 @@ func ParseTracksInto(dst []*Track, moovBuf []byte) ([]*Track, uint64, error) {
}
mr.Exit()
- // Parse samples for all tracks; filter out those that fail
+ // Parse samples for each track, dropping any that fail. The result reuses
+ // dst's backing array when it fits, so repeated same-shape parses don't
+ // allocate; overwriting in place is safe as kept tracks only move earlier.
var valid []*Track
+ if cap(dst) >= len(tracks) {
+ valid = dst[:0]
+ } else {
+ valid = make([]*Track, 0, len(tracks))
+ }
for _, t := range tracks {
if err := t.parseSamples(); err != nil {
continue