<?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;
/**
* WebmDemuxer reads the pieces of compressed sound back out of a .webm file. A
* webm file is built out of nested boxes. Each box says what it is, then how
* long it is, then holds either more boxes or a run of plain data. The sound
* itself sits in boxes called blocks, gathered into larger boxes called
* clusters, and what kind of sound it is sits in a separate box near the front
* of the file. Reading the file means walking the boxes, remembering the one
* that says what the sound is, and handing back the sound out of the blocks.
* This is the kind Chrome and Firefox both write when a page asks them to
* record, so it is the kind most recordings arrive in. A block may hold several
* pieces of sound at once, packed nose to tail with their lengths written in
* front in one of three ways. All three are read here, though a recording of
* sound alone normally uses none of them and puts one piece in each block. The
* layout of the boxes is Matroska, which webm is a cut down form of; the box
* lengths and numbers follow the way a WebM file is built out of numbered
* parts, which is called EBML, the binary markup language Matroska is
* written in.
*/
class WebmDemuxer
{
/**
* SEGMENT_BOX is box holding everything else in the file.
*/
const SEGMENT_BOX = 0x18538067;
/**
* INFO_BOX is box holding facts about the file as a whole, such as how its
* times are counted.
*/
const INFO_BOX = 0x1549A966;
/**
* TIME_SCALE_BOX is box saying what one tick of the file's clock is worth
* in billionths of a second.
*/
const TIME_SCALE_BOX = 0x2AD7B1;
/**
* TRACKS_BOX is box holding the description of each sound or picture in the
* file.
*/
const TRACKS_BOX = 0x1654AE6B;
/**
* TRACK_BOX is the number naming the part of the file that describes
* one track, whether that track carries sound or pictures.
*/
const TRACK_BOX = 0xAE;
/**
* TRACK_NUMBER_BOX is box giving the number blocks of this sound are
* labeled with.
*/
const TRACK_NUMBER_BOX = 0xD7;
/**
* TRACK_KIND_BOX is box saying whether this is sound, picture, or something
* else.
*/
const TRACK_KIND_BOX = 0x83;
/**
* SOUND_KIND is value of the box above that means sound.
*/
const SOUND_KIND = 2;
/**
* CODEC_NAME_BOX is box naming how the sound was compressed.
*/
const CODEC_NAME_BOX = 0x86;
/**
* CODEC_SETUP_BOX is box holding the settings a player needs before it can
* make sense of the compressed sound.
*/
const CODEC_SETUP_BOX = 0x63A2;
/**
* CODEC_DELAY_BOX is box saying how much sound at the start is only there
* to let the decoder settle, counted in billionths of a second.
*/
const CODEC_DELAY_BOX = 0x56AA;
/**
* SOUND_BOX is box holding facts about the sound itself.
*/
const SOUND_BOX = 0xE1;
/**
* SAMPLE_RATE_BOX is box giving how many samples a second the sound was
* taken at.
*/
const SAMPLE_RATE_BOX = 0xB5;
/**
* CHANNEL_COUNT_BOX is box giving how many channels the sound has.
*/
const CHANNEL_COUNT_BOX = 0x9F;
/**
* CLUSTER_BOX is box gathering a run of blocks that share a starting time.
*/
const CLUSTER_BOX = 0x1F43B675;
/**
* CLUSTER_TIME_BOX is box giving the starting time a cluster's blocks count
* from.
*/
const CLUSTER_TIME_BOX = 0xE7;
/**
* SIMPLE_BLOCK_BOX is box holding sound with nothing else attached to it.
*/
const SIMPLE_BLOCK_BOX = 0xA3;
/**
* BLOCK_GROUP_BOX is box holding sound together with extra facts about it.
*/
const BLOCK_GROUP_BOX = 0xA0;
/**
* BLOCK_BOX is box holding the sound inside the group above.
*/
const BLOCK_BOX = 0xA1;
/**
* OPUS_CODEC_NAME is what the sound is named when it was compressed with
* Opus.
*/
const OPUS_CODEC_NAME = "A_OPUS";
/**
* DEFAULT_TIME_SCALE is ticks of the file's clock in one second when the
* file does not say otherwise, in billionths of a second.
*/
const DEFAULT_TIME_SCALE = 1000000;
/**
* TIME_UNITS_PER_SECOND is billionths of a second in one second, used to
* turn the file's times into a count of samples.
*/
const TIME_UNITS_PER_SECOND = 1000000000;
/**
* SAMPLE_RATE is samples a second the sound is counted in once decoded.
*/
const SAMPLE_RATE = 48000;
/**
* MAX_FILE_SIZE is largest file this will take in. A recording sent in a
* message is small; anything past this is refused rather than read whole
* into memory.
*/
const MAX_FILE_SIZE = 268435456;
/**
* NO_LACING is how the lengths of several pieces packed into one block are
* written, when they are not written at all.
*/
const NO_LACING = 0;
/**
* XIPH_LACING is lengths written as runs of 255 that add up, the oldest of
* the three ways.
*/
const XIPH_LACING = 1;
/**
* FIXED_LACING is every piece the same length, so only the count is
* written.
*/
const FIXED_LACING = 2;
/**
* EBML_LACING is the packing where each length is written the way a
* part's length is written elsewhere in the file, and each
* length after
* the first as a difference from the one before.
*/
const EBML_LACING = 3;
/**
* LACING_SHIFT is where in a block's flags the way lengths are written
* sits.
*/
const LACING_SHIFT = 1;
/**
* LACING_MASK is how much of the flags to look at to read the way above.
*/
const LACING_MASK = 0x03;
/**
* data stores the whole file, held in memory.
* @var string
*/
public $data;
/**
* track_number stores which number the sound's blocks are labeled with.
* @var int
*/
public $track_number;
/**
* codec_name stores how the sound was compressed, as the file names it.
* @var string
*/
public $codec_name;
/**
* codec_setup stores the settings a decoder needs before it can read the
* sound, as the file gave them.
* @var string
*/
public $codec_setup;
/**
* codec_delay stores sound at the start that is only there to let the
* decoder settle, in billionths of a second.
* @var int
*/
public $codec_delay;
/**
* sample_rate stores how many samples a second the sound was taken at.
* @var float
*/
public $sample_rate;
/**
* channel_count stores how many channels the sound has.
* @var int
*/
public $channel_count;
/**
* time_scale stores what one tick of the file's clock is worth in
* billionths of a second.
* @var int
*/
public $time_scale;
/**
* block_count stores how many blocks of sound have been read.
* @var int
*/
public $block_count;
/**
* __construct sets up a read over the contents of a webm file
*
* @param string $data the whole file
*/
public function __construct($data)
{
$this->data = $data;
$this->track_number = -1;
$this->codec_name = "";
$this->codec_setup = "";
$this->codec_delay = 0;
$this->sample_rate = self::SAMPLE_RATE;
$this->channel_count = 1;
$this->time_scale = self::DEFAULT_TIME_SCALE;
$this->block_count = 0;
}
/**
* fromName opens a file by name and sets up a read over it
*
* @param string $name path of the file to read
* @return object a reader over that file
*/
public static function fromName($name)
{
$size = filesize($name);
if ($size === false) {
throw new \Exception("Could not measure $name");
}
if ($size > self::MAX_FILE_SIZE) {
throw new \Exception("$name is larger than this reads");
}
$data = file_get_contents($name);
if ($data === false) {
throw new \Exception("Could not read $name");
}
return new self($data);
}
/**
* packets hands back the pieces of sound in the file one at a time, in the
* order they were stored. Reading the description of the sound comes first,
* so what kind of sound it is is known before the first piece is given
* back.
*
* @return \Generator each piece of sound as a MediaPacket
*/
public function packets()
{
$length = strlen($this->data);
$at = 0;
$given = 0;
$cluster_time = 0;
while ($at < $length) {
$box = $this->readBoxStart($at);
if ($box === null) {
break;
}
$name = $box["name"];
$body_at = $box["body_at"];
$body_size = $box["body_size"];
if ($name == self::SEGMENT_BOX || $name == self::CLUSTER_BOX ||
$name == self::BLOCK_GROUP_BOX) {
/* These hold more boxes rather than plain data, so the
walk steps into them instead of over them. */
if ($name == self::CLUSTER_BOX) {
$cluster_time = 0;
}
$at = $body_at;
continue;
}
if ($name == self::INFO_BOX) {
$this->readInfo($body_at, $body_size);
} else if ($name == self::TRACKS_BOX) {
$this->readTracks($body_at, $body_size);
} else if ($name == self::CLUSTER_TIME_BOX) {
$cluster_time = $this->readNumber($body_at, $body_size);
} else if ($name == self::SIMPLE_BLOCK_BOX ||
$name == self::BLOCK_BOX) {
foreach ($this->readBlock($body_at, $body_size,
$cluster_time) as $piece) {
yield new MediaPacket($piece["data"], $this->track_number,
$piece["position"], $given, false);
$given++;
}
}
$at = $body_at + $body_size;
}
}
/**
* readInfo reads what the file says about itself, which is where the worth
* of one tick of its clock is written
*
* @param int $at where the box's contents begin
* @param int $size how long those contents are
*/
public function readInfo($at, $size)
{
$end = $at + $size;
while ($at < $end) {
$box = $this->readBoxStart($at);
if ($box === null) {
return;
}
if ($box["name"] == self::TIME_SCALE_BOX) {
$this->time_scale = $this->readNumber($box["body_at"],
$box["body_size"]);
}
$at = $box["body_at"] + $box["body_size"];
}
}
/**
* readTracks reads the description of each sound or picture in the file and
* keeps the first sound found
*
* @param int $at where the box's contents begin
* @param int $size how long those contents are
*/
public function readTracks($at, $size)
{
$end = $at + $size;
while ($at < $end) {
$box = $this->readBoxStart($at);
if ($box === null) {
return;
}
if ($box["name"] == self::TRACK_BOX && $this->track_number < 0) {
$this->readTrack($box["body_at"], $box["body_size"]);
}
$at = $box["body_at"] + $box["body_size"];
}
}
/**
* readTrack reads the description of one sound or picture, keeping it only
* where it turns out to be sound
*
* @param int $at where the box's contents begin
* @param int $size how long those contents are
*/
public function readTrack($at, $size)
{
$end = $at + $size;
$number = -1;
$kind = 0;
$name = "";
$setup = "";
$delay = 0;
$rate = self::SAMPLE_RATE;
$channels = 1;
while ($at < $end) {
$box = $this->readBoxStart($at);
if ($box === null) {
return;
}
$body_at = $box["body_at"];
$body_size = $box["body_size"];
if ($box["name"] == self::TRACK_NUMBER_BOX) {
$number = $this->readNumber($body_at, $body_size);
} else if ($box["name"] == self::TRACK_KIND_BOX) {
$kind = $this->readNumber($body_at, $body_size);
} else if ($box["name"] == self::CODEC_NAME_BOX) {
$name = rtrim(substr($this->data, $body_at, $body_size),
"\0");
} else if ($box["name"] == self::CODEC_SETUP_BOX) {
$setup = substr($this->data, $body_at, $body_size);
} else if ($box["name"] == self::CODEC_DELAY_BOX) {
$delay = $this->readNumber($body_at, $body_size);
} else if ($box["name"] == self::SOUND_BOX) {
$sound_end = $body_at + $body_size;
$sound_at = $body_at;
while ($sound_at < $sound_end) {
$inner = $this->readBoxStart($sound_at);
if ($inner === null) {
break;
}
if ($inner["name"] == self::SAMPLE_RATE_BOX) {
$rate = $this->readFloat($inner["body_at"],
$inner["body_size"]);
} else if ($inner["name"] == self::CHANNEL_COUNT_BOX) {
$channels = $this->readNumber($inner["body_at"],
$inner["body_size"]);
}
$sound_at = $inner["body_at"] + $inner["body_size"];
}
}
$at = $body_at + $body_size;
}
if ($kind == self::SOUND_KIND && $number >= 0) {
$this->track_number = $number;
$this->codec_name = $name;
$this->codec_setup = $setup;
$this->codec_delay = $delay;
$this->sample_rate = $rate;
$this->channel_count = $channels;
}
}
/**
* readBlock pulls the pieces of sound out of one block, working out where
* each belongs from the time the block carries
*
* @param int $at where the block's contents begin
* @param int $size how long those contents are
* @param int $cluster_time the starting time the block counts from
* @return array each piece of sound with where it belongs
*/
public function readBlock($at, $size, $cluster_time)
{
$end = $at + $size;
$label = $this->readVariableNumber($at, true);
if ($label === null) {
return [];
}
$at = $label["next_at"];
if ($label["value"] != $this->track_number || $at + 3 > $end) {
return [];
}
/* The time a block carries is a difference from its cluster's
starting time and may run backwards, so it is read as a
number that can be negative. */
$offset = (ord($this->data[$at]) << 8) | ord($this->data[$at + 1]);
if ($offset >= 0x8000) {
$offset -= 0x10000;
}
$flags = ord($this->data[$at + 2]);
$at += 3;
$lacing = ($flags >> self::LACING_SHIFT) & self::LACING_MASK;
$sizes = $this->readLacedSizes($at, $end, $lacing);
if ($sizes === null) {
return [];
}
$at = $sizes["next_at"];
$ticks = $cluster_time + $offset;
$position = (int)round($ticks * $this->time_scale *
self::SAMPLE_RATE / self::TIME_UNITS_PER_SECOND);
$pieces = [];
foreach ($sizes["sizes"] as $piece_size) {
if ($piece_size < 0 || $at + $piece_size > $end) {
break;
}
$pieces[] = ["data" => substr($this->data, $at, $piece_size),
"position" => $position];
$at += $piece_size;
$this->block_count++;
/* Only the first piece in a block carries a time; the rest
follow it, and how far apart they are is a question for
whatever reads the sound itself. */
$position = -1;
}
return $pieces;
}
/**
* readLacedSizes works out how long each piece packed into a block is, in
* whichever of the three ways the block wrote them where the lengths could
* not be read
*
* @param int $at where the lengths begin
* @param int $end where the block's contents end
* @param int $lacing which of the three ways was used
* @return mixed the lengths and where the sound begins, or null
*/
public function readLacedSizes($at, $end, $lacing)
{
if ($lacing == self::NO_LACING) {
return ["sizes" => [$end - $at], "next_at" => $at];
}
if ($at >= $end) {
return null;
}
$count = ord($this->data[$at]) + 1;
$at++;
if ($lacing == self::FIXED_LACING) {
$left = $end - $at;
if ($count < 1 || $left % $count != 0) {
return null;
}
return ["sizes" => array_fill(0, $count, intdiv($left, $count)),
"next_at" => $at];
}
$sizes = [];
if ($lacing == self::XIPH_LACING) {
for ($i = 0; $i < $count - 1; $i++) {
$piece_size = 0;
while (true) {
if ($at >= $end) {
return null;
}
$part = ord($this->data[$at]);
$at++;
$piece_size += $part;
if ($part != 255) {
break;
}
}
$sizes[] = $piece_size;
}
} else {
$first = $this->readVariableNumber($at, true);
if ($first === null) {
return null;
}
$piece_size = $first["value"];
$sizes[] = $piece_size;
$at = $first["next_at"];
for ($i = 1; $i < $count - 1; $i++) {
$step = $this->readVariableNumber($at, true);
if ($step === null) {
return null;
}
/* Each length after the first is written as a
difference from the one before, shifted so it can
run either way. */
$middle = (1 << ($step["width"] * 7 - 1)) - 1;
$piece_size += $step["value"] - $middle;
$sizes[] = $piece_size;
$at = $step["next_at"];
}
}
$used = array_sum($sizes);
$sizes[] = $end - $at - $used;
return ["sizes" => $sizes, "next_at" => $at];
}
/**
* readBoxStart reads the start of a box: what it is, and where and how long
* its contents are long they are, or null where it could not be read
*
* @param int $at where the box begins
* @return mixed the box's name, where its contents begin, and how
*/
public function readBoxStart($at)
{
$name = $this->readVariableNumber($at, false);
if ($name === null) {
return null;
}
$size = $this->readVariableNumber($name["next_at"], true);
if ($size === null) {
return null;
}
$body_at = $size["next_at"];
$body_size = $size["value"];
$length = strlen($this->data);
/* A box may say it does not know its own length, which a
recorder writes when it cannot go back and fill the length
in. Such a box runs to the end of what there is. */
if ($size["unstated"] || $body_at + $body_size > $length) {
$body_size = $length - $body_at;
}
return ["name" => $name["value"], "body_at" => $body_at,
"body_size" => $body_size];
}
/**
* readVariableNumber reads a number whose length is written into its own
* first byte, which is how box names and box lengths are both stored
* length, which box lengths do and box names do not and whether it was the
* all ones value meaning unstated, or null where it could not be read
*
* @param int $at where the number begins
* @param bool $strip whether to drop the bit that marked the
* @return mixed the number, how many bytes it took, where it ends,
*/
public function readVariableNumber($at, $strip)
{
$length = strlen($this->data);
if ($at < 0 || $at >= $length) {
return null;
}
$first = ord($this->data[$at]);
if ($first == 0) {
return null;
}
$width = 1;
$marker = 0x80;
while (!($first & $marker)) {
$marker >>= 1;
$width++;
}
if ($at + $width > $length) {
return null;
}
$value = $strip ? ($first & ($marker - 1)) : $first;
$all_ones = $strip ? ($marker - 1) : 0;
for ($i = 1; $i < $width; $i++) {
$value = ($value << 8) | ord($this->data[$at + $i]);
$all_ones = ($all_ones << 8) | 0xFF;
}
return ["value" => $value, "width" => $width,
"next_at" => $at + $width,
"unstated" => $strip && $value == $all_ones];
}
/**
* readNumber reads a plain number stored most significant byte first
*
* @param int $at where the number begins
* @param int $size how many bytes it takes
* @return int the number read
*/
public function readNumber($at, $size)
{
$value = 0;
for ($i = 0; $i < $size; $i++) {
$value = ($value << 8) | ord($this->data[$at + $i]);
}
return $value;
}
/**
* readFloat reads a number with a fractional part, which the file writes in
* either of two widths
*
* @param int $at where the number begins
* @param int $size how many bytes it takes
* @return float the number read
*/
public function readFloat($at, $size)
{
if ($size == 4) {
$read = unpack("G", substr($this->data, $at, 4));
return $read[1];
}
if ($size == 8) {
$read = unpack("E", substr($this->data, $at, 8));
return $read[1];
}
return (float)$this->readNumber($at, $size);
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software