aboutsummaryrefslogtreecommitdiff
path: root/track
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-09-15 00:06:26 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-09-15 00:06:26 +0200
commitc2eabe534a236ec52e4aaecc51cceb4e70ba3d20 (patch)
tree7628218865e6c33d882e81c2a0f6667587219528 /track
parent641feb730b9984ae2a280ee61783b133ab949e5f (diff)
downloadmp4-c2eabe534a236ec52e4aaecc51cceb4e70ba3d20.tar.gz
mp4-c2eabe534a236ec52e4aaecc51cceb4e70ba3d20.zip
track: parse H.264 sequence parameter sets
Diffstat (limited to 'track')
-rw-r--r--track/sps.go209
-rw-r--r--track/sps_test.go130
2 files changed, 339 insertions, 0 deletions
diff --git a/track/sps.go b/track/sps.go
new file mode 100644
index 0000000..52b6948
--- /dev/null
+++ b/track/sps.go
@@ -0,0 +1,209 @@
+package track
+
+import "errors"
+
+// ErrInvalidSPS is returned when an H.264 sequence parameter set cannot be
+// parsed.
+var ErrInvalidSPS = errors.New("track: invalid H.264 SPS")
+
+// SPSInfo holds the fields of an H.264 sequence parameter set that packaging
+// needs: the three bytes echoed into an avcC and codec string, and the coded
+// picture dimensions.
+type SPSInfo struct {
+ Profile uint8 // profile_idc
+ Compat uint8 // constraint flags byte, avcC profile_compatibility
+ Level uint8 // level_idc
+ Width uint16
+ Height uint16
+}
+
+// ParseSPS parses an H.264 sequence parameter set NAL unit (header byte
+// included, no start code or length prefix) and returns its profile, level,
+// and cropped picture dimensions.
+func ParseSPS(nalu []byte) (SPSInfo, error) {
+ if len(nalu) < 4 || nalu[0]&0x1f != 7 {
+ return SPSInfo{}, ErrInvalidSPS
+ }
+ info := SPSInfo{Profile: nalu[1], Compat: nalu[2], Level: nalu[3]}
+
+ r := bitReader{data: unescapeRBSP(nalu[4:])}
+ r.ue() // seq_parameter_set_id
+
+ // Defaults for profiles that do not code chroma_format_idc (7.3.2.1.1):
+ // 4:2:0 with luma and chroma coded together.
+ chromaFormatIDC := uint32(1)
+ separateColourPlane := false
+
+ switch info.Profile {
+ case 100, 110, 122, 244, 44, 83, 86, 118, 128, 138, 139, 134, 135:
+ chromaFormatIDC = r.ue()
+ if chromaFormatIDC == 3 {
+ separateColourPlane = r.flag()
+ }
+ r.ue() // bit_depth_luma_minus8
+ r.ue() // bit_depth_chroma_minus8
+ r.bit() // qpprime_y_zero_transform_bypass_flag
+ if r.flag() { // seq_scaling_matrix_present_flag
+ lists := 8
+ if chromaFormatIDC == 3 {
+ lists = 12
+ }
+ for i := 0; i < lists; i++ {
+ if !r.flag() {
+ continue
+ }
+ size := 16
+ if i >= 6 {
+ size = 64
+ }
+ skipScalingList(&r, size)
+ }
+ }
+ }
+
+ r.ue() // log2_max_frame_num_minus4
+ switch r.ue() { // pic_order_cnt_type
+ case 0:
+ r.ue() // log2_max_pic_order_cnt_lsb_minus4
+ case 1:
+ r.bit() // delta_pic_order_always_zero_flag
+ r.se() // offset_for_non_ref_pic
+ r.se() // offset_for_top_to_bottom_field
+ n := r.ue() // num_ref_frames_in_pic_order_cnt_cycle
+ if n > 255 {
+ return SPSInfo{}, ErrInvalidSPS
+ }
+ for range n {
+ r.se() // offset_for_ref_frame
+ }
+ }
+ r.ue() // max_num_ref_frames
+ r.bit() // gaps_in_frame_num_value_allowed_flag
+
+ widthMBs := r.ue() + 1 // pic_width_in_mbs_minus1
+ heightMUs := r.ue() + 1 // pic_height_in_map_units_minus1
+ frameMBsOnly := r.flag()
+ if !frameMBsOnly {
+ r.bit() // mb_adaptive_frame_field_flag
+ }
+ r.bit() // direct_8x8_inference_flag
+
+ var cropL, cropR, cropT, cropB uint32
+ if r.flag() { // frame_cropping_flag
+ cropL, cropR, cropT, cropB = r.ue(), r.ue(), r.ue(), r.ue()
+ }
+ if r.err {
+ return SPSInfo{}, ErrInvalidSPS
+ }
+
+ // Crop offsets count chroma sample units per Table 6-1; monochrome and
+ // separate-colour-plane content crops in luma samples. Field-coded content
+ // (frame_mbs_only_flag == 0) doubles both the frame height in map units
+ // and the vertical crop unit.
+ unitX, unitY := uint32(1), uint32(1)
+ if !separateColourPlane {
+ switch chromaFormatIDC {
+ case 1:
+ unitX, unitY = 2, 2
+ case 2:
+ unitX, unitY = 2, 1
+ }
+ }
+ frameHeightMul := uint32(2)
+ if frameMBsOnly {
+ frameHeightMul = 1
+ }
+ unitY *= frameHeightMul
+
+ width := widthMBs * 16
+ height := frameHeightMul * heightMUs * 16
+ cropX := unitX * (cropL + cropR)
+ cropY := unitY * (cropT + cropB)
+ if width > 16384 || height > 16384 || cropX >= width || cropY >= height {
+ return SPSInfo{}, ErrInvalidSPS
+ }
+ info.Width = uint16(width - cropX)
+ info.Height = uint16(height - cropY)
+ return info, nil
+}
+
+// skipScalingList consumes one scaling list (7.3.2.1.1.1); only the bit
+// positions matter here, not the scales.
+func skipScalingList(r *bitReader, size int) {
+ lastScale, nextScale := int32(8), int32(8)
+ for range size {
+ if nextScale != 0 {
+ nextScale = (lastScale + r.se() + 256) % 256
+ }
+ if nextScale != 0 {
+ lastScale = nextScale
+ }
+ }
+}
+
+// unescapeRBSP removes H.264 emulation-prevention bytes: each 0x03 that
+// follows two zero bytes is dropped.
+func unescapeRBSP(b []byte) []byte {
+ out := make([]byte, 0, len(b))
+ zeros := 0
+ for _, c := range b {
+ if zeros == 2 && c == 3 {
+ zeros = 0
+ continue
+ }
+ if c == 0 {
+ zeros++
+ } else {
+ zeros = 0
+ }
+ out = append(out, c)
+ }
+ return out
+}
+
+// bitReader reads bits most-significant first. Reading past the end sets err
+// and returns zeros, so a parse over truncated input fails once at the end
+// instead of needing a check per read.
+type bitReader struct {
+ data []byte
+ pos int // bit position
+ err bool
+}
+
+func (r *bitReader) bit() uint32 {
+ if r.pos >= len(r.data)*8 {
+ r.err = true
+ return 0
+ }
+ b := r.data[r.pos>>3] >> (7 - uint(r.pos&7)) & 1
+ r.pos++
+ return uint32(b)
+}
+
+func (r *bitReader) flag() bool { return r.bit() == 1 }
+
+// ue reads one unsigned exp-golomb code.
+func (r *bitReader) ue() uint32 {
+ zeros := 0
+ for r.bit() == 0 {
+ zeros++
+ if zeros > 31 || r.err {
+ r.err = true
+ return 0
+ }
+ }
+ v := uint32(1)
+ for i := 0; i < zeros; i++ {
+ v = v<<1 | r.bit()
+ }
+ return v - 1
+}
+
+// se reads one signed exp-golomb code.
+func (r *bitReader) se() int32 {
+ u := r.ue()
+ if u&1 == 1 {
+ return int32(u/2 + 1)
+ }
+ return -int32(u / 2)
+}
diff --git a/track/sps_test.go b/track/sps_test.go
new file mode 100644
index 0000000..fe0f121
--- /dev/null
+++ b/track/sps_test.go
@@ -0,0 +1,130 @@
+package track_test
+
+import (
+ "encoding/binary"
+ "fmt"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/tetsuo/mp4"
+ "github.com/tetsuo/mp4/track"
+)
+
+// spsFromStsd digs the first SPS out of the avcC inside a raw stsd box, the
+// same bytes an RTMP publisher sends in its AVC sequence header.
+func spsFromStsd(stsd []byte) []byte {
+ for i := 4; i+8 < len(stsd); i++ {
+ if string(stsd[i:i+4]) != "avcC" {
+ continue
+ }
+ p := stsd[i+4:]
+ // version, profile, compat, level, lengthSize, SPS count, SPS length.
+ if len(p) < 8 || p[0] != 1 {
+ return nil
+ }
+ n := int(binary.BigEndian.Uint16(p[6:8]))
+ if 8+n > len(p) {
+ return nil
+ }
+ return p[8 : 8+n]
+ }
+ return nil
+}
+
+// TestParseSPSAgainstParsedTracks checks ParseSPS against the sample-table
+// parser on every local H.264 sample: the SPS-derived dimensions and codec
+// bytes must match what the moov says.
+func TestParseSPSAgainstParsedTracks(t *testing.T) {
+ files, _ := filepath.Glob("../test-data/*.mp4")
+ if len(files) == 0 {
+ t.Skip("no sample files")
+ }
+ checked := 0
+ for _, path := range files {
+ moov, tracks := parseFile(t, path)
+ if moov == nil {
+ continue
+ }
+ for _, tr := range tracks {
+ if tr.Kind != track.TrackVideo || tr.Codec()[:4] != "avc1" {
+ continue
+ }
+ sps := spsFromStsd(tr.StsdRaw())
+ if sps == nil {
+ t.Errorf("%s: no SPS in stsd", path)
+ continue
+ }
+ info, err := track.ParseSPS(sps)
+ if err != nil {
+ t.Errorf("%s: ParseSPS: %v", path, err)
+ continue
+ }
+ if info.Width != tr.Width || info.Height != tr.Height {
+ t.Errorf("%s: SPS %dx%d, track %dx%d", path, info.Width, info.Height, tr.Width, tr.Height)
+ }
+ want := fmt.Sprintf("avc1.%02x%02x%02x", info.Profile, info.Compat, info.Level)
+ if got := tr.Codec(); got != want {
+ t.Errorf("%s: SPS codec %q, track codec %q", path, want, got)
+ }
+ checked++
+ }
+ }
+ if checked == 0 {
+ t.Fatal("no H.264 tracks checked")
+ }
+}
+
+// parseFile parses path's moov into tracks, returning nils when the file has
+// none (not an error: some samples are other codecs or formats).
+func parseFile(t *testing.T, path string) ([]byte, []*track.Track) {
+ t.Helper()
+ f, err := os.Open(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer f.Close()
+ sc := mp4.NewScanner(f)
+ for sc.Next() {
+ e := sc.Entry()
+ if e.Type != mp4.TypeMoov {
+ continue
+ }
+ buf := make([]byte, e.Size)
+ if err := sc.ReadBox(buf); err != nil {
+ t.Fatal(err)
+ }
+ tracks, _, _, err := track.ParseTracks(buf)
+ if err != nil {
+ t.Fatal(err)
+ }
+ return buf, tracks
+ }
+ return nil, nil
+}
+
+func TestParseSPSRejectsMalformed(t *testing.T) {
+ cases := [][]byte{
+ nil,
+ {0x67},
+ {0x67, 0x64, 0x00}, // too short for profile bytes
+ {0x68, 0x64, 0x00, 0x1f, 0xac}, // PPS, not SPS
+ {0x67, 0x64, 0x00, 0x1f}, // no RBSP at all
+ }
+ for _, c := range cases {
+ if _, err := track.ParseSPS(c); err == nil {
+ t.Errorf("ParseSPS(%x): no error", c)
+ }
+ }
+}
+
+func FuzzParseSPS(f *testing.F) {
+ f.Add([]byte{0x67, 0x64, 0x00, 0x1f, 0xac, 0xd9, 0x40, 0x50, 0x05, 0xbb, 0x01, 0x6c, 0x80, 0x00, 0x00, 0x03, 0x00, 0x80, 0x00, 0x00, 0x1e, 0x07, 0x8c, 0x18, 0xcb})
+ f.Add([]byte{0x67, 0x42, 0xc0, 0x1e, 0xd9, 0x00, 0xb4, 0x3d, 0xa1, 0x00, 0x00, 0x03, 0x00, 0x01})
+ f.Fuzz(func(t *testing.T, data []byte) {
+ info, err := track.ParseSPS(data)
+ if err == nil && (info.Width == 0 || info.Height == 0) {
+ t.Fatalf("accepted SPS with zero dimension: %+v", info)
+ }
+ })
+}