Merge pull request #80 from edgeware/file-encode-modes

Change/refactor: Replace file.EncodeVerbatim with more options

Author: tobbee

README.md

@@ -25,7 +25,7 @@ In the non-fragmented files, the members Ftyp, Moov, and Mdat are used.
 A fragmented `mp4.File` file can be a single init segment, one or more media segments, or a a
 combination of both like a CMAF track which renders into a playable one-track asset.
 
-The following high-level structures are used:
+For fragmented files, following high-level structures are used:
 
 * `InitSegment` contains an `ftyp` and `moov` box and provides the metadata for a fragmented files.
    It corresponds to a CMAF header
@@ -39,7 +39,7 @@ The typical child boxes are exported so that one can write paths such as
 
 to access the (only) trun box in a fragment.
 
-The codec currently supported are AVC/H.264 and AAC.
+The codecs currently supported are AVC/H.264, HEVC/H.265 and AAC.
 
 ## Usage for creating new fragmented files
 
@@ -104,18 +104,15 @@ adds a box to its slice of children boxes `Children`, but also sets a specific
 member reference such as `Tfdt`  to point to that box. If `Children` is manipulated
 directly, that link will not be valid.
 
-## Automatic settings of values on Fragment.Encode
-It is possible to optimize the `TrunBox` size by writing default values in `TfhdBox`.
-To do this, one must analyze if, for example, the duration of all samples is the same.
-This is done by the method `TrafBox.OptimizeTfhdTrun` which changes its children `Tfhd`and `Trun`.
-Since this will change the size of boxes, it is important that this function is called
-before `Encode` on any parent box of `Traf`. In particular, this method is called automatically
-when running `Fragment.Encode`.
-
-Another value which is automatically set by `Moof.Encode` is `MoofBox.Traf.Trun.DataOffset`.
-This value is the address of the first media sample relative to the start of the `MoofBox` start.
-It therefore depends on the size of `MoofBox` and is unknown until all values are in place so that
-it can be calculated. It is set to `MoofBox.Size()+8`.
+## Encoding modes and optimizations
+For fragmented files, one can choose to either encode all boxes in a file, or only code
+the ones which are inclueded in the init and media segments. The attribute that controls that
+is called `FragEncMode`.
+Another attribute `EncOptimize` controls possible optimizations of the file encoding process.
+Currently there is only one possible optimization called `OptimizeTrun`.
+It can reduce the size of the `TrunBox` by finding and writing default
+values in the `TfhdBox` and omitting the corresponding values from the `TrunBox`.
+Note that this may change the size of all ancestor boxes of `trun`.
 
 ## Sample Number Offset
 Following the ISOBMFF standard, sample numbers and other numbers start at 1 (one-based).

examples/multitrack/multitrack_test.go

@@ -80,7 +80,8 @@ func TestGetMultiTrackSamples(t *testing.T) {
 	}
 
 	var buf bytes.Buffer
-	parsedMp4.EncodeVerbatim = true
+	parsedMp4.FragEncMode = mp4.EncModeBoxTree
+	parsedMp4.EncOptimize = mp4.OptimizeNone
 	err = parsedMp4.Encode(&buf)
 	if err != nil {
 		t.Error(err)

mp4/file.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"strings"
 )
 
 // File - an MPEG-4 file asset
@@ -22,22 +23,49 @@ import (
 // To Encode the same data as Decoded, this flag must therefore be set.
 // In all cases, Children contain all top-level boxes
 type File struct {
-	Ftyp           *FtypBox
-	Moov           *MoovBox
-	Mdat           *MdatBox        // Only used for non-fragmented files
-	Init           *InitSegment    // Init data (ftyp + moov for fragmented file)
-	Sidx           *SidxBox        // SidxBox for a DASH OnDemand file
-	Segments       []*MediaSegment // Media segments
-	Children       []Box           // All top-level boxes in order
-	EncodeVerbatim bool            // Set to encode box by box without fragment optimizations
-	isFragmented   bool
+	Ftyp         *FtypBox
+	Moov         *MoovBox
+	Mdat         *MdatBox        // Only used for non-fragmented files
+	Init         *InitSegment    // Init data (ftyp + moov for fragmented file)
+	Sidx         *SidxBox        // SidxBox for a DASH OnDemand file
+	Segments     []*MediaSegment // Media segments
+	Children     []Box           // All top-level boxes in order
+	FragEncMode  EncFragFileMode // Determine how fragmented files are encoded
+	EncOptimize  EncOptimize     // Bit field with optimizations being done at encoding
+	isFragmented bool
+}
+
+type EncFragFileMode byte
+
+const (
+	EncModeSegment = EncFragFileMode(0) // Only encode boxes that are part of Init and MediaSegments
+	EncModeBoxTree = EncFragFileMode(1) // Encode all boxes in file tree
+)
+
+type EncOptimize uint32
+
+const (
+	OptimizeNone = EncOptimize(0)
+	OptimizeTrun = EncOptimize(1 << 0)
+)
+
+func (eo EncOptimize) String() string {
+	var optList []string
+	msg := "OptimizeNone"
+	if eo&OptimizeTrun != 0 {
+		optList = append(optList, "OptimizeTrun")
+	}
+	if len(optList) > 0 {
+		msg = strings.Join(optList, " | ")
+	}
+	return msg
 }
 
 // NewFile - create MP4 file
 func NewFile() *File {
 	return &File{
-		Children: []Box{},
-		Segments: []*MediaSegment{},
+		FragEncMode: EncModeSegment,
+		EncOptimize: OptimizeNone,
 	}
 }
 
@@ -205,35 +233,41 @@ func (f *File) DumpWithSampleData(w io.Writer, specificBoxLevels string) error {
 // Encode - encode a file to a Writer
 // Fragmented files are encoded based on InitSegment and MediaSegments, unless EncodeVerbatim is set.
 func (f *File) Encode(w io.Writer) error {
-	if f.isFragmented && !f.EncodeVerbatim {
-		if f.Init != nil {
-			err := f.Init.Encode(w)
-			if err != nil {
-				return err
-			}
-		}
-		if f.Sidx != nil {
-			err := f.Sidx.Encode(w)
-			if err != nil {
-				return err
+	if f.isFragmented {
+		switch f.FragEncMode {
+		case EncModeSegment:
+			if f.Init != nil {
+				err := f.Init.Encode(w)
+				if err != nil {
+					return err
+				}
 			}
-		}
-		if !f.EncodeVerbatim {
-			for _, seg := range f.Segments {
-				err := seg.Encode(w)
+			if f.Sidx != nil {
+				err := f.Sidx.Encode(w)
 				if err != nil {
 					return err
 				}
 			}
-			return nil
-		}
-		// Fragmented and Verbatim. Don't optimize trun
-		for _, seg := range f.Segments {
-			err := seg.EncodeVerbatim(w)
-			if err != nil {
-				return err
+			if f.EncOptimize&OptimizeTrun != 0 {
+				for _, seg := range f.Segments {
+					seg.EncOptimize = f.EncOptimize
+					err := seg.Encode(w)
+					if err != nil {
+						return err
+					}
+				}
+			}
+		case EncModeBoxTree:
+			for _, b := range f.Children {
+				err := b.Encode(w)
+				if err != nil {
+					return err
+				}
 			}
+		default:
+			return fmt.Errorf("Unknown FragEncMode=%d", f.FragEncMode)
 		}
+		return nil
 	}
 	// Progressive file
 	for _, b := range f.Children {

mp4/fragment.go

@@ -9,11 +9,12 @@ import (
 
 // Fragment - MP4 Fragment ([prft] + moof + mdat)
 type Fragment struct {
-	Prft       *PrftBox
-	Moof       *MoofBox
-	Mdat       *MdatBox
-	Children   []Box  // All top-level boxes in order
-	nextTrunNr uint32 // To handle multi-trun cases
+	Prft        *PrftBox
+	Moof        *MoofBox
+	Mdat        *MdatBox
+	Children    []Box       // All top-level boxes in order
+	nextTrunNr  uint32      // To handle multi-trun cases
+	EncOptimize EncOptimize // Bit field with optimizations being done at encoding
 }
 
 // NewFragment - New emtpy one-track MP4 Fragment
@@ -206,9 +207,11 @@ func (f *Fragment) Encode(w io.Writer) error {
 		return fmt.Errorf("moof not set in fragment")
 	}
 	traf := f.Moof.Traf
-	err := traf.OptimizeTfhdTrun()
-	if err != nil {
-		return err
+	if f.EncOptimize&OptimizeTrun != 0 {
+		err := traf.OptimizeTfhdTrun()
+		if err != nil {
+			return err
+		}
 	}
 	if f.Mdat == nil {
 		return fmt.Errorf("mdat not set in fragment")
@@ -253,21 +256,3 @@ func (f *Fragment) SetTrunDataOffsets() {
 		dataOffset += trun.SizeOfData()
 	}
 }
-
-// EncodeVerbatim - write fragment without trun optimization via writer
-func (f *Fragment) EncodeVerbatim(w io.Writer) error {
-	if f.Moof == nil {
-		return fmt.Errorf("moof not set in fragment")
-	}
-	if f.Mdat == nil {
-		return fmt.Errorf("mdat not set in fragment")
-	}
-	f.SetTrunDataOffsets()
-	for _, b := range f.Children {
-		err := b.Encode(w)
-		if err != nil {
-			return err
-		}
-	}
-	return nil
-}

mp4/mediasegment.go

@@ -6,16 +6,18 @@ import (
 
 // MediaSegment - MP4 Media Segment
 type MediaSegment struct {
-	Styp      *StypBox
-	Sidx      *SidxBox // Sidx for a segment
-	Fragments []*Fragment
+	Styp        *StypBox
+	Sidx        *SidxBox // Sidx for a segment
+	Fragments   []*Fragment
+	EncOptimize EncOptimize
 }
 
 // NewMediaSegment - New empty MediaSegment
 func NewMediaSegment() *MediaSegment {
 	return &MediaSegment{
-		Styp:      CreateStyp(),
-		Fragments: []*Fragment{},
+		Styp:        CreateStyp(),
+		Fragments:   []*Fragment{},
+		EncOptimize: OptimizeNone,
 	}
 }
 
@@ -44,6 +46,7 @@ func (s *MediaSegment) Encode(w io.Writer) error {
 		}
 	}
 	for _, f := range s.Fragments {
+		f.EncOptimize = s.EncOptimize
 		err := f.Encode(w)
 		if err != nil {
 			return err
@@ -113,26 +116,3 @@ func (s *MediaSegment) Fragmentify(timescale uint64, trex *TrexBox, duration uin
 	}
 	return outFragments, nil
 }
-
-// EncodeVerbatim - Write MediaSegment via writer with verbatim Fragments
-func (s *MediaSegment) EncodeVerbatim(w io.Writer) error {
-	if s.Styp != nil {
-		err := s.Styp.Encode(w)
-		if err != nil {
-			return err
-		}
-	}
-	if s.Sidx != nil {
-		err := s.Sidx.Encode(w)
-		if err != nil {
-			return err
-		}
-	}
-	for _, f := range s.Fragments {
-		err := f.EncodeVerbatim(w)
-		if err != nil {
-			return err
-		}
-	}
-	return nil
-}

mp4/mediasegment_test.go

@@ -35,7 +35,8 @@ func TestMediaSegmentFragmentation(t *testing.T) {
 	}
 
 	var bufInSeg bytes.Buffer
-	f.EncodeVerbatim = true
+	f.EncOptimize = OptimizeNone // Avoid trun optimization
+	f.FragEncMode = EncModeBoxTree
 	err = f.Encode(&bufInSeg)
 	if err != nil {
 		t.Error(err)
@@ -71,6 +72,7 @@ func TestMediaSegmentFragmentation(t *testing.T) {
 
 	var bufFrag bytes.Buffer
 	fragmentedSegment := NewMediaSegment()
+	fragmentedSegment.EncOptimize = OptimizeTrun
 	fragmentedSegment.Styp = f.Segments[0].Styp
 	fragmentedSegment.Fragments = fragments
 
@@ -102,7 +104,6 @@ func TestMediaSegmentFragmentation(t *testing.T) {
 }
 
 func TestDoubleDecodeEncodeOptimize(t *testing.T) {
-	encodeVerbatim := false
 	inFile := "testdata/1.m4s"
 
 	fd, err := os.Open(inFile)
@@ -111,17 +112,17 @@ func TestDoubleDecodeEncodeOptimize(t *testing.T) {
 	}
 	defer fd.Close()
 
-	enc1 := decodeEncode(t, fd, encodeVerbatim)
+	enc1 := decodeEncode(t, fd, OptimizeTrun)
 	buf1 := bytes.NewBuffer(enc1)
-	enc2 := decodeEncode(t, buf1, encodeVerbatim)
+	enc2 := decodeEncode(t, buf1, OptimizeTrun)
 	diff := deep.Equal(enc2, enc1)
 	if diff != nil {
 		t.Errorf("Second write gives diff %s", diff)
 	}
 }
 
 func TestDoubleDecodeEncodeNoOptimize(t *testing.T) {
-	encodeVerbatim := true
+
 	inFile := "testdata/1.m4s"
 
 	fd, err := os.Open(inFile)
@@ -130,23 +131,23 @@ func TestDoubleDecodeEncodeNoOptimize(t *testing.T) {
 	}
 	defer fd.Close()
 
-	enc1 := decodeEncode(t, fd, encodeVerbatim)
+	enc1 := decodeEncode(t, fd, OptimizeNone)
 	buf1 := bytes.NewBuffer(enc1)
-	enc2 := decodeEncode(t, buf1, encodeVerbatim)
+	enc2 := decodeEncode(t, buf1, OptimizeNone)
 	diff := deep.Equal(enc2, enc1)
 	if diff != nil {
 		t.Errorf("Second write gives diff %s", diff)
 	}
 }
 
-func decodeEncode(t *testing.T, r io.Reader, encodeVerbatim bool) []byte {
+func decodeEncode(t *testing.T, r io.Reader, optimize EncOptimize) []byte {
 	f, err := DecodeFile(r)
 	if err != nil {
 		t.Error(err)
 	}
 
 	buf := bytes.Buffer{}
-	f.EncodeVerbatim = encodeVerbatim
+	f.EncOptimize = optimize
 	err = f.Encode(&buf)
 	if err != nil {
 		t.Error(err)
@@ -170,7 +171,7 @@ func TestMoofEncrypted(t *testing.T) {
 	}
 
 	var bufOut bytes.Buffer
-	f.EncodeVerbatim = true
+	f.FragEncMode = EncModeBoxTree
 	err = f.Encode(&bufOut)
 	if err != nil {
 		t.Error(err)
@@ -206,7 +207,7 @@ func BenchmarkDecodeEncode(b *testing.B) {
 		buf := bytes.NewBuffer(raw)
 		f, _ := DecodeFile(buf)
 		var bufInSeg bytes.Buffer
-		f.EncodeVerbatim = true
+		f.FragEncMode = EncModeBoxTree
 		_ = f.Encode(&bufInSeg)
 	}
 }