Handle negative ctts sample_offset values in mp4 parsing

Summary:
Some encodings like H.264 and H.265 support negative offsets.
We cannot rely on the version field since some encoders incorrectly set
ctts version to 0 instead of 1 even when using signed offsets.
Leigitimate positive values are relatively small so we can assume the value is signed.

The unsigned to signed conversion could have been gated based on the encoding. However I chose not to since large positive values exceeding 2^31 is unrealistic.

For reference the stsd and ctts boxes from a video:

stsd box: Container:
    size = 233
    type = b'stsd' (total 4)
    data = Container:
        version = 0
        flags = 0
        entries = ListContainer:
            Container:
                format = b'hvc1' (total 4)

ctts box Container:
    size = 128480
    type = b'ctts' (total 4)
    data = Container:
        version = 0
        flags = 0
        entries = ListContainer:
            Container:
                sample_count = 1
                sample_offset = 0
            Container:
                sample_count = 1
                sample_offset = 60
            Container:
                sample_count = 1
                sample_offset = 0
            Container:
                sample_count = 1
                sample_offset = 4294967256
            Container:
                sample_count = 1
                sample_offset = 4294967276

Author: caglarpir

mapillary_tools/mp4/mp4_sample_parser.py

@@ -7,6 +7,14 @@
 from . import construct_mp4_parser as cparser, simple_mp4_parser as sparser
 
 
+def _convert_to_signed_int32(unsigned_int32: int) -> int:
+    """Interpret an unsigned 32-bit value as negative if high bit is set."""
+    if (unsigned_int32 & (1 << 31)) == 0:
+        return unsigned_int32
+    else:
+        return unsigned_int32 - (1 << 32)
+
+
 class RawSample(T.NamedTuple):
     # 1-based index
     description_idx: int
@@ -192,7 +200,13 @@ def extract_raw_samples_from_stbl_data(
             composition_offsets = []
             for entry in data["entries"]:
                 for _ in range(entry["sample_count"]):
-                    composition_offsets.append(entry["sample_offset"])
+                    # Some encodings like H.264 and H.265 support negative offsets.
+                    # We cannot rely on the version field since some encoders incorrectly set
+                    # ctts version to 0 instead of 1 even when using signed offsets.
+                    # Leigitimate positive values are relatively small so we can assume the value is signed.
+                    composition_offsets.append(
+                        _convert_to_signed_int32(entry["sample_offset"])
+                    )
         elif box["type"] == b"stss":
             syncs = set(data["entries"])
 

tests/data/videos/sample-5s_h265.mp4

@@ -52,3 +52,16 @@ def test_movie_box_parser():
         assert sample.raw_sample.offset == raw_sample.offset
         assert sample.raw_sample.is_sync == raw_sample.is_sync
         assert sample.raw_sample.size == raw_sample.size
+
+
+def test_movie_box_parser_negative_composition_offset():
+    moov_parser = mp4_sample_parser.MovieBoxParser.parse_file(
+        Path("tests/data/videos/sample-5s_h265.mp4")
+    )
+    assert 2 == len(list(moov_parser.extract_tracks()))
+    video_track = moov_parser.extract_track_at(0)
+    assert video_track.is_video_track()
+    raw_samples = list(video_track.extract_raw_samples())
+    assert 146 == len(raw_samples)
+    # Make sure the parser can parse negative composition offsets
+    assert 0 < len([s for s in raw_samples if s.composition_offset < 0])