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

/**
 * SpeechPulses reads the pulses of a stretch of speech: the sound left
 * over once the shape of the mouth and the pitch of the voice have been
 * taken out of it.
 *
 * The pulses are written a block of sixteen samples at a time. A block
 * carries how many pulses it holds altogether, and that count is then
 * split in half again and again: first between the two halves of the
 * block, then between the halves of those, until each sample has a count
 * of its own. A block written loudly carries extra bits after the split,
 * one for each doubling of its counts. Last of all, each sample that
 * holds any pulses says which way they point.
 *
 * A caller reads the pulses after the shape and the pitch. What comes
 * back is one number for each sample of the stretch, which the next step
 * scales by the loudness of its quarter and passes through the two
 * filters.
 *
 * @author Chris Pollett
 */
class SpeechPulses
{
    /**
     * $density stores which level of pulse density the stretch named,
     * counting from zero. The level chooses the likelihoods the counts
     * are read with.
     * @var int
     */
    public $density = 0;
    /**
     * $block_counts stores how many pulses each block of sixteen samples
     * holds, in the order the blocks are played.
     * @var array
     */
    public $block_counts = [];
    /**
     * $samples stores the pulses of each sample of the stretch, in
     * playing order, each with the sign the stretch gave it.
     * @var array
     */
    public $samples = [];
    /**
     * $seed stores the starting number the stretch gives for the noise
     * the decoder adds back to the pulses.
     * @var int
     */
    public $seed = 0;
    /**
     * SPLITS_IN_BLOCK is how many times a block's count is halved before
     * each sample has a count of its own: sixteen samples take four
     * halvings.
     */
    const SPLITS_IN_BLOCK = 4;
    /**
     * MOST_EXTRA_BITS is the most doublings a block may carry. Past this
     * the writer stops offering the choice, so the table it reads counts
     * from is shifted by one.
     */
    const MOST_EXTRA_BITS = 10;
    /**
     * SIGN_SETS_PER_KIND is how many sets of sign likelihoods each kind
     * of sound has, one for each band of block loudness.
     */
    const SIGN_SETS_PER_KIND = 6;
    /**
     * read gives the pulses a stretch carries: the density it named, how
     * many pulses each block holds, and the pulses of each sample.
     *
     * @param object $reader the range decoder reading the stretch
     * @param string $kind which kind of sound the stretch holds, since
     *     speech made with the voice uses different likelihoods
     * @param string $pulse_writing which of the two ways the pulses were
     *     written, the quieter or the louder
     * @param int $samples how many samples the stretch covers
     * @param bool $independent whether the stretch stands on its own
     *     rather than leaning on the stretch before it, since a stretch
     *     that stands alone writes one extra thing before its pulses
     * @return object the pulses of the stretch
     */
    public static function read($reader, $kind, $pulse_writing, $samples,
        $independent = true)
    {
        $pulses = new self();
        $voiced = ($kind === SpeechTables::VOICED_KIND);
        /* Between the pitch and the pulses a stretch writes a starting
           number for the noise the decoder adds back. How much of the
           sound before it to lean on is read with the pitch, since only
           a voiced stretch writes it. */
        $pulses->seed = $reader->decodeFromTable(
            SpeechPulseTables::SEED_CHANCES,
            SpeechPulseTables::WHOLE_BITS);
        $rates = SpeechPulseTables::PULSE_RATE_CHANCES;
        $half = intdiv(count($rates), 2);
        $table = array_slice($rates, $voiced ? $half : 0, $half);
        $pulses->density = $reader->decodeFromTable($table,
            SpeechPulseTables::WHOLE_BITS);
        $blocks = intdiv($samples, SpeechPulseTables::SAMPLES_IN_BLOCK);
        $doublings = [];
        $pulses->block_counts = self::readBlockCounts($reader,
            $pulses->density, $blocks, $doublings);
        $pulses->samples = [];
        foreach ($pulses->block_counts as $at => $count) {
            $spread = ($count > 0) ? self::splitCount($reader, $count) :
                array_fill(0, SpeechPulseTables::SAMPLES_IN_BLOCK, 0);
            $spread = self::addExtraBits($reader, $spread,
                $doublings[$at]);
            foreach ($spread as $one) {
                $pulses->samples[] = $one;
            }
        }
        self::addSigns($reader, $pulses, $kind, $pulse_writing,
            $doublings);
        return $pulses;
    }
    /**
     * readBlockCounts gives how many pulses each block of the stretch
     * holds. A count one past the largest allowed says the block was
     * written loudly, so its counts are doubled afterwards and a fresh
     * count is read; that may happen several times over.
     *
     * @param object $reader the range decoder reading the stretch
     * @param int $density which level of pulse density the stretch named
     * @param int $blocks how many blocks the stretch holds
     * @param array $doublings filled in with how many doublings each
     *     block carries
     * @return array the count of pulses in each block
     */
    public static function readBlockCounts($reader, $density, $blocks,
        &$doublings)
    {
        $chances = SpeechPulseTables::PULSES_IN_BLOCK_CHANCES;
        $each = intdiv(count($chances), SpeechPulseTables::RATE_LEVELS);
        $table = array_slice($chances, $density * $each, $each);
        $loudest = array_slice($chances,
            (SpeechPulseTables::RATE_LEVELS - 1) * $each, $each);
        $counts = [];
        $doublings = [];
        for ($at = 0; $at < $blocks; $at++) {
            $doubled = 0;
            $count = $reader->decodeFromTable($table,
                SpeechPulseTables::WHOLE_BITS);
            while ($count == SpeechPulseTables::MOST_PULSES_IN_BLOCK + 1) {
                $doubled++;
                $shifted = ($doubled == self::MOST_EXTRA_BITS) ?
                    array_slice($loudest, 1) : $loudest;
                $count = $reader->decodeFromTable($shifted,
                    SpeechPulseTables::WHOLE_BITS);
            }
            $counts[] = $count;
            $doublings[] = $doubled;
        }
        return $counts;
    }
    /**
     * splitCount spreads a block's count of pulses over its sixteen
     * samples. The count is split between the two halves of the block,
     * then between the halves of those, and so on four times over. Each
     * split is read with the likelihoods for the count being split.
     *
     * @param object $reader the range decoder reading the stretch
     * @param int $count how many pulses the block holds altogether
     * @return array the count of pulses at each of the sixteen samples
     */
    public static function splitCount($reader, $count)
    {
        return self::splitPart($reader, $count,
            self::SPLITS_IN_BLOCK);
    }
    /**
     * splitPart spreads a count over the samples of one part of a block,
     * splitting it in half and then working each half all the way down
     * before starting on the other. The writer wrote the splits in that
     * order, so a reader that took a whole level at a time would take
     * the bits of one half for the other.
     *
     * @param object $reader the range decoder reading the stretch
     * @param int $count how many pulses this part holds
     * @param int $depth how many halvings are left to do
     * @return array the count of pulses at each sample of this part
     */
    public static function splitPart($reader, $count, $depth)
    {
        if ($depth <= 0) {
            return [$count];
        }
        $tables = [SpeechPulseTables::SPLIT_CHANCES_ONE,
            SpeechPulseTables::SPLIT_CHANCES_TWO,
            SpeechPulseTables::SPLIT_CHANCES_FOUR,
            SpeechPulseTables::SPLIT_CHANCES_EIGHT];
        $left = self::splitOne($reader, $count, $tables[$depth - 1]);
        $first = self::splitPart($reader, $left, $depth - 1);
        $second = self::splitPart($reader, $count - $left, $depth - 1);
        return array_merge($first, $second);
    }
    /**
     * splitOne says how many of a count of pulses fall in the first of
     * two halves. Where the count is nothing, so is the answer, and no
     * bits are read for it.
     *
     * @param object $reader the range decoder reading the stretch
     * @param int $count how many pulses are being split
     * @param array $table the likelihoods for this depth of splitting
     * @return int how many pulses fall in the first half
     */
    public static function splitOne($reader, $count, $table)
    {
        if ($count <= 0) {
            return 0;
        }
        $starts = SpeechPulseTables::SPLIT_TABLE_STARTS;
        $where = $starts[min($count, count($starts) - 1)];
        $next = ($count + 1 < count($starts)) ? $starts[$count + 1] :
            count($table);
        $slice = array_slice($table, $where, max(1, $next - $where));
        return $reader->decodeFromTable($slice,
            SpeechPulseTables::WHOLE_BITS);
    }
    /**
     * addExtraBits doubles the counts of a block that was written loudly
     * and reads one extra bit for each doubling. A loud block writes its
     * counts small and makes up the difference this way.
     *
     * @param object $reader the range decoder reading the stretch
     * @param array $spread the count of pulses at each sample
     * @param int $doublings how many doublings the block carries
     * @return array the counts after doubling and adding the extra bits
     */
    public static function addExtraBits($reader, $spread, $doublings)
    {
        for ($round = 0; $round < $doublings; $round++) {
            foreach ($spread as $at => $one) {
                $spread[$at] = $one * 2 + $reader->decodeFromTable(
                    SpeechPulseTables::EXTRA_BIT_CHANCES,
                    SpeechPulseTables::WHOLE_BITS);
            }
        }
        return $spread;
    }
    /**
     * addSigns gives each sample that holds pulses the direction it
     * points. A sample holding nothing needs no sign, so none is written
     * for it. The likelihoods depend on the kind of sound, on how the
     * pulses were written, and on how many pulses the block holds.
     *
     * @param object $reader the range decoder reading the stretch
     * @param object $pulses the pulses read so far, changed in place
     * @param string $kind which kind of sound the stretch holds
     * @param string $pulse_writing which of the two ways the pulses were
     *     written
     * @param array $doublings how many doublings each block carries
     * @return void nothing is handed back; the pulses are changed in
     *     place
     */
    public static function addSigns($reader, $pulses, $kind,
        $pulse_writing, $doublings)
    {
        $chances = SpeechPulseTables::PULSE_SIGN_CHANCES;
        $kinds = [SpeechTables::QUIET_KIND, SpeechTables::VOICELESS_KIND,
            SpeechTables::VOICED_KIND];
        $which_kind = array_search($kind, $kinds);
        $louder = ($pulse_writing === SpeechTables::LOUDER_PULSES) ? 1 : 0;
        $per_kind = self::SIGN_SETS_PER_KIND + 1;
        $in_block = SpeechPulseTables::SAMPLES_IN_BLOCK;
        /* The sets run seven apart, and which set a block uses comes
           from the kind of sound and the way its pulses were written. */
        $start = ($louder + $which_kind * 2) * $per_kind;
        foreach ($pulses->block_counts as $at => $count) {
            if ($count <= 0) {
                continue;
            }
            $band = min($count, self::SIGN_SETS_PER_KIND);
            $where = min($start + $band, count($chances) - 1);
            $table = [$chances[$where], 0];
            for ($step = 0; $step < $in_block; $step++) {
                $sample = $at * $in_block + $step;
                if (empty($pulses->samples[$sample])) {
                    continue;
                }
                $up = $reader->decodeFromTable($table,
                    SpeechPulseTables::WHOLE_BITS);
                if ($up == 0) {
                    $pulses->samples[$sample] =
                        -$pulses->samples[$sample];
                }
            }
        }
    }
}
