<?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\tests;
use seekquarry\yioop\library\av_processing\CeltBands;
use seekquarry\yioop\library\av_processing\CeltEnergy;
use seekquarry\yioop\library\av_processing\CeltStretch;
use seekquarry\yioop\library\av_processing\OpusPacket;
use seekquarry\yioop\library\av_processing\RangeDecoder;
use seekquarry\yioop\library\av_processing\WebmDemuxer;
use seekquarry\yioop\configs as C;
use seekquarry\yioop\library\UnitTest;
/**
* Reads whole stretches of real recordings and checks where the
* reading lands.
*
* This is the strongest check in the whole of this work, and it is
* worth saying why. Whatever wrote these recordings filled each
* stretch to the bit: there is no slack at the end, because slack
* would be room that could have carried sound. So a reading that
* agrees with the writer at every step will finish a stretch with
* almost nothing left over.
*
* A reading that has gone wrong anywhere will not. It will not be a
* little out; it will be hundreds or thousands of bits out, because
* every step decides how much room the next has, and one wrong step
* throws off every step after it. There is no way for a reading with a
* fault in it to land near the end by accident.
*
* The cases below read every stretch of three recordings made by other
* software and check that each lands within a bit of its end. That
* covers the whole chain at once: the compressed number reader, the
* loudnesses, the sharing out of room, the splitting of wide bands,
* the smearing, the filling of empty bands, and the leftover bits.
*
* @author Chris Pollett
*/
class CeltStretchTest extends UnitTest
{
/**
* Recordings to read whole stretches of
*/
const RECORDINGS = ["/test_files/tiny_tone_webm.txt",
"/test_files/tiny_noise_webm.txt",
"/test_files/tiny_silence_webm.txt"];
/**
* The longest stretch, which nearly every recording uses
*/
const DOUBLINGS = 3;
/**
* How many bands the recordings carry
*/
const BANDS = 21;
/**
* Which band covers the tone the first recording holds. Band two
* runs from 400 to 600 cycles a second and the tone is at 440.
*/
const TONE_BAND = 2;
/**
* How much room may be left at the end of a stretch. A whole bit
* is generous: the reading normally lands within half of one.
*/
const ROOM_ALLOWED = 8;
/**
* How far over the end a stretch may run. The finest amount that
* exists is an eighth of a bit, and rounding at the very end of a
* recording can cost that much.
*/
const OVERRUN_ALLOWED = 1;
/**
* How many stretches of each recording to read. Reading a stretch
* whole is the most work anything here does, so the cases read
* enough to be convincing and leave measuring the speed of it to
* the experiment beside them.
*/
const STRETCHES_READ = 3;
/**
* How many stretches the case that reads twice uses, since it
* cannot share the reading the other cases share
*/
const STRETCHES_READ_TWICE = 2;
/**
* What reading each recording gave, kept so the work is done once
* @var array
*/
public static $read_already = [];
/**
* Nothing needs setting up for these cases
*/
public function setUp()
{
}
/**
* Nothing needs clearing away after these cases
*/
public function tearDown()
{
}
/**
* Reads every stretch of one recording
*
* @param string $where which recording to read
* @return array what each stretch gave
*/
public function readEverything($where)
{
if (isset(self::$read_already[$where])) {
return self::$read_already[$where];
}
$stored = file_get_contents(C\PARENT_DIR . "/tests" . $where);
$file = new WebmDemuxer(base64_decode($stored));
$before = CeltEnergy::nothingYet(1);
$seed = 0;
$found = [];
foreach ($file->packets() as $piece) {
$sound = OpusPacket::fromString($piece->data);
if ($sound->method != OpusPacket::MUSIC_METHOD) {
continue;
}
foreach ($sound->stretches as $stretch) {
if (strlen($stretch) < 2) {
continue;
}
$reader = new RangeDecoder($stretch);
$read = CeltStretch::readFrom($reader, self::DOUBLINGS,
$before, $seed, 0, self::BANDS);
$before = $read["loudness"];
$seed = $read["seed"];
$read["size"] = strlen($stretch);
$found[] = $read;
if (count($found) >= self::STRETCHES_READ) {
break 2;
}
}
}
self::$read_already[$where] = $found;
return $found;
}
/**
* Reads every stretch of every recording
*
* @return array what each stretch gave
*/
public function readAll()
{
$found = [];
foreach (self::RECORDINGS as $where) {
foreach ($this->readEverything($where) as $one) {
$found[] = $one;
}
}
return $found;
}
/**
* Every stretch should be read right to its end, with less than a
* bit left over. This case runs for about fifteen thousandths of a
* second, since it decodes every stretch of a real recording.
*/
public function everyStretchIsReadToItsEndTestCase()
{
$short = 0;
$over = 0;
$checked = 0;
$total = 0;
foreach ($this->readAll() as $one) {
if ($one["header"]->silent) {
continue;
}
if ($one["left"] > self::ROOM_ALLOWED) {
$short++;
}
if ($one["left"] < -self::OVERRUN_ALLOWED) {
$over++;
}
$total += $one["left"];
$checked++;
}
$this->assertTrue($checked > 4, "many stretches were read whole");
$this->assertEqual($short, 0,
"every stretch was read to within a bit of its end");
$this->assertEqual($over, 0, "no stretch was read past its end");
$this->assertTrue($total / $checked < self::ROOM_ALLOWED / 2,
"on average less than half a bit is left over");
}
/**
* Every band kept should end up holding something, since a band
* given no room is filled rather than left silent
*/
public function keptBandsHoldSomethingTestCase()
{
$empty = 0;
$checked = 0;
foreach ($this->readAll() as $one) {
if ($one["header"]->silent) {
continue;
}
for ($band = 0; $band < $one["shared"]["kept"]; $band++) {
if ($one["marks"][$band] == 0) {
$empty++;
}
$checked++;
}
}
$this->assertTrue($checked > 50, "many bands were checked");
$this->assertEqual($empty, 0,
"every band kept ends up holding something");
}
/**
* The slots a stretch gives back should all be real numbers rather
* than anything that has gone astray
*/
public function everySlotIsARealNumberTestCase()
{
$astray = 0;
$checked = 0;
$loudest = 0.0;
foreach ($this->readAll() as $one) {
foreach ($one["slots"] as $slot) {
if (!is_finite($slot)) {
$astray++;
}
$loudest = max($loudest, abs($slot));
$checked++;
}
}
$this->assertTrue($checked > 2000, "many slots were checked");
$this->assertEqual($astray, 0, "every slot is a real number");
$this->assertTrue($loudest > 0.0 && $loudest < 100.0,
"no slot has run away");
}
/**
* A stretch of silence should be read as silent, and should still
* give back a full set of slots.
*
* A silent stretch is not skipped. Its room is marked as used up
* and the reading carries on, so every band is given nothing and
* is filled with faint noise instead. What makes it silent is the
* loudness, which sits at its floor, rather than the slots being
* empty. Skipping such a stretch would leave the reading in a
* different place than the recording expects.
*/
public function silenceIsStillReadThroughTestCase()
{
$silent = 0;
$checked = 0;
foreach ($this->readEverything(self::RECORDINGS[2]) as $one) {
if ($one["header"]->silent) {
$silent++;
$this->assertTrue(count($one["slots"]) > 100,
"a silent stretch still gives back a full set of slots");
$filled = 0;
foreach ($one["slots"] as $slot) {
if ($slot != 0.0) {
$filled++;
}
}
$this->assertTrue($filled > 100,
"and those slots hold the faint noise it is filled with");
}
$checked++;
if ($checked > 2) {
break;
}
}
$this->assertTrue($silent > 0, "the silence was read as silent");
}
/**
* The loudnesses read from a recording of one steady tone should
* put that tone in the band it really belongs to.
*
* This is the check that does not depend on anything downstream.
* The recording holds a 440 cycle tone, the bands are known
* stretches of the sound spectrum, and band two covers 400 to 600
* cycles a second. So the loudest band must be band two, and the
* loudness must fall away on both sides of it. A reading that had
* gone wrong would put the peak somewhere else or spread it
* everywhere.
*/
public function toneLandsInTheRightBandTestCase()
{
$found = $this->readEverything(self::RECORDINGS[0]);
$this->assertTrue(count($found) > 1, "stretches were read");
$checked = 0;
$wrong_band = 0;
$not_peaked = 0;
foreach ($found as $one) {
if ($one["header"]->silent) {
continue;
}
$loudest = -1000.0;
$which = -1;
$levels = [];
foreach ($one["loudness"][0] as $band => $value) {
/* What a band really comes to is what was read plus
what that band was expected to be. */
$levels[$band] = $value + CeltBands::EXPECTED[$band];
if ($levels[$band] > $loudest) {
$loudest = $levels[$band];
$which = $band;
}
}
if ($which != self::TONE_BAND) {
$wrong_band++;
}
if ($levels[self::TONE_BAND] <= $levels[self::TONE_BAND - 1] ||
$levels[self::TONE_BAND] <= $levels[self::TONE_BAND + 1] ||
$levels[self::TONE_BAND] - $levels[11] < 5.0) {
$not_peaked++;
}
$checked++;
}
$this->assertTrue($checked > 1, "stretches of the tone were read");
$this->assertEqual($wrong_band, 0,
"the tone is loudest in the band it belongs to");
$this->assertEqual($not_peaked, 0,
"the loudness falls away on both sides of that band");
}
/**
* Reading the same recording twice should give the same answer
* both times, since nothing in the reading may depend on anything
* outside the recording
*/
public function readingTwiceAgreesTestCase()
{
$stored = file_get_contents(C\PARENT_DIR .
"/tests" . self::RECORDINGS[0]);
$once = [];
$twice = [];
foreach ([0, 1] as $turn) {
$file = new WebmDemuxer(base64_decode($stored));
$before = CeltEnergy::nothingYet(1);
$seed = 0;
foreach ($file->packets() as $piece) {
$sound = OpusPacket::fromString($piece->data);
if ($sound->method != OpusPacket::MUSIC_METHOD) {
continue;
}
foreach ($sound->stretches as $stretch) {
$reader = new RangeDecoder($stretch);
$read = CeltStretch::readFrom($reader, self::DOUBLINGS,
$before, $seed, 0, self::BANDS);
$before = $read["loudness"];
$seed = $read["seed"];
if ($turn == 0) {
$once[] = $read["slots"];
} else {
$twice[] = $read["slots"];
}
if (count($once) >= self::STRETCHES_READ_TWICE &&
$turn == 0) {
break 2;
}
if (count($twice) >= self::STRETCHES_READ_TWICE &&
$turn == 1) {
break 2;
}
}
}
}
$this->assertTrue(count($once) > 1, "stretches were read");
$this->assertEqual($once, $twice, "both readings agree throughout");
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software