go-mp4

The mp4.NewWriter provides a way to build or modify MP4 box trees. When editing an existing file, you typically use ReadBoxStructure to traverse the source and a Writer to write to the destination.

Common operations within the ReadBoxStructure callback:

• w.StartBox(&h.BoxInfo): Starts writing a box with the specified header.
• mp4.Marshal(w, box, context): Writes the payload of a specific box type.
• w.EndBox(): Finalizes the current box (useful for updating size).
• w.CopyBox(r, &h.BoxInfo): Copies an existing box from the reader to the writer without modification.

Warning: When modifying boxes that change the file structure (like adding metadata), you must manually update dependent boxes (like stco chunk offsets) if the mdat box offset changes.

r := bufseekio.NewReadSeeker(inputFile, 128*1024, 4)
w := mp4.NewWriter(outputFile)
_, err = mp4.ReadBoxStructure(r, func(h *mp4.ReadHandle) (interface{}, error) {
	switch h.BoxInfo.Type {
	case mp4.BoxTypeEmsg():
		// write box size and box type
		_, err := w.StartBox(&h.BoxInfo)
		if err != nil {
			return nil, err
		}
		// read payload
		box, _, err := h.ReadPayload()
		if err != nil {
			return nil, err
		}
		// update MessageData
		emsg := box.(*mp4.Emsg)
		emsg.MessageData = []byte("hello world")
		// write box playload
		if _, err := mp4.Marshal(w, emsg, h.BoxInfo.Context); err != nil {
			return nil, err
		}
		// rewrite box size
		_, err = w.EndBox()
		return nil, err
	default:
		// copy all
		return nil, w.CopyBox(r, &h.BoxInfo)
	}
})

A Track object represents a single media stream (e.g., video or audio) within the MP4 file. It contains detailed information about the codec and the layout of the media data.

Key fields:

• TrackID (uint32): Unique identifier for the track.
• Codec (Codec): The type of codec used (CodecAVC1 for H.264, CodecMP4A for AAC, or CodecUnknown).
• Encrypted (bool): Indicates if the track is encrypted.
• AVC (*AVCDecConfigInfo): Detailed configuration for AVC (H.264) tracks, including Profile, Level, Width, and Height.
• MP4A (*MP4AInfo): Detailed configuration for AAC tracks, including ChannelCount and AAC profile indicators (OTI, AudOTI).
• Samples (Samples): A list of Sample objects containing Size, TimeDelta, and CompositionTimeOffset.
• Chunks (Chunks): A list of Chunk objects mapping DataOffset and SamplesPerChunk to the physical file location.

The mp4 package provides BoxInfo and Context types to manage metadata for MP4 boxes (atoms) as defined in ISO/IEC 14496-12.

BoxInfo

BoxInfo contains the structural metadata for a box, including its position and size in a file. Key fields include:

• Offset: The byte offset of the box in the file.
• Size: The total size of the box in bytes.
• HeaderSize: The size of the box header (either SmallHeaderSize (8 bytes) or LargeHeaderSize (16 bytes)).
• Type: The 4-character BoxType identifier.
• ExtendToEOF: A boolean indicating if the box extends to the end of the file (when Size is 0).
• Context: Structural metadata about where the box resides in the MP4 hierarchy.

Context

Context provides state about the box's location within the MP4 structure, which is used to determine if a box type is supported via IsSupportedType(). It tracks properties such as:

• IsQuickTimeCompatible: Whether the file is QuickTime compatible.
• UnderWave, UnderIlst, UnderUdta, etc.: Boolean flags indicating if the current box is nested under specific parent boxes like moov.movie.track.mdia.minf.stbl.stts (implied by hierarchy) or specific containers like udta or ilst.
• QuickTimeKeysMetaEntryCount: Expected items under an ilst box.

To scan an MP4 box (atom) tree in depth-first order, use mp4.ReadBoxStructure or mp4.ReadBoxStructureFromInternal. You provide an io.ReadSeeker and a callback function that receives a *mp4.ReadHandle for each box.

Inside the callback, you can:

• Access box metadata via h.BoxInfo (Type, Size, etc.).
• Read the payload using h.ReadPayload().
• Convert the payload to a string using mp4.Stringify().
• Recursively expand children by returning h.Expand() from the callback.

Note: This library is designed for low-level I/O and is not intended for complex data conversions.

// expand all boxes
_, err := mp4.ReadBoxStructure(file, func(h *mp4.ReadHandle) (interface{}, error) {
	fmt.Println("depth", len(h.Path))

	// Box Type (e.g. "mdhd", "tfdt", "mdat")
	fmt.Println("type", h.BoxInfo.Type.String())

	// Box Size
	fmt.Println("size", h.BoxInfo.Size)

	if h.BoxInfo.IsSupportedType() {
		// Payload
		box, _, err := h.ReadPayload()
		if err != nil {
			return nil, err
		}
		str, err := mp4.Stringify(box, h.BoxInfo.Context)
		if err != nil {
			return nil, err
		}
		fmt.Println("payload", str)

		// Expands children
		return h.Expand()
	}
	return nil, nil
})

The mp4 package provides IAnyType and AnyTypeBox to handle MP4 boxes where the specific type is not fixed at compile time but can be set or retrieved dynamically.

• IAnyType is an interface that embeds IBox and requires a SetType(BoxType) method. Use this when you need to interact with a box that has a variable type.
• AnyTypeBox is a concrete implementation of IAnyType. It embeds a standard Box and includes a Type field of type BoxType.

You can use AnyTypeBox to represent a box whose type is determined during parsing or runtime, allowing you to call GetType() to identify it or SetType(boxType) to modify it.

// Example of using AnyTypeBox to manage a box with a dynamic type
var box mp4.IAnyType = &mp4.AnyTypeBox{
    Box: mp4.Box{ /* ... */ },
    Type: mp4.BoxType{ /* ... */ },
}

// Set a new type
box.SetType(mp4.BoxType{ /* ... */ })

// Retrieve the type
type := box.(*mp4.AnyTypeBox).GetType()