<?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;
/**
* SpeechPitch reads the pitch of a stretch of speech made with the
* voice: how far back in its own recent past the sound repeats, and how
* strongly.
*
* The vocal folds open and close at some rate, so one opening sounds
* much like the one before it. A stretch therefore carries a lag, being
* the distance back to the last opening, and a filter of five taps
* saying how much of the sound found there to add back in. Each of the
* four quarters of a stretch gets its own lag, worked out from the
* stretch's lag and a shape shared across the four, so the pitch may
* drift within the stretch as a speaker's voice does.
*
* A caller reads the pitch after the shape of a stretch and before its
* pulses. A stretch of speech made without the voice, or one holding no
* speech, carries no pitch at all and this is not called for it.
*
* @author Chris Pollett
*/
class SpeechPitch
{
/**
* $lag stores how far back the stretch as a whole looks, in samples
* at the rate the sound was written at.
* @var int
*/
public $lag = 0;
/**
* $quarter_lags stores the lag of each of the four quarters, in the
* order the quarters are played.
* @var array
*/
public $quarter_lags = [];
/**
* $book stores which of the three books of filters the stretch named
* its filter from, counting from zero.
* @var int
*/
public $book = 0;
/**
* $filter stores the five taps of the first quarter's filter, kept
* for a caller that wants one filter for the stretch.
* @var array
*/
public $filter = [];
/**
* $quarter_filters stores the five taps of each quarter's filter, in
* playing order. How strongly the voice repeats changes within a
* stretch, so each quarter names its own.
* @var array
*/
public $quarter_filters = [];
/**
* $lean stores how much of the sound before this stretch is leaned
* on when its pitch is added back, written out of 16384.
* @var int
*/
public $lean = 0;
/**
* TAPS_IN_FILTER is how many taps one filter holds. The middle tap
* sits at the lag itself and the other four at the two samples
* either side of it.
*/
const TAPS_IN_FILTER = 5;
/**
* TAP_BITS_ADDED is how many bits of fraction are added to a tap
* taken from the book, which holds seven, to bring it to the
* fourteen the pitch filter works with.
*/
const TAP_BITS_ADDED = 7;
/**
* COARSE_LAG_STEPS is how many coarse steps of lag a stretch may
* name when it writes its pitch outright.
*/
const COARSE_LAG_STEPS = 32;
/**
* LAG_CHANGE_MIDDLE is the place in the table of changes that means
* no change at all. A number below it is a fall in pitch and one
* above it a rise.
*/
const LAG_CHANGE_MIDDLE = 9;
/**
* read gives the pitch a stretch of voiced speech carries: the lag
* of the stretch, the lag of each quarter, and the filter that says
* how strongly the sound repeats.
*
* @param object $reader the range decoder reading the stretch
* @param int $carried the lag the stretch before this one used, or
* -1 where this stretch stands on its own
* @param bool $independent whether the stretch stands on its own, in
* which case it also says how much of the sound before it to
* lean on
* @return object a pitch holding the lags, the book and the filter
*/
public static function read($reader, $carried = -1,
$independent = true)
{
$pitch = new self();
$pitch->lag = self::readLag($reader, $carried);
$pitch->quarter_lags = self::quarterLags($reader, $pitch->lag);
$pitch->book = $reader->decodeFromTable(
SpeechPitchTables::REPEAT_BOOK_CHANCES,
SpeechPitchTables::WHOLE_BITS);
/* Each quarter names its own filter out of the one book, since
how strongly the voice repeats changes within a stretch. */
$pitch->quarter_filters = [];
for ($at = 0; $at < SpeechPitchTables::QUARTERS_IN_STRETCH;
$at++) {
$pitch->quarter_filters[] = self::readFilter($reader,
$pitch->book);
}
$pitch->filter = $pitch->quarter_filters[0];
if ($independent) {
$which = $reader->decodeFromTable(
SpeechPulseTables::LEAN_CHANCES,
SpeechPitchTables::WHOLE_BITS);
$pitch->lean = SpeechPitchTables::REPEAT_LEAN_SCALES[
$which % count(SpeechPitchTables::REPEAT_LEAN_SCALES)];
}
return $pitch;
}
/**
* readLag gives how far back the stretch as a whole looks. A stretch
* standing on its own writes the lag outright, as a coarse step and
* a place within that step; a stretch following a voiced one writes
* it as a change from the lag before, which costs fewer bits because
* pitch moves slowly.
*
* @param object $reader the range decoder reading the stretch
* @param int $carried the lag the stretch before this one used, or
* -1 where this stretch stands on its own
* @return int the lag, in samples
*/
public static function readLag($reader, $carried)
{
if ($carried > 0) {
$step = $reader->decodeFromTable(
SpeechPitchTables::PITCH_LAG_CHANGE,
SpeechPitchTables::WHOLE_BITS);
/* A change of zero is the writer saying the lag follows
outright rather than as a move, so the reading goes on to
the coarse and fine parts below. */
if ($step > 0) {
return self::heldInRange($carried + $step -
self::LAG_CHANGE_MIDDLE);
}
}
$coarse = $reader->decodeFromTable(
SpeechPitchTables::PITCH_FIRST_LAG,
SpeechPitchTables::WHOLE_BITS);
$fine = $reader->decodeFromTable(
SpeechPitchTables::PITCH_FINE_LAG,
SpeechPitchTables::WHOLE_BITS);
$steps = SpeechPitchTables::LAG_STEPS_WIDE;
return self::heldInRange(SpeechPitchTables::LEAST_LAG_WIDE +
$coarse * $steps + $fine);
}
/**
* quarterLags gives the lag of each quarter of a stretch. The four
* share one shape, read once, and each quarter's lag is the
* stretch's lag plus that shape's step for the quarter.
*
* @param object $reader the range decoder reading the stretch
* @param int $lag the lag the stretch as a whole uses
* @return array the lag of each quarter, in playing order
*/
public static function quarterLags($reader, $lag)
{
$shape = $reader->decodeFromTable(
SpeechPitchTables::PITCH_SHAPE_WIDE,
SpeechPitchTables::WHOLE_BITS);
$steps = SpeechPitchTables::PITCH_SHAPE_WIDE_STEPS;
$quarters = SpeechPitchTables::QUARTERS_IN_STRETCH;
$shapes = intdiv(count($steps), $quarters);
$shape = $shape % $shapes;
$lags = [];
for ($at = 0; $at < $quarters; $at++) {
/* The table holds a row for each quarter and a column for
each shape, so the quarter picks the row. Reading it the
other way about gave each quarter the wrong step. */
$lags[] = self::heldInRange($lag +
$steps[$at * $shapes + $shape]);
}
return $lags;
}
/**
* readFilter gives the five taps of the filter a stretch names. The
* stretch names a book first, and the book fixes both how likely
* each filter within it was and where its taps are kept.
*
* @param object $reader the range decoder reading the stretch
* @param int $book which of the three books the stretch named
* @return array the five taps, each a fraction written out of 128
*/
public static function readFilter($reader, $book)
{
$chances = [SpeechPitchTables::REPEAT_STRENGTH_CHANCES_0,
SpeechPitchTables::REPEAT_STRENGTH_CHANCES_1,
SpeechPitchTables::REPEAT_STRENGTH_CHANCES_2];
$books = [SpeechPitchTables::REPEAT_FILTERS_0,
SpeechPitchTables::REPEAT_FILTERS_1,
SpeechPitchTables::REPEAT_FILTERS_2];
$book = $book % count($books);
$which = $reader->decodeFromTable($chances[$book],
SpeechPitchTables::WHOLE_BITS);
$taps = $books[$book];
$count = intdiv(count($taps), self::TAPS_IN_FILTER);
$which = $which % $count;
/* The book holds its taps with seven bits of fraction, and the
filter works with fourteen, so each is shifted up. */
$out = [];
foreach (array_slice($taps, $which * self::TAPS_IN_FILTER,
self::TAPS_IN_FILTER) as $one) {
$out[] = $one << self::TAP_BITS_ADDED;
}
return $out;
}
/**
* heldInRange keeps a lag within the distance a stretch of wide
* sound may look back. A lag outside that range would reach into
* sound the decoder does not hold.
*
* @param int $lag the lag to hold
* @return int the lag, held between the shortest and the longest
*/
public static function heldInRange($lag)
{
if ($lag < SpeechPitchTables::LEAST_LAG_WIDE) {
return SpeechPitchTables::LEAST_LAG_WIDE;
}
if ($lag > SpeechPitchTables::MOST_LAG_WIDE) {
return SpeechPitchTables::MOST_LAG_WIDE;
}
return $lag;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software