<?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
 */
namespace seekquarry\yioop\library\av_processing;

/**
 * OpusPacket one piece of Opus sound, taken apart into the separate stretches
 * it is built from. A piece of Opus sound begins with a single byte saying how
 * the rest was compressed: which of the two methods inside Opus was used, how
 * much of the sound spectrum was kept, how long a stretch it covers, whether it
 * is one channel or two, and how many stretches follow. The stretches
 * themselves may be all the same length, or their lengths may be written out in
 * front of them, so getting at them means reading those lengths first. Opus is
 * really two ways of compressing sound in one wrapper: one built for speech,
 * one built for music, and a middle setting that runs both at once and splits
 * the spectrum between them. Which one a recording used decides how much work
 * playing it back takes, and the first byte of every piece is where that is
 * written down. Counting those bytes across a whole file says which of the two
 * a given recorder actually reaches for. The layout is set out in RFC 6716, the
 * specification of the Opus audio codec.
 */
class OpusPacket
{
    /**
     * SPEECH_METHOD is the way of compressing built for speech.
     */
    const SPEECH_METHOD = "speech";
    /**
     * BOTH_METHODS is both ways at once, splitting the spectrum between them.
     */
    const BOTH_METHODS = "both";
    /**
     * MUSIC_METHOD is the way of compressing built for music.
     */
    const MUSIC_METHOD = "music";
    /**
     * NARROW_SPECTRUM is only the lowest part of the spectrum was kept, to
     * about 4000 cycles a second.
     */
    const NARROW_SPECTRUM = "narrow";
    /**
     * MEDIUM_SPECTRUM is a little more was kept, to about 6000 cycles a second.
     */
    const MEDIUM_SPECTRUM = "medium";
    /**
     * WIDE_SPECTRUM is more still, to about 8000 cycles a second.
     */
    const WIDE_SPECTRUM = "wide";
    /**
     * WIDER_SPECTRUM is most of it, to about 12000 cycles a second.
     */
    const WIDER_SPECTRUM = "wider";
    /**
     * FULL_SPECTRUM is all a person can hear, to about 20000 cycles a second.
     */
    const FULL_SPECTRUM = "full";
    /**
     * SAMPLE_RATE is samples a second Opus gives back, whatever it was fed.
     */
    const SAMPLE_RATE = 48000;
    /**
     * MILLISECONDS_PER_SECOND is milliseconds in a second, used to turn a
     * stretch's length into a count of samples.
     */
    const MILLISECONDS_PER_SECOND = 1000;
    /**
     * SETTING_SHIFT is how far to shift the first byte to reach the setting
     * number.
     */
    const SETTING_SHIFT = 3;
    /**
     * SETTING_MASK is how much of the shifted first byte the setting number
     * takes.
     */
    const SETTING_MASK = 0x1F;
    /**
     * PAIRED_BIT is which bit of the first byte says the sound has two
     * channels.
     */
    const PAIRED_BIT = 0x04;
    /**
     * ARRANGEMENT_MASK is how much of the first byte says how many stretches
     * follow.
     */
    const ARRANGEMENT_MASK = 0x03;
    /**
     * ONE_STRETCH is one stretch, taking up the rest of the piece.
     */
    const ONE_STRETCH = 0;
    /**
     * TWO_EVEN_STRETCHES is the packing where a packet carries two
     * stretches of sound of the same length.
     */
    const TWO_EVEN_STRETCHES = 1;
    /**
     * TWO_UNEVEN_STRETCHES is the packing where a packet carries two
     * stretches of different lengths, with the first one's length
     * written out.
     */
    const TWO_UNEVEN_STRETCHES = 2;
    /**
     * MANY_STRETCHES is any number of stretches, counted in a byte of its own.
     */
    const MANY_STRETCHES = 3;
    /**
     * UNEVEN_BIT is which bit of the count byte says the stretches differ in
     * length.
     */
    const UNEVEN_BIT = 0x80;
    /**
     * FILLER_BIT is which bit of the count byte says filler was added at the
     * end.
     */
    const FILLER_BIT = 0x40;
    /**
     * COUNT_MASK is how much of the count byte holds the count itself.
     */
    const COUNT_MASK = 0x3F;
    /**
     * MAX_STRETCHES is the most stretches of sound one packet may carry,
     * which bounds how long a packet can run.
     */
    const MAX_STRETCHES = 48;
    /**
     * MAX_DURATION is longest a whole piece may run, in milliseconds.
     */
    const MAX_DURATION = 120;
    /**
     * SHORT_LENGTH_LIMIT is largest length that fits in a single byte; past
     * this a second byte is used.
     */
    const SHORT_LENGTH_LIMIT = 252;
    /**
     * LENGTH_STEP is what the second length byte counts in.
     */
    const LENGTH_STEP = 4;
    /**
     * FILLER_CONTINUES is a run of filler bytes of this value means more filler
     * follows.
     */
    const FILLER_CONTINUES = 255;
    /**
     * FILLER_PER_BYTE is how much filler a byte of the value above stands for.
     */
    const FILLER_PER_BYTE = 254;
    /**
     * Which of the thirty two settings the first byte named
     * @var int
     */
    public $setting;
    /**
     * is_paired stores whether the sound is two channels rather than one.
     * @var bool
     */
    public $is_paired;
    /**
     * method stores which of the two ways of compressing was used.
     * @var string
     */
    public $method;
    /**
     * How much of the sound spectrum was kept
     * @var string
     */
    public $spectrum;
    /**
     * stretch_duration stores how long one stretch covers, in milliseconds.
     * @var float
     */
    public $stretch_duration;
    /**
     * stretches stores the compressed pieces of sound this packet
     * carries, each covering the same fraction of a second.
     * @var array
     */
    public $stretches;
    /**
     * How much filler was added at the end of the piece, in bytes
     * @var int
     */
    public $filler;
    /**
     * The thirty two settings the first byte of a piece may name, each
     * giving the way of compressing, how much spectrum was kept, and
     * how long one stretch runs in milliseconds
     *
     * @return array the settings, in the order they are numbered
     */
    public static function settings()
    {
        static $settings = null;
        if ($settings !== null) {
            return $settings;
        }
        $settings = [];
        $speech_durations = [10.0, 20.0, 40.0, 60.0];
        $speech_spectra = [self::NARROW_SPECTRUM, self::MEDIUM_SPECTRUM,
            self::WIDE_SPECTRUM];
        foreach ($speech_spectra as $i => $spectrum) {
            foreach ($speech_durations as $j => $duration) {
                $settings[$i * 4 + $j] = [self::SPEECH_METHOD, $spectrum,
                    $duration];
            }
        }
        $both_durations = [10.0, 20.0];
        $both_spectra = [self::WIDER_SPECTRUM, self::FULL_SPECTRUM];
        foreach ($both_spectra as $i => $spectrum) {
            foreach ($both_durations as $j => $duration) {
                $settings[12 + $i * 2 + $j] = [self::BOTH_METHODS, $spectrum,
                    $duration];
            }
        }
        $music_durations = [2.5, 5.0, 10.0, 20.0];
        $music_spectra = [self::NARROW_SPECTRUM, self::WIDE_SPECTRUM,
            self::WIDER_SPECTRUM, self::FULL_SPECTRUM];
        foreach ($music_spectra as $i => $spectrum) {
            foreach ($music_durations as $j => $duration) {
                $settings[16 + $i * 4 + $j] = [self::MUSIC_METHOD, $spectrum,
                    $duration];
            }
        }
        ksort($settings);
        return $settings;
    }
    /**
     * fromString takes a piece of Opus sound apart into the stretches it is
     * built from
     *
     * @param string $data the piece as it was stored
     * @return object the piece taken apart
     */
    public static function fromString($data)
    {
        $length = strlen($data);
        if ($length < 1) {
            throw new \Exception("Opus piece is empty");
        }
        $packet = new self();
        $first = ord($data[0]);
        $packet->setting = ($first >> self::SETTING_SHIFT) &
            self::SETTING_MASK;
        $packet->is_paired = ($first & self::PAIRED_BIT) != 0;
        $arrangement = $first & self::ARRANGEMENT_MASK;
        $settings = self::settings();
        $packet->method = $settings[$packet->setting][0];
        $packet->spectrum = $settings[$packet->setting][1];
        $packet->stretch_duration = $settings[$packet->setting][2];
        $packet->filler = 0;
        $at = 1;
        if ($arrangement == self::ONE_STRETCH) {
            $packet->stretches = [substr($data, $at)];
        } else if ($arrangement == self::TWO_EVEN_STRETCHES) {
            $left = $length - $at;
            if ($left % 2 != 0) {
                throw new \Exception("Opus piece says two even stretches " .
                    "but cannot be halved");
            }
            $half = intdiv($left, 2);
            $packet->stretches = [substr($data, $at, $half),
                substr($data, $at + $half, $half)];
        } else if ($arrangement == self::TWO_UNEVEN_STRETCHES) {
            $first_length = self::readLength($data, $at);
            $at = $first_length["next_at"];
            if ($first_length["value"] > $length - $at) {
                throw new \Exception("Opus piece says a first stretch " .
                    "longer than the piece");
            }
            $packet->stretches = [
                substr($data, $at, $first_length["value"]),
                substr($data, $at + $first_length["value"])];
        } else {
            $packet->stretches = self::readManyStretches($data, $at, $packet);
        }
        return $packet;
    }
    /**
     * readManyStretches pulls apart a piece holding any number of stretches,
     * whose count and lengths are written in front of them records
     *
     * @param string $data the piece as it was stored
     * @param int $at where the count byte sits
     * @param object $packet the piece being built, whose filler this
     * @return array the stretches pulled out
     */
    public static function readManyStretches($data, $at, $packet)
    {
        $length = strlen($data);
        if ($at >= $length) {
            throw new \Exception("Opus piece is missing its count of " .
                "stretches");
        }
        $count_byte = ord($data[$at]);
        $at++;
        $uneven = ($count_byte & self::UNEVEN_BIT) != 0;
        $has_filler = ($count_byte & self::FILLER_BIT) != 0;
        $count = $count_byte & self::COUNT_MASK;
        if ($count < 1 || $count > self::MAX_STRETCHES) {
            throw new \Exception("Opus piece says an impossible number " .
                "of stretches");
        }
        if ($count * $packet->stretch_duration > self::MAX_DURATION) {
            throw new \Exception("Opus piece runs longer than a piece may");
        }
        if ($has_filler) {
            while (true) {
                if ($at >= $length) {
                    throw new \Exception("Opus piece ends part way through " .
                        "how much filler it has");
                }
                $part = ord($data[$at]);
                $at++;
                if ($part == self::FILLER_CONTINUES) {
                    $packet->filler += self::FILLER_PER_BYTE;
                } else {
                    $packet->filler += $part;
                    break;
                }
            }
        }
        $lengths = [];
        if ($uneven) {
            for ($i = 0; $i < $count - 1; $i++) {
                $read = self::readLength($data, $at);
                $lengths[] = $read["value"];
                $at = $read["next_at"];
            }
        }
        $left = $length - $at - $packet->filler;
        if ($left < 0) {
            throw new \Exception("Opus piece says more filler than it holds");
        }
        if ($uneven) {
            $used = array_sum($lengths);
            if ($used > $left) {
                throw new \Exception("Opus piece says stretches longer " .
                    "than it holds");
            }
            $lengths[] = $left - $used;
        } else {
            if ($left % $count != 0) {
                throw new \Exception("Opus piece says even stretches but " .
                    "cannot be divided");
            }
            $lengths = array_fill(0, $count, intdiv($left, $count));
        }
        $stretches = [];
        foreach ($lengths as $stretch_length) {
            $stretches[] = substr($data, $at, $stretch_length);
            $at += $stretch_length;
        }
        return $stretches;
    }
    /**
     * readLength reads how long one stretch is, which takes one byte for
     * shorter stretches and two for longer ones
     *
     * @param string $data the piece as it was stored
     * @param int $at where the length sits
     * @return array the length and where it ends
     */
    public static function readLength($data, $at)
    {
        $length = strlen($data);
        if ($at >= $length) {
            throw new \Exception("Opus piece ends where a stretch length " .
                "was expected");
        }
        $first = ord($data[$at]);
        $at++;
        if ($first < self::SHORT_LENGTH_LIMIT) {
            return ["value" => $first, "next_at" => $at];
        }
        if ($at >= $length) {
            throw new \Exception("Opus piece ends part way through a " .
                "stretch length");
        }
        $second = ord($data[$at]);
        $at++;
        return ["value" => $first + $second * self::LENGTH_STEP,
            "next_at" => $at];
    }
    /**
     * duration how long the whole piece covers, in milliseconds
     *
     * @return float the length of the piece in milliseconds
     */
    public function duration()
    {
        return $this->stretch_duration * count($this->stretches);
    }
    /**
     * describe a short phrase naming how this piece was compressed, for
     * counting up what a file is built from kept, how long a stretch runs, and
     * how many channels
     *
     * @return string the way of compressing, how much spectrum was
     */
    public function describe()
    {
        return $this->method . "/" . $this->spectrum . "/" .
            $this->stretch_duration . "ms/" .
            ($this->is_paired ? "two channel" : "one channel");
    }
}
