<?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 Ogg file. It finds the video stream, gathers its
 * pages, and gives the Theora frames they carry.
 */
namespace seekquarry\yioop\library\av_processing;
/**
 * OggReader ogg container reader. An Ogg file is a sequence of pages, each
 * belonging to a logical stream identified by a serial number. A page carries a
 * segment table; a run of 255-byte segments continues a packet and any shorter
 * segment ends one, so packets can span pages in either direction. Only the
 * byte ranges of each packet are kept, not the bytes themselves, so indexing a
 * long file costs a few integers per frame rather than its payload.
 */
final class OggReader
{
    use ByteSource;
    /**
     * $pages_block_y_stream stores the pages of each stream in the file, kept
     * by the
     * number the file gives that stream. An Ogg may carry sound and video
     * together, so the two are read apart.
     * @var array
     */
    private array $pages_block_y_stream = [];
    /**
     * $stream_numbers_in_order stores the stream numbers in the order they
     * first appear, so the video stream can be found without guessing.
     * @var array
     */
    private array $stream_numbers_in_order = [];
    /**
     * __construct opens an Ogg file and walks its pages so that every packet's
     * byte range is known.
     *
     * @param string $path file to read
     */
    public function __construct(string $path)
    {
        $this->openSource($path);
        $this->scanPages();
    }
    /**
     * serials gives the numbers of the streams the file carries, in the order
     * they first appear.
     *
     * @return array serial numbers, in the order the streams start
     */
    public function serials(): array
    {
        return $this->stream_numbers_in_order;
    }
    /**
     * packets gathers every packet of one stream, in the order the
     * file wrote them. An Ogg file cuts its streams into pages and
     * may spread one packet over several pages, so this puts the
     * pieces back together before a decoder sees them.
     *
     * @param int $video_stream_number The number the file gives the
     *     stream to gather.
     * @return array The packets of that stream, in order.
     */
    public function packets(int $video_stream_number): array
    {
        return $this->pages_block_y_stream[$video_stream_number] ?? [];
    }
    /**
     * packetData gathers a packet from the stretches of the file its parts sit
     * in. An Ogg page may carry part of a packet, so a packet is often spread
     * over several pages
     *
     * @param array $packet the packet read off the stream
     * @return string what was read
     */
    public function packetData(array $packet): string
    {
        $written = '';
        foreach ($packet['ranges'] as [$off, $length]) {
            $written .= $this->readBytesAt($off, $length);
        }
        return $written;
    }
    /**
     * packetPrefix the first bytes of a packet, without reading all of it
     *
     * @param array $packet the packet read off the stream
     * @param int $length how many bytes to read
     * @return string what was read
     */
    public function packetPrefix(array $packet, int $length): string
    {
        $written = '';
        foreach ($packet['ranges'] as [$off, $length]) {
            $written .= $this->readBytesAt($off, min($length, $length -
                strlen($written)));
            if (strlen($written) >= $length) {
                break;
            }
        }
        return $written;
    }
    /**
     * scanPages walks the file's pages and records where each packet sits.
     */
    private function scanPages(): void
    {
        $position = 0;
        /* serial => ranges of the packet still being assembled */
        $partial = [];
        while ($position + 27 <= $this->sourceSize()) {
            $head = $this->readBytesAt($position, 27);
            if (strlen($head) < 27) {
                break;
            }
            if (substr($head, 0, 4) !== 'OggS') {
                /* resynchronise on the next capture pattern */
                $next = $this->findCapture($position + 1);
                if ($next === null) {
                    break;
                }
                $position = $next;
                continue;
            }
            $header_type = ord($head[5]);
            $eight = substr($head, 6, 8);
            $low = unpack('V', substr($eight, 0, 4))[1];
            $high = unpack('V', substr($eight, 4, 4))[1];
            $granule = $low | ($high << 32);
            if ($high & 0x80000000) {
                $granule = $granule - (1 << 64);
            }
            $video_stream_number = unpack('V', substr($head, 14, 4))[1];
            $segment_count = ord($head[26]);
            $table = $this->readBytesAt($position + 27, $segment_count);
            if (strlen($table) < $segment_count) {
                break;
            }
            $data_start = $position + 27 + $segment_count;
            if (!isset($this->pages_block_y_stream[$video_stream_number])) {
                $this->pages_block_y_stream[$video_stream_number] = [];
                $this->stream_numbers_in_order[] = $video_stream_number;
            }
            if (($header_type & 0x01) === 0) {
                /* a fresh page that does not continue a packet */
                $partial[$video_stream_number] = [];
            }
            $offset = $data_start;
            $current = $partial[$video_stream_number] ?? [];
            $page_total = 0;
            for ($i = 0; $i < $segment_count; $i++) {
                $length = ord($table[$i]);
                $page_total += $length;
                if ($length > 0) {
                    $current[] = [$offset, $length];
                    $offset += $length;
                }
                if ($length < 255) {
                    /* a segment shorter than 255 bytes ends the packet */
                    $this->pages_block_y_stream[$video_stream_number][] = [
                        'ranges'  => $current,
                        'granule' => -1,
                    ];
                    $current = [];
                }
            }
            $partial[$video_stream_number] = $current;
            /* the granule position on a page belongs to the last packet that */
            /* finishes on it */
            $pages = $this->pages_block_y_stream[$video_stream_number];
            if ($current === [] && $pages !== []) {
                $last = count($pages) - 1;
                $this->pages_block_y_stream[$video_stream_number][$last]
                    ['granule'] = $granule;
            }
            $position = $data_start + $page_total;
        }
    }
    /**
     * findCapture finds the next page marker in the file, used to pick the
     * stream back up after damage.
     *
     * @param int $from where it is read from
     * @return int what was read
     */
    private function findCapture(int $from): ?int
    {
        $chunk_size = 65536;
        $position = $from;
        while ($position < $this->sourceSize()) {
            $bytes = $this->readBytesAt($position, $chunk_size);
            if ($bytes === '') {
                return null;
            }
            $hit = strpos($bytes, 'OggS');
            if ($hit !== false) {
                return $position + $hit;
            }
            /* keep three bytes of overlap so a split capture pattern is found
              */
            $position += max(1, strlen($bytes) - 3);
        }
        return null;
    }
}

/**
 * OggExtractor reads an Ogg file, gathering the pages of its video stream
 * and the frames they carry.
 */
final class OggExtractor extends VideoExtractor
{
    /**
     * $page_reader stores the reader that walks the file's pages. Every packet
     * handed to the decoder comes through it.
     * @var OggReader
     */
    private OggReader $page_reader;
    /**
     * $theora_decoder stores the Theora decoder, made once the stream's headers
     * have been read. Read by decodeTheora(), frameHeight(), frameRate().
     * @var TheoraDecoder
     */
    private TheoraDecoder $theora_decoder;
    /**
     * $video_stream_number stores which stream of the file the video is, by the
     * number the file gives it. Pages of any other stream are passed over.
     * @var int
     */
    private int $video_stream_number = -1;
    /**
     * $frame_table stores where each frame's packet sits and when it is shown.
     * Read by durationSeconds(), frameCount(), sampleData().
     * @var array
     */
    private array $frame_table = [];
    /**
     * $self_contained_frames stores which of those frames stand on their own. A
     * thumbnail is decoded from one of these, so a moment asked for picks the
     * nearest before it.
     * @var array
     */
    private array $self_contained_frames = [];
    /**
     * __construct opens an Ogg file and indexes its Theora stream. The pages
     * are read once so that the byte range of every packet is known, which
     * frame each packet holds, and which of those are keyframes.
     *
     * @param string $path file to read
     */
    public function __construct(string $path)
    {
        $this->page_reader = new OggReader($path);
        $this->theora_decoder = new TheoraDecoder();
        foreach ($this->page_reader->serials() as $video_stream_number) {
            $packets = $this->page_reader->packets($video_stream_number);
            if ($packets === []) {
                continue;
            }
            if ($this->page_reader->packetPrefix($packets[0],
                7) === "\x80theora") {
                $this->video_stream_number = $video_stream_number;
                break;
            }
        }
        if ($this->video_stream_number < 0) {
            throw new VideoException('no Theora video stream in this Ogg file');
        }
        foreach ($this->page_reader->packets($this
            ->video_stream_number) as $packet) {
            $first = $this->page_reader->packetPrefix($packet, 1);
            if ($first === '') {
                continue;
            }
            if ((ord($first) & 0x80) !== 0) {
                $this->theora_decoder->addHeader($this->page_reader
                    ->packetData($packet));
                continue;
            }
            /* a data packet: bit 6 of the first byte distinguishes a keyframe
              */
            if ((ord($first) & 0x40) === 0) {
                $this->self_contained_frames[] = count($this->frame_table);
            }
            $this->frame_table[] = $packet;
        }
        if (!$this->theora_decoder->isReady()) {
            throw new VideoException(
                'Theora headers are missing or incomplete');
        }
        if ($this->frame_table === []) {
            throw new VideoException('no Theora frames in this file');
        }
    }
    /**
     * frameRate frames a second, taken from the stream's identification header.
     *
     * @return float what was read
     */
    private function frameRate(): float
    {
        $den = $this->theora_decoder->frame_rate_den;
        return $den > 0 ? $this->theora_decoder->frame_rate_count / $den : 25.0;
    }
    /**
     * durationSeconds works out how long the video runs.
     *
     * @return float what was read
     */
    public function durationSeconds(): float
    {
        return count($this->frame_table) / $this->frameRate();
    }
    /**
     * syncSamples positions of the frames that can be decoded on their own.
     *
     * @return array what was read
     */
    public function syncSamples(): array
    {
        return $this->self_contained_frames;
    }
    /**
     * sampleTime works out when a frame is shown, in seconds from the start.
     *
     * @param int $index position of the sample in decode order
     * @return float what was read
     */
    public function sampleTime(int $index): float
    {
        return $index / $this->frameRate();
    }
    /**
     * sampleData the stored bytes of one frame.
     *
     * @param int $index position of the sample in decode order
     * @return string what was read
     */
    public function sampleData(int $index): string
    {
        if (!isset($this->frame_table[$index])) {
            throw new VideoException("no frame at index $index");
        }
        return $this->page_reader->packetData($this->frame_table[$index]);
    }
    /**
     * codecKind works out which decoder handles this stream.
     *
     * @return string what was read
     */
    public function codecKind(): string
    {
        return 'theora';
    }
    /**
     * codecName the codec name as the file spells it.
     *
     * @return string what was read
     */
    public function codecName(): string
    {
        return 'theora';
    }
    /**
     * containerName the container format this reader handles.
     *
     * @return string what was read
     */
    public function containerName(): string
    {
        return 'Ogg';
    }
    /**
     * frameWidth width of the picture in samples.
     *
     * @return int what was read
     */
    public function frameWidth(): int
    {
        return $this->theora_decoder->picture_w;
    }
    /**
     * frameHeight height of the picture in samples.
     *
     * @return int what was read
     */
    public function frameHeight(): int
    {
        return $this->theora_decoder->picture_h;
    }
    /**
     * frameCount works out how many frames the video holds.
     *
     * @return int what was read
     */
    public function frameCount(): int
    {
        return count($this->frame_table);
    }
    /**
     * settingsUnits nothing, since Theora carries its setup in its own headers.
     *
     * @return array what was read
     */
    public function settingsUnits(): array
    {
        return [];
    }
    /**
     * toPlainStream refuses, since Theora is not an H.264 stream.
     *
     * @param string $sample the stored bytes of one sample
     * @return string what was read
     */
    public function toPlainStream(string $sample): string
    {
        throw new VideoException('Theora is not an H.264 stream');
    }
    /**
     * decodeTheora decodes one Theora keyframe into a picture.
     *
     * @param string $packet the stored bytes of one packet
     * @return VideoPicture what was read
     */
    public function decodeTheora(string $packet): VideoPicture
    {
        return $this->theora_decoder->decodeIntra($packet);
    }
}
