<?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;
/**
* OpusDecoder turns a whole recording into samples, and writes samples out as a
* sound file anything can play. This is what puts every other part together end
* to end: the file is taken apart into pieces, each piece into stretches, each
* stretch read, and each stretch's tones turned into samples and joined to the
* ones before. What comes out is not right yet. A recording of a single 440
* cycle tone comes back as a tone near 510 cycles, which says the shape within
* a band is wrong even though the band itself is right. The fault is in how a
* wide band is cut in half and put back together. This is here so that the
* state of the work can be listened to rather than only read about, and so that
* the next fix has something to be measured against.
*/
class OpusDecoder
{
/**
* SAMPLE_RATE is how many samples a second the decoder hands back.
* Opus always decodes at this rate, whatever rate the sound was
* recorded at.
*/
const SAMPLE_RATE = 48000;
/**
* USUAL_TONES is how many tones a stretch of the usual length holds.
*/
const USUAL_TONES = 960;
/**
* USUAL_DOUBLINGS is how many times the shortest stretch has been doubled
* to reach the usual one.
*/
const USUAL_DOUBLINGS = 3;
/**
* SUDDEN_BLOCKS is how many blocks a stretch is split into where the sound
* changed suddenly.
*/
const SUDDEN_BLOCKS = 8;
/**
* BANDS is how many frequency bands the sound is split into,
* from the lowest to the highest a recording carries.
*/
const BANDS = 21;
/**
* VERY_QUIET is the loudness a band is taken to have had before the
* recording began, quiet enough that nothing is filled back toward it.
*/
const VERY_QUIET = -28.0;
/**
* LOUDEST is how loud a sample may be before it is held back, so that a
* fault cannot produce something painful to listen to.
*/
const LOUDEST = 1.0;
/**
* eachStretch turns every stretch of a recording into samples, handing each
* stretch's worth over as it is made rather than keeping them all. A
* recording of any length has to work, and holding every sample of it at
* once does not: four minutes of sound comes to eleven million of them,
* which is most of a gigabyte once each is a number in memory. So the
* samples are given out a stretch at a time and whatever wants them decides
* what to keep.
*
* @param array $stretches the compressed stretches, in order
* @param int $channels how many channels the recording carries
* @return \Generator each stretch's worth of samples in turn
*/
public static function eachStretch($stretches, $channels = 1)
{
$loudness = CeltEnergy::nothingYet($channels);
$quiet = [];
for ($channel = 0; $channel < $channels; $channel++) {
$quiet[] = array_fill(0, self::BANDS, self::VERY_QUIET);
}
$previous_one = $quiet;
$previous_two = $quiet;
$seed = 0;
$hanging = null;
$carried = 0.0;
$past = array_fill(0, CeltPitchFilter::LONGEST_REACH, 0.0);
$was = (["reach" => 0, "loudness" => 0.0, "shape" => 0]);
foreach ($stretches as $stretch) {
$reader = new RangeDecoder($stretch);
$read = CeltStretch::readFrom($reader, self::USUAL_DOUBLINGS,
$loudness, $seed, 0, self::BANDS, $previous_one, $previous_two);
$loudness = $read["loudness"];
$previous_two = $previous_one;
$previous_one = $loudness;
/* The number used to fill empty bands carries on from where
the reader itself ended, not from nothing. */
$seed = $reader->range;
$blocks = $read["header"]->sudden ? self::SUDDEN_BLOCKS : 1;
if ($read["header"]->silent) {
$tones = array_fill(0, self::USUAL_TONES, 0.0);
} else {
/* Where there are two channels the shapes have been
averaged already, so the louder of the two loudnesses
is the one to bring them up by. */
$level = $read["loudness"][0];
if (count($read["loudness"]) > 1) {
foreach ($level as $band => $one) {
$level[$band] = max($one,
$read["loudness"][1][$band]);
}
}
$tones = CeltShape::toTones($read["slots"], $level,
self::USUAL_DOUBLINGS, 0, self::BANDS,
self::USUAL_TONES);
}
if ($hanging === null) {
$hanging = array_fill(0,
intdiv(CeltSynthesis::TAPER, 2), 0.0);
}
$settled = CeltSynthesis::toSamples($tones, $blocks, $hanging);
/* The filter reaches back as much as a thousand samples, so
the sound before this stretch is kept in front of it. */
$now = ["reach" => $read["header"]->filter_pitch,
"loudness" => $read["header"]->filter_strength,
"shape" => $read["header"]->filter_shape];
$with_past = array_merge($past, $settled);
$settled = CeltPitchFilter::apply($with_past, count($past),
count($settled), $was, $now);
$was = $now;
$past = array_slice(array_merge($past, $settled),
-CeltPitchFilter::LONGEST_REACH);
yield CeltSynthesis::letDownTilt($settled, $carried);
}
}
/**
* toSamples turns a recording into samples and keeps them all, which suits
* a short recording and nothing longer
*
* @param array $stretches the compressed stretches, in order
* @return array the samples, at 48000 a second
*/
public static function toSamples($stretches)
{
$wave = [];
foreach (self::eachStretch($stretches) as $settled) {
foreach ($settled as $sample) {
$wave[] = $sample;
}
}
return $wave;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software