<?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\CeltAllocation;
use seekquarry\yioop\library\av_processing\CeltBands;
use seekquarry\yioop\library\av_processing\CeltEnergy;
use seekquarry\yioop\library\av_processing\CeltFrameHeader;
use seekquarry\yioop\library\av_processing\CeltPulseCache;
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;
/**
* Checks how a stretch's room is shared out between its bands.
*
* Almost nothing about the sharing is stored in a recording. The
* writer and the reader run the same arithmetic from the same starting
* point and are expected to arrive at the same answer, so there is
* nothing to compare a wrong answer against. That makes it the hardest
* part to check and the worst part to get wrong: a fault does not spoil
* one value, it hands every band the wrong amount of room.
*
* What can be checked is that the answer holds together. Everything
* handed out has to add back up to what there was to hand out, and the
* only room unaccounted for should be the bit held back to say where
* the dropping of bands stops, plus one bit for each band the
* recording was actually asked about. No band may be given more than
* it can use. The finer loudness pass may not be given more bits than
* it can spend. Bands dropped entirely must be left with nothing.
*
* Those hold across every stretch of four real recordings made by
* other software. A sharing that had gone wrong would fail them almost
* at once, since the amounts would stop adding up.
*
* @author Chris Pollett
*/
class CeltAllocationTest extends UnitTest
{
/**
* Recordings to share out the room of
*/
const RECORDINGS = ["/test_files/tiny_tone_webm.txt",
"/test_files/tiny_noise_webm.txt",
"/test_files/tiny_recording_webm.txt"];
/**
* The longest stretch, which nearly every recording uses
*/
const DOUBLINGS = 3;
/**
* How many bands the recordings carry
*/
const BANDS = 21;
/**
* How finely room is counted, as parts of a bit
*/
const BIT_PARTS = 3;
/**
* How many stretches of each recording to share out. Sharing is
* real work, so the cases do enough to be convincing rather than
* every stretch there is.
*/
const STRETCHES_SHARED = 6;
/**
* A whole bit, in those parts
*/
const WHOLE_BIT = 8;
/**
* Most bits the finer loudness pass may spend on one band
*/
const MOST_FINE_BITS = 8;
/**
* Nothing needs setting up for these cases
*/
public function setUp()
{
}
/**
* Nothing needs clearing away after these cases
*/
public function tearDown()
{
}
/**
* Shares out the room of every stretch of one recording
*
* @param string $where which recording to read
* @return array what the sharing gave for each stretch
*/
public function shareEverything($where)
{
$stored = file_get_contents(C\PARENT_DIR . "/tests" . $where);
$reader = new WebmDemuxer(base64_decode($stored));
$before = CeltEnergy::nothingYet(1);
$shared = [];
foreach ($reader->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;
}
$entropy = new RangeDecoder($stretch);
$header = CeltFrameHeader::readFrom($entropy, self::DOUBLINGS,
$before, 0, self::BANDS);
$before = $header->loudness;
if ($header->silent) {
continue;
}
$shared[] = $this->shareOne($entropy, $header,
strlen($stretch));
if (count($shared) >= self::STRETCHES_SHARED) {
break 2;
}
}
}
return $shared;
}
/**
* Shares out the room of one stretch
*
* @param object $entropy the reader partway through the stretch
* @param object $header what the stretch said about itself
* @param int $size how long the stretch is, in bytes
* @return array what the sharing gave, and what it had to give
*/
public function shareOne($entropy, $header, $size)
{
$whole = $size * 8 << self::BIT_PARTS;
$asked = CeltAllocation::readBoosts($entropy, self::DOUBLINGS, 1, 0,
self::BANDS, $whole);
$tilt = CeltAllocation::readTilt($entropy, $asked["room"]);
$left = $whole - $entropy->bitsUsedFinely() - 1;
/* A stretch where the sound changed suddenly holds back one bit
to say whether a band that fell silent should be filled back
in. */
if ($header->sudden && $left >= (self::DOUBLINGS + 2) *
self::WHOLE_BIT) {
$left -= self::WHOLE_BIT;
}
$given = CeltAllocation::shareOut($entropy, $asked["boosts"], $tilt,
$left, self::DOUBLINGS, 1, 0, self::BANDS);
$given["had"] = $left;
$given["size"] = $size;
$given["used"] = $entropy->bitsUsedFinely();
$given["tilt"] = $tilt;
$given["boosts"] = $asked["boosts"];
return $given;
}
/**
* What sharing every recording gave, kept so that the work is done
* once for the whole file rather than once for each case
* @var array
*/
public static $shared_already = [];
/**
* Shares out every stretch of every recording
*
* @return array what the sharing gave for each stretch
*/
public function shareAll()
{
if (self::$shared_already != []) {
return self::$shared_already;
}
$shared = [];
foreach (self::RECORDINGS as $where) {
foreach ($this->shareEverything($where) as $one) {
$shared[] = $one;
}
}
self::$shared_already = $shared;
return $shared;
}
/**
* Everything handed out should add back up to what there was to
* hand out, apart from the bit held back to say where dropping
* stops and one bit for each band the recording was asked about
*/
public function everythingAddsUpTestCase()
{
$wrong = 0;
$ragged = 0;
$checked = 0;
foreach ($this->shareAll() as $one) {
$handed = array_sum($one["shape"]) +
array_sum($one["fine"]) * self::WHOLE_BIT + $one["spare"];
$gap = $one["had"] - $handed;
if ($gap % self::WHOLE_BIT != 0) {
$ragged++;
}
$dropped = self::BANDS - $one["kept"];
if ($gap < self::WHOLE_BIT ||
$gap > self::WHOLE_BIT * (1 + $dropped)) {
$wrong++;
}
$checked++;
}
$this->assertTrue($checked > 8, "many stretches were shared out");
$this->assertEqual($ragged, 0,
"what is left over is always a whole number of bits");
$this->assertEqual($wrong, 0,
"what is left over is the bit held back plus the bands asked " .
"about, $checked stretches");
}
/**
* No band should be given more room than it can use, since room
* beyond that is wasted while another band goes short
*/
public function noBandGetsMoreThanItCanUseTestCase()
{
$over = 0;
$checked = 0;
foreach ($this->shareAll() as $one) {
for ($band = 0; $band < $one["kept"]; $band++) {
$ceiling = CeltPulseCache::ceilingRoom($band,
self::DOUBLINGS, 1);
if ($one["shape"][$band] > $ceiling) {
$over++;
}
$checked++;
}
}
$this->assertTrue($checked > 150, "many bands were checked");
$this->assertEqual($over, 0,
"no band was given more room than it can use");
}
/**
* The finer loudness pass should never be given more bits than it
* can spend, nor a negative number of them
*/
public function finerPassStaysInItsLimitsTestCase()
{
$wrong = 0;
$any = 0;
foreach ($this->shareAll() as $one) {
foreach ($one["fine"] as $bits) {
if ($bits < 0 || $bits > self::MOST_FINE_BITS) {
$wrong++;
}
if ($bits > 0) {
$any++;
}
}
}
$this->assertEqual($wrong, 0,
"every band's finer pass sits within its limits");
$this->assertTrue($any > 50,
"the finer pass is given something to do");
}
/**
* A band dropped entirely should be left with no room for a shape
*/
public function droppedBandsGetNoShapeTestCase()
{
$wrong = 0;
$dropped = 0;
foreach ($this->shareAll() as $one) {
for ($band = $one["kept"]; $band < self::BANDS; $band++) {
if ($one["shape"][$band] != 0) {
$wrong++;
}
$dropped++;
}
}
$this->assertTrue($dropped > 0, "some bands were dropped");
$this->assertEqual($wrong, 0, "a dropped band gets no shape room");
}
/**
* At least one band should always be kept, since a stretch that
* kept none would be silence and would have said so
*/
public function somethingIsAlwaysKeptTestCase()
{
$empty = 0;
$checked = 0;
foreach ($this->shareAll() as $one) {
if ($one["kept"] < 1) {
$empty++;
}
$checked++;
}
$this->assertTrue($checked > 8, "many stretches were checked");
$this->assertEqual($empty, 0, "every stretch keeps some bands");
}
/**
* Sharing should never account for more of a stretch than there is
*/
public function readingStaysInsideTheStretchTestCase()
{
$over = 0;
$checked = 0;
foreach ($this->shareAll() as $one) {
if ($one["used"] > $one["size"] * 8 * self::WHOLE_BIT) {
$over++;
}
$checked++;
}
$this->assertEqual($over, 0,
"no stretch was read past its end, $checked read");
}
/**
* The lean and the extra room asked for should both name something
* the stretch could really have said
*/
public function whatWasReadIsBelievableTestCase()
{
$wrong = 0;
$any_asked = 0;
foreach ($this->shareAll() as $one) {
if ($one["tilt"] < 0 || $one["tilt"] > 10) {
$wrong++;
}
foreach ($one["boosts"] as $band => $boost) {
if ($boost < 0 || $boost > CeltPulseCache::ceilingRoom($band,
self::DOUBLINGS, 1) * 2) {
$wrong++;
}
if ($boost > 0) {
$any_asked++;
}
}
}
$this->assertEqual($wrong, 0,
"the lean and the extra asked for are both believable");
$this->assertTrue($any_asked > 0,
"some band somewhere asked for extra room");
}
/**
* A recording given more room overall should end up with more room
* for its shapes
*/
public function moreRoomOverallMeansMoreForShapesTestCase()
{
$spare = $this->shareEverything(self::RECORDINGS[1]);
$plenty = 0;
$stretches = 0;
foreach ($spare as $one) {
$plenty += array_sum($one["shape"]);
$stretches++;
}
$tight = $this->shareEverything(self::RECORDINGS[0]);
$little = 0;
$fewer = 0;
foreach ($tight as $one) {
$little += array_sum($one["shape"]);
$fewer++;
}
$this->assertTrue($stretches > 0 && $fewer > 0,
"both recordings had stretches");
$this->assertTrue($plenty / $stretches > $little / $fewer,
"the recording with more room gives its shapes more");
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software