diff options
| author | Onur Gündüz <ogunduz@gmail.com> | 2026-06-30 17:12:12 +0200 |
|---|---|---|
| committer | Onur Gündüz <ogunduz@gmail.com> | 2026-06-30 17:12:12 +0200 |
| commit | c56d4fa173d3a851a1ebb4a2d27684669e699630 (patch) | |
| tree | b176914225419cb4f708f5fc352af16d50b408b8 /fragment/reader.go | |
| parent | 0f5c3761970cdf122da63a2454dfcce545ab357c (diff) | |
| download | mp4-c56d4fa173d3a851a1ebb4a2d27684669e699630.tar.gz mp4-c56d4fa173d3a851a1ebb4a2d27684669e699630.zip | |
fragment: add streaming MP4 fragmentation
Diffstat (limited to 'fragment/reader.go')
| -rw-r--r-- | fragment/reader.go | 656 |
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() +} |
