<?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 an AVI file. It uses the file's index where that can be
* trusted, and walks the movie list where it cannot.
*/
namespace seekquarry\yioop\library\av_processing;
/**
* AviExtractor reads an AVI file. It uses the file's own index where that
* can be trusted, and walks the movie list where it cannot.
*/
final class AviExtractor extends VideoExtractor
{
use ByteSource;
/**
* $stream_index stores which stream of the file carries the video. An AVI
* may hold several streams, and every chunk of the movie list names the
* stream it belongs to, so this says which chunks to keep. Set by
* walkChunks() while it reads the file's headers.
* @var int
*/
private int $stream_index = -1;
/**
* $compression_name stores the four letters the stream header gives for the
* codec, such as H264 or motion the still picture format, where each frame
* is a still picture. codecKind() reads it to decide which decoder to hand
* a frame to.
* @var string
*/
private string $compression_name = '';
/**
* $handler_name stores the four letters the stream's handler is named by,
* which some writers fill in where the compression field is left empty.
* codecKind() falls back to it.
* @var string
*/
private string $handler_name = '';
/**
* $frame_width stores how wide a frame is, in pixels, as the file says. A
* thumbnail is scaled against it, so a reader can ask before decoding.
* @var int
*/
private int $frame_width = 0;
/**
* $frame_height stores how tall a frame is, in pixels, as the file says.
* Used with the width to keep a thumbnail's shape.
* @var int
*/
private int $frame_height = 0;
/**
* $frame_rate_lower stores the lower half of the frame rate the file gives,
* as a fraction of rate over scale. durationSeconds() and sampleTime()
* divide by it to turn a frame number into a moment in the video.
* @var int
*/
private int $frame_rate_lower = 1;
/**
* $frame_rate_upper stores the upper half of that frame rate. Twenty-five
* stands until the file says otherwise, so a file with no rate still gives
* times.
* @var int
*/
private int $frame_rate_upper = 25;
/**
* $claimed_frame_count stores how many frames the file's header claims to
* hold. It is not trusted for seeking, since writers often leave it wrong,
* but it says whether the index is worth reading.
* @var int
*/
private int $claimed_frame_count = 0;
/**
* $codec_setup_bytes stores the bytes the stream header carries after its
* own fields, which for H.264 hold the settings a decoder needs.
* avcConfig() reads them before any frame is decoded.
* @var string
*/
private string $codec_setup_bytes = '';
/**
* $frame_table stores where every frame sits in the file, how long it is,
* and whether it stands on its own. This is what a seek walks, so it is
* built once when the file is opened.
* @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 can only be decoded from
* one of these, so asking for a moment picks the nearest one before it.
* @var array
*/
private array $self_contained_frames = [];
/**
* $h264_settings stores the H.264 settings read out of the stream header,
* kept after the first reading so a second frame does not read them again.
* Nothing where the file carries none.
* @var AvcConfig
*/
private ?AvcConfig $h264_settings = null;
/**
* $has_been_read stores whether the file's headers and index have been
* read. The reading is done once, the first time anything is asked of the
* file.
* @var bool
*/
private bool $has_been_read = false;
/**
* __construct opens an AVI file and indexes its video stream.
*
* @param string $path file to read
*/
public function __construct(string $path)
{
$this->openSource($path);
$this->readSettings();
}
/**
* readFourBytes reads a four byte number stored least significant byte
* first.
*
* @param string $source the file or bytes being read
* @param int $origin where the reading started
* @return int what was read
*/
private static function readFourBytes(string $source, int $origin): int
{
return unpack('V', substr($source, $origin, 4))[1];
}
/**
* readSettings walks the file's chunks and gathers the stream and its
* frames.
*/
private function readSettings(): void
{
if ($this->has_been_read) {
return;
}
$this->has_been_read = true;
$head = $this->readBytesAt(0, 12);
if (strlen($head) < 12 || substr($head, 0, 4) !== 'RIFF'
|| substr($head, 8, 4) !== 'AVI ') {
throw new VideoException('not an AVI file');
}
$movie_list_parts = [];
$chunk_index = null;
/* walk every top-level RIFF segment: 'AVI ' then any 'AVIX' extensions
*/
$position = 0;
while ($position + 12 <= $this->sourceSize()) {
$header = $this->readBytesAt($position, 12);
if (strlen($header) < 12 || substr($header, 0, 4) !== 'RIFF') {
break;
}
$chunked_file_size = self::readFourBytes($header, 4);
$end = min($this->sourceSize(), $position + 8 + $chunked_file_size);
$this->walkChunks($position + 12, $end, $movie_list_parts,
$chunk_index);
$position =
$position + 8 + $chunked_file_size + ($chunked_file_size & 1);
}
if ($this->stream_index < 0) {
throw new VideoException('no video stream in this AVI file');
}
if ($movie_list_parts === []) {
throw new VideoException("no 'movi' list found");
}
$this->buildFrameIndex($movie_list_parts, $chunk_index);
if ($this->frame_table === []) {
throw new VideoException('no video frames found');
}
$this->deriveSyncSamples();
}
/**
* walkChunks reads the file from one place to another, gathering
* where the movie list sits and where the index of frames sits. An
* AVI is built of named chunks, some of which hold further chunks,
* so this calls itself for each of those and stops at six levels
* down, which is deeper than any real file goes.
*
* @param int $start Where in the file to start reading.
* @param int $end Where to stop.
* @param array $movie_list_parts Filled in with where each part of
* the movie list starts and ends.
* @param array $chunk_index Filled in with where each frame sits in
* the file and how long it is, where the file carries an index.
* @param int $depth How many levels of chunks deep the reading has
* gone, which stops it following a damaged file forever.
*/
private function walkChunks(int $start, int $end,
array &$movie_list_parts, &$chunk_index, int $depth = 0): void
{
if ($depth > 6) {
return;
}
$position = $start;
$stream_count = 0;
while ($position + 8 <= $end) {
$header = $this->readBytesAt($position, 8);
if (strlen($header) < 8) {
break;
}
$codec_name = substr($header, 0, 4);
$size = self::readFourBytes($header, 4);
$payload = $position + 8;
if ($payload + $size > $end + 8) {
$size = max(0, $end - $payload);
}
if ($codec_name === 'LIST' || $codec_name === 'RIFF') {
$list_type = $this->readBytesAt($payload, 4);
if ($list_type === 'movi') {
$movie_list_parts[] = [$payload, $payload + $size];
} else {
$this->walkChunks($payload + 4, $payload
+ $size, $movie_list_parts, $chunk_index, $depth + 1);
}
} elseif ($codec_name === 'strh') {
$delta = $this->readBytesAt($payload, min(56, $size));
if (strlen($delta) >= 40 && substr($delta, 0, 4) === 'vids'
&& $this->stream_index < 0) {
$this->stream_index = $this->streams_named_so_far;
$this->handler_name = substr($delta, 4, 4);
$this->frame_rate_lower = max(1,
self::readFourBytes($delta, 20));
$this->frame_rate_upper = max(1,
self::readFourBytes($delta, 24));
$this->claimed_frame_count = self::readFourBytes($delta,
32);
$this->reading_video_format = true;
}
$this->streams_named_so_far++;
} elseif ($codec_name === 'strf' && $this->reading_video_format) {
$this->reading_video_format = false;
$delta = $this->readBytesAt($payload, $size);
if (strlen($delta) >= 40) {
$block_size = self::readFourBytes($delta, 0);
$this->frame_width = self::readFourBytes($delta, 4);
$header = self::readFourBytes($delta, 8);
/* a negative height means a top-down bitmap; only the */
/* magnitude matters here */
$this->frame_height = ($header >= 0x80000000) ? 0x100000000
- $header : $header;
$this->compression_name = substr($delta, 16, 4);
if ($block_size >= 40 && strlen($delta) > $block_size) {
$this->codec_setup_bytes = substr($delta, $block_size);
}
}
} elseif ($codec_name === 'idx1') {
$chunk_index = [$payload, $size];
}
$position = $payload + $size + ($size & 1);
}
}
/**
* $streams_named_so_far stores how many streams the header has named so far
* while it is being walked. A stream's number is its place in that order,
* which is what the chunks in the movie list refer to.
* @var int
*/
private int $streams_named_so_far = 0;
/**
* $reading_video_format stores whether the stream now being walked is the
* video one, so that the format chunk which follows its header is read
* rather than passed over.
* @var bool
*/
private bool $reading_video_format = false;
/**
* chunkIdPrefix the two digit stream number a chunk name starts with.
*
* @return string what was read
*/
private function chunkIdPrefix(): string
{
return sprintf('%02d', $this->stream_index);
}
/**
* isVideoChunkId says whether a chunk name marks video rather than sound.
*
* @param string $id which one, by the number the format gives it
* @param string $prefix the bytes a unit starts with
* @return bool what was read
*/
private static function isVideoChunkId(string $id, string $prefix): bool
{
if (substr($id, 0, 2) !== $prefix) {
return false;
}
$kind = substr($id, 2, 2);
return $kind === 'dc' || $kind === 'db';
}
/**
* buildFrameIndex parts sit in the file chunks, where it has one
*
* @param array $movie_list_parts where the movie list's
* @param array $chunk_index the index the file keeps of its
*/
private function buildFrameIndex(array $movie_list_parts,
?array $chunk_index): void
{
if ($chunk_index !== null && count($movie_list_parts) === 1) {
$frame_table = $this->framesFromIndex($chunk_index,
$movie_list_parts[0][0]);
if ($frame_table !== []) {
$this->frame_table = $frame_table;
return;
}
}
foreach ($movie_list_parts as [$codec_name_position, $end]) {
$this->scanMovi($codec_name_position + 4, $end);
}
if ($chunk_index !== null) {
$this->applyIndexFlags($chunk_index);
}
}
/**
* framesFromIndex the chunk index offsets are normally measured from the
* 'movi (the list an AVI keeps its frames in)' four-character code, but
* some writers store absolute file offsets. The base is chosen by checking
* which one lands on the chunk the entry claims to describe. at sit
*
* @return array the frames the index points
* @param array $chunk_index the index the file keeps of its chunks
* @param int $movie_list_name_position where the movie list's four letters
*/
private function framesFromIndex(array $chunk_index,
int $movie_list_name_position): array
{
[$offset, $size] = $chunk_index;
$count = intdiv($size, 16);
if ($count === 0) {
return [];
}
$data = $this->readBytesAt($offset, $count * 16);
if (strlen($data) < 16) {
return [];
}
$prefix = $this->chunkIdPrefix();
/* find the first entry belonging to the video stream to test the base
*/
$first = null;
for ($i = 0; $i < $count; $i++) {
$id = substr($data, $i * 16, 4);
if (self::isVideoChunkId($id, $prefix)) {
$first = $i;
break;
}
}
if ($first === null) {
return [];
}
$first_offset = self::readFourBytes($data, $first * 16 + 8);
$first_id = substr($data, $first * 16, 4);
$base = null;
foreach ([$movie_list_name_position, 0, $movie_list_name_position -
4] as $candidate) {
if ($this->readBytesAt($candidate + $first_offset,
4) === $first_id) {
$base = $candidate;
break;
}
}
if ($base === null) {
return [];
}
$frame_table = [];
for ($i = 0; $i < $count; $i++) {
$record = $i * 16;
$id = substr($data, $record, 4);
if (!self::isVideoChunkId($id, $prefix)) {
continue;
}
$flags = self::readFourBytes($data, $record + 4);
$chunk_offset = self::readFourBytes($data, $record + 8);
$length = self::readFourBytes($data, $record + 12);
$data_offset = $base + $chunk_offset + 8;
if ($length === 0 || $data_offset + $length > $this->sourceSize()) {
continue;
}
$frame_table[] = [$data_offset, $length, ($flags & 0x10) !== 0];
}
return $frame_table;
}
/**
* scanMovi walk the movi (the list an AVI keeps its frames in) list
* directly, descending into 'rec ' groupings
*
* @param int $start where it starts
* @param int $end where it ends
* @param int $depth how deep in the tree
*/
private function scanMovi(int $start, int $end, int $depth = 0): void
{
$prefix = $this->chunkIdPrefix();
$position = $start;
while ($position + 8 <= $end) {
$header = $this->readBytesAt($position, 8);
if (strlen($header) < 8) {
break;
}
$id = substr($header, 0, 4);
$size = self::readFourBytes($header, 4);
$payload = $position + 8;
if ($id === 'LIST' && $depth < 3) {
$this->scanMovi($payload
+ 4, min($end, $payload + $size), $depth + 1);
} elseif (self::isVideoChunkId($id, $prefix) && $size > 0) {
$this->frame_table[] = [$payload, $size, false];
}
$position = $payload + $size + ($size & 1);
}
}
/**
* applyIndexFlags attach keyframe flags from the chunk index to a frame
* list built by scanning
*
* @param array $chunk_index the index the file keeps of its chunks
*/
private function applyIndexFlags(array $chunk_index): void
{
[$offset, $size] = $chunk_index;
$count = intdiv($size, 16);
$data = $this->readBytesAt($offset, $count * 16);
$prefix = $this->chunkIdPrefix();
$i = 0;
for ($k = 0; $k < $count && $i < count($this->frame_table); $k++) {
$id = substr($data, $k * 16, 4);
if (!self::isVideoChunkId($id, $prefix)) {
continue;
}
$flags = self::readFourBytes($data, $k * 16 + 4);
$this->frame_table[$i][2] = ($flags & 0x10) !== 0;
$i++;
}
}
/**
* deriveSyncSamples works out which frames can be decoded on their own.
* An AVI may mark each frame that stands on its own, and those
* marks are trusted where the file carries them. Where it marks
* nothing, every frame of a motion still picture stream stands
* on its own, and an H.264 stream is read far enough to find
* the frames that do.
*/
private function deriveSyncSamples(): void
{
$this->self_contained_frames = [];
foreach ($this->frame_table as $i => $frame) {
if ($frame[2]) {
$this->self_contained_frames[] = $i;
}
}
if ($this->self_contained_frames !== []) {
return;
}
$kind = $this->codecKind();
if ($kind === 'jpeg') {
$this->self_contained_frames = array_keys($this->frame_table);
return;
}
if ($kind !== 'h264') {
return;
}
foreach ($this->frame_table as $i => $frame) {
if ($this->holdsSelfContainedPicture($this->readBytesAt($frame[0],
min($frame[1], 65536)))) {
$this->self_contained_frames[] = $i;
}
}
}
/**
* holdsSelfContainedPicture says whether a frame holds a picture that can
* be decoded on its own.
*
* @param string $data the bytes to read
* @return bool what was read
*/
private function holdsSelfContainedPicture(string $data): bool
{
if (self::isPlainStream($data)) {
$total = strlen($data);
for ($i = 0; $i + 4 < $total; $i++) {
if ($data[$i] === "\x00" && $data[$i + 1] === "\x00"
&& $data[$i + 2] === "\x01") {
$type = ord($data[$i + 3]) & 0x1F;
if ($type === 5) {
return true;
}
}
}
return false;
}
$level_scale = $this->avcConfig()->stream_unit_length_size;
$position = 0;
$total = strlen($data);
while ($position + $level_scale < $total) {
$length = 0;
for ($i = 0; $i < $level_scale; $i++) {
$length = ($length << 8) | ord($data[$position + $i]);
}
$position += $level_scale;
if ($length <= 0 || $position >= $total) {
break;
}
if ((ord($data[$position]) & 0x1F) === 5) {
return true;
}
$position += $length;
}
return false;
}
/**
* avcConfig the H.264 setup record the stream header 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;
}
/**
* durationSeconds works out how long the video runs.
*
* @return float what was read
*/
public function durationSeconds(): float
{
return count($this->frame_table) * $this->frame_rate_lower / $this
->frame_rate_upper;
}
/**
* 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.
* AVI stores no times, so this is the frame position divided by the rate.
*
* @param int $index position of the sample in decode order
* @return float what was read
*/
public function sampleTime(int $index): float
{
return $index * $this->frame_rate_lower / $this->frame_rate_upper;
}
/**
* 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");
}
[$offset, $size] = $this->frame_table[$index];
return $this->readBytesAt($offset, $size);
}
/**
* containerName the container format this reader handles.
*
* @return string what was read
*/
public function containerName(): string
{
return 'AVI';
}
/**
* codecName the codec name as the file spells it.
*
* @return string what was read
*/
public function codecName(): string
{
$chunk = trim($this->compression_name);
return $chunk !== '' ? $chunk : trim($this->handler_name);
}
/**
* codecKind works out which decoder handles this stream.
*
* @return string what was read
*/
public function codecKind(): string
{
$chunk = strtoupper(trim($this->compression_name));
if ($chunk === '' || $chunk === "\x00\x00\x00\x00") {
$chunk = strtoupper(trim($this->handler_name));
}
if (in_array($chunk,
['H264', 'X264', 'AVC1', 'DAVC', 'VSSH', 'H.264', 'GAVC'], true)) {
return 'h264';
}
if (in_array($chunk,
['MJPG', 'MJPA', 'MJPB', 'JPEG', 'AVRN', 'DMB1', 'ADJV'], true)) {
return 'jpeg';
}
return $this->codecName();
}
/**
* 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 stream header carries.
*
* @return array what was read
*/
public function settingsUnits(): array
{
$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->codec_setup_bytes !== '' && self::isPlainStream($this
->codec_setup_bytes)) {
/* Some writers keep the settings as a raw stream in the
form H.264 takes on its own, which is called Annex-B. */
return $this->codec_setup_bytes . $sample;
}
return self::plainStreamFrom($this->avcConfig(), $sample);
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software