aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-09-15 00:06:50 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-09-15 00:06:50 +0200
commit63391b66a7c5d10e84d4d8c64510e3620152dc26 (patch)
tree0197f7361113f47a74e037c0e12f5cb180e3ebd8
parentc2eabe534a236ec52e4aaecc51cceb4e70ba3d20 (diff)
downloadmp4-63391b66a7c5d10e84d4d8c64510e3620152dc26.tar.gz
mp4-63391b66a7c5d10e84d4d8c64510e3620152dc26.zip
track: expose richer stream metadata
-rw-r--r--box.go2
-rw-r--r--track/codec_test.go57
-rw-r--r--track/display_test.go40
-rw-r--r--track/ffprobe_test.go190
-rw-r--r--track/track.go105
5 files changed, 366 insertions, 28 deletions
diff --git a/box.go b/box.go
index 9476a44..7c4021d 100644
--- a/box.go
+++ b/box.go
@@ -100,7 +100,9 @@ var (
TypeAv1C = BoxType{'a', 'v', '1', 'C'} // AV1 codec configuration record
TypeBtrt = BoxType{'b', 't', 'r', 't'} // MPEG-4 bit rate
TypePasp = BoxType{'p', 'a', 's', 'p'} // Pixel aspect ratio
+ TypeColr = BoxType{'c', 'o', 'l', 'r'} // Color information
TypeMp4a = BoxType{'m', 'p', '4', 'a'} // MPEG-4 audio sample entry
+ TypeAlac = BoxType{'a', 'l', 'a', 'c'} // Apple Lossless audio sample entry
TypeEsds = BoxType{'e', 's', 'd', 's'} // ES descriptor
)
diff --git a/track/codec_test.go b/track/codec_test.go
index 182c445..2552d4c 100644
--- a/track/codec_test.go
+++ b/track/codec_test.go
@@ -1,27 +1,44 @@
-package track
+package track_test
-import "testing"
+import (
+ "testing"
-func TestAppendAv1CProfile(t *testing.T) {
- tests := []struct {
- name string
- rec []byte
+ "github.com/tetsuo/mp4/track"
+)
+
+// TestParseAV1CodecString checks the av01 codec string the track parser derives
+// from the av1C configuration record for each combination of seq_profile,
+// seq_level_idx, seq_tier, and bit depth. The fixtures are produced by
+// test-data/generate-av1.sh and skipped when absent.
+func TestParseAV1CodecString(t *testing.T) {
+ cases := []struct {
+ file string
want string
}{
- // rec[1] = seq_profile<<5 | seq_level_idx
- // rec[2] = seq_tier<<7 | high_bitdepth<<6 | twelve_bit<<5
- {"main 8-bit level 8", []byte{0x81, 0x08, 0x00, 0x00}, "av01.0.08M.08"},
- {"main 8-bit level 12", []byte{0x81, 0x0c, 0x00, 0x00}, "av01.0.12M.08"},
- {"high tier 10-bit", []byte{0x81, 0x0c, 0xc0, 0x00}, "av01.0.12H.10"},
- {"profile 2 12-bit", []byte{0x81, 0x48, 0x60, 0x00}, "av01.2.08M.12"},
+ {"../test-data/av1-main8-level8.mp4", "av01.0.08M.08"},
+ {"../test-data/av1-main8-level12.mp4", "av01.0.12M.08"},
+ {"../test-data/av1-hightier10.mp4", "av01.0.12H.10"},
+ {"../test-data/av1-profile2-12bit.mp4", "av01.2.08M.12"},
}
- for _, tt := range tests {
- tr := &Track{}
- tr.setCodec("av01")
- tr.appendAv1CProfile(tt.rec)
- got := string(tr.raw.codecBuf[:tr.raw.codecLen])
- if got != tt.want {
- t.Errorf("%s: got %q, want %q", tt.name, got, tt.want)
- }
+ for _, tc := range cases {
+ t.Run(tc.want, func(t *testing.T) {
+ tracks, _, _, err := track.ParseTracks(readMoov(t, tc.file))
+ if err != nil {
+ t.Fatal(err)
+ }
+ var vt *track.Track
+ for _, tr := range tracks {
+ if tr.Kind == track.TrackVideo {
+ vt = tr
+ break
+ }
+ }
+ if vt == nil {
+ t.Fatal("no video track parsed")
+ }
+ if got := vt.Codec(); got != tc.want {
+ t.Errorf("Codec() = %q, want %q", got, tc.want)
+ }
+ })
}
}
diff --git a/track/display_test.go b/track/display_test.go
new file mode 100644
index 0000000..aae4739
--- /dev/null
+++ b/track/display_test.go
@@ -0,0 +1,40 @@
+package track_test
+
+import (
+ "bytes"
+ "encoding/binary"
+ "testing"
+
+ "github.com/tetsuo/mp4/track"
+)
+
+func TestCodedDimensionsStaySeparateFromTrackHeaderDisplayDimensions(t *testing.T) {
+ moov := readMoov(t, "../test-data/h264-aac-10s.mp4")
+ marker := bytes.Index(moov, []byte("tkhd"))
+ if marker < 0 || marker+88 > len(moov) {
+ t.Fatal("fixture has no usable tkhd")
+ }
+ version := moov[marker+4]
+ offset := marker + 8 + 72
+ if version == 1 {
+ offset = marker + 8 + 84
+ }
+ if offset+8 > len(moov) {
+ t.Fatal("truncated tkhd")
+ }
+ binary.BigEndian.PutUint32(moov[offset:], 1111<<16)
+ binary.BigEndian.PutUint32(moov[offset+4:], 777<<16)
+
+ tracks, _, _, err := track.ParseTracks(moov)
+ if err != nil {
+ t.Fatal(err)
+ }
+ video := tracks[0]
+ if video.DisplayWidth != 1111 || video.DisplayHeight != 777 {
+ t.Fatalf("display dimensions = %dx%d", video.DisplayWidth, video.DisplayHeight)
+ }
+ if video.Width == video.DisplayWidth || video.Height == video.DisplayHeight {
+ t.Fatalf("coded dimensions were overwritten: coded=%dx%d display=%dx%d",
+ video.Width, video.Height, video.DisplayWidth, video.DisplayHeight)
+ }
+}
diff --git a/track/ffprobe_test.go b/track/ffprobe_test.go
new file mode 100644
index 0000000..9afd33b
--- /dev/null
+++ b/track/ffprobe_test.go
@@ -0,0 +1,190 @@
+package track_test
+
+import (
+ "encoding/json"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "strconv"
+ "strings"
+ "testing"
+
+ "github.com/tetsuo/mp4"
+ "github.com/tetsuo/mp4/track"
+)
+
+type ffStream struct {
+ CodecType string `json:"codec_type"`
+ CodecName string `json:"codec_name"`
+ Width int `json:"width"`
+ Height int `json:"height"`
+ SampleRate string `json:"sample_rate"`
+ Channels int `json:"channels"`
+ NbFrames string `json:"nb_frames"`
+}
+
+type ffProbe struct {
+ Streams []ffStream `json:"streams"`
+}
+
+// codecFamily maps an RFC 6381 codec string to the codec name ffprobe reports.
+func codecFamily(codec string) string {
+ switch {
+ case strings.HasPrefix(codec, "avc1"):
+ return "h264"
+ case strings.HasPrefix(codec, "av01"):
+ return "av1"
+ case strings.HasPrefix(codec, "mp4a"):
+ return "aac"
+ }
+ return codec
+}
+
+func readMoov(t *testing.T, path string) []byte {
+ t.Helper()
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Skipf("test file not available: %v", err)
+ }
+ r := mp4.NewReader(data)
+ for r.Next() {
+ if r.Type() == mp4.TypeMoov {
+ return append([]byte(nil), r.RawBox()...)
+ }
+ }
+ t.Fatalf("no moov box in %s", path)
+ return nil
+}
+
+func atoi(t *testing.T, s string) int {
+ t.Helper()
+ n, err := strconv.Atoi(strings.TrimSpace(s))
+ if err != nil {
+ t.Fatalf("parse %q: %v", s, err)
+ }
+ return n
+}
+
+// TestParityWithFFprobe checks the parser against ffprobe for each sample file:
+// the audio+video stream count, codec family, video dimensions, audio sample
+// rate, per-track sample count, and the video sync-sample count against
+// ffprobe's keyframe count. It is skipped when ffprobe or a file is absent.
+func TestParityWithFFprobe(t *testing.T) {
+ if _, err := exec.LookPath("ffprobe"); err != nil {
+ t.Skip("ffprobe not installed")
+ }
+
+ files := []string{
+ "../test-data/h264-aac-10s.mp4",
+ "../test-data/h264-aac-60s.mp4",
+ "../test-data/aac-stereo-2s.m4a",
+ "../test-data/alac-5.1-2s.m4a",
+ }
+ for _, path := range files {
+ t.Run(filepath.Base(path), func(t *testing.T) {
+ if _, err := os.Stat(path); err != nil {
+ t.Skipf("test file not available: %v", err)
+ }
+
+ tracks, _, _, err := track.ParseTracks(readMoov(t, path))
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ out, err := exec.Command("ffprobe", "-v", "error",
+ "-print_format", "json", "-show_streams", path).Output()
+ if err != nil {
+ t.Fatalf("ffprobe: %v", err)
+ }
+ var probe ffProbe
+ if err := json.Unmarshal(out, &probe); err != nil {
+ t.Fatal(err)
+ }
+
+ var ffVideo, ffAudio *ffStream
+ ffCount := 0
+ for i := range probe.Streams {
+ switch probe.Streams[i].CodecType {
+ case "video":
+ ffVideo = &probe.Streams[i]
+ ffCount++
+ case "audio":
+ ffAudio = &probe.Streams[i]
+ ffCount++
+ }
+ }
+ if len(tracks) != ffCount {
+ t.Fatalf("track count = %d, ffprobe audio+video streams = %d", len(tracks), ffCount)
+ }
+
+ var libVideo, libAudio *track.Track
+ for _, tr := range tracks {
+ switch tr.Kind {
+ case track.TrackVideo:
+ libVideo = tr
+ case track.TrackAudio:
+ libAudio = tr
+ }
+ }
+
+ if ffVideo != nil {
+ if libVideo == nil {
+ t.Fatal("ffprobe found a video stream, parser did not")
+ }
+ if got := codecFamily(libVideo.Codec()); got != ffVideo.CodecName {
+ t.Errorf("video codec = %q (%q), ffprobe = %q", libVideo.Codec(), got, ffVideo.CodecName)
+ }
+ if int(libVideo.Width) != ffVideo.Width || int(libVideo.Height) != ffVideo.Height {
+ t.Errorf("video dimensions = %dx%d, ffprobe = %dx%d",
+ libVideo.Width, libVideo.Height, ffVideo.Width, ffVideo.Height)
+ }
+ if n := atoi(t, ffVideo.NbFrames); n != len(libVideo.Samples) {
+ t.Errorf("video sample count = %d, ffprobe frames = %d", len(libVideo.Samples), n)
+ }
+ sync := 0
+ for i := range libVideo.Samples {
+ if libVideo.Samples[i].IsSync() {
+ sync++
+ }
+ }
+ if kf := ffprobeKeyframes(t, path); sync != kf {
+ t.Errorf("video sync samples = %d, ffprobe keyframes = %d", sync, kf)
+ }
+ }
+
+ if ffAudio != nil {
+ if libAudio == nil {
+ t.Fatal("ffprobe found an audio stream, parser did not")
+ }
+ if got := codecFamily(libAudio.Codec()); got != ffAudio.CodecName {
+ t.Errorf("audio codec = %q (%q), ffprobe = %q", libAudio.Codec(), got, ffAudio.CodecName)
+ }
+ if sr := atoi(t, ffAudio.SampleRate); sr != int(libAudio.SampleRate) {
+ t.Errorf("audio sample rate = %d, ffprobe = %d", libAudio.SampleRate, sr)
+ }
+ if int(libAudio.ChannelCount) != ffAudio.Channels {
+ t.Errorf("audio channel count = %d, ffprobe = %d", libAudio.ChannelCount, ffAudio.Channels)
+ }
+ if n := atoi(t, ffAudio.NbFrames); n != len(libAudio.Samples) {
+ t.Errorf("audio sample count = %d, ffprobe frames = %d", len(libAudio.Samples), n)
+ }
+ }
+ })
+ }
+}
+
+// ffprobeKeyframes counts the keyframes in the first video stream.
+func ffprobeKeyframes(t *testing.T, path string) int {
+ t.Helper()
+ out, err := exec.Command("ffprobe", "-v", "error", "-select_streams", "v:0",
+ "-skip_frame", "nokey", "-show_entries", "frame=pts_time",
+ "-of", "csv=p=0", path).Output()
+ if err != nil {
+ t.Fatalf("ffprobe keyframes: %v", err)
+ }
+ trimmed := strings.TrimSpace(string(out))
+ if trimmed == "" {
+ return 0
+ }
+ return strings.Count(trimmed, "\n") + 1
+}
diff --git a/track/track.go b/track/track.go
index f2e23ec..11dfd00 100644
--- a/track/track.go
+++ b/track/track.go
@@ -1,6 +1,7 @@
package track
import (
+ "encoding/binary"
"errors"
"fmt"
@@ -58,10 +59,22 @@ type Track struct {
TimeScale uint32
Duration uint64
- Width uint16
- Height uint16
- ChannelCount uint16
- SampleRate uint32
+ Width uint16
+ Height uint16
+ DisplayWidth uint16
+ DisplayHeight uint16
+ ChannelCount uint16
+ SampleRate uint32
+ SampleSize uint16
+
+ PixelAspectHorizontal uint32
+ PixelAspectVertical uint32
+ ColorPrimaries uint16
+ ColorTransfer uint16
+ ColorMatrix uint16
+ FullColorRange bool
+ HasColor bool
+ RotationDegrees uint16
Samples []Sample
SampleDescIdx uint32
@@ -444,8 +457,9 @@ func parseTrakInto(mr *mp4.Reader, track *Track) bool {
track.raw.tkhd = mr.Data()
trackId, _, w, h := mr.ReadTkhd()
track.ID = trackId
- track.Width = uint16(w >> 16)
- track.Height = uint16(h >> 16)
+ track.DisplayWidth = uint16(w >> 16)
+ track.DisplayHeight = uint16(h >> 16)
+ track.RotationDegrees = tkhdRotation(track.raw.tkhd, track.raw.tkhdVersion)
case mp4.TypeEdts:
parseEdts(mr, track)
case mp4.TypeMdia:
@@ -581,18 +595,32 @@ func parseStsd(mr *mp4.Reader, track *Track, handlerType [4]byte) {
return
}
v := mp4.ReadVisualSampleEntry(entryData)
+ children := visualChildren(mr, v.ChildOffset)
track.Width = v.Width
track.Height = v.Height
+ if d := children.pasp; len(d) >= 8 {
+ track.PixelAspectHorizontal = binary.BigEndian.Uint32(d[0:4])
+ track.PixelAspectVertical = binary.BigEndian.Uint32(d[4:8])
+ }
+ if d := children.colr; len(d) >= 10 && (string(d[:4]) == "nclx" || string(d[:4]) == "nclc") {
+ track.ColorPrimaries = binary.BigEndian.Uint16(d[4:6])
+ track.ColorTransfer = binary.BigEndian.Uint16(d[6:8])
+ track.ColorMatrix = binary.BigEndian.Uint16(d[8:10])
+ track.HasColor = true
+ if len(d) >= 11 && string(d[:4]) == "nclx" {
+ track.FullColorRange = d[10]&0x80 != 0
+ }
+ }
switch entryType {
case mp4.TypeAvc1:
track.setCodec("avc1")
- if d := childBox(mr, v.ChildOffset, mp4.TypeAvcC); len(d) >= 4 {
+ if d := children.avcC; len(d) >= 4 {
track.appendCodec(".")
track.appendAvcCProfile(d[1], d[2], d[3])
}
case mp4.TypeAv01:
track.setCodec("av01")
- if d := childBox(mr, v.ChildOffset, mp4.TypeAv1C); len(d) >= 3 {
+ if d := children.av1C; len(d) >= 3 {
track.appendAv1CProfile(d)
}
default:
@@ -607,10 +635,19 @@ func parseStsd(mr *mp4.Reader, track *Track, handlerType [4]byte) {
a := mp4.ReadAudioSampleEntry(entryData)
track.ChannelCount = a.ChannelCount
track.SampleRate = a.SampleRate >> 16
+ track.SampleSize = a.SampleSize
if d := childBox(mr, a.ChildOffset, mp4.TypeEsds); d != nil {
track.appendEsdsCodec(d)
}
}
+ case mp4.TypeAlac:
+ track.setCodec("alac")
+ if len(entryData) >= 28 {
+ a := mp4.ReadAudioSampleEntry(entryData)
+ track.ChannelCount = a.ChannelCount
+ track.SampleRate = a.SampleRate >> 16
+ track.SampleSize = a.SampleSize
+ }
default:
track.setCodec(entryType.String())
}
@@ -620,6 +657,58 @@ func parseStsd(mr *mp4.Reader, track *Track, handlerType [4]byte) {
}
}
+type visualSampleChildren struct {
+ avcC []byte
+ av1C []byte
+ pasp []byte
+ colr []byte
+}
+
+func visualChildren(mr *mp4.Reader, childOffset int) visualSampleChildren {
+ var children visualSampleChildren
+ mr.Enter()
+ defer mr.Exit()
+ mr.Skip(childOffset)
+ for mr.Next() {
+ switch mr.Type() {
+ case mp4.TypeAvcC:
+ children.avcC = mr.Data()
+ case mp4.TypeAv1C:
+ children.av1C = mr.Data()
+ case mp4.TypePasp:
+ children.pasp = mr.Data()
+ case mp4.TypeColr:
+ children.colr = mr.Data()
+ }
+ }
+ return children
+}
+
+func tkhdRotation(data []byte, version uint8) uint16 {
+ offset := 36
+ if version == 1 {
+ offset = 48
+ }
+ if offset+20 > len(data) {
+ return 0
+ }
+ a := int32(binary.BigEndian.Uint32(data[offset:]))
+ b := int32(binary.BigEndian.Uint32(data[offset+4:]))
+ c := int32(binary.BigEndian.Uint32(data[offset+12:]))
+ d := int32(binary.BigEndian.Uint32(data[offset+16:]))
+ const one = int32(1 << 16)
+ switch {
+ case a == 0 && b == one && c == -one && d == 0:
+ return 90
+ case a == -one && b == 0 && c == 0 && d == -one:
+ return 180
+ case a == 0 && b == -one && c == one && d == 0:
+ return 270
+ default:
+ return 0
+ }
+}
+
// childBox enters the current sample entry, skips its fixed header of
// childOffset bytes, and returns the data of the first child box of boxType, or
// nil if none is found.