container

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 30, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package container provides JPEG XS (ISO/IEC 21122-3) transport format parsing.

This package implements Part 3 of the JPEG XS standard, which specifies transport formats for JPEG XS codestreams. Three container formats are supported:

Raw Codestream Format

The simplest format is raw codestreams in .jxs files. These contain one or more JPEG XS codestreams concatenated together, each bounded by SOC (Start of Codestream) and EOC (End of Codestream) markers.

reader := container.NewRawReader(data)
info, err := reader.Parse()
if err != nil {
    return err
}
for i := 0; i < info.PictureCount; i++ {
    csData, _ := reader.ExtractPicture(i)
    // Process codestream...
}

ISOBMFF Container Format

ISO base media file format (MP4-style) containers are used for video applications. The container stores timing metadata and allows efficient frame access.

reader := container.NewISOBMFFReader(data)
info, err := reader.Parse()
if err != nil {
    return err
}
frame, _ := reader.ExtractFrame(0)
fmt.Printf("Frame 0: %d bytes\n", len(frame.Data))

RTP Payload Format

For streaming applications, JPEG XS can be transported over RTP using the payload format defined in RFC 9134. This package provides header parsing only, not full transport handling.

parser := container.NewRTPParser(packetData)
info, err := parser.ParseHeader()
if err != nil {
    return err
}
if info.MarkerBit {
    // Last packet of frame
}

Security Considerations

All parsers validate input against security limits to prevent denial-of-service:

  • Maximum box size for ISOBMFF containers
  • Maximum picture/frame count
  • Input bounds checking for all operations

Thread Safety

Reader instances are not safe for concurrent use from multiple goroutines. Create separate readers for parallel processing.

Package container provides JPEG XS (ISO/IEC 21122-3) transport format parsing. This file implements the ISOBMFF (ISO base media file format) container reader.

Package container provides JPEG XS (ISO/IEC 21122-3) transport format parsing. This file implements the raw codestream container reader.

Package container provides JPEG XS (ISO/IEC 21122-3) transport format parsing. This file implements the RTP payload format parser per RFC 9134.

Package container provides JPEG XS (ISO/IEC 21122-3) transport format parsing. This package implements Part 3 of the JPEG XS standard which defines:

  • Raw codestream format (.jxs files)
  • ISO base media file format (ISOBMFF) container
  • RTP payload format for streaming

The package supports extracting individual frames from containers and parsing timing metadata for video applications.

Index

Constants

View Source
const (
	// BoxTypeFtyp is the file type box.
	BoxTypeFtyp = 0x66747970 // "ftyp"

	// BoxTypeMoov is the movie box (metadata container).
	BoxTypeMoov = 0x6D6F6F76 // "moov"

	// BoxTypeMvhd is the movie header box.
	BoxTypeMvhd = 0x6D766864 // "mvhd"

	// BoxTypeTrak is the track box.
	BoxTypeTrak = 0x7472616B // "trak"

	// BoxTypeTkhd is the track header box.
	BoxTypeTkhd = 0x746B6864 // "tkhd"

	// BoxTypeMdia is the media box.
	BoxTypeMdia = 0x6D646961 // "mdia"

	// BoxTypeMdhd is the media header box.
	BoxTypeMdhd = 0x6D646864 // "mdhd"

	// BoxTypeMinf is the media information box.
	BoxTypeMinf = 0x6D696E66 // "minf"

	// BoxTypeStbl is the sample table box.
	BoxTypeStbl = 0x7374626C // "stbl"

	// BoxTypeStsd is the sample description box.
	BoxTypeStsd = 0x73747364 // "stsd"

	// BoxTypeStts is the decoding time to sample box.
	BoxTypeStts = 0x73747473 // "stts"

	// BoxTypeStsc is the sample to chunk box.
	BoxTypeStsc = 0x73747363 // "stsc"

	// BoxTypeStsz is the sample size box.
	BoxTypeStsz = 0x7374737A // "stsz"

	// BoxTypeStco is the chunk offset box.
	BoxTypeStco = 0x7374636F // "stco"

	// BoxTypeCo64 is the 64-bit chunk offset box.
	BoxTypeCo64 = 0x636F3634 // "co64"

	// BoxTypeMdat is the media data box.
	BoxTypeMdat = 0x6D646174 // "mdat"

	// BoxTypeJxsm is the JPEG XS sample entry.
	BoxTypeJxsm = 0x6A78736D // "jxsm"
)

ISOBMFF box types.

View Source
const (
	// MarkerSOC is the Start of Codestream marker.
	MarkerSOC = 0xFF10

	// MarkerEOC is the End of Codestream marker.
	MarkerEOC = 0xFF11

	// MarkerPIH is the Picture Header marker.
	MarkerPIH = 0xFF12
)

JPEG XS marker codes for codestream detection.

View Source
const (
	// MaxBoxSize is the maximum allowed box size (1 GB).
	MaxBoxSize = 1 << 30

	// MaxPictureCount is the maximum number of pictures in a container.
	MaxPictureCount = 65536

	// MaxFrameCount is the maximum number of frames in a container.
	MaxFrameCount = MaxPictureCount

	// MinRTPHeaderSize is the minimum RTP header size.
	MinRTPHeaderSize = 12

	// MaxCSRCCount is the maximum number of CSRC entries.
	MaxCSRCCount = 15
)

Security limits for container parsing.

Variables

View Source
var (
	// BrandJXSM is the main JPEG XS brand.
	BrandJXSM = [4]byte{'j', 'x', 's', 'm'}

	// BrandJXSS is the JPEG XS simple profile brand.
	BrandJXSS = [4]byte{'j', 'x', 's', 's'}
)

JPEG XS compatible brands.

View Source
var (
	// ErrInvalidContainer indicates the container format is invalid.
	ErrInvalidContainer = errors.New("invalid container format")

	// ErrMissingFtyp indicates the ftyp box is missing.
	ErrMissingFtyp = errors.New("missing ftyp box")

	// ErrUnsupportedBrand indicates the brand is not supported.
	ErrUnsupportedBrand = errors.New("unsupported container brand")

	// ErrTruncatedBox indicates a box is truncated.
	ErrTruncatedBox = errors.New("truncated box data")

	// ErrBoxTooLarge indicates a box size exceeds limits.
	ErrBoxTooLarge = errors.New("box size exceeds maximum limit")

	// ErrInvalidBoxSize indicates a box size is invalid.
	ErrInvalidBoxSize = errors.New("invalid box size")

	// ErrMissingSOC indicates no SOC marker was found.
	ErrMissingSOC = errors.New("missing SOC marker")

	// ErrTruncatedCodestream indicates the codestream is incomplete.
	ErrTruncatedCodestream = errors.New("truncated codestream")

	// ErrInvalidPictureIndex indicates an invalid picture index.
	ErrInvalidPictureIndex = errors.New("invalid picture index")

	// ErrInvalidFrameIndex indicates an invalid frame index.
	ErrInvalidFrameIndex = errors.New("invalid frame index")

	// ErrInvalidRTPHeader indicates an invalid RTP header.
	ErrInvalidRTPHeader = errors.New("invalid RTP header")

	// ErrInvalidRTPVersion indicates an unsupported RTP version.
	ErrInvalidRTPVersion = errors.New("invalid RTP version (must be 2)")

	// ErrTruncatedRTPHeader indicates the RTP header is too short.
	ErrTruncatedRTPHeader = errors.New("truncated RTP header")

	// ErrEmptyData indicates the input data is empty.
	ErrEmptyData = errors.New("empty input data")

	// ErrNoFrames indicates no frames were found in the container.
	ErrNoFrames = errors.New("no frames found in container")
)

Container format errors.

Functions

func DetectISOBMFF

func DetectISOBMFF(data []byte) bool

DetectISOBMFF attempts to detect if data is an ISOBMFF container. Returns true if the data appears to be ISOBMFF with a valid box structure.

func DetectRTP

func DetectRTP(data []byte) bool

DetectRTP attempts to detect if data is an RTP packet. Returns true if the data appears to be a valid RTP packet.

func DetectRawFormat

func DetectRawFormat(data []byte) bool

DetectFormat attempts to detect if data is a raw JPEG XS codestream. Returns true if the data starts with a SOC marker.

Types

type ContainerInfo

type ContainerInfo struct {
	// Format indicates the container format type.
	Format Format

	// PictureCount is the number of pictures/frames in the container.
	PictureCount int

	// FrameCount is an alias for PictureCount (for video terminology).
	FrameCount int

	// Duration is the total duration of the content (for video containers).
	Duration time.Duration

	// Timescale is the time units per second used in the container.
	Timescale uint32

	// Pictures contains information about each picture in the container.
	Pictures []PictureInfo

	// Frames is an alias for Pictures (for video terminology).
	Frames []FrameInfo

	// Brand is the major brand for ISOBMFF containers.
	Brand string

	// CompatibleBrands lists compatible brands for ISOBMFF containers.
	CompatibleBrands []string
}

ContainerInfo contains information about a parsed container.

type Format

type Format int

Container format types.

const (
	// FormatUnknown indicates an unrecognized container format.
	FormatUnknown Format = iota

	// FormatRaw indicates a raw JPEG XS codestream (.jxs file).
	// This is the simplest format containing one or more concatenated codestreams.
	FormatRaw

	// FormatISOBMFF indicates ISO base media file format container.
	// This is the MP4-style container format specified in ISO/IEC 21122-3 Annex A.
	FormatISOBMFF

	// FormatRTP indicates RTP payload format for streaming.
	// This follows RFC 9134 for JPEG XS over RTP.
	FormatRTP
)

func (Format) String

func (f Format) String() string

String returns a human-readable name for the format.

type FrameInfo

type FrameInfo struct {
	// Index is the zero-based frame index.
	Index int

	// StartOffset is the byte offset to the start of the frame data.
	StartOffset int64

	// Size is the size of the frame data in bytes.
	Size int64

	// Timestamp is the presentation timestamp in timescale units.
	Timestamp uint64

	// Duration is the frame duration in timescale units.
	Duration uint32

	// Data contains the frame codestream data (populated when extracted).
	Data []byte

	// IsKeyframe indicates if this is an I-frame/keyframe.
	IsKeyframe bool
}

FrameInfo contains information about a single frame in a video container.

type ISOBMFFReader

type ISOBMFFReader struct {
	// contains filtered or unexported fields
}

ISOBMFFReader parses ISOBMFF containers containing JPEG XS frames. This follows ISO/IEC 21122-3 Annex A and ISO/IEC 14496-12 (ISOBMFF).

func NewISOBMFFReader

func NewISOBMFFReader(data []byte) *ISOBMFFReader

NewISOBMFFReader creates a new ISOBMFF reader.

func (*ISOBMFFReader) ExtractFrame

func (r *ISOBMFFReader) ExtractFrame(index int) (*FrameInfo, error)

ExtractFrame extracts a frame by index.

func (*ISOBMFFReader) GetInfo

func (r *ISOBMFFReader) GetInfo() *ContainerInfo

GetInfo returns the parsed container information.

func (*ISOBMFFReader) GetTiming

func (r *ISOBMFFReader) GetTiming() *TimingInfo

GetTiming returns the parsed timing information.

func (*ISOBMFFReader) Parse

func (r *ISOBMFFReader) Parse() (*ContainerInfo, error)

Parse parses the ISOBMFF container and returns container information.

type JPEGXSPayloadHeader

type JPEGXSPayloadHeader struct {
	// TransmissionMode indicates the transmission mode.
	TransmissionMode byte

	// PacketMode indicates progressive or interlaced mode.
	PacketMode byte

	// LastBuffer indicates if this is the last buffer of a frame.
	LastBuffer bool

	// PictureIndex identifies the picture within a sequence.
	PictureIndex uint16

	// Kmax is the maximum codestream size for rate control.
	Kmax uint32

	// SliceIndex is the slice index for this packet.
	SliceIndex uint16

	// FragmentOffset is the byte offset within the slice.
	FragmentOffset uint32
}

JPEGXSPayloadHeader contains JPEG XS specific RTP payload header fields. This is defined in RFC 9134 Section 4.2.

type PacketizationMode

type PacketizationMode int

PacketizationMode defines how JPEG XS codestreams are packetized for RTP.

const (
	// PacketizationModeUnknown indicates unknown packetization mode.
	PacketizationModeUnknown PacketizationMode = iota

	// PacketizationModeNonInterleaved uses non-interleaved mode.
	// Each packet contains data from a single slice.
	PacketizationModeNonInterleaved

	// PacketizationModeInterleaved uses interleaved mode.
	// Packets may contain data from multiple slices.
	PacketizationModeInterleaved
)

func (PacketizationMode) String

func (m PacketizationMode) String() string

String returns a human-readable name for the packetization mode.

type PictureInfo

type PictureInfo struct {
	// Index is the zero-based picture index.
	Index int

	// StartOffset is the byte offset to the start of the codestream.
	StartOffset int64

	// Size is the size of the codestream in bytes.
	Size int64

	// Profile is the JPEG XS profile if detected.
	Profile uint16

	// Width is the image width in pixels.
	Width int

	// Height is the image height in pixels.
	Height int
}

PictureInfo contains information about a single picture in a raw container.

type RTPInfo

type RTPInfo struct {
	// Version is the RTP protocol version (should be 2).
	Version byte

	// Padding indicates if the packet has padding.
	Padding bool

	// HasExtension indicates if header extension is present.
	HasExtension bool

	// CSRCCount is the number of CSRC identifiers.
	CSRCCount byte

	// MarkerBit indicates end of frame in JPEG XS RTP.
	MarkerBit bool

	// PayloadType is the RTP payload type.
	PayloadType byte

	// SequenceNumber is the packet sequence number.
	SequenceNumber uint16

	// Timestamp is the RTP timestamp.
	Timestamp uint32

	// SSRC is the synchronization source identifier.
	SSRC uint32

	// CSRCList contains CSRC identifiers if present.
	CSRCList []uint32

	// ExtensionHeader contains extension data if present.
	ExtensionHeader []byte

	// PayloadOffset is the byte offset to the start of payload data.
	PayloadOffset int

	// PacketizationMode indicates how the codestream is packetized.
	PacketizationMode PacketizationMode
}

RTPInfo contains information from an RTP packet header.

func (*RTPInfo) IsLastPacket

func (info *RTPInfo) IsLastPacket() bool

IsLastPacket returns true if the marker bit indicates this is the last packet of a JPEG XS picture.

type RTPPacket

type RTPPacket struct {
	Info    *RTPInfo
	Payload []byte
}

RTPPacket represents a single RTP packet with parsed header.

type RTPPacketizer

type RTPPacketizer struct {
	// contains filtered or unexported fields
}

RTPPacketizer helps reassemble JPEG XS frames from RTP packets. This is a helper for applications that need to reassemble frames.

func NewRTPPacketizer

func NewRTPPacketizer() *RTPPacketizer

NewRTPPacketizer creates a new RTP packetizer for frame reassembly.

func (*RTPPacketizer) AddPacket

func (p *RTPPacketizer) AddPacket(data []byte) (bool, error)

AddPacket adds a packet to the packetizer. Returns true if a complete frame is available.

func (*RTPPacketizer) GetFrame

func (p *RTPPacketizer) GetFrame() []byte

GetFrame returns the reassembled frame data. Should be called after AddPacket returns true.

func (*RTPPacketizer) Reset

func (p *RTPPacketizer) Reset()

Reset clears the packetizer state.

type RTPParser

type RTPParser struct {
	// contains filtered or unexported fields
}

RTPParser parses RTP packet headers for JPEG XS payloads. This follows RFC 9134 "RTP Payload Format for JPEG XS".

func NewRTPParser

func NewRTPParser(data []byte) *RTPParser

NewRTPParser creates a new RTP parser.

func (*RTPParser) GetPayload

func (p *RTPParser) GetPayload(info *RTPInfo) []byte

GetPayload returns the payload data (after the header).

func (*RTPParser) ParseHeader

func (p *RTPParser) ParseHeader() (*RTPInfo, error)

ParseHeader parses the RTP header and returns RTP information. This parses headers only and does not handle the transport layer.

func (*RTPParser) ParseJPEGXSPayloadHeader

func (p *RTPParser) ParseJPEGXSPayloadHeader(rtpInfo *RTPInfo) (*JPEGXSPayloadHeader, error)

ParseJPEGXSPayloadHeader parses the JPEG XS specific payload header. This is called after ParseHeader() to get JPEG XS specific information.

type RawReader

type RawReader struct {
	// contains filtered or unexported fields
}

RawReader parses raw JPEG XS codestream files (.jxs). These files contain one or more concatenated JPEG XS codestreams.

func NewRawReader

func NewRawReader(data []byte) *RawReader

NewRawReader creates a new raw codestream reader.

func (*RawReader) ExtractPicture

func (r *RawReader) ExtractPicture(index int) ([]byte, error)

ExtractPicture extracts the raw codestream data for a picture by index.

func (*RawReader) GetInfo

func (r *RawReader) GetInfo() *ContainerInfo

GetInfo returns the parsed container information. Returns nil if Parse() has not been called.

func (*RawReader) Parse

func (r *RawReader) Parse() (*ContainerInfo, error)

Parse parses the raw codestream file and returns container information. It identifies all pictures in the file and extracts their boundaries.

type TimingInfo

type TimingInfo struct {
	// Timescale is the number of time units per second.
	Timescale uint32

	// Duration is the total duration in timescale units.
	Duration uint64

	// FrameRate is the frame rate as a rational (numerator/denominator).
	FrameRateNumerator   uint32
	FrameRateDenominator uint32

	// CreationTime is when the content was created.
	CreationTime time.Time

	// ModificationTime is when the content was last modified.
	ModificationTime time.Time
}

TimingInfo contains timing metadata for video content.

func (*TimingInfo) FrameRate

func (t *TimingInfo) FrameRate() float64

FrameRate returns the frame rate as a float64.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL