<?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;
/**
* CeltSynthesis turns the tones of a stretch back into samples, and joins each
* stretch to the one before it. The transform that does the turning has already
* been written and checked. What is left is the joining, and the shape of the
* fade the joining uses. That fade is unusual. An ordinary one rises across a
* whole stretch and falls across the next, so neighboring stretches overlap by
* their whole length and half the sound is being faded at any moment. Opus
* cannot afford that, because the overlap is delay: a player cannot give out a
* sample until both stretches covering it have arrived. So the fade here is
* flat across nearly all of a stretch and tapers only over a short run at each
* end, which is two and a half milliseconds rather than twenty. The stretches
* still cancel each other's errors exactly, because the taper satisfies the
* same condition an ordinary fade does. The last step undoes a tilt the
* recording was given before it was compressed. Sound has more of its energy at
* low pitches than high, and compressing it evenly would spend too much on the
* low end, so the high end is lifted before compressing and let back down here.
* This follows RFC 6716, the specification of the Opus audio codec, in its
* section on the transform layer.
*/
class CeltSynthesis
{
/**
* TAPER is how long the taper at each end of a stretch is, in samples at
* the shortest stretch's rate.
*/
const TAPER = 120;
/**
* TILT_BACK is how much of the tilt is let back down at each sample.
*/
const TILT_BACK = 0.8500061035;
/**
* fades stores the fade used to join stretches, worked out once for each
* length and kept
*
* @var array
*/
public static $fades = [];
/**
* fadeFor the fade for a stretch of a given length. It is nothing at all
* outside a middle region, rises across a short taper, holds flat, and
* falls again, so that only the tapers overlap between one stretch and the
* next. half how many samples the fade covers
*
* @param int $tones how many tones the stretch holds, which is
* @param int $taper how long each taper is
* @return array the fade, one value per sample
*/
public static function fadeFor($tones, $taper)
{
$key = $tones . ":" . $taper;
if (isset(self::$fades[$key])) {
return self::$fades[$key];
}
$length = 2 * $tones;
$fade = array_fill(0, $length, 0.0);
$begins = intdiv($tones - $taper, 2);
for ($i = 0; $i < $tones; $i++) {
if ($i < $begins) {
$value = 0.0;
} else if ($i < $begins + $taper) {
$value = self::taperAt($i - $begins, $taper);
} else {
$value = 1.0;
}
$fade[$i] = $value;
/* The second half is the first half backwards, which is
what makes neighboring stretches cancel. */
$fade[$length - 1 - $i] = $value;
}
self::$fades[$key] = $fade;
return $fade;
}
/**
* taperAt how far up the taper has risen at a given point
*
* @param int $at how far along the taper
* @param int $taper how long the taper is
* @return float how far up it has risen, from nothing to one
*/
public static function taperAt($at, $taper)
{
$along = sin(0.5 * M_PI * ($at + 0.5) / $taper);
return sin(0.5 * M_PI * $along * $along);
}
/**
* toSamples turns a stretch of tones into samples and joins it to what came
* before which is more than one where the sound changed suddenly before,
* replaced by what this one leaves hanging
*
* @param array $tones the stretch's tones
* @param int $blocks how many blocks the stretch is split into,
* @param array $tail what was left hanging over from the stretch
* @return array the samples this stretch settles
*/
public static function toSamples($tones, $blocks, &$tail)
{
$length = count($tones);
$each = intdiv($length, $blocks);
$taper = self::TAPER;
$half = intdiv($taper, 2);
$running = array_fill(0, $length + $taper, 0.0);
for ($i = 0; $i < $half; $i++) {
$running[$i] = $tail[$i] ?? 0.0;
}
$rise = [];
for ($i = 0; $i < $taper; $i++) {
$rise[] = self::taperAt($i, $taper);
}
$middle = intdiv($each, 2);
$scale = $each / 2.0;
for ($block = 0; $block < $blocks; $block++) {
/* A stretch split into blocks keeps its tones interleaved,
so a block's own tones are every so many along. */
$mine = [];
for ($tone = 0; $tone < $each; $tone++) {
$mine[] = $tones[$tone * $blocks + $block];
}
$samples = Mdct::forSize($each)->inverse($mine);
$at = $block * $each;
/* The middle of the transform's result is laid down as it
is, reaching a little past this block's end. */
for ($i = 0; $i < $each; $i++) {
$running[$at + $half + $i] = $samples[$middle + $i] *
$scale;
}
/* The start is folded against the raw end the block before
left lying there, which is what makes the two cancel
each other's aliasing exactly. */
for ($i = 0; $i < $half; $i++) {
$near = $running[$at + $i];
$far = $running[$at + $taper - 1 - $i];
$low = $rise[$i];
$high = $rise[$taper - 1 - $i];
$running[$at + $i] = $high * $near - $low * $far;
$running[$at + $taper - 1 - $i] = $low * $near +
$high * $far;
}
}
$settled = array_slice($running, 0, $length);
/* The raw end of the last block is carried to the next
stretch, which folds its own start against it. */
$tail = [];
for ($i = 0; $i < $half; $i++) {
$tail[] = $running[$length + $i];
}
return $settled;
}
/**
* letDownTilt lets back down the tilt the recording was given before it was
* compressed stretch before, replaced by what it holds after
*
* @param array $samples the samples to let down
* @param float $carried what the filter was holding from the
* @return array the samples with the tilt let down
*/
public static function letDownTilt($samples, &$carried)
{
$out = [];
$held = $carried;
foreach ($samples as $sample) {
$now = $sample + $held;
$held = self::TILT_BACK * $now;
$out[] = $now;
}
$carried = $held;
return $out;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software