<?php
/**
 * SeekQuarry/Yioop --
 * Open Source Pure PHP Search Engine, Crawler, and Indexer
 *
 * Copyright (C) 2009 - 2026  Chris Pollett chris@pollett.org
 *
 * LICENSE:
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 *
 * END LICENSE
 *
 * @author Chris Pollett chris@pollett.org
 * @license https://www.gnu.org/licenses/ GPL3
 * @link https://www.seekquarry.com/
 * @copyright 2009 - 2026
 * @filesource
 *
 * This class reads an MP4, an MP4 carrying video alone or QuickTime file. It
 * walks the tables that
 * say where each frame sits and which frames stand on their own.
 */
namespace seekquarry\yioop\library\av_processing;
/**
 * Mp4Exception kept as its own type for callers that catch it by name.
 */
class Mp4Exception extends VideoException {}

/**
 * Mp4VideoTrack one video track of an MP4 or QuickTime file: where its samples
 * sit, how long each is shown, which of them can be decoded on their own, and
 * the codec setup that goes with them.
 */
final class Mp4VideoTrack
{
    /**
     * $codec_name stores the four letters naming the codec of this track, such
     * as avc1 for H.264. A reader looks at it to decide which decoder to hand a
     * frame to, and reports it when asked to describe the file.
     * @var string
     */
    public string $codec_name = '';
    /**
     * $clock_units_per_second stores how many units of the track's own clock
     * make one second. Every time in the tables below is in those units, so a
     * moment in seconds is turned into them before a sample is looked up.
     * @var int
     */
    public int $clock_units_per_second = 1;
    /**
     * $track_length stores how long the track runs, in the units of that clock.
     * @var int
     */
    public int $track_length = 0;
    /**
     * $frame_width stores how wide a frame is, in pixels, as the track's header
     * says. A thumbnail is scaled against it without decoding anything.
     * @var int
     */
    public int $frame_width = 0;
    /**
     * $frame_height stores how tall a frame is, in pixels, as the
     * file's own header gives it. A thumbnail keeps the shape of
     * the frame, so its height follows from this and the width.
     * @var int
     */
    public int $frame_height = 0;
    /**
     * $sample_lengths stores how long each sample lasts, written as runs of
     * samples that share a length. Walking it turns a moment into the sample
     * showing then.
     * @var array
     */
    public array $sample_lengths = [];
    /**
     * $self_contained_samples stores which samples stand on their own, by
     * number. Only these can be decoded without the frames before them, so a
     * thumbnail is taken from the nearest one at or before the moment asked
     * for.
     * @var array
     */
    public array $self_contained_samples = [];
    /**
     * $samples_per_chunk stores how many samples sit in each chunk of the file,
     * written as runs of chunks that hold the same number. It is what turns a
     * sample number into a place in the file.
     * @var array
     */
    public array $samples_per_chunk = [];
    /**
     * $sample_sizes stores how many bytes each sample takes, where they differ
     * from one another.
     * @var array
     */
    public array $sample_sizes = [];
    /**
     * $one_size_for_all stores how many bytes every sample takes, where they
     * are all the same. The list above is then left empty.
     * @var int
     */
    public int $one_size_for_all = 0;
    /**
     * $sample_count stores how many samples the track holds altogether.
     * @var int
     */
    public int $sample_count = 0;
    /**
     * $chunk_offsets stores where each chunk begins in the file. With the
     * samples-per-chunk table above, this gives the place of any sample.
     * @var array
     */
    public array $chunk_offsets = [];
    /**
     * $sequence_settings stores the sequence settings, or nothing where there
     * is none.
     * @var string
     */
    public ?string $sequence_settings = null;
    /**
     * $picture_settings stores the picture settings, or nothing where there is
     * none.
     * @var string
     */
    public ?string $picture_settings = null;
    /**
     * $parameter_sets stores parameter sets of an H.265 track, as the setup
     * record stores them.
     * @var array
     */
    public array $parameter_sets = [];
    /**
     * $stream_unit_length_size stores how many bytes each unit's length
     * field takes. An MP4 writes a length in front of every unit of
     * the stream, and a decoder cannot find the next unit without
     * knowing the width of that field.
     * @var int
     */
    public int $stream_unit_length_size = 4;
    /**
     * $showing_offsets stores how far each sample's showing time sits from its
     * decoding time, where the two differ. Frames may be stored out of order,
     * and this puts them back.
     * @var array
     */
    public array $showing_offsets = [];
    /**
     * $edit_media_start stores media time the first edit starts at, in media
     * timescale units.
     * @var int
     */
    public int $edit_media_start = 0;
    /**
     * $edit_delay stores empty edit at the head of the timeline, in seconds.
     * @var float
     */
    public float $edit_delay = 0.0;
    /**
     * $edit_duration stores presentation duration from the edit list, in
     * seconds, 0 when absent.
     * @var float
     */
    public float $edit_duration = 0.0;
    /**
     * compositionOffset says how far a sample's showing time sits from its
     * decoding time. Frames may be stored out of the order they are shown in,
     * and this offset puts them back, so a thumbnail asked for at a moment
     * lands on the right frame. zero.
     *
     * @param int $sample Which sample of the track, counting from
     * @return int How many units of the track's clock to add.
     */
    public function compositionOffset(int $sample): int
    {
        if ($this->showing_offsets === []) {
            return 0;
        }
        $at = 0;
        foreach ($this->showing_offsets as [$count, $offset]) {
            if ($sample < $at + $count) {
                return $offset;
            }
            $at += $count;
        }
        return 0;
    }
    /**
     * presentationTime presentation time of a sample in seconds, edit list
     * applied
     *
     * @param int $sample which sample of the track
     * @return float what was read
     */
    public function presentationTime(int $sample): float
    {
        $media = $this->timeOfSample($sample) * $this->clock_units_per_second
            + $this->compositionOffset($sample);
        return ($media - $this->edit_media_start) / $this
            ->clock_units_per_second
            + $this->edit_delay;
    }
    /**
     * sizeOfSample the stored length of one sample.
     *
     * @param int $sample the stored bytes of one sample
     * @return int what was read
     */
    public function sizeOfSample(int $sample): int
    {
        if ($this->one_size_for_all > 0) {
            return $this->one_size_for_all;
        }
        if (!isset($this->sample_sizes[$sample])) {
            throw new Mp4Exception("No size for sample $sample");
        }
        return $this->sample_sizes[$sample];
    }
    /**
     * timeOfSample decode time of a 0-based sample, in seconds
     *
     * @param int $sample which sample of the track
     * @return float what was read
     */
    public function timeOfSample(int $sample): float
    {
        $track = 0;
        $at = 0;
        foreach ($this->sample_lengths as [$count, $delta]) {
            if ($sample < $at + $count) {
                return ($track
                    + ($sample - $at) * $delta) / $this->clock_units_per_second;
            }
            $track += $count * $delta;
            $at += $count;
        }
        return $track / $this->clock_units_per_second;
    }
}

/**
 * Mp4Extractor reads an MP4 file, one carrying video alone, or a
 * QuickTime file. It walks the tables that say where each frame sits
 * and which frames stand on their own.
 */
final class Mp4Extractor extends VideoExtractor
{
    /**
     * $hevc stores the H.265 decoder, made when the first such frame is asked
     * for.
     * @var HevcDecoder
     */
    private ?HevcDecoder $hevc = null;
    use ByteSource;
    /**
     * $track stores the track, or nothing where there is none.
     * @var Mp4VideoTrack
     */
    private ?Mp4VideoTrack $track = null;
    /**
     * $movie_clock_units_per_second stores how many units of the file's own
     * clock make one second, which is not always the track's. The edit list is
     * written in these units.
     * @var int
     */
    private int $movie_clock_units_per_second = 1000;
    /**
     * $file_brand stores the four letters the file names itself by, such as the
     * name an MP4 gives itself or qt. It is reported when the file is
     * described, and tells an MP4 from an older QuickTime file.
     * @var string
     */
    private string $file_brand = '';
    /**
     * __construct opens an MP4, an MP4 carrying video alone or QuickTime file
     * and indexes its video track.
     *
     * @param string $path file to read
     */
    public function __construct(string $path)
    {
        $this->openSource($path);
        $head = $this->readBytesAt(0, 12);
        if (strlen($head) === 12 && substr($head, 4, 4) === 'ftyp') {
            $this->file_brand = substr($head, 8, 4);
        }
    }
    /**
     * children immediate children of the byte range [$start, $end). offset
     *
     * @return array start = payload
     * @param int $start where it starts
     * @param int $end where it ends
     */
    private function children(int $start, int $end): array
    {
        $written = [];
        $position = $start;
        while ($position + 8 <= $end) {
            $header = $this->readExact($position, 8);
            $size = unpack('N', substr($header, 0, 4))[1];
            $type = substr($header, 4, 4);
            $header_length = 8;
            if ($size === 1) {
                $size = unpack('J', $this->readExact($position + 8, 8))[1];
                $header_length = 16;
            } elseif ($size === 0) {
                $size = $end - $position;
            }
            if ($size < $header_length || $position + $size > $end) {
                /* truncated or garbage; stop rather than guess */
                break;
            }
            $written[] = ['type' => $type,
                'start' => $position + $header_length,
                'end'
                => $position + $size];
            $position += $size;
        }
        return $written;
    }
    /**
     * chooseTable to look through
     *
     * @param array $boxes the boxes
     * @param string $type which kind
     * @return array what was read
     */
    private static function chooseTable(array $boxes, string $type): ?array
    {
        foreach ($boxes as $bits) {
            if ($bits['type'] === $type) {
                return $bits;
            }
        }
        return null;
    }
    /**
     * descend finds a box by following a path of box names from a parent.
     *
     * @param int $start where it starts
     * @param int $end where it ends
     * @param string ... $path file to read
     * @return array what was read
     */
    private function descend(int $start, int $end, string ...$path): ?array
    {
        $current = ['start' => $start, 'end' => $end];
        foreach ($path as $type) {
            $hit
                = self::chooseTable($this->children($current['start'],
                    $current['end']),
                    $type);
            if ($hit === null) {
                return null;
            }
            $current = $hit;
        }
        return $current;
    }
    /**
     * readFourBytes reads a four byte number stored most significant byte
     * first.
     *
     * @param string $source the file or bytes being read
     * @param int $origin where the reading started
     * @return int what was read
     */
    private static function readFourBytes(string $source, int $origin): int
    {
        return unpack('N', substr($source, $origin, 4))[1];
    }
    /**
     * readTwoBytes reads a two byte number stored most significant byte first.
     *
     * @param string $source the file or bytes being read
     * @param int $origin where the reading started
     * @return int what was read
     */
    private static function readTwoBytes(string $source, int $origin): int
    {
        return unpack('n', substr($source, $origin, 2))[1];
    }
    /**
     * readEightBytes reads an eight byte number stored most significant byte
     * first.
     *
     * @param string $source the file or bytes being read
     * @param int $origin where the reading started
     * @return int what was read
     */
    private static function readEightBytes(string $source, int $origin): int
    {
        return unpack('J', substr($source, $origin, 8))[1];
    }
    /**
     * videoTrack the video track, read from the file the first time it is asked
     * for.
     *
     * @return Mp4VideoTrack what was read
     */
    public function videoTrack(): Mp4VideoTrack
    {
        if ($this->track !== null) {
            return $this->track;
        }
        $movie_box = self::chooseTable($this->children(0, $this->sourceSize()),
            'moov');
        if ($movie_box === null) {
            throw new Mp4Exception(
                'No moov box (fragmented or streaming-only file?)');
        }
        $movie_box_kids = $this->children($movie_box['start'],
            $movie_box['end']);
        $movie_header = self::chooseTable($movie_box_kids, 'mvhd');
        if ($movie_header !== null) {
            $payload = $this->readExact($movie_header['start'], min(24,
                $movie_header['end']
                - $movie_header['start']));
            if (strlen($payload) >= 20) {
                $ts = (ord($payload[0]) === 1)
                    ? self::readFourBytes($payload, 20)
                    : self::readFourBytes($payload, 12);
                if ($ts > 0) {
                    $this->movie_clock_units_per_second = $ts;
                }
            }
        }
        foreach ($movie_box_kids as $box) {
            if ($box['type'] !== 'trak') {
                continue;
            }
            $handler_box = $this->descend($box['start'], $box['end'],
                'mdia', 'hdlr');
            if ($handler_box === null) {
                continue;
            }
            $header = $this->readExact($handler_box['start'], min(12,
                $handler_box['end']
                - $handler_box['start']));
            if (strlen($header) < 12 || substr($header, 8, 4) !== 'vide') {
                continue;
            }
            $this->track = $this->parseTrack($box['start'], $box['end']);
            return $this->track;
        }
        throw new Mp4Exception('No video track found');
    }
    /**
     * parseTrack reads one track and keeps it if it carries video.
     *
     * @param int $start where it starts
     * @param int $end where it ends
     * @return Mp4VideoTrack what was read
     */
    private function parseTrack(int $start, int $end): Mp4VideoTrack
    {
        $track = new Mp4VideoTrack();
        $media_header = $this->descend($start, $end, 'mdia', 'mdhd');
        if ($media_header === null) {
            throw new Mp4Exception('Missing mdhd');
        }
        $payload
            = $this->readExact($media_header['start'],
                $media_header['end'] - $media_header['start']);
        $ver = ord($payload[0]);
        if ($ver === 1) {
            $track->clock_units_per_second = self::readFourBytes($payload, 20);
            $track->track_length  = self::readEightBytes($payload, 24);
        } else {
            $track->clock_units_per_second = self::readFourBytes($payload, 12);
            $track->track_length  = self::readFourBytes($payload, 16);
        }
        if ($track->clock_units_per_second <= 0) {
            throw new Mp4Exception('Bad media timescale');
        }
        $sample_table = $this->descend($start, $end, 'mdia', 'minf', 'stbl');
        if ($sample_table === null) {
            throw new Mp4Exception('Missing stbl');
        }
        $tables = $this->children($sample_table['start'], $sample_table['end']);
        $this->readSampleDescription($tables, $track);
        $this->readSampleLengths($tables, $track);
        $this->readSelfContainedSamples($tables, $track);
        $this->readSamplesPerChunk($tables, $track);
        $this->readSampleSizes($tables, $track);
        $this->parseChunkOffsets($tables, $track);
        $this->readShowingOffsets($tables, $track);
        $this->parseEditList($start, $end, $track);
        return $track;
    }
    /**
     * readSampleDescription reads the sample description, which names the codec
     * and gives the picture size.
     *
     * @param array $tables the tables the format fixes
     * @param Mp4VideoTrack $track the track being read
     */
    private function readSampleDescription(array $tables,
        Mp4VideoTrack $track): void
    {
        $sample_kinds = self::chooseTable($tables, 'stsd');
        if ($sample_kinds === null) {
            throw new Mp4Exception('Missing stsd');
        }
        $entries = $this->children($sample_kinds['start']
            /* skip version/flags + entry_count */
            + 8, $sample_kinds['end']);
        if ($entries === []) {
            throw new Mp4Exception('Empty stsd');
        }
        $entry = $entries[0];
        $track->codec_name = $entry['type'];
        /* VisualSampleEntry body: width at +24, height at +26 relative to
          payload start */
        $body
            = $this->readExact($entry['start'], min(78, $entry['end']
                - $entry['start']));
        if (strlen($body) >= 28) {
            $track->frame_width  = self::readTwoBytes($body, 24);
            $track->frame_height = self::readTwoBytes($body, 26);
        }
        /* child boxes of the sample entry start 78 bytes into the payload */
        $child_start = $entry['start'] + 78;
        if ($child_start >= $entry['end']) {
            return;
        }
        foreach ($this->children($child_start, $entry['end']) as $chunk) {
            if ($chunk['type'] === 'avcC') {
                $this->readH264SetupRecord($this->readExact($chunk['start'],
                    $chunk['end'] - $chunk['start']), $track);
            }
            if ($chunk['type'] === 'hvcC') {
                $this->readHevcSetupRecord($this->readExact($chunk['start'],
                    $chunk['end'] - $chunk['start']), $track);
            }
        }
    }
    /**
     * Reads the H.264 setup record, which holds the parameter sets
     * and says how long each unit's length field is.
     *
     * @param string $payload the bytes the element carries
     * @param Mp4VideoTrack $track the track being read
     */
    /**
     * readHevcSetupRecord reads the H.265 setup record, which holds the
     * parameter sets and says how long each unit's length field is.
     *
     * @param string $record the record's bytes
     * @param Mp4VideoTrack $track track the record belongs to
     */
    private function readHevcSetupRecord(string $record,
        Mp4VideoTrack $track): void
    {
        if (strlen($record) < 23) {
            throw new Mp4Exception('hvcC record is too short');
        }
        $track->stream_unit_length_size = (ord($record[21]) & 3) + 1;
        $arrays = ord($record[22]);
        $position = 23;
        $sets = [];
        for ($group = 0; $group < $arrays; $group++) {
            if ($position + 3 > strlen($record)) {
                break;
            }
            $count = (ord($record[$position + 1]) << 8)
                | ord($record[$position + 2]);
            $position += 3;
            for ($entry = 0; $entry < $count; $entry++) {
                if ($position + 2 > strlen($record)) {
                    break 2;
                }
                $length = (ord($record[$position]) << 8)
                    | ord($record[$position + 1]);
                $position += 2;
                $sets[] = substr($record, $position, $length);
                $position += $length;
            }
        }
        $track->parameter_sets = $sets;
    }
    /**
     * readH264SetupRecord reads the H.264 setup record, which holds the
     * parameter sets and says how long each unit's length field is.
     *
     * @param string $payload the record's bytes
     * @param Mp4VideoTrack $track track the record belongs to
     */
    private function readH264SetupRecord(string $payload,
        Mp4VideoTrack $track): void
    {
        if (strlen($payload) < 7) {
            return;
        }
        $track->stream_unit_length_size = (ord($payload[4]) & 0x03) + 1;
        $sequence_setting_count = ord($payload[5]) & 0x1F;
        $position = 6;
        for ($i = 0; $i < $sequence_setting_count && $position + 2 <=
            strlen($payload); $i++) {
            $length = self::readTwoBytes($payload, $position);
            $position += 2;
            if ($i === 0) {
                $track->sequence_settings = substr($payload, $position,
                    $length);
            }
            $position += $length;
        }
        if ($position >= strlen($payload)) {
            return;
        }
        $picture_setting_count = ord($payload[$position]);
        $position++;
        for ($i = 0; $i < $picture_setting_count && $position + 2 <=
            strlen($payload); $i++) {
            $length = self::readTwoBytes($payload, $position);
            $position += 2;
            if ($i === 0) {
                $track->picture_settings = substr($payload, $position, $length);
            }
            $position += $length;
        }
    }
    /**
     * readSampleLengths reads how long each sample is shown.
     *
     * @param array $tables the tables the format fixes
     * @param Mp4VideoTrack $track the track being read
     */
    private function readSampleLengths(array $tables,
        Mp4VideoTrack $track): void
    {
        $bits = self::chooseTable($tables, 'stts');
        if ($bits === null) {
            throw new Mp4Exception('Missing stts');
        }
        $payload
            = $this->readExact($bits['start'], $bits['end'] - $bits['start']);
        $total = self::readFourBytes($payload, 4);
        for ($i = 0; $i < $total; $i++) {
            $origin = 8 + $i * 8;
            if ($origin + 8 > strlen($payload)) {
                break;
            }
            $track->sample_lengths[]
                = [self::readFourBytes($payload, $origin),
                    self::readFourBytes($payload, $origin + 4)];
        }
    }
    /**
     * readSelfContainedSamples reads which samples can be decoded on their own.
     *
     * @param array $tables the tables the format fixes
     * @param Mp4VideoTrack $track the track being read
     */
    private function readSelfContainedSamples(array $tables,
        Mp4VideoTrack $track): void
    {
        $bits = self::chooseTable($tables, 'stss');
        if ($bits === null) {
            /* absent => every sample is a sync sample */
            return;
        }
        $payload
            = $this->readExact($bits['start'], $bits['end'] - $bits['start']);
        $total = self::readFourBytes($payload, 4);
        for ($i = 0; $i < $total; $i++) {
            $origin = 8 + $i * 4;
            if ($origin + 4 > strlen($payload)) {
                break;
            }
            $track->self_contained_samples[] = self::readFourBytes($payload,
                $origin);
        }
    }
    /**
     * readSamplesPerChunk reads how samples are grouped into chunks.
     *
     * @param array $tables the tables the format fixes
     * @param Mp4VideoTrack $track the track being read
     */
    private function readSamplesPerChunk(array $tables,
        Mp4VideoTrack $track): void
    {
        $bits = self::chooseTable($tables, 'stsc');
        if ($bits === null) {
            throw new Mp4Exception('Missing stsc');
        }
        $payload
            = $this->readExact($bits['start'], $bits['end'] - $bits['start']);
        $total = self::readFourBytes($payload, 4);
        for ($i = 0; $i < $total; $i++) {
            $origin = 8 + $i * 12;
            if ($origin + 12 > strlen($payload)) {
                break;
            }
            $track->samples_per_chunk[]
                = [self::readFourBytes($payload, $origin),
                    self::readFourBytes($payload, $origin + 4),
                        self::readFourBytes($payload, $origin
                    + 8)];
        }
    }
    /**
     * readSampleSizes reads the stored length of every sample.
     *
     * @param array $tables the tables the format fixes
     * @param Mp4VideoTrack $track the track being read
     */
    private function readSampleSizes(array $tables, Mp4VideoTrack $track): void
    {
        $bits = self::chooseTable($tables, 'stsz');
        if ($bits === null) {
            throw new Mp4Exception('Missing stsz');
        }
        $payload
            = $this->readExact($bits['start'], $bits['end'] - $bits['start']);
        $uniform = self::readFourBytes($payload, 4);
        $track->sample_count = self::readFourBytes($payload, 8);
        if ($uniform > 0) {
            $track->one_size_for_all = $uniform;
            return;
        }
        for ($i = 0; $i < $track->sample_count; $i++) {
            $origin = 12 + $i * 4;
            if ($origin + 4 > strlen($payload)) {
                break;
            }
            $track->sample_sizes[] = self::readFourBytes($payload, $origin);
        }
    }
    /**
     * readShowingOffsets composition offsets; present whenever decode and
     * display order differ
     *
     * @param array $tables the tables the format fixes
     * @param Mp4VideoTrack $track the track being read
     */
    private function readShowingOffsets(array $tables,
        Mp4VideoTrack $track): void
    {
        $bits = self::chooseTable($tables, 'ctts');
        if ($bits === null) {
            return;
        }
        $payload
            = $this->readExact($bits['start'], $bits['end'] - $bits['start']);
        $version = ord($payload[0]);
        $total = self::readFourBytes($payload, 4);
        for ($i = 0; $i < $total; $i++) {
            $origin = 8 + $i * 8;
            if ($origin + 8 > strlen($payload)) {
                break;
            }
            $count = self::readFourBytes($payload, $origin);
            $offset = self::readFourBytes($payload, $origin + 4);
            if ($version === 1 && $offset >= 0x80000000) {
                /* version 1 offsets are signed */
                $offset -= 0x100000000;
            }
            $track->showing_offsets[] = [$count, $offset];
        }
    }
    /**
     * parseEditList quickTime and MP4 both allow an edit list, and QuickTime
     * writers use it far more often. A leading empty edit delays the timeline;
     * the first real edit says which media time the presentation starts at,
     * which is how a stream with reordered frames avoids negative timestamps.
     *
     * @param int $start where it starts
     * @param int $end where it ends
     * @param Mp4VideoTrack $track the track being read
     */
    private function parseEditList(int $start, int $end,
        Mp4VideoTrack $track): void
    {
        $edit_list = $this->descend($start, $end, 'edts', 'elst');
        if ($edit_list === null) {
            return;
        }
        $payload
            = $this->readExact($edit_list['start'], $edit_list['end'] -
                $edit_list['start']);
        if (strlen($payload) < 8) {
            return;
        }
        $version = ord($payload[0]);
        $total = self::readFourBytes($payload, 4);
        $entry_size = ($version === 1) ? 20 : 12;
        $position = 8;
        $total_duration = 0;
        $started = false;
        for ($i = 0; $i < $total && $position
            + $entry_size <= strlen($payload); $i++, $position += $entry_size) {
            if ($version === 1) {
                $segment = self::readEightBytes($payload, $position);
                $media_time = self::readEightBytes($payload, $position + 8);
                if ($media_time >= 0x8000000000000000) {
                    $media_time = -1;
                }
            } else {
                $segment = self::readFourBytes($payload, $position);
                $media_time = self::readFourBytes($payload, $position + 4);
                if ($media_time >= 0x80000000) {
                    $media_time -= 0x100000000;
                }
            }
            $total_duration += $segment;
            if ($media_time < 0) {
                if (!$started) {
                    $track->edit_delay += $segment /
                        $this->movie_clock_units_per_second;
                }
                continue;
            }
            if (!$started) {
                $track->edit_media_start = $media_time;
                $started = true;
            }
        }
        if ($total_duration > 0) {
            $track->edit_duration = $total_duration /
                $this->movie_clock_units_per_second;
        }
    }
    /**
     * parseChunkOffsets reads where each chunk sits in the file, from either of
     * the two tables that can carry it.
     *
     * @param array $tables the tables the format fixes
     * @param Mp4VideoTrack $track the track being read
     */
    private function parseChunkOffsets(
        array $tables, Mp4VideoTrack $track): void
    {
        $bits = self::chooseTable($tables, 'stco');
        $wide = false;
        if ($bits === null) {
            $bits = self::chooseTable($tables, 'co64');
            $wide = true;
        }
        if ($bits === null) {
            throw new Mp4Exception('Missing stco/co64');
        }
        $payload
            = $this->readExact($bits['start'], $bits['end'] - $bits['start']);
        $total = self::readFourBytes($payload, 4);
        $step = $wide ? 8 : 4;
        for ($i = 0; $i < $total; $i++) {
            $origin = 8 + $i * $step;
            if ($origin + $step > strlen($payload)) {
                break;
            }
            $track->chunk_offsets[] = $wide ? self::readEightBytes($payload,
                $origin)
                : self::readFourBytes($payload, $origin);
        }
    }
    /**
     * findBox finds a named box inside a stretch of the file. An MP4 is built
     * of boxes inside boxes, so a reader walks down to the one it wants.
     *
     * @return array [absolute offset, size]
     * @param Mp4VideoTrack $track the track being read
     * @param int $sample which sample of the track
     */
    private function findBox(Mp4VideoTrack $track, int $sample): array
    {
        $n_chunks = count($track->chunk_offsets);
        $seen = 0;
        $total = count($track->samples_per_chunk);
        for ($entry = 0; $entry < $total; $entry++) {
            [$first_chunk, $per_chunk] = $track->samples_per_chunk[$entry];
            $last_chunk = ($entry + 1 < $total)
                ? $track->samples_per_chunk[$entry + 1][0] - 1 : $n_chunks;
            $run_chunks = $last_chunk - $first_chunk + 1;
            if ($run_chunks <= 0 || $per_chunk <= 0) {
                continue;
            }
            $run_samples = $run_chunks * $per_chunk;
            if ($sample < $seen + $run_samples) {
                $within       = $sample - $seen;
                /* 1-based */
                $chunk_position     = $first_chunk + intdiv($within,
                    $per_chunk);
                $sample_in_chunk = $within % $per_chunk;
                if (!isset($track->chunk_offsets[$chunk_position - 1])) {
                    throw new Mp4Exception("chunk $chunk_position "
                        . "is past the end of the file");
                }
                $offset = $track->chunk_offsets[$chunk_position - 1];
                for ($source = $sample
                    - $sample_in_chunk; $source < $sample; $source++) {
                    $offset += $track->sizeOfSample($source);
                }
                return [$offset, $track->sizeOfSample($sample)];
            }
            $seen += $run_samples;
        }
        throw new Mp4Exception("Sample $sample not covered by stsc");
    }
    /**
     * toPlainStream convert a stored H.264 sample to an Annex-B, the form an
     * H.264 stream takes on its own stream, with the parameter sets from the
     * avcC (the box holding an MP4's H.264 settings) record in front.
     *
     * @param string $sample which sample of the track
     * @return string what was read
     */
    public function toPlainStream(string $sample): string
    {
        $track = $this->videoTrack();
        $settings = new AvcConfig();
        $settings->sequence_settings = $track->sequence_settings;
        $settings->picture_settings = $track->picture_settings;
        $settings->stream_unit_length_size = $track->stream_unit_length_size;
        return self::plainStreamFrom($settings, $sample);
    }
    /**
     * durationSeconds works out how long the video runs.
     *
     * @return float what was read
     */
    public function durationSeconds(): float
    {
        $track = $this->videoTrack();
        if ($track->edit_duration > 0.0) {
            return $track->edit_duration;
        }
        return $track->clock_units_per_second > 0
            ? $track->track_length / $track->clock_units_per_second : 0.0;
    }
    /**
     * syncSamples 0-based indices of the sync samples, in decode order.
     *
     * @return array what was read
     */
    public function syncSamples(): array
    {
        $track = $this->videoTrack();
        if ($track->self_contained_samples !== []) {
            return array_map(static fn(int $total): int => $total
                - 1, $track->self_contained_samples);
        }
        return $track->sample_count > 0
            ? range(0, $track->sample_count - 1) : [];
    }
    /**
     * sampleTime works out when a sample is shown, in seconds from the start.
     * Edit lists and composition offsets are both taken into account, so this
     * agrees with what a player shows.
     *
     * @param int $index position of the sample in decode order
     * @return float what was read
     */
    public function sampleTime(int $index): float
    {
        return $this->videoTrack()->presentationTime($index);
    }
    /**
     * sampleData the stored bytes of one sample.
     *
     * @param int $index position of the sample in decode order
     * @return string what was read
     */
    public function sampleData(int $index): string
    {
        $track = $this->videoTrack();
        [$offset, $size] = $this->findBox($track, $index);
        return $this->readExact($offset, $size);
    }
    /**
     * codecName the codec name as the file spells it.
     *
     * @return string what was read
     */
    public function codecName(): string
    {
        return $this->videoTrack()->codec_name;
    }
    /**
     * containerName quickTime when the file says so in its brand, MP4
     * otherwise.
     *
     * @return string what was read
     */
    public function containerName(): string
    {
        return $this->file_brand === 'qt  ' ? 'QuickTime' : 'MP4';
    }
    /**
     * codecKind works out which decoder handles this track.
     *
     * @return string what was read
     */
    public function codecKind(): string
    {
        $chunk = $this->videoTrack()->codec_name;
        if ($chunk === 'avc1' || $chunk === 'avc3') {
            return 'h264';
        }
        if (in_array($chunk, ['hvc1', 'hev1', 'dvh1', 'dvhe'], true)) {
            return 'hevc';
        }
        /* MJPEG in MP4 and QuickTime goes under several sample entry names */
        if (in_array($chunk, ['jpeg', 'mjpa', 'mjpb', 'AVDJ', 'dmb1'], true)) {
            return 'jpeg';
        }
        return $chunk;
    }
    /**
     * frameWidth width of the picture in samples.
     *
     * @return int what was read
     */
    public function frameWidth(): int
    {
        return $this->videoTrack()->frame_width;
    }
    /**
     * frameHeight height of the picture in samples.
     *
     * @return int what was read
     */
    public function frameHeight(): int
    {
        return $this->videoTrack()->frame_height;
    }
    /**
     * settingsUnits the H.264 parameter sets the setup record carries.
     *
     * @return array what was read
     */
    public function settingsUnits(): array
    {
        if ($this->codecKind() === 'hevc') {
            return $this->videoTrack()->parameter_sets;
        }
        $track = $this->videoTrack();
        /* The box called avcC keeps whole units of the H.264 stream,
           header byte included */
        return array_values(array_filter([$track->sequence_settings,
            $track->picture_settings]));
    }
    /**
     * decodeHevc decodes one H.265 keyframe into a picture.
     *
     * @param string $frame the stored bytes of one frame
     * @return VideoPicture the decoded picture
     */
    public function decodeHevc(string $frame): VideoPicture
    {
        if ($this->hevc === null) {
            $this->hevc = new HevcDecoder();
            $this->hevc->consumeStored($this->settingsUnits());
        }
        return $this->hevc->decodeKeyframe($this->toPlainStream($frame));
    }
}
