<?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;
/**
* SpeechFrameHeader reads the opening of a stretch of sound compressed
* the way built for speech: which stretches hold speech at all, whether
* a second copy of the sound was written for a listener who loses a
* packet, what kind of sound each stretch holds, and how loud each
* quarter of it is.
*
* A browser records speech this way, so every recording a wiki page
* takes arrives compressed like this. Reading the opening is the first
* step of decoding one: the kind of sound decides which tables the rest
* of the stretch is read with, and the loudness of each quarter scales
* the pulses that follow.
*
* The reading order is fixed by the standard. All the speech marks come
* first, one for each stretch in the packet, then the mark saying
* whether a second copy follows, and only then the stretches themselves.
*
* @author Chris Pollett
*/
class SpeechFrameHeader
{
/**
* $has_speech stores, for each stretch in the packet, whether that
* stretch was marked as holding speech. A stretch holding none is
* written with its own quieter tables.
* @var array
*/
public $has_speech = [];
/**
* $has_spare_copy stores whether the packet carries a second, poorer
* copy of its sound for a listener who lost the packet before it.
* @var bool
*/
public $has_spare_copy = false;
/**
* $spare_copies stores, for each stretch in the packet, whether a
* spare copy of that stretch follows. A listener who lost the
* packet before this one plays those instead of nothing.
* @var array
*/
public $spare_copies = [];
/**
* $kind stores which kind of sound the stretch holds: no speech,
* speech made without the voice, or speech made with the voice.
* @var string
*/
public $kind = "";
/**
* $pulse_writing stores which of the two ways the pulses of the
* stretch were written, the quieter or the louder.
* @var string
*/
public $pulse_writing = "";
/**
* $loudness stores the step of loudness of each quarter of the
* stretch, in the order the quarters are played. A step covers six
* decibels.
* @var array
*/
public $loudness = [];
/**
* $loudness_indices stores the numbers read for each quarter's
* loudness before they are added up, which is what a reference
* decoding prints and so what a comparison lines up against.
* @var array
*/
public $loudness_indices = [];
/**
* readMarks reads the speech marks that open a packet, one for each
* stretch it carries, and the mark saying whether a second copy of
* the sound follows. A caller reads these before any stretch, since
* the standard writes them all together at the front.
*
* @param object $reader the range decoder reading the packet
* @param int $stretches how many stretches the packet carries
* @return object a header holding the marks that were read
*/
public static function readMarks($reader, $stretches)
{
$header = new self();
$header->has_speech = [];
for ($at = 0; $at < $stretches; $at++) {
$header->has_speech[] =
($reader->decodeBit(1) == 1);
}
$header->has_spare_copy = ($reader->decodeBit(1) == 1);
$header->spare_copies = array_fill(0, $stretches, false);
if ($header->has_spare_copy) {
if ($stretches == 1) {
$header->spare_copies[0] = true;
} else {
/* Where a packet carries more than one stretch, one
number says which of them the spare copies cover, a
bit to a stretch. */
$which = $reader->decodeFromTable(
SpeechTables::SPARE_COPY_CHANCES,
SpeechTables::WHOLE_BITS) + 1;
for ($at = 0; $at < $stretches; $at++) {
$header->spare_copies[$at] =
(($which >> $at) & 1) == 1;
}
}
}
return $header;
}
/**
* readSound reads what one stretch says about the sound it holds:
* its kind, the way its pulses were written, and how loud each of
* its quarters is. A caller reads this once the marks at the front
* of the packet have been read, and before the shape of the sound.
*
* The loudness of the first quarter is written outright where the
* stretch stands on its own. Every later quarter is written as a
* change from the quarter before it, which costs fewer bits because
* loudness moves slowly within a stretch.
*
* @param object $reader the range decoder reading the packet
* @param bool $has_speech whether this stretch was marked as holding
* speech
* @param int $carried the loudness step the stretch before this one
* ended at, or -1 where this stretch stands on its own
* @return object a header holding what the stretch says about its
* sound
*/
public static function readSound($reader, $has_speech, $carried = -1)
{
$header = new self();
$header->has_speech = [$has_speech];
$table = $has_speech ? SpeechTables::SPOKEN_KINDS :
SpeechTables::QUIET_KINDS;
$chosen = $reader->decodeFromTable($table,
SpeechTables::WHOLE_BITS);
list($header->kind, $header->pulse_writing) =
SpeechTables::kindOfSound($chosen, $has_speech);
$header->loudness = self::readLoudness($reader, $header->kind,
$carried, $header->loudness_indices);
return $header;
}
/**
* readLoudness reads how loud each quarter of a stretch is. The
* first quarter is written outright where nothing was carried over
* from the stretch before, and as a change otherwise; every quarter
* after the first is written as a change from the one before it.
*
* @param object $reader the range decoder reading the packet
* @param string $kind which kind of sound the stretch holds
* @param int $carried the loudness step the stretch before this one
* ended at, or -1 where this stretch stands on its own
* @param array $indices filled in with the numbers read before they
* are added up, for lining a reading up against another decoder
* @return array the loudness step of each quarter, in playing order
*/
public static function readLoudness($reader, $kind, $carried,
&$indices = [])
{
$steps = [];
$indices = [];
$so_far = $carried;
for ($at = 0; $at < SpeechTables::QUARTERS_IN_STRETCH; $at++) {
if ($at == 0 && $carried < 0) {
$step = $reader->decodeFromTable(
SpeechTables::loudnessTableFor($kind),
SpeechTables::WHOLE_BITS);
$within = $reader->decodeFromTable(
SpeechTables::LOUDNESS_WITHIN_STEP,
SpeechTables::WHOLE_BITS);
$so_far = $step * SpeechTables::PLACES_IN_STEP +
$within;
$indices[] = $so_far;
} else {
$change = $reader->decodeFromTable(
SpeechTables::LOUDNESS_CHANGE,
SpeechTables::WHOLE_BITS);
/* The change is written as a number from zero upward.
The standard reads the first four of those as a fall
of four to one step, and everything above them as a
rise, so the number is moved back to a change around
zero before it is added. */
$moved = ($change < SpeechTables::CHANGES_THAT_FALL) ?
$change - SpeechTables::CHANGES_THAT_FALL :
$change - SpeechTables::CHANGES_THAT_FALL + 1;
$indices[] = $change;
$so_far = self::heldInRange($so_far + $moved);
}
$steps[] = $so_far;
}
return $steps;
}
/**
* heldInRange keeps a step of loudness within the range a stretch
* may be written at. A run of rises would otherwise carry the
* loudness past what the pulses can be scaled by.
*
* @param int $step the step of loudness to hold
* @return int the step, held between the lowest and the highest
*/
public static function heldInRange($step)
{
if ($step < SpeechTables::LEAST_LOUDNESS_STEP) {
return SpeechTables::LEAST_LOUDNESS_STEP;
}
if ($step > SpeechTables::MOST_LOUDNESS_STEP) {
return SpeechTables::MOST_LOUDNESS_STEP;
}
return $step;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software