aboutsummaryrefslogtreecommitdiff
path: root/fragment/reader.go
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 /fragment/reader.go
parent0f5c3761970cdf122da63a2454dfcce545ab357c (diff)
downloadmp4-c56d4fa173d3a851a1ebb4a2d27684669e699630.tar.gz
mp4-c56d4fa173d3a851a1ebb4a2d27684669e699630.zip
fragment: add streaming MP4 fragmentation
Diffstat (limited to 'fragment/reader.go')
-rw-r--r--fragment/reader.go656
1 files changed, 656 insertions, 0 deletions
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()
+}