<?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
*
* This class reads a Matroska or WebM file. It finds the video track and
* the frames that stand on their own.
*/
namespace seekquarry\yioop\library\av_processing;
/**
* WebmExtractor reads a Matroska or WebM file, finding the video track and
* the frames that stand on their own.
*/
final class WebmExtractor extends VideoExtractor
{
/**
* $hevc stores the H.265 decoder, made when the first such frame is asked
* for.
* @var HevcDecoder
*/
private ?HevcDecoder $hevc = null;
use ByteSource;
/**
* $clock_units_per_second stores how many thousand-millionths of a second
* one tick
* of the file's clock stands for. Every time in the file is in ticks, so
* this turns them into seconds. Read by durationSeconds(), frameRate(),
* sampleTime().
* @var int
*/
private int $clock_units_per_second = 1000000;
/**
* $file_length_ticks stores how long the file runs, in those ticks, as its
* header says. Where the header leaves it out, the last frame's time is
* used instead.
* @var float
*/
private float $file_length_ticks = 0.0;
/**
* $track_number stores which track of the file carries the video. Every
* block names the track it belongs to, so blocks of any other track are
* passed over.
* @var int
*/
private int $track_number = -1;
/**
* $codec_name stores the name the file gives the codec, such as the one it
* uses for VP9 or for a the MPEG-4 family of formats/ISO/AVC. codecKind()
* reads it to decide which decoder a frame goes to.
* @var string
*/
private string $codec_name = '';
/**
* $frame_width stores how wide a frame is, in pixels, as the track's header
* says. A thumbnail is scaled against it without decoding anything.
* @var int
*/
private int $frame_width = 0;
/**
* $frame_height stores how tall a frame is, in pixels, as the
* file's own header gives it. A thumbnail keeps the shape of
* the frame, so its height follows from this and the width.
* @var int
*/
private int $frame_height = 0;
/**
* $codec_setup_bytes stores the settings the file keeps beside the track
* for its codec. For H.264 and HEVC a decoder needs them before it can read
* a frame.
* @var string
*/
private string $codec_setup_bytes = '';
/**
* $default_frame_length stores how long a frame lasts where the file does
* not say otherwise, in ticks. frameRate() turns it into frames a second.
* @var float
*/
private float $default_frame_length = 0.0;
/**
* $frame_table stores where each frame sits in the file, when it is shown,
* and whether it stands on its own. This is what a seek walks. Read by
* durationSeconds(), frameCount(), frameRate().
* @var array
*/
private array $frame_table = [];
/**
* $self_contained_frames stores which of those frames stand on their own,
* by their place in the list above. A thumbnail is decoded from one of
* these.
* @var array
*/
private array $self_contained_frames = [];
/**
* $h264_settings stores the H.264 settings settings, or nothing where there
* is none.
* @var AvcConfig
*/
private ?AvcConfig $h264_settings = null;
/**
* $vp8 stores the vp8, or nothing where there is none.
* @var Vp8Decoder
*/
private ?Vp8Decoder $vp8 = null;
/**
* $vp9 stores the vp9, or nothing where there is none.
* @var Vp9Header
*/
private ?Vp9Header $vp9 = null;
/**
* ID_SEGMENT is the number naming the part of the file that holds
* everything else: the tracks, the timing and the frames.
* @var mixed
*/
private const ID_SEGMENT = 0x18538067;
/**
* ID_INFO is the number naming the part that carries the file's clock and
* how long it runs.
* @var mixed
*/
private const ID_INFO = 0x1549A966;
/**
* ID_TIMECODE_SCALE is the number naming the field that says how long one
* tick of that clock is.
* @var mixed
*/
private const ID_TIMECODE_SCALE = 0x2AD7B1;
/**
* ID_DURATION is the number naming the field that says how many ticks the
* file runs for.
* @var mixed
*/
private const ID_DURATION = 0x4489;
/**
* ID_TRACKS is the number naming the part that lists the file's tracks.
* @var mixed
*/
private const ID_TRACKS = 0x1654AE6B;
/**
* ID_TRACK_ENTRY is the number naming one track within that list.
* @var mixed
*/
private const ID_TRACK_ENTRY = 0xAE;
/**
* ID_TRACK_NUMBER is the number naming the field that gives a track its
* number, which every frame refers back to.
* @var mixed
*/
private const ID_TRACK_NUMBER = 0xD7;
/**
* ID_TRACK_TYPE is the number naming the field that says whether a track
* carries video, sound or something else.
* @var mixed
*/
private const ID_TRACK_TYPE = 0x83;
/**
* ID_CODEC_ID is the number naming the field that says which codec a track
* uses.
* @var mixed
*/
private const ID_CODEC_ID = 0x86;
/**
* ID_CODEC_PRIVATE is the number naming the field that carries the settings
* a codec needs before a frame can be read.
* @var mixed
*/
private const ID_CODEC_PRIVATE = 0x63A2;
/**
* ID_DEFAULT_FRAME_LENGTH is the number naming the field that says how
* long a frame
* lasts where the file does not say otherwise.
* @var mixed
*/
private const ID_DEFAULT_FRAME_LENGTH = 0x23E383;
/**
* ID_VIDEO is the number naming the part of a track that describes its
* picture.
* @var mixed
*/
private const ID_VIDEO = 0xE0;
/**
* ID_PIXEL_WIDTH is the number naming the field that gives a frame's width.
* @var mixed
*/
private const ID_PIXEL_WIDTH = 0xB0;
/**
* ID_PIXEL_HEIGHT is the number naming the field that gives a frame's
* height.
* @var mixed
*/
private const ID_PIXEL_HEIGHT = 0xBA;
/**
* ID_CLUSTER is the number naming a group of frames that share a starting
* time.
* @var mixed
*/
private const ID_CLUSTER = 0x1F43B675;
/**
* ID_TIMECODE is the number naming the field that gives that starting time.
* @var mixed
*/
private const ID_TIMECODE = 0xE7;
/**
* ID_SIMPLE_BLOCK is the number naming a frame written on its own, which is
* how most video frames are stored.
* @var mixed
*/
private const ID_SIMPLE_BLOCK = 0xA3;
/**
* ID_BLOCK_GROUP is the number naming a frame written with extra fields
* around it, such as how long it lasts.
* @var mixed
*/
private const ID_BLOCK_GROUP = 0xA0;
/**
* ID_BLOCK is the number naming the frame inside such a group.
* @var mixed
*/
private const ID_BLOCK = 0xA1;
/**
* __construct opens a Matroska or WebM file and indexes its video track.
* The element tree is walked once so that the byte range, time and keyframe
* flag of every frame are known before anything is decoded.
*
* @param string $path file to read
*/
public function __construct(string $path)
{
$this->openSource($path);
$this->readSettings();
}
/**
* readVariableLength read a variable-length integer. marker]
*
* @return array [value, bytes consumed, all-ones
* @param int $off how far into the file to read from
* @param bool $keep_marker whether the packing markers are left in
*/
private function readVariableLength(int $off, bool $keep_marker): array
{
$first = $this->readBytesAt($off, 1);
if ($first === '') {
throw new VideoException('unexpected end of file in EBML');
}
$right_zero = ord($first);
if ($right_zero === 0) {
throw new VideoException('invalid EBML length');
}
$length = 1;
$mask = 0x80;
while (($right_zero & $mask) === 0) {
$mask >>= 1;
$length++;
}
$bytes = $this->readBytesAt($off, $length);
if (strlen($bytes) < $length) {
throw new VideoException('truncated EBML element');
}
$value = $keep_marker ? $right_zero : ($right_zero & ($mask - 1));
$unknown = !$keep_marker && ($right_zero & ($mask - 1)) === ($mask - 1);
for ($i = 1; $i < $length; $i++) {
$value = ($value << 8) | ord($bytes[$i]);
if (ord($bytes[$i]) !== 0xFF) {
$unknown = false;
}
}
return [$value, $length, $unknown];
}
/**
* readWholeNumberFrom reads a whole number stored most significant byte
* first.
*
* @param string $source the file or bytes being read
* @return int what was read
*/
private static function readWholeNumberFrom(string $source): int
{
$variant = 0;
for ($i = 0, $total = strlen($source); $i < $total; $i++) {
$variant = ($variant << 8) | ord($source[$i]);
}
return $variant;
}
/**
* floatOf reads a floating point number of four or eight bytes.
*
* @param string $source the file or bytes being read
* @return float what was read
*/
private static function floatOf(string $source): float
{
if (strlen($source) === 4) {
return unpack('G', $source)[1];
}
if (strlen($source) === 8) {
return unpack('E', $source)[1];
}
return 0.0;
}
/**
* readSettings walks the file and gathers the track and its frames.
*/
private function readSettings(): void
{
$this->walkChunks(0, $this->sourceSize(), 0);
if ($this->track_number < 0) {
throw new VideoException('no video track in this WebM file');
}
if ($this->frame_table === []) {
throw new VideoException('no video frames in this WebM file');
}
usort($this->frame_table, static fn(array $amount, array $bits): int
=> $amount[2] <=> $bits[2]);
foreach ($this->frame_table as $i => $field) {
if ($field[3]) {
$this->self_contained_frames[] = $i;
}
}
}
/**
* walkChunks walks one level of the element tree, descending where it must.
*
* @param int $start where it starts
* @param int $end where it ends
* @param int $depth how deep in the tree
* @param int $cluster_time when the cluster this block belongs to starts
*/
private function walkChunks(int $start, int $end, int $depth,
int $cluster_time
= 0): void
{
if ($depth > 8) {
return;
}
$position = $start;
while ($position < $end && $position < $this->sourceSize()) {
[$id, $id_length] = $this->readVariableLength($position, true);
[$size, $size_length, $unknown] = $this
->readVariableLength($position + $id_length,
false);
$payload = $position + $id_length + $size_length;
if ($unknown) {
/* an element of unknown length runs to the end of its parent */
$size = $end - $payload;
}
$next = $payload + $size;
if ($size < 0 || $payload > $this->sourceSize()) {
break;
}
switch ($id) {
case self::ID_SEGMENT:
case self::ID_TRACKS:
case self::ID_TRACK_ENTRY:
case self::ID_INFO:
case self::ID_VIDEO:
$this->walkChunks($payload, min($end, $next), $depth + 1);
break;
case self::ID_CLUSTER:
$this->walkCluster($payload, min($end, $next), $depth + 1);
break;
case self::ID_TIMECODE_SCALE:
$this->clock_units_per_second
= max(1, self::readWholeNumberFrom($this
->readBytesAt($payload, $size)));
break;
case self::ID_DURATION:
$this->file_length_ticks
= self::floatOf($this->readBytesAt($payload, $size));
break;
case self::ID_TRACK_NUMBER:
$this->pending_track_number
= self::readWholeNumberFrom($this
->readBytesAt($payload, $size));
break;
case self::ID_TRACK_TYPE:
$this->pending_track_type
= self::readWholeNumberFrom($this
->readBytesAt($payload, $size));
break;
case self::ID_CODEC_ID:
$this->pending_codec_name
= rtrim($this->readBytesAt($payload, $size), "\x00");
break;
case self::ID_CODEC_PRIVATE:
$this->pending_codec_setup_bytes = $this
->readBytesAt($payload,
$size);
break;
case self::ID_DEFAULT_FRAME_LENGTH:
$this->pending_frame_length
= (float) self::readWholeNumberFrom($this
->readBytesAt($payload, $size));
break;
case self::ID_PIXEL_WIDTH:
$this->pending_frame_width
= self::readWholeNumberFrom($this
->readBytesAt($payload, $size));
break;
case self::ID_PIXEL_HEIGHT:
$this->pending_frame_height
= self::readWholeNumberFrom($this
->readBytesAt($payload, $size));
break;
}
/* a TrackEntry ends: keep it if it is the first video track */
if ($id === self::ID_TRACK_ENTRY) {
if ($this->pending_track_type === 1 &&
$this->track_number < 0) {
$this->track_number = $this->pending_track_number;
$this->codec_name = $this->pending_codec_name;
$this->codec_setup_bytes = $this->pending_codec_setup_bytes;
$this->frame_width = $this->pending_frame_width;
$this->frame_height = $this->pending_frame_height;
$this->default_frame_length = $this->pending_frame_length;
}
$this->pending_track_type = 0;
$this->pending_track_number = -1;
$this->pending_codec_name = '';
$this->pending_codec_setup_bytes = '';
$this->pending_frame_width = 0;
$this->pending_frame_height = 0;
$this->pending_frame_length = 0.0;
}
if ($next <= $position) {
break;
}
$position = $next;
}
}
/**
* $pending_track_number stores the track being read while the file's header
* is walked. A track's fields arrive one at a time, so they are gathered
* here and kept only if the track turns out to be the video one.
* @var int
*/
private int $pending_track_number = -1;
/**
* $pending_track_type stores whether the track being walked
* carries video, sound or something else. A track's fields arrive
* one at a time, so they are gathered here and kept only if the
* track turns out to be the video one.
* @var int
*/
private int $pending_track_type = 0;
/**
* $pending_codec_name stores that track's codec name, held until the track
* is known to be the one wanted.
* @var string
*/
private string $pending_codec_name = '';
/**
* $pending_codec_setup_bytes stores the codec settings of the track
* being walked, kept until the track is known to be the video
* one. A track's fields arrive one at a time. The
* same way.
* @var string
*/
private string $pending_codec_setup_bytes = '';
/**
* $pending_frame_width stores the frame width of the track being
* walked, kept until that track is known to be the video one. Way.
* @var int
*/
private int $pending_frame_width = 0;
/**
* $pending_frame_height stores the frame height of the track being
* walked, kept until that track is known to be the video one. S
* way.
* @var int
*/
private int $pending_frame_height = 0;
/**
* $pending_frame_length stores how long a frame of the track being
* walked lasts, kept until that track is known to be the video
* one. S
* way.
* @var float
*/
private float $pending_frame_length = 0.0;
/**
* walkCluster walks a cluster, which holds the frames and their times.
*
* @param int $start where it starts
* @param int $end where it ends
* @param int $depth how deep in the tree
*/
private function walkCluster(int $start, int $end, int $depth): void
{
$cluster_time = 0;
$position = $start;
while ($position < $end && $position < $this->sourceSize()) {
[$id, $id_length] = $this->readVariableLength($position, true);
[$size, $size_length, $unknown] = $this
->readVariableLength($position + $id_length,
false);
$payload = $position + $id_length + $size_length;
if ($unknown) {
$size = $end - $payload;
}
$next = $payload + $size;
if ($id === self::ID_TIMECODE) {
$cluster_time = self::readWholeNumberFrom($this
->readBytesAt($payload, $size));
} elseif ($id === self::ID_SIMPLE_BLOCK) {
$this->readBlock($payload, $size, $cluster_time, null);
} elseif ($id === self::ID_BLOCK_GROUP) {
/* a Block inside a BlockGroup carries no keyframe flag of its
*/
/* own; the absence of a ReferenceBlock is what marks it */
$inner = $payload;
$block_at = null;
$block_size = 0;
$has_reference = false;
while ($inner < min($end, $next)) {
[$item_id, $item_id_length] = $this
->readVariableLength($inner,
true);
[$item_size, $item_size_length] = $this
->readVariableLength($inner + $item_id_length,
false);
$inner_payload = $inner + $item_id_length +
$item_size_length;
if ($item_id === self::ID_BLOCK) {
$block_at = $inner_payload;
$block_size = $item_size;
/* ReferenceBlock */
} elseif ($item_id === 0xFB) {
$has_reference = true;
}
$inner = $inner_payload + $item_size;
if ($item_size < 0) {
break;
}
}
if ($block_at !== null) {
$this->readBlock(
$block_at, $block_size, $cluster_time, !$has_reference);
}
}
if ($next <= $position) {
break;
}
$position = $next;
}
}
/** @param bool|null $keyframe null means take the flag from the block
header */
/**
* readBlock records one frame's byte range, time and keyframe flag.
*
* @param int $offset where in the file to start reading
* @param int $size how many bytes
* @param int $cluster_time when the cluster this block belongs to starts
* @param bool $keyframe whether this frame stands on its own
*/
private function readBlock(int $offset, int $size, int $cluster_time,
?bool $keyframe): void
{
if ($size < 4) {
return;
}
[$track, $track_length] = $this->readVariableLength($offset, false);
if ($track !== $this->track_number) {
return;
}
$head = $this->readBytesAt($offset + $track_length, 3);
if (strlen($head) < 3) {
return;
}
$relative = (ord($head[0]) << 8) | ord($head[1]);
if ($relative >= 0x8000) {
$relative -= 0x10000;
}
$flags = ord($head[2]);
$is_key = $keyframe ?? (($flags & 0x80) !== 0);
$lacing = ($flags >> 1) & 3;
$data_start = $offset + $track_length + 3;
$data_end = $offset + $size;
if ($lacing !== 0) {
/* laced blocks pack several frames together; only the first is */
/* needed for a thumbnail and only keyframes are ever decoded */
$data_start += 1;
}
if ($data_end <= $data_start) {
return;
}
$this->frame_table[]
= [$data_start, $data_end - $data_start, $cluster_time
+ $relative, $is_key];
}
/**
* frameRate frames a second, from the track's stated frame duration if it
* gives one, otherwise from the spread of frame times.
*
* @return float what was read
*/
private function frameRate(): float
{
if ($this->default_frame_length > 0) {
return 1e9 / $this->default_frame_length;
}
if (count($this->frame_table) > 1) {
$span = ($this->frame_table[count($this->frame_table) - 1][2]
- $this->frame_table[0][2]) * $this
->clock_units_per_second / 1e9;
if ($span > 0) {
return (count($this->frame_table) - 1) / $span;
}
}
return 25.0;
}
/**
* durationSeconds works out how long the video runs.
*
* @return float what was read
*/
public function durationSeconds(): float
{
if ($this->file_length_ticks > 0) {
return $this->file_length_ticks * $this
->clock_units_per_second / 1e9;
}
return count($this->frame_table) / $this->frameRate();
}
/**
* syncSamples positions of the frames that can be decoded on their own.
*
* @return array what was read
*/
public function syncSamples(): array
{
return $this->self_contained_frames;
}
/**
* sampleTime works out when a frame is shown, in seconds from the start.
*
* @param int $index position of the sample in decode order
* @return float what was read
*/
public function sampleTime(int $index): float
{
if (!isset($this->frame_table[$index])) {
return 0.0;
}
return $this->frame_table[$index][2] * $this
->clock_units_per_second / 1e9;
}
/**
* sampleData the stored bytes of one frame.
*
* @param int $index position of the sample in decode order
* @return string what was read
*/
public function sampleData(int $index): string
{
if (!isset($this->frame_table[$index])) {
throw new VideoException("no frame at index $index");
}
return $this->readBytesAt(
$this->frame_table[$index][0], $this->frame_table[$index][1]);
}
/**
* codecName the codec name as the file spells it.
*
* @return string what was read
*/
public function codecName(): string
{
return $this->codec_name;
}
/**
* containerName webM when the track carries a codec that format allows,
* Matroska otherwise.
*
* @return string what was read
*/
public function containerName(): string
{
/* WebM is the subset of Matroska carrying VP8, VP9 or AV1 */
return in_array($this->codec_name, ['V_VP8', 'V_VP9', 'V_AV1'], true)
? 'WebM' : 'Matroska';
}
/**
* vp9Header the VP9 header of the first keyframe, parsed on demand
*
* @return Vp9Header what was read
*/
public function vp9Header(): Vp9Header
{
if ($this->vp9 === null) {
$self_contained_frames = $this->syncSamples();
if ($self_contained_frames === []) {
throw new VideoException('no VP9 keyframe to inspect');
}
$this->vp9 = Vp9Header::readSettings($this
->sampleData($self_contained_frames[0]));
}
return $this->vp9;
}
/**
* codecKind works out which decoder handles this track.
*
* @return string what was read
*/
public function codecKind(): string
{
if ($this->codec_name === 'V_VP8') {
return 'vp8';
}
if ($this->codec_name === 'V_VP9') {
return 'vp9';
}
if ($this->codec_name === 'V_MPEGH/ISO/HEVC') {
return 'hevc';
}
/* Matroska also carries H.264, whose decoder is already here */
if ($this->codec_name === 'V_MPEG4/ISO/AVC') {
return 'h264';
}
return $this->codec_name;
}
/**
* avcConfig the H.264 setup record the container carries, parsed once.
*
* @return AvcConfig what was read
*/
private function avcConfig(): AvcConfig
{
if ($this->h264_settings === null) {
$this->h264_settings
= ($this->codec_setup_bytes !== ''
&& ord($this->codec_setup_bytes[0]) === 1)
? AvcConfig::readSettings($this->codec_setup_bytes)
: new AvcConfig();
}
return $this->h264_settings;
}
/**
* frameWidth width of the picture in samples.
*
* @return int what was read
*/
public function frameWidth(): int
{
return $this->frame_width;
}
/**
* frameHeight height of the picture in samples.
*
* @return int what was read
*/
public function frameHeight(): int
{
return $this->frame_height;
}
/**
* frameCount works out how many frames the video holds.
*
* @return int what was read
*/
public function frameCount(): int
{
return count($this->frame_table);
}
/**
* settingsUnits the H.264 parameter sets the container carries, if any.
*
* @return array what was read
*/
public function settingsUnits(): array
{
if ($this->codecKind() === 'hevc') {
return HevcParamParser::settingsFromSetupRecord($this
->codecPrivate());
}
$chunk = $this->avcConfig();
return array_values(array_filter([$chunk->sequence_settings,
$chunk->picture_settings]));
}
/**
* toPlainStream turns a stored H.264 frame into a stream of start coded
* units.
*
* @param string $sample the stored bytes of one sample
* @return string what was read
*/
public function toPlainStream(string $sample): string
{
if ($this->codecKind() === 'hevc') {
$settings = new AvcConfig();
$record = $this->codecPrivate();
$settings->stream_unit_length_size = (strlen($record) < 22) ?
4 : (ord($record[21]) & 3) + 1;
return self::plainStreamFrom($settings, $sample);
}
if ($this->codecKind() !== 'h264') {
throw new VideoException(
"'{$this->codec_name}' is not an H.264 stream");
}
return self::plainStreamFrom($this->avcConfig(), $sample);
}
/**
* decodeVp8 decodes one VP8 keyframe into a picture.
*
* @param string $frame the stored bytes of one frame
* @return VideoPicture what was read
*/
public function decodeVp8(string $frame): VideoPicture
{
if ($this->vp8 === null) {
$this->vp8 = new Vp8Decoder();
}
return $this->vp8->decodeKeyframe($frame);
}
/**
* decodeVp9 decodes one VP9 keyframe into a picture.
*
* @param string $frame the stored bytes of one frame
* @return VideoPicture what was read
*/
public function decodeVp9(string $frame): VideoPicture
{
$header = Vp9Header::readSettings($frame);
$decoder = new Vp9Entropy($header, $frame);
$decoder->decodePicture();
return $decoder->toPicture();
}
/**
* unsupportedDetail extra words describing a codec this reader can index
* but not decode, so the refusal names what was found.
*
* @return string what was read
*/
protected function unsupportedDetail(): string
{
if ($this->codec_name !== 'V_VP9') {
return '';
}
try {
return ' (' . $this->vp9Header()->describe() . ')';
} catch (Throwable $entry) {
return '';
}
}
/**
* codecPrivate the codec's private setup data as the container stores it.
*
* @return string what was read
*/
public function codecPrivate(): string
{
return $this->codec_setup_bytes;
}
/**
* decodeHevc decodes one H.265 keyframe into a picture.
*
* @param string $frame the stored bytes of one frame
* @return VideoPicture the decoded picture
*/
public function decodeHevc(string $frame): VideoPicture
{
if ($this->hevc === null) {
$this->hevc = new HevcDecoder();
$this->hevc->consumeStored($this->settingsUnits());
}
return $this->hevc->decodeKeyframe($this->toPlainStream($frame));
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software