---
title: "ClikaRT::io::VideoReader"
sidebar_label: "VideoReader"
description: "A lazily-opened video. open reads the header only; info() reports the stream metadata; the frames_* getters decode on demand."
---

<!-- Generated by tools/doxygen2mdx from Doxygen XML. Do not edit. -->

<span class="api-kind api-kind--class">class</span>

**Header:** `ClikaRT/io/video.h`

A lazily-opened video. [`open`](./VideoReader.md#open) reads the header only; [`info()`](./VideoReader.md#info) reports the stream metadata; the `frames_*` getters decode on demand. [`frames_at`](./VideoReader.md#frames_at) is the primitive; a custom sampling policy computes its own indices against [`info()`](./VideoReader.md#info) and calls it. Move-only.

Every fallible method returns its value directly and raises [`ClikaRT::Error`](../Error.md) on failure (wrap in [`CLIKART_TRY(...)`](../../index.md#CLIKART_TRY) to inspect a [`Result`](../Result.md) instead).

## Nested types

| Name | Description |
| --- | --- |
| [`FrameRange`](./VideoReader.FrameRange.md) | A lazy range over frames yielding [`FrameBatch`](./FrameBatch.md)es of up to `batch_size` frames each. The consecutive form covers all frames `[0, T)`; the explicit form covers an arbitrary `indices` set. Each dereference decodes its window (and raises [`ClikaRT::Error`](../Error.md) on a decode failure). An index past the clip's last frame is refused by name at the decode, whichever form asked for it. |

## Static member functions

### open(string\_view) {#open}

<div class="api-signature">

`static` [`VideoReader`](./VideoReader.md) **`open`**(`std::string_view` `path`)

</div>

Open a reader over a file (reads the header only). `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 47

</div>

### open(Span\< uint8\_t\>) {#open-2}

<div class="api-signature">

`static` [`VideoReader`](./VideoReader.md) **`open`**([`ClikaRT::Span`](../Span.md)`<const std::uint8_t>` `bytes`)

</div>

Open a reader over a file (reads the header only). `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 51

</div>

## Member functions

### VideoReader() {#VideoReader}

<div class="api-signature">

**`VideoReader`**(`VideoReader&&`) `noexcept`

</div>

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 53

</div>

### operator=() {#operator-assign}

<div class="api-signature">

[`VideoReader`](./VideoReader.md)`&` **`operator=`**([`VideoReader`](./VideoReader.md)`&&`) `noexcept`

</div>

Move-assign: transfers the reader.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 55

</div>

### \~VideoReader() {#VideoReader-2}

<div class="api-signature">

**`~VideoReader`**()

</div>

Releases the reader and its decoder state.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 57

</div>

### info() {#info}

<div class="api-signature">

[`VideoInfo`](./VideoInfo.md) **`info`**() `const`

</div>

The stream's static metadata (read at open). Infallible.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 60

</div>

### frames\_at() {#frames_at}

<div class="api-signature">

[`FrameBatch`](./FrameBatch.md) **`frames_at`**([`ClikaRT::Span`](../Span.md)`<const std::int64_t>` `indices`) `const`

</div>

Decode exactly the frames at `indices` (in order) → a [`FrameBatch`](./FrameBatch.md). The primitive every other getter routes through. `indices` is read during the call, not retained.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 66

</div>

### sample\_uniform() {#sample_uniform}

<div class="api-signature">

[`FrameBatch`](./FrameBatch.md) **`sample_uniform`**(`std::int64_t` `n`) `const`

</div>

Uniformly sample `n` frames across the whole clip (the built-in default sampling policy).

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 71

</div>

### frames\_at\_timestamps() {#frames_at_timestamps}

<div class="api-signature">

[`FrameBatch`](./FrameBatch.md) **`frames_at_timestamps`**([`ClikaRT::Span`](../Span.md)`<const double>` `seconds`) `const`

</div>

Decode the frames nearest each timestamp in `seconds`. `seconds` is read during the call, not retained.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 76

</div>

### frame\_bytes() {#frame_bytes}

<div class="api-signature">

`std::vector<std::uint8_t>` **`frame_bytes`**(`std::int64_t` `index`) `const`

</div>

A single frame's raw RGB bytes (length `H * W * 3`) copied into a vector.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 80

</div>

### to\_process\_metadata() {#to_process_metadata}

<div class="api-signature">

[`VideoInfo`](./VideoInfo.md) **`to_process_metadata`**() `const`

</div>

The [`to_process_metadata`](./VideoReader.md#to_process_metadata) bridge: the reader's info as the processor's 3-field `VideoMetadata`-shaped [`VideoInfo`](./VideoInfo.md) (total\_num\_frames / fps / duration\_seconds), so a clip feeds a video processor directly. Infallible.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 85

</div>

### frames(int64\_t) {#frames}

<div class="api-signature">

[`FrameRange`](./VideoReader.FrameRange.md) **`frames`**(`std::int64_t` `batch_size` `=` `1`) `const`

</div>

Iterate all frames `[0, T)` in batches of `batch_size`.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 136

</div>

### frames(Span\< int64\_t\>, int64\_t) {#frames-2}

<div class="api-signature">

[`FrameRange`](./VideoReader.FrameRange.md) **`frames`**([`ClikaRT::Span`](../Span.md)`<const std::int64_t>` `indices`, `std::int64_t` `batch_size` `=` `1`) `const`

</div>

Iterate an explicit `indices` set in batches of `batch_size`.

<div class="api-declared">

Declared in `ClikaRT/io/video.h`, line 138

</div>