<?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;

/**
 * CeltStereoBands reads a band that carries two channels. Two channels of the
 * same moment are nearly the same sound, so storing them separately would store
 * almost everything twice. Instead the two are turned into their average and
 * their difference before being stored. The average carries nearly all of the
 * sound and the difference carries only what the two channels disagree about,
 * which for most recordings is little, so the difference costs far less than a
 * second channel would. How the loudness divided between the average and the
 * difference is stored for each band, in the same way a split band's lean is
 * stored, and the two are put back into left and right afterwards. High up the
 * range the ear stops telling the two channels apart by their difference and
 * hears only their relative loudness. Above the band where that begins, the
 * difference is not stored at all and the two channels are given the same sound
 * at different loudnesses. A recording may also say that a stretch was stored
 * as two plain channels side by side rather than as an average and a
 * difference, which suits sound where the two channels have little in common.
 * This follows RFC 6716, the specification of the Opus audio codec.
 */
class CeltStereoBands
{
    /**
     * BIT_PARTS is how finely room is counted, as parts of a bit.
     */
    const BIT_PARTS = 3;
    /**
     * SPLIT_OFFSET is how much a split is favored in the usual case.
     */
    const SPLIT_OFFSET = 4;
    /**
     * SPLIT_OFFSET_PAIR is the same where a band has only two slots, which is
     * stored a different way.
     */
    const SPLIT_OFFSET_PAIR = 16;
    /**
     * QUARTER_TURN is a quarter turn, which is what a lean of everything to one
     * side comes to.
     */
    const QUARTER_TURN = 16384;
    /**
     * EVEN_LEAN is half a quarter turn, the lean at which the two sides are
     * even.
     */
    const EVEN_LEAN = 8192;
    /**
     * LOWER_WEIGHT is how much likelier the lower half of the lean range is
     * than the upper, since two channels usually agree more than they differ.
     */
    const LOWER_WEIGHT = 3;
    /**
     * OPPOSED_CHANCE is how unlikely it is that the two channels are opposed
     * rather than alike.
     */
    const OPPOSED_CHANCE = 2;
    /**
     * TOO_QUIET is below this the two channels are taken as the same sound
     * rather than merged, since merging them would divide by almost nothing.
     */
    const TOO_QUIET = 0.0006;
    /**
     * readPair reads one band of two channels been doubled sound at different
     * loudnesses
     *
     * @param object $reader the band reader walking this stretch
     * @param array $left the first channel's slots, changed in place
     * @param array $right the second channel's slots, changed in place
     * @param int $at where in those the band begins
     * @param int $width how many slots the band has
     * @param int $room how much room the band gets
     * @param int $groups how many groups the band is looked at in
     * @param mixed $below the band to copy from, or null
     * @param int $doublings how many times the shortest stretch has
     * @param int $filled which groups of the band below hold something
     * @param bool $joined whether the two channels are given the same
     * @return int which groups this band holds
     */
    public static function readPair($reader, &$left, &$right, $at, $width,
        $room, $groups, $below, $doublings, $filled, $joined)
    {
        $lean = self::readLean($reader, $width, $room, $groups, $doublings,
            $filled, $joined);
        $room = $lean["room"];
        $filled = $lean["filled"];
        if ($width == 2) {
            return self::readNarrowPair($reader, $left, $right, $at, $room,
                $groups, $below, $doublings, $lean, $filled);
        }
        $middle_room = max(0, min($room, intdiv($room - $lean["gap"], 2)));
        $side_room = $room - $middle_room;
        $marks = 0;
        if ($middle_room >= $side_room) {
            $before = $reader->room_left;
            $read = $reader->readBand($left, $at, $width, $middle_room,
                $groups, $below, $doublings, $filled);
            $marks = $read["marks"];
            $spare = $middle_room - ($before - $reader->room_left);
            if ($spare > 3 << self::BIT_PARTS && $lean["turn"] != 0) {
                $side_room += $spare - (3 << self::BIT_PARTS);
            }
            $read = $reader->readBand($right, $at, $width, $side_room,
                $groups, null, $doublings, $filled >> $groups,
                $lean["side"]);
            $marks |= $read["marks"];
        } else {
            $before = $reader->room_left;
            $read = $reader->readBand($right, $at, $width, $side_room,
                $groups, null, $doublings, $filled >> $groups,
                $lean["side"]);
            $marks = $read["marks"];
            $spare = $side_room - ($before - $reader->room_left);
            if ($spare > 3 << self::BIT_PARTS &&
                $lean["turn"] != self::QUARTER_TURN) {
                $middle_room += $spare - (3 << self::BIT_PARTS);
            }
            $read = $reader->readBand($left, $at, $width, $middle_room,
                $groups, $below, $doublings, $filled);
            $marks |= $read["marks"];
        }
        /* What lower bands are copied from is the average channel as
           it stood here, before it was turned back into left and
           right, at the loudness the split gave it. */
        $mid_kept = [];
        for ($slot = 0; $slot < $width; $slot++) {
            $mid_kept[] = $lean["middle"] * $left[$at + $slot];
        }
        self::merge($left, $right, $at, $width, $lean["middle"]);
        if ($lean["opposed"]) {
            for ($slot = 0; $slot < $width; $slot++) {
                $right[$at + $slot] = -$right[$at + $slot];
            }
        }
        return ["marks" => $marks, "mid" => $mid_kept];
    }
    /**
     * readNarrowPair reads a band of two slots, where the difference between
     * the channels needs only a single bit because it can only point one of two
     * ways been doubled was stored, which lower bands copy from
     *
     * @param object $reader the band reader walking this stretch
     * @param array $left the first channel's slots, changed in place
     * @param array $right the second channel's slots, changed in place
     * @param int $at where in those the band begins
     * @param int $room how much room the band gets
     * @param int $groups how many groups the band is looked at in
     * @param mixed $below the band to copy from, or null
     * @param int $doublings how many times the shortest stretch has
     * @param array $lean how the loudness divided
     * @param int $filled which groups of the band below hold something
     * @return array which groups this band holds and the channel that
     */
    public static function readNarrowPair($reader, &$left, &$right, $at,
        $room, $groups, $below, $doublings, $lean, $filled)
    {
        $side_room = 0;
        if ($lean["turn"] != 0 && $lean["turn"] != self::QUARTER_TURN) {
            $side_room = 1 << self::BIT_PARTS;
        }
        $middle_room = $room - $side_room;
        $swapped = ($lean["turn"] > self::EVEN_LEAN);
        $reader->room_left -= $side_room;
        $sign = 1.0;
        if ($side_room > 0) {
            $sign = ($reader->reader->decodeRawBits(1) != 0) ? -1.0 : 1.0;
        }
        /* The louder of the two is read and the quieter follows from
           it, turned a quarter way round, since the two are at right
           angles to each other. */
        $first = $swapped ? $right : $left;
        $read = $reader->readBand($first, $at, 2, $middle_room, $groups,
            $below, $doublings, $filled);
        $marks = $read["marks"];
        $second = [$at => -$sign * $first[$at + 1],
            $at + 1 => $sign * $first[$at]];
        if ($swapped) {
            $right = $first;
            $left[$at] = $second[$at];
            $left[$at + 1] = $second[$at + 1];
        } else {
            $left = $first;
            $right[$at] = $second[$at];
            $right[$at + 1] = $second[$at + 1];
        }
        /* For a band this narrow the channel that was stored is the
           one lower bands copy from, as it was read. */
        $mid_kept = [$first[$at], $first[$at + 1]];
        $middle = $lean["middle"];
        $side = $lean["side"];
        for ($slot = 0; $slot < 2; $slot++) {
            $one = $middle * $left[$at + $slot];
            $other = $side * $right[$at + $slot];
            $left[$at + $slot] = $one - $other;
            $right[$at + $slot] = $one + $other;
        }
        return ["marks" => $marks, "mid" => $mid_kept];
    }
    /**
     * readLean reads how the loudness divided between the average of the two
     * channels and their difference been doubled room
     *
     * @param object $reader the band reader walking this stretch
     * @param int $width how many slots the band has
     * @param int $room how much room the band gets
     * @param int $groups how many groups the band is looked at in
     * @param int $doublings how many times the shortest stretch has
     * @param int $filled which groups of the band below hold something
     * @param bool $joined whether the difference is not stored at all
     * @return array how the loudness divided and what is left of the
     */
    public static function readLean($reader, $width, $room, $groups,
        $doublings, $filled, $joined)
    {
        $before = $reader->reader->bitsUsedFinely();
        $ceiling = CeltPulseCache::widthLog($reader->band) +
            $doublings * (1 << self::BIT_PARTS);
        $offset = ($ceiling >> 1) -
            (($width == 2) ? self::SPLIT_OFFSET_PAIR : self::SPLIT_OFFSET);
        $steps = CeltBandReader::leanSteps($width, $room, $offset, $ceiling);
        if ($joined) {
            $steps = 1;
        }
        $turn = 0;
        $opposed = false;
        if ($steps != 1) {
            if ($width > 2) {
                $turn = self::readWeighted($reader, $steps);
            } else {
                $turn = $reader->reader->decodeNumber($steps + 1);
            }
            $turn = intdiv($turn * self::QUARTER_TURN, $steps);
        } else {
            /* Where the difference is not stored, one bit may still say
               that the two channels are opposed rather than alike. */
            if ($room > (2 << self::BIT_PARTS) &&
                $reader->room_left > (2 << self::BIT_PARTS)) {
                $opposed = ($reader->reader->decodeBit(
                    self::OPPOSED_CHANCE) != 0);
            }
        }
        $spent = $reader->reader->bitsUsedFinely() - $before;
        $reader->room_left -= $spent;
        $room -= $spent;
        if ($turn == 0) {
            $middle = 32767 / 32768.0;
            $side = 0.0;
            $filled &= (1 << $groups) - 1;
            $gap = -self::QUARTER_TURN;
        } else if ($turn == self::QUARTER_TURN) {
            $middle = 0.0;
            $side = 32767 / 32768.0;
            $filled &= ((1 << $groups) - 1) << $groups;
            $gap = self::QUARTER_TURN;
        } else {
            $across = CeltShape::steadyCos($turn);
            $up = CeltShape::steadyCos(self::QUARTER_TURN - $turn);
            $middle = $across / 32768.0;
            $side = $up / 32768.0;
            $gap = CeltShape::fracTimes(($width - 1) << 7,
                CeltShape::leanLog($up, $across));
        }
        return ["turn" => $turn, "middle" => $middle, "side" => $side,
            "gap" => $gap, "room" => $room, "filled" => $filled,
            "opposed" => $opposed];
    }
    /**
     * readWeighted reads a lean where the lower half of the range is likelier
     * than the upper, which is how a two channel split is stored because two
     * channels usually agree more than they differ
     *
     * @param object $reader the band reader walking this stretch
     * @param int $steps how many steps the lean is stored in
     * @return int which step the lean fell on
     */
    public static function readWeighted($reader, $steps)
    {
        $half = intdiv($steps, 2);
        $whole = self::LOWER_WEIGHT * ($half + 1) + $half;
        $found = $reader->reader->decode($whole);
        if ($found < ($half + 1) * self::LOWER_WEIGHT) {
            $turn = intdiv($found, self::LOWER_WEIGHT);
        } else {
            $turn = $half + 1 + ($found - ($half + 1) * self::LOWER_WEIGHT);
        }
        if ($turn <= $half) {
            $below = self::LOWER_WEIGHT * $turn;
            $above = self::LOWER_WEIGHT * ($turn + 1);
        } else {
            $below = ($turn - 1 - $half) + ($half + 1) * self::LOWER_WEIGHT;
            $above = ($turn - $half) + ($half + 1) * self::LOWER_WEIGHT;
        }
        $reader->reader->update($below, $above, $whole);
        return $turn;
    }
    /**
     * merge turns the average of the two channels and their difference back
     * into left and right, each brought to the loudness it should have
     *
     * @param array $left the average, replaced by the left channel
     * @param array $right the difference, replaced by the right
     * @param int $at where in those the band begins
     * @param int $width how many slots the band has
     * @param float $middle how loud the average is
     */
    public static function merge(&$left, &$right, $at, $width, $middle)
    {
        $crossed = 0.0;
        $difference = 0.0;
        for ($slot = 0; $slot < $width; $slot++) {
            $crossed += $right[$at + $slot] * $left[$at + $slot];
            $difference += $right[$at + $slot] * $right[$at + $slot];
        }
        $crossed *= $middle;
        $one = $middle * $middle + $difference - 2 * $crossed;
        $other = $middle * $middle + $difference + 2 * $crossed;
        /* Where either side comes to almost nothing, dividing by it
           would run away, so the two channels are given the same
           sound. */
        if ($one < self::TOO_QUIET || $other < self::TOO_QUIET) {
            for ($slot = 0; $slot < $width; $slot++) {
                $right[$at + $slot] = $left[$at + $slot];
            }
            return;
        }
        $one_gain = 1.0 / sqrt($one);
        $other_gain = 1.0 / sqrt($other);
        for ($slot = 0; $slot < $width; $slot++) {
            $average = $middle * $left[$at + $slot];
            $differs = $right[$at + $slot];
            $left[$at + $slot] = $one_gain * ($average - $differs);
            $right[$at + $slot] = $other_gain * ($average + $differs);
        }
    }
}
