format_parser 2.1.0 → 2.2.0

data/lib/parsers/iso_base_media_file_format/decoder.rb

@@ -0,0 +1,1041 @@
+# This class provides generic methods for parsing file formats based on QuickTime-style "atoms", such as those seen in
+# the ISO base media file format (ISO/IEC 14496-12), a.k.a MPEG-4, and those that extend it (MP4, CR3, HEIF, etc.).
+#
+# For more information on atoms, see https://developer.apple.com/library/archive/documentation/QuickTime/QTFF/QTFFChap1/qtff1.html
+# or https://b.goeswhere.com/ISO_IEC_14496-12_2015.pdf.
+#
+# TODO: The vast majority of the methods have been commented out here. This decision was taken to expedite the release
+#   of support for the CR3 format, such that it was not blocked by the undertaking of testing this class in its
+#   entirety. We should migrate existing formats that are based on the ISO base media file format and reintroduce these
+#   methods with tests down-the-line.
+
+module FormatParser
+  module ISOBaseMediaFileFormat
+    class Decoder
+      include FormatParser::IOUtils
+
+      class Atom < Struct.new(:type, :position, :size, :fields, :children)
+        def initialize(type, position, size, fields = nil, children = nil)
+          super
+          self.fields ||= {}
+          self.children ||= []
+        end
+
+        # Find and return the first descendent (using depth-first search) of a given type.
+        #
+        # @param [Array<String>] types
+        # @return [Atom, nil]
+        def find_first_descendent(types)
+          children.each do |child|
+            return child if types.include?(child.type)
+            if (descendent = child.find_first_descendent(types))
+              return descendent
+            end
+          end
+          nil
+        end
+
+        # Find and return all descendents of a given type.
+        #
+        # @param [Array<String>] types
+        # @return [Array<Atom>]
+        def select_descendents(types)
+          children.map do |child|
+            descendents = child.select_descendents(types)
+            types.include?(child.type) ? [child] + descendents : descendents
+          end.flatten
+        end
+      end
+
+      # @param [Integer] max_read
+      # @param [IO, FormatParser::IOConstraint] io
+      # @return [Array<Atom>]
+      def build_atom_tree(max_read, io = nil)
+        @buf = FormatParser::IOConstraint.new(io) if io
+        raise ArgumentError, "IO missing - supply a valid IO object" unless @buf
+        atoms = []
+        max_pos = @buf.pos + max_read
+        loop do
+          break if @buf.pos >= max_pos
+          atom = parse_atom
+          break unless atom
+          atoms << atom
+        end
+        atoms
+      end
+
+      protected
+
+      # A mapping of atom types to their respective parser methods. Each method must take a single Integer parameter, size,
+      # and return the atom's fields and children where appropriate as a Hash and Array of Atoms respectively.
+      ATOM_PARSERS = {
+        # 'bxml' => :bxml,
+        # 'co64' => :co64,
+        # 'cprt' => :cprt,
+        # 'cslg' => :cslg,
+        # 'ctts' => :ctts,
+        'dinf' => :container,
+        # 'dref' => :dref,
+        'edts' => :container,
+        # 'fecr' => :fecr,
+        # 'fiin' => :fiin,
+        # 'fire' => :fire,
+        # 'fpar' => :fpar,
+        # 'ftyp' => :typ,
+        # 'gitn' => :gitn,
+        # 'hdlr' => :hdlr,
+        # 'hmhd' => :hmhd,
+        # 'iinf' => :iinf,
+        # 'iloc' => :iloc,
+        # 'infe' => :infe,
+        # 'ipro' => :ipro,
+        # 'iref' => :iref,
+        # 'leva' => :leva,
+        # 'mdhd' => :mdhd,
+        'mdia' => :container,
+        'meco' => :container,
+        # 'mehd' => :mehd,
+        # 'mere' => :mere,
+        # 'meta' => :meta,
+        # 'mfhd' => :mfhd,
+        'mfra' => :container,
+        # 'mfro' => :mfro,
+        'minf' => :container,
+        'moof' => :container,
+        'moov' => :container,
+        'mvex' => :container,
+        # 'mvhd' => :mvhd,
+        'nmhd' => :empty,
+        # 'padb' => :padb,
+        'paen' => :container,
+        # 'pdin' => :pdin,
+        # 'pitm' => :pitm,
+        # 'prft' => :prft,
+        # 'saio' => :saio,
+        # 'saiz' => :saiz,
+        # 'sbgp' => :sbgp,
+        'schi' => :container,
+        # 'schm' => :schm,
+        # 'sdtp' => :sdtp,
+        # 'segr' => :segr,
+        # 'sgpd' => :sgpd,
+        # 'sidx' => :sidx,
+        'sinf' => :container,
+        # 'smhd' => :smhd,
+        # 'ssix' => :ssix,
+        'stbl' => :container,
+        # 'stco' => :stco,
+        # 'stdp' => :stdp,
+        'sthd' => :empty,
+        'strd' => :container,
+        # 'stri' => :stri,
+        'strk' => :container,
+        # 'stsc' => :stsc,
+        # 'stsd' => :stsd,
+        # 'stsh' => :stsh,
+        # 'stss' => :stss,
+        # 'stsz' => :stsz,
+        # 'stts' => :stts,
+        # 'styp' => :typ,
+        # 'stz2' => :stz2,
+        # 'subs' => :subs,
+        # 'tfra' => :tfra,
+        # 'tkhd' => :tkhd,
+        'trak' => :container,
+        # 'trex' => :trex,
+        # 'tsel' => :tsel,
+        'udta' => :container,
+        # 'url ' => :dref_url,
+        # 'urn ' => :dref_urn,
+        'uuid' => :uuid,
+        # 'vmhd' => :vmhd,
+        # 'xml ' => :xml,
+      }
+
+      # Parse the atom at the IO's current position.
+      #
+      # @return [Atom, nil]
+      def parse_atom
+        position = @buf.pos
+
+        size = read_int_32
+        type = read_string(4)
+        size = read_int_64 if size == 1
+        body_size = size - (@buf.pos - position)
+        next_atom_position = position + size
+
+        if self.class::ATOM_PARSERS.include?(type)
+          fields, children = method(self.class::ATOM_PARSERS[type]).call(body_size)
+          if @buf.pos != next_atom_position
+            # We should never end up in this state. If we do, it likely indicates a bug in the atom's parser method.
+            warn("Unexpected IO position after parsing #{type} atom at position #{position}. Atom size: #{size}. Expected position: #{next_atom_position}. Actual position: #{@buf.pos}.")
+            @buf.seek(next_atom_position)
+          end
+          Atom.new(type, position, size, fields, children)
+        else
+          skip_bytes(body_size)
+          Atom.new(type, position, size)
+        end
+      rescue FormatParser::IOUtils::InvalidRead
+        nil
+      end
+
+      # Parse any atom that serves as a container, with only children and no fields of its own.
+      def container(size)
+        [nil, build_atom_tree(size)]
+      end
+
+      # Parse only an atom's version and flags, skipping the remainder of the atom's body.
+      def empty(size)
+        fields = read_version_and_flags
+        skip_bytes(size - 4)
+        [fields, nil]
+      end
+
+      # Parse a binary XML atom.
+      # def bxml(size)
+      #   fields = read_version_and_flags.merge({
+      #     data: (size - 4).times.map { read_int_8 }
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a chunk large offset atom.
+      # def co64(_)
+      #   fields = read_version_and_flags
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map { { chunk_offset: read_int_64 } }
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a copyright atom.
+      # def cprt(size)
+      #   fields = read_version_and_flags
+      #   tmp = read_int_16
+      #   fields.merge!({
+      #     language: [(tmp >> 10) & 0x1F, (tmp >> 5) & 0x1F, tmp & 0x1F],
+      #     notice: read_string(size - 6)
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a composition to decode atom.
+      # def cslg(_)
+      #   fields = read_version_and_flags
+      #   version = fields[:version]
+      #   fields.merge!({
+      #     composition_to_dts_shift: version == 1 ? read_int_64 : read_int_32,
+      #     least_decode_to_display_delta: version == 1 ? read_int_64 : read_int_32,
+      #     greatest_decode_to_display_delta: version == 1 ? read_int_64 : read_int_32,
+      #     composition_start_time: version == 1 ? read_int_64 : read_int_32,
+      #     composition_end_time: version == 1 ? read_int_64 : read_int_32,
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a composition time to sample atom.
+      # def ctts(_)
+      #   fields = read_version_and_flags
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map do
+      #       {
+      #         sample_count: read_int_32,
+      #         sample_offset: read_int_32
+      #       }
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a data reference atom.
+      # def dref(size)
+      #   fields = read_version_and_flags.merge({
+      #     entry_count: read_int_32
+      #   })
+      #   [fields, build_atom_tree(size - 8)]
+      # end
+
+      # Parse a data reference URL entry atom.
+      # def dref_url(size)
+      #   fields = read_version_and_flags.merge({
+      #     location: read_string(size - 4)
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a data reference URN entry atom.
+      # def dref_urn(size)
+      #   fields = read_version_and_flags
+      #   name, location = read_bytes(size - 4).unpack('Z2')
+      #   fields.merge!({
+      #     name: name,
+      #     location: location
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse an FEC reservoir atom.
+      # def fecr(_)
+      #   fields = read_version_and_flags
+      #   version = fields[:version]
+      #   entry_count = version == 0 ? read_int_16 : read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map do
+      #       {
+      #         item_id: version == 0 ? read_int_16 : read_int_32,
+      #         symbol_count: read_int_8
+      #       }
+      #     end
+      #   })
+      # end
+
+      # Parse an FD item information atom.
+      # def fiin(size)
+      #   fields = read_version_and_flags.merge({
+      #     entry_count: read_int_16
+      #   })
+      #   [fields, build_atom_tree(size - 6)]
+      # end
+
+      # Parse a file reservoir atom.
+      # def fire(_)
+      #   fields = read_version_and_flags
+      #   entry_count = version == 0 ? read_int_16 : read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map do
+      #       {
+      #         item_id: version == 0 ? read_int_16 : read_int_32,
+      #         symbol_count: read_int_32
+      #       }
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a file partition atom.
+      # def fpar(_)
+      #   fields = read_version_and_flags
+      #   version = fields[:version]
+      #   fields.merge!({
+      #     item_id: version == 0 ? read_int_16 : read_int_32,
+      #     packet_payload_size: read_int_16,
+      #     fec_encoding_id: skip_bytes(1) { read_int_8 },
+      #     fec_instance_id: read_int_16,
+      #     max_source_block_length: read_int_16,
+      #     encoding_symbol_length: read_int_16,
+      #     max_number_of_encoding_symbols: read_int_16,
+      #   })
+      #   # TODO: Parse scheme_specific_info, entry_count and entries { block_count, block_size }.
+      #   skip_bytes(size - 20)
+      #   skip_bytes(2) if version == 0
+      #   [fields, nil]
+      # end
+
+      # Parse a group ID to name atom.
+      # def gitn(size)
+      #   fields = read_version_and_flags
+      #   entry_count = read_int_16
+      #   fields.merge!({
+      #     entry_count: entry_count
+      #   })
+      #   # TODO: Parse entries.
+      #   skip_bytes(size - 6)
+      #   [fields, nil]
+      # end
+
+      # Parse a handler atom.
+      # def hdlr(size)
+      #   fields = read_version_and_flags.merge({
+      #     handler_type: skip_bytes(4) { read_int_32 },
+      #     name: skip_bytes(12) { read_string(size - 24) }
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a hint media header atom.
+      # def hmhd(_)
+      #   fields = read_version_and_flags.merge({
+      #     max_pdu_size: read_int_16,
+      #     avg_pdu_size: read_int_16,
+      #     max_bitrate: read_int_32,
+      #     avg_bitrate: read_int_32
+      #   })
+      #   skip_bytes(4)
+      #   [fields, nil]
+      # end
+
+      # Parse an item info atom.
+      # def iinf(size)
+      #   fields = read_version_and_flags.merge({
+      #     entry_count: version == 0 ? read_int_16 : read_int_32
+      #   })
+      #   [fields, build_atom_tree(size - 8)]
+      # end
+
+      # Parse an item location atom.
+      # def iloc(_)
+      #   fields = read_version_and_flags
+      #   tmp = read_int_16
+      #   item_count = if version < 2
+      #     read_int_16
+      #   elsif version == 2
+      #     read_int_32
+      #   end
+      #   offset_size = (tmp >> 12) & 0x7
+      #   length_size = (tmp >> 8) & 0x7
+      #   base_offset_size = (tmp >> 4) & 0x7
+      #   index_size = tmp & 0x7
+      #   fields.merge!({
+      #     offset_size: offset_size,
+      #     length_size: length_size,
+      #     base_offset_size: base_offset_size,
+      #     item_count: item_count,
+      #     items: item_count.times.map do
+      #       item = {
+      #         item_id: if version < 2
+      #           read_int_16
+      #         elsif version == 2
+      #           read_int_32
+      #         end
+      #       }
+      #       item[:construction_method] = read_int_16 & 0x7 if version == 1 || version == 2
+      #       item[:data_reference_index] = read_int_16
+      #       skip_bytes(base_offset_size) # TODO: Dynamically parse base_offset based on base_offset_size
+      #       extent_count = read_int_16
+      #       item[:extent_count] = extent_count
+      #       # TODO: Dynamically parse extent_index, extent_offset and extent_length based on their respective sizes.
+      #       skip_bytes(extent_count * (offset_size + length_size))
+      #       skip_bytes(extent_count * index_size) if (version == 1 || version == 2) && index_size > 0
+      #     end
+      #   })
+      # end
+
+      # Parse an item info entry atom.
+      # def infe(size)
+      #   # TODO: This atom is super-complicated with optional and/or version-dependent fields and children.
+      #   empty(size)
+      # end
+
+      # Parse an item protection atom.
+      # def ipro(size)
+      #   fields = read_version_and_flags.merge({
+      #     protection_count: read_int_16
+      #   })
+      #   [fields, build_atom_tree(size - 6)]
+      # end
+
+      # Parse an item reference atom.
+      # def iref(_)
+      #   [read_version_and_flags, build_atom_tree(size - 4)]
+      # end
+
+      # Parse a level assignment atom.
+      # def leva(_)
+      #   fields = read_version_and_flags
+      #   level_count = read_int_8
+      #   fields.merge!({
+      #     level_count: level_count,
+      #     levels: level_count.times.map do
+      #       track_id = read_int_32
+      #       tmp = read_int_8
+      #       assignment_type = tmp & 0x7F
+      #       level = {
+      #         track_id: track_id,
+      #         padding_flag: tmp >> 7,
+      #         assignment_type: assignment_type
+      #       }
+      #       if assignment_type == 0
+      #         level[:grouping_type] = read_int_32
+      #       elsif assignment_type == 1
+      #         level.merge!({
+      #           grouping_type: read_int_32,
+      #           grouping_type_parameter: read_int_32
+      #         })
+      #       elsif assignment_type == 4
+      #         level[:sub_track_id] = read_int_32
+      #       end
+      #       level
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a media header atom.
+      # def mdhd(_)
+      #   fields = read_version_and_flags
+      #   version = fields[:version]
+      #   fields.merge!({
+      #     creation_time: version == 1 ? read_int_64 : read_int_32,
+      #     modification_time: version == 1 ? read_int_64 : read_int_32,
+      #     timescale: read_int_32,
+      #     duration: version == 1 ? read_int_64 : read_int_32,
+      #   })
+      #   tmp = read_int_16
+      #   fields[:language] = [(tmp >> 10) & 0x1F, (tmp >> 5) & 0x1F, tmp & 0x1F]
+      #   skip_bytes(2)
+      #   [fields, nil]
+      # end
+
+      # Parse a movie extends header atom.
+      # def mehd(_)
+      #   fields = read_version_and_flags
+      #   version = fields[:version]
+      #   fields[:fragment_duration] = version == 1 ? read_int_64 : read_int_32
+      #   [fields, nil]
+      # end
+
+      # Parse an metabox relation atom.
+      # def mere(_)
+      #   fields = read_version_and_flags.merge({
+      #     first_metabox_handler_type: read_int_32,
+      #     second_metabox_handler_type: read_int_32,
+      #     metabox_relation: read_int_8
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a meta atom.
+      # def meta(size)
+      #   fields = read_version_and_flags
+      #   [fields, build_atom_tree(size - 4)]
+      # end
+
+      # Parse a movie fragment header atom.
+      # def mfhd(_)
+      #   fields = read_version_and_flags.merge({
+      #     sequence_number: read_int_32
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a movie fragment random access offset atom.
+      # def mfro(_)
+      #   fields = read_version_and_flags.merge({
+      #     size: read_int_32
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a movie header atom.
+      # def mvhd(_)
+      #   fields = read_version_and_flags
+      #   version = fields[:version]
+      #   fields.merge!({
+      #     creation_time: version == 1 ? read_int_64 : read_int_32,
+      #     modification_time: version == 1 ? read_int_64 : read_int_32,
+      #     timescale: read_int_32,
+      #     duration: version == 1 ? read_int_64 : read_int_32,
+      #     rate: read_fixed_point_32,
+      #     volume: read_fixed_point_16,
+      #     matrix: skip_bytes(10) { read_matrix },
+      #     next_trak_id: skip_bytes(24) { read_int_32 },
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a padding bits atom.
+      # def padb(_)
+      #   fields = read_version_and_flags
+      #   sample_count = read_int_32
+      #   fields.merge!({
+      #     sample_count: sample_count,
+      #     padding: ((sample_count + 1) / 2).times.map do
+      #       tmp = read_int_8
+      #       {
+      #         padding_1: tmp >> 4,
+      #         padding_2: tmp & 0x07
+      #       }
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a progressive download information atom.
+      # def pdin(size)
+      #   fields = read_version_and_flags.merge({
+      #     entries: ((size - 4) / 8).times.map do
+      #       {
+      #         rate: read_int_32,
+      #         initial_delay: read_int_32
+      #       }
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a primary item atom.
+      # def pitm(_)
+      #   fields = read_version_and_flags.merge({
+      #     item_id: version == 0 ? read_int_16 : read_int_32
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a producer reference time atom.
+      # def prft(_)
+      #   fields = read_version_and_flags
+      #   version = fields[:version]
+      #   fields.merge!({
+      #     reference_track_id: read_int_32,
+      #     ntp_timestamp: read_int_64,
+      #     media_time: version == 0 ? read_int_32 : read_int_64
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a sample auxiliary information offsets atom.
+      # def saio(_)
+      #   fields = read_version_and_flags
+      #   version = field[:version]
+      #   flags = fields[:flags]
+      #   fields.merge!({
+      #     aux_info_type: read_int_32,
+      #     aux_info_type_parameter: read_int_32
+      #   }) if flags & 0x1
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     offsets: entry_count.times.map { version == 0 ? read_int_32 : read_int_64 }
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a sample auxiliary information sizes atom.
+      # def saiz(_)
+      #   fields = read_version_and_flags
+      #   flags = fields[:flags]
+      #   fields.merge!({
+      #     aux_info_type: read_int_32,
+      #     aux_info_type_parameter: read_int_32
+      #   }) if flags & 0x1
+      #   default_sample_info_size = read_int_8
+      #   sample_count = read_int_32
+      #   fields.merge!({
+      #     default_sample_info_size: default_sample_info_size,
+      #     sample_count: sample_count
+      #   })
+      #   fields[:sample_info_sizes] = sample_count.times.map { read_int_8 } if default_sample_info_size == 0
+      #   [fields, nil]
+      # end
+
+      # Parse a sample to group atom.
+      # def sbgp(_)
+      #   fields = read_version_and_flags
+      #   fields[:grouping_type] = read_int_32
+      #   fields[:grouping_type_parameter] = read_int_32 if fields[:version] == 1
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map do
+      #       {
+      #         sample_count: read_int_32,
+      #         group_description_index: read_int_32
+      #       }
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a scheme type atom.
+      # def schm(_)
+      #   fields = read_version_and_flags.merge({
+      #     scheme_type: read_string(4),
+      #     scheme_version: read_int_32,
+      #   })
+      #   fields[:scheme_uri] = (size - 12).times.map { read_int_8 } if flags & 0x1 != 0
+      #   [fields, nil]
+      # end
+
+      # Parse an independent and disposable samples atom.
+      # def sdtp(size)
+      #   # TODO: Parsing this atom needs the sample_count from the sample size atom (`stsz`).
+      #   empty(size)
+      # end
+
+      # Parse an FD session group atom.
+      # def segr(_)
+      #   num_session_groups = read_int_16
+      #   fields = {
+      #     num_session_groups: num_session_groups,
+      #     session_groups: num_session_groups.times.map do
+      #       entry_count = read_int_8
+      #       session_group = {
+      #         entry_count: entry_count,
+      #         entries: entry_count.times.map { { group_id: read_int_32 } }
+      #       }
+      #       num_channels_in_session_group = read_int_16
+      #       session_group.merge({
+      #         num_channels_in_session_group: num_channels_in_session_group,
+      #         channels: num_channels_in_session_group.times.map { { hint_track_id: read_int_32 } }
+      #       })
+      #     end
+      #   }
+      #   [fields, nil]
+      # end
+
+      # Parse a sample group description atom.
+      # def sgpd(_)
+      #   fields = read_version_and_flags
+      #   version = fields[:version]
+      #   fields[:grouping_type] = read_int_32
+      #   fields[:default_length] = read_int_32 if version == 1
+      #   fields[:default_sample_description_index] = read_int_32 if version >= 2
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map do
+      #       entry = {}
+      #       entry[:description_length] = read_int_32 if version == 1 && fields[:default_length] == 0
+      #       entry[:atom] = parse_atom
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a segment index atom.
+      # def sidx(_)
+      #   fields = read_version_and_flags.merge({
+      #     reference_id: read_int_32,
+      #     timescale: read_int_32
+      #   })
+      #   version = fields[:version]
+      #   fields.merge!({
+      #     earliest_presentation_time: version == 0 ? read_int_32 : read_int_64,
+      #     first_offset: version == 0 ? read_int_32 : read_int_64,
+      #   })
+      #   reference_count = skip_bytes(2) { read_int_16 }
+      #   fields.merge!({
+      #     reference_count: reference_count,
+      #     references: reference_count.times.map do
+      #       tmp = read_int_32
+      #       reference = {
+      #         reference_type: tmp >> 31,
+      #         referenced_size: tmp & 0x7FFFFFFF,
+      #         subsegment_duration: read_int_32
+      #       }
+      #       tmp = read_int_32
+      #       reference.merge({
+      #         starts_with_sap: tmp >> 31,
+      #         sap_type: (tmp >> 28) & 0x7,
+      #         sap_delta_time: tmp & 0x0FFFFFFF
+      #       })
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a sound media header atom.
+      # def smhd(_)
+      #   fields = read_version_and_flags.merge({
+      #     balance: read_fixed_point_16,
+      #   })
+      #   skip_bytes(2)
+      #   [fields, nil]
+      # end
+
+      # Parse a subsegment index atom.
+      # def ssix(_)
+      #   fields = read_version_and_flags
+      #   subsegment_count = read_int_32
+      #   fields.merge!({
+      #     subsegment_count: subsegment_count,
+      #     subsegments: subsegment_count.times.map do
+      #       range_count = read_int_32
+      #       {
+      #         range_count: range_count,
+      #         ranges: range_count.times.map do
+      #           tmp = read_int_32
+      #           {
+      #             level: tmp >> 24,
+      #             range_size: tmp & 0x00FFFFFF
+      #           }
+      #         end
+      #       }
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a chunk offset atom.
+      # def stco(_)
+      #   fields = read_version_and_flags
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map { { chunk_offset: read_int_32 } }
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a degradation priority atom.
+      # def stdp(size)
+      #   # TODO: Parsing this atom needs the sample_count from the sample size atom (`stsz`).
+      #   empty(size)
+      # end
+
+      # Parse a sub track information atom.
+      # def stri(size)
+      #   fields = read_version_and_flags.merge({
+      #     switch_group: read_int_16,
+      #     alternate_group: read_int_16,
+      #     sub_track_id: read_int_32,
+      #     attribute_list: ((size - 12) / 4).times.map { read_int_32 }
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a sample to chunk atom.
+      # def stsc(_)
+      #   fields = read_version_and_flags
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map do
+      #       {
+      #         first_chunk: read_int_32,
+      #         samples_per_chunk: read_int_32,
+      #         sample_description_index: read_int_32
+      #       }
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a sample descriptions atom.
+      # def stsd(size)
+      #   fields = read_version_and_flags.merge({
+      #     entry_count: read_int_32
+      #   })
+      #   [fields, build_atom_tree(size - 8)]
+      # end
+
+      # Parse a shadow sync sample atom.
+      # def stsh(_)
+      #   fields = read_version_and_flags
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map {
+      #       {
+      #         shadowed_sample_number: read_int_32,
+      #         sync_sample_number: read_int_32
+      #       }
+      #     }
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a sync sample atom.
+      # def stss(_)
+      #   fields = read_version_and_flags
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map { { sample_number: read_int_32 } }
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a sample size atom.
+      # def stsz(_)
+      #   fields = read_version_and_flags
+      #   sample_size = read_int_32
+      #   sample_count = read_int_32
+      #   fields.merge!({
+      #     sample_size: sample_size,
+      #     sample_count: sample_count,
+      #   })
+      #   fields[:entries] = sample_count.times.map { { entry_size: read_int_32 } } if sample_size == 0
+      #   [fields, nil]
+      # end
+
+      # Parse a decoding time to sample atom.
+      # def stts(_)
+      #   fields = read_version_and_flags
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map do
+      #       {
+      #         sample_count: read_int_32,
+      #         sample_delta: read_int_32
+      #       }
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a compact sample size atom.
+      # def stz2(size)
+      #   fields = read_version_and_flags.merge({
+      #     field_size: skip_bytes(3) { read_int_8 },
+      #     sample_count: read_int_32
+      #   })
+      #   # TODO: Handling for parsing entry sizes dynamically based on field size.
+      #   skip_bytes(size - 12)
+      #   [fields, nil]
+      # end
+
+      # Parse a sub-sample information atom.
+      # def subs(_)
+      #   fields = read_version_and_flags
+      #   entry_count = read_int_32
+      #   fields[:entries] = entry_count.times.map do
+      #     sample_delta = read_int_32
+      #     subsample_count = read_int_16
+      #     {
+      #       sample_delta: sample_delta,
+      #       subsample_count: subsample_count,
+      #       subsample_information: subsample_count.times.map do
+      #         {
+      #           subsample_size: version == 1 ? read_int_32 : read_int_16,
+      #           subsample_priority: read_int_8,
+      #           discardable: read_int_8,
+      #           codec_specific_parameters: read_int_32
+      #         }
+      #       end
+      #     }
+      #   end
+      #   [fields, nil]
+      # end
+
+      # Parse a track fragment random access atom.
+      # def tfra(_)
+      #   fields = read_version_and_flags
+      #   version = fields[:version]
+      #   fields[:track_id] = read_int_32
+      #   skip_bytes(3)
+      #   tmp = read_int_8
+      #   size_of_traf_number = (tmp >> 4) & 0x3
+      #   size_of_trun_number = (tmp >> 2) & 0x3
+      #   size_of_sample_number = tmp & 0x3
+      #   entry_count = read_int_32
+      #   fields.merge!({
+      #     size_of_traf_number: size_of_traf_number,
+      #     size_of_trun_number: size_of_trun_number,
+      #     size_of_sample_number: size_of_sample_number,
+      #     entry_count: entry_count,
+      #     entries: entry_count.times.map do
+      #       entry = {
+      #         time: version == 1 ? read_int_64 : read_int_32,
+      #         moof_offset: version == 1 ? read_int_64 : read_int_32
+      #       }
+      #       # TODO: Handling for parsing traf_number, trun_number and sample_number dynamically based on their sizes.
+      #       skip_bytes(size_of_traf_number + size_of_trun_number + size_of_sample_number + 3)
+      #       entry
+      #     end
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a track header atom.
+      # def tkhd(_)
+      #   fields = read_version_and_flags
+      #   version = fields[:version]
+      #   fields.merge!({
+      #     creation_time: version == 1 ? read_int_64 : read_int_32,
+      #     modification_time: version == 1 ? read_int_64 : read_int_32,
+      #     track_id: read_int_32,
+      #     duration: skip_bytes(4) { version == 1 ? read_int_64 : read_int_32 },
+      #     layer: skip_bytes(8) { read_int_16 },
+      #     alternate_group: read_int_16,
+      #     volume: read_fixed_point_16,
+      #     matrix: skip_bytes(2) { read_matrix },
+      #     width: read_fixed_point_32,
+      #     height: read_fixed_point_32
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a track extends atom.
+      # def trex(_)
+      #   fields = read_version_and_flags.merge({
+      #     track_id: read_int_32,
+      #     default_sample_description_index: read_int_32,
+      #     default_sample_duration: read_int_32,
+      #     default_sample_size: read_int_32,
+      #     default_sample_flags: read_int_32
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a track selection atom.
+      # def tsel(size)
+      #   fields = read_version_and_flags.merge({
+      #     switch_group: read_int_32,
+      #     attribute_list: ((size - 8) / 4).times.map { read_int_32 }
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a file/segment type compatibility atom.
+      # def typ(size)
+      #   compatible_brands_count = (size - 8) / 4
+      #   fields = {
+      #     major_brand: read_string(4),
+      #     minor_version: read_int_32,
+      #     compatible_brands: compatible_brands_count.times.map { read_string(4) }
+      #   }
+      #   [fields, nil]
+      # end
+
+      # Parse a UUID atom.
+      def uuid(size)
+        fields = { usertype: read_bytes(16).unpack('H*').first }
+        skip_bytes(size - 16)
+        [fields, nil]
+      end
+
+      # Parse a video media header atom.
+      # def vmhd(_)
+      #   fields = read_version_and_flags.merge({
+      #     graphics_mode: read_int_16,
+      #     op_color: (1..3).map { read_int_16 }
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse an XML atom.
+      # def xml(size)
+      #   fields = read_version_and_flags.merge({
+      #     xml: read_string(size - 4)
+      #   })
+      #   [fields, nil]
+      # end
+
+      # Parse a matrix.
+      #
+      # Matrices are 3×3 and encoded row-by-row as 32-bit fixed-point numbers divided as 16.16, except for the rightmost
+      # column which is divided as 2.30.
+      #
+      # See https://developer.apple.com/library/archive/documentation/QuickTime/QTFF/QTFFChap4/qtff4.html#//apple_ref/doc/uid/TP40000939-CH206-18737.
+      def read_matrix
+        9.times.map do |i|
+          if i % 3 == 2
+            read_fixed_point_32_2_30
+          else
+            read_fixed_point_32
+          end
+        end
+      end
+
+      # Parse an atom's version and flags.
+      #
+      # It's common for atoms to begin with a single byte representing the version followed by three bytes representing any
+      # associated flags. Both of these are often 0.
+      def read_version_and_flags
+        {
+          version: read_int_8,
+          flags: read_bytes(3)
+        }
+      end
+    end
+  end
+end