---
title: "ClikaRT::io"
sidebar_label: "io"
description: "Namespace ClikaRT::io"
---

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

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

## Classes

| Name | Description |
| --- | --- |
| [`AdaptCompose`](./AdaptCompose.md) | N source parts produce ONE adapted entry under [`to`](./AdaptCompose.md#to), the value view. The parts are CONSUMED (their names leave the adapted key space); [`to`](./AdaptCompose.md#to) may equal one of the parts (the `weight` + `weight_scale` → `weight` shape). |
| [`AdaptDrop`](./AdaptDrop.md) | One key removed from the adapted key space (consumed, never bound), how a checkpoint's unread extras leave the strict walk's accounting. |
| [`AdaptRename`](./AdaptRename.md) | One key rename: the entry under [`from`](./AdaptRename.md#from) appears under [`to`](./AdaptRename.md#to); metadata only (byte range, laziness, and quantization metadata are preserved). [`reverse_dims`](./AdaptRename.md#reverse_dims) additionally relabels a DENSE ≥2-D entry's shape with its dims reversed, the row-contiguous-first export re-labeled to the C order a consumer's slots declare; a quantized payload's logical shape is already row-contiguous-first, so the flag passes it through unchanged. The relabel is this explicit flag, never implicit. |
| [`AudioData`](./AudioData.md) | A decoded waveform plus its effective layout. |
| [`AudioInfo`](./AudioInfo.md) | An audio stream's effective layout, read from its header. With non-zero `target_*` the figures reflect what a decode to that target produces: [`frames`](./AudioInfo.md#frames) is exactly the count [`load_audio`](./index.md#load_audio) with the same targets returns (duration in seconds = [`frames`](./AudioInfo.md#frames)` / `[`sample_rate`](./AudioInfo.md#sample_rate)). |
| [`AudioTrack`](./AudioTrack.md) | The audio track a clip carries beside its frames: [`sample_rate`](./AudioTrack.md#sample_rate) in Hz, [`channels`](./AudioTrack.md#channels) (1 mono, 2 stereo, ...) and the audio [`codec`](./AudioTrack.md#codec); an empty codec picks the container's default encoder (AAC in an MP4). Declared at [`VideoWriter::open`](./VideoWriter.md#open); the samples arrive through `write_audio` and are written with the frames at `close`, so one file carries the clip and its sound. |
| [`FrameBatch`](./FrameBatch.md) | A decoded batch of frames plus the alignment metadata a video model needs: the packed `[K, H, W, 3]` UInt8 frames, the source frame [`indices`](./FrameBatch.md#indices) they were taken from, and per-frame [`pts_seconds`](./FrameBatch.md#pts_seconds) / [`duration_seconds`](./FrameBatch.md#duration_seconds). Indexable / iterable: `operator[]` yields a single-frame view, and `begin()`/`end()` iterate single-frame views in order. |
| [`GgufCheckpoint`](./GgufCheckpoint.md) | A GGUF checkpoint opened lazily: the tensors as a [`TensorsContainer`](./TensorsContainer.md) (materialize-on-`get`) plus the file's metadata key/value pairs as JSON. |
| [`GgufModel`](./GgufModel.md) | A loaded GGUF checkpoint: the tensors plus the file's metadata key/value pairs as a JSON object (e.g. `metadata.at("general.architecture")`). |
| [`ImageInfo`](./ImageInfo.md) | An image's pixel geometry as displayed (channels-last), read from its header: an EXIF Orientation tag (JPEG APP1, PNG `eXIf`) is applied, so a 90° orientation reports the swapped height and width, the same `[H, W, C]` [`load_image`](./index.md#load_image) returns. |
| [`LoadPlan`](./LoadPlan.md) | The recommended load PLAN: the policy plus the placement budget a weight-residency scheduler consumes: how many bytes of weights to KEEP device-resident (the rest streams; evicted after use, prefetched ahead of it). When the checkpoint fits under the runtime's offload-headroom share of the device's available memory, the budget is the checkpoint's `total_bytes()` (keep everything) and `policy.sticky` is false; when it doesn't fit, the budget is that headroom share and `policy.sticky` is true; when the available figure is unknown, the budget is 0 and the policy is plain; the runtime never guesses. |
| [`LoadPolicy`](./LoadPolicy.md) | How a policy-taking loader materializes tensors. |
| [`OnnxAttr`](./OnnxAttr.md) | A typed node attribute for `add_node`: the attribute name plus one of the ONNX attribute kinds: INT, FLOAT, STRING, INTS, or FLOATS. |
| [`OnnxModel`](./OnnxModel.md) | An ONNX model, opened from disk or built from scratch. Move-only. |
| [`OnnxModelOptions`](./OnnxModelOptions.md) | Options governing an [`OnnxModel`](./OnnxModel.md)'s editing and serialization behavior; pass to `open` / `create`, they hold for the model's lifetime. |
| [`OnnxNodeInfo`](./OnnxNodeInfo.md) | One node of the ONNX graph as the node listing reports it: the node's name, its op type, its domain (empty for the standard `ai.onnx` domain), and the tensor names on its input and output slots (an omitted optional input is an empty name). |
| [`SafetensorsEntries`](./SafetensorsEntries.md) | A safetensors checkpoint read in the file's own order: [`entries`](./SafetensorsEntries.md#entries) as the header states them (a sharded checkpoint: the index's `weight_map` order) and the checkpoint-level metadata as `(key, value)` text pairs in header order. The order is the point: [`NamedTensors`](../NamedTensors.md) is an unordered map, and a consumer that must give a checkpoint back with its keys in their original order (a saved pytree, a state dict) reads and writes through this form. |
| [`SubsetSpec`](./SubsetSpec.md) | Which entries [`TensorsContainer::subset`](./TensorsContainer.md#subset) takes, and under which names the sub-container serves them. |
| [`TensorsAdapter`](./TensorsAdapter.md) | The declarative adaptation [`adapt`](./index.md#adapt) applies. Keys no entry references pass through under their own names. |
| [`TensorsContainer`](./TensorsContainer.md) | A lazily-materializing view of a checkpoint's tensors. Move-only: the container caches each materialized tensor so repeated [`get`](./TensorsContainer.md#get)s share one storage, and that cache must have a single owner (a sub-container from [`subset`](./TensorsContainer.md#subset) shares the cache of the entries it carries). A container from [`io::peek_gguf`](./index.md#peek_gguf) holds a header only: the queries ([`names`](./TensorsContainer.md#names), [`entry`](./TensorsContainer.md#entry), [`size`](./TensorsContainer.md#size), [`total_bytes`](./TensorsContainer.md#total_bytes), [`entry_bytes`](./TensorsContainer.md#entry_bytes), [`contains`](./TensorsContainer.md#contains)) answer, and every call that reads tensor data fails with [`Status::InvalidArgument`](../../index.md#Status). |
| [`VideoData`](./VideoData.md) | A decoded clip plus its stream info: the returned [`FrameBatch`](./FrameBatch.md) carries every frame `[T, H, W, 3]` UInt8 (host). Guarded against a decompression bomb; a large clip should use [`VideoReader`](./VideoReader.md) ([`ClikaRT/io/video.h`](./index.md#video-h)) for per-index access. `path` is copied. |
| [`VideoInfo`](./VideoInfo.md) | A video stream's static geometry / timing, read from its header. Named [`VideoInfo`](./VideoInfo.md) (NOT `VideoMetadata`, which is the processor's 3-field timing struct) since it is a superset: geometry + codec identity too. |
| [`VideoReader`](./VideoReader.md) | 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. |
| [`VideoWriter`](./VideoWriter.md) | Encode a stream of channels-last RGB `[H, W, 3]` UInt8 frames to a video file, with an optional audio track. Move-only. Every fallible method raises [`ClikaRT::Error`](../Error.md) on failure. |

## Functions

### peek\_image(string\_view) {#peek_image}

<div class="api-signature">

[`ImageInfo`](./ImageInfo.md) **`peek_image`**(`std::string_view` `path`)

</div>

Read an image header. Decodes JPEG, PNG, GIF, BMP, TGA, PSD, HDR, PNM and PIC. The figures are the image as displayed: an EXIF Orientation tag (JPEG APP1, PNG `eXIf`) is applied exactly as [`load_image`](./index.md#load_image) applies it, so the two always agree; a missing, malformed or out-of-range tag reads as upright; an orientation carried only in XMP metadata is not read. A missing/unreadable file → a failure [`Result`](../Result.md) naming the path; a format outside that set (WebP, TIFF, AVIF, ...) → [`Status::Unsupported`](../../index.md#Status) naming the file and the format; damaged data, or a file of another family (audio handed to the image reader) → [`Status::InvalidArgument`](../../index.md#Status) naming the file and what it holds. `path` is copied, not retained.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 62

</div>

### peek\_image(Span\< uint8\_t\>) {#peek_image-2}

<div class="api-signature">

[`ImageInfo`](./ImageInfo.md) **`peek_image`**([`ClikaRT::Span`](../Span.md)`<const std::uint8_t>` `bytes`)

</div>

Header peek over an in-memory encoded image (e.g. an uploaded body). `bytes` is read during the call, not retained.

<div class="api-declared">

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

</div>

### peek\_audio(string\_view, int, int) {#peek_audio}

<div class="api-signature">

[`AudioInfo`](./AudioInfo.md) **`peek_audio`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `path`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`int` `target_sample_rate` `=` `0`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`int` `target_channels` `=` `0`<br />
)

</div>

Read an audio header. Decodes WAV, FLAC, MP3 and OGG (Vorbis). `target_sample_rate` / `target_channels` of 0 report the file's native values; a non-zero value reports the effective figures after the resample/downmix a decode applies; `frames` is exactly what [`load_audio`](./index.md#load_audio) with the same targets returns. A missing/unreadable file → a failure [`Result`](../Result.md) naming the path; a container outside that set (OGG Opus, MP4/M4A AAC, ...) → [`Status::Unsupported`](../../index.md#Status) naming the file and the container; damaged data, or a file of another family (an image handed to the audio reader) → [`Status::InvalidArgument`](../../index.md#Status) naming the file and what it holds. `path` is copied, not retained.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 79

</div>

### peek\_audio(Span\< uint8\_t\>, int, int) {#peek_audio-2}

<div class="api-signature">

[`AudioInfo`](./AudioInfo.md) **`peek_audio`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const std::uint8_t>` `bytes`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`int` `target_sample_rate` `=` `0`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`int` `target_channels` `=` `0`<br />
)

</div>

Header peek over an in-memory encoded audio payload; same `target_*` semantics as the path overload. `bytes` is read during the call, not retained.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 83

</div>

### load\_npy() {#load_npy}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`load_npy`**(`std::string_view` `path`, [`Device`](../Device.md) `device` `=` [`Device::cpu`](../Device.md#cpu)`()`)

</div>

Load a NumPy `.npy` array as a [`Tensor`](../Tensor.md) on [`device`](../device-namespace/index.md). `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 102

</div>

### save\_npy() {#save_npy}

<div class="api-signature">

`void` **`save_npy`**(`const` [`Tensor`](../Tensor.md)`&` `tensor`, `std::string_view` `path`)

</div>

Write `tensor` as a `.npy` file at `path` (materialized contiguous on host). A quantized tensor (`is_quantized()`) is a failure [`Result`](../Result.md) (`INVALID_ARGUMENT`) with nothing written: the array would hold its codes and lose its scale, so dequantize it first ([`ops::dequantize`](../ops/dequantize.md#dequantize)).

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 108

</div>

### load\_image(string\_view, int) {#load_image}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`load_image`**(`std::string_view` `path`, `int` `requested_channels` `=` `0`)

</div>

Decode an image to a host [`Tensor`](../Tensor.md) `[H, W, C]` (channels-last). `requested_channels` of 0 keeps the native channel count; 1/3/4 force gray/RGB/RGBA. Move it to a device with `.to(...)`. The tensor is the image as displayed: an EXIF Orientation tag (JPEG APP1, PNG `eXIf`) is applied at decode: mirrored or rotated per the tag, so `[H, W]` are the displayed rows and columns and match [`peek_image`](./index.md#peek_image); a missing, malformed or out-of-range tag reads as upright; an orientation carried only in XMP metadata is not read.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 118

</div>

### load\_image(Span\< uint8\_t\>, int) {#load_image-2}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`load_image`**([`ClikaRT::Span`](../Span.md)`<const std::uint8_t>` `bytes`, `int` `requested_channels` `=` `0`)

</div>

Decode an in-memory encoded image (an uploaded body, say); same `requested_channels` contract as the path overload. `bytes` is not retained.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 122

</div>

### encode\_image() {#encode_image}

<div class="api-signature">

`std::vector<std::uint8_t>` **`encode_image`**(`const` [`Tensor`](../Tensor.md)`&` `image`)

</div>

Encode a host image [`Tensor`](../Tensor.md) as an untagged PNG payload (exactly IHDR/IDAT/IEND; no color-profile chunks, so a color-managing decoder such as a browser canvas never perturbs the pixel values; class-index masks and depth maps round-trip exactly). `image` is `[H, W]` or `[H, W, C]` channels-last: UInt8 with 1/3/4 channels (gray/RGB/RGBA), or UInt16 single-channel (16-bit gray). Strided views and device tensors are materialized internally. A quantized tensor is a failure [`Result`](../Result.md) (`INVALID_ARGUMENT`): its codes are not pixel values, so dequantize it first ([`ops::dequantize`](../ops/dequantize.md#dequantize)).

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 134

</div>

### deflate\_size() {#deflate_size}

<div class="api-signature">

`std::size_t` **`deflate_size`**([`ClikaRT::Span`](../Span.md)`<const std::uint8_t>` `bytes`)

</div>

The byte count of `bytes` as a zlib stream under the image writer's own deflate (its default level): a two-byte header, fixed-Huffman blocks over an LZ77 match search, an Adler-32 trailer. On short text it reads within about a third of the size a default-level zlib answers, and a repetition law judged on the ratio (2.4) agrees with zlib's on every text measured; its use is the compression ratio a caller reads as `bytes.size() / deflate_size(bytes)` (a transcript that fell into repetition compresses far below its length). The empty input answers the stream's own overhead. An input longer than 2147483647 bytes is a failure [`Result`](../Result.md) (`INVALID_ARGUMENT`). `bytes` is not retained.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 146

</div>

### save\_image() {#save_image}

<div class="api-signature">

`void` **`save_image`**(`const` [`Tensor`](../Tensor.md)`&` `image`, `std::string_view` `path`)

</div>

Write an image [`Tensor`](../Tensor.md) to `path` (created / truncated) in the format the extension asks for: `.png` (or no extension) writes the untagged PNG [`encode_image`](./index.md#encode_image) produces; `.jpg` / `.jpeg`, `.bmp` and `.tga` write those formats (8-bit images; JPEG drops an alpha plane). A 16-bit image writes as PNG only. An extension this writer does not produce (`.webp`, `.gif`, `.tiff`, ...) → [`Status::Unsupported`](../../index.md#Status) naming the path and the format, with nothing written. Same accepted shapes/dtypes as [`encode_image`](./index.md#encode_image), and a quantized tensor is refused the same way, with nothing written.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 156

</div>

### load\_audio(string\_view, int, int) {#load_audio}

<div class="api-signature">

[`AudioData`](./AudioData.md) **`load_audio`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `path`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`int` `target_sample_rate` `=` `0`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`int` `target_channels` `=` `0`<br />
)

</div>

Decode audio to a host Float32 [`Tensor`](../Tensor.md) + its layout. `target_sample_rate` / `target_channels` of 0 keep the native values; a non-zero channel count mixes to it (mono is the equal-weight average of the source channels); a non-zero rate resamples the decoded waveform with the same windowed-sinc filter as [`ops::resample`](../ops/resample.md#resample) (output frames = `ceil(frames · L / M)` over the gcd-reduced rate pair), so [`peek_audio`](./index.md#peek_audio) with the same targets reports the frame count this returns.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 166

</div>

### load\_audio(Span\< uint8\_t\>, int, int) {#load_audio-2}

<div class="api-signature">

[`AudioData`](./AudioData.md) **`load_audio`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const std::uint8_t>` `bytes`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`int` `target_sample_rate` `=` `0`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`int` `target_channels` `=` `0`<br />
)

</div>

Decode an in-memory encoded audio payload; same `target_*` semantics as the path overload. `bytes` is not retained.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 170

</div>

### encode\_audio() {#encode_audio}

<div class="api-signature">

`std::vector<std::uint8_t>` **`encode_audio`**(`const` [`Tensor`](../Tensor.md)`&` `samples`, `int` `sample_rate`)

</div>

Encode a waveform as a 16-bit PCM WAV payload (RIFF/WAVE: the 44-byte header with one PCM `fmt ` chunk and one `data` chunk, then little-endian interleaved frames); [`load_audio`](./index.md#load_audio) reads it back with the same layout. `samples` is `[frames]` (mono) or `[frames, channels]` interleaved: a float tensor (Float16 / BFloat16 / Float32 / Float64) holds values in \[-1, 1\] and converts to 16-bit codes (a value outside \[-1, 1\] clips); an Int16 tensor is written as is. `sample_rate` is in Hz. Strided views and device tensors are materialized internally. Any other rank or dtype, an empty tensor, a non-positive `sample_rate`, or a payload past the format's 4 GiB data limit is a failure [`Result`](../Result.md) (`INVALID_ARGUMENT`), and so is a quantized tensor: its codes are not sample values, so dequantize it first ([`ops::dequantize`](../ops/dequantize.md#dequantize)). To write a decoded clip back, pass `audio.samples` with `audio.info.sample_rate`.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 186

</div>

### save\_audio() {#save_audio}

<div class="api-signature">

`void` **`save_audio`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`const` [`Tensor`](../Tensor.md)`&` `samples`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`int` `sample_rate`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `path`<br />
)

</div>

Write a waveform as a 16-bit PCM WAV file at `path` (created / truncated); the file's bytes are exactly [`encode_audio`](./index.md#encode_audio)'s. The extension is the format request: `.wav` (or no extension) writes; a name asking for another container (`.mp3`, `.ogg`, `.flac`, `.m4a`, ...) → [`Status::Unsupported`](../../index.md#Status) naming the path and the container, with nothing written. Same accepted shapes and dtypes as [`encode_audio`](./index.md#encode_audio), and a quantized tensor is refused the same way, with nothing written; a file that cannot be opened or written is a failure [`Result`](../Result.md) naming the path. `path` is copied, not retained.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 196

</div>

### load\_safetensors(string\_view, Device) {#load_safetensors}

<div class="api-signature">

[`NamedTensors`](../NamedTensors.md) **`load_safetensors`**(`std::string_view` `path`, [`Device`](../Device.md) `device` `=` [`Device::cpu`](../Device.md#cpu)`()`)

</div>

Load a safetensors checkpoint (single-file or sharded `*.index.json`) into a [`NamedTensors`](../NamedTensors.md) on [`device`](../device-namespace/index.md). `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 201

</div>

### save\_safetensors(NamedTensors, string\_view) {#save_safetensors}

<div class="api-signature">

`void` **`save_safetensors`**(`const` [`NamedTensors`](../NamedTensors.md)`&` `tensors`, `std::string_view` `path`)

</div>

Write `tensors` to a single-file safetensors checkpoint at `path` (created / truncated). A quantized tensor is refused with `INVALID_ARGUMENT` and nothing is written; dequantize it first ([`ops::dequantize`](../ops/dequantize.md#dequantize)).

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 206

</div>

### load\_safetensors(string\_view, LoadPolicy) {#load_safetensors-2}

<div class="api-signature">

[`TensorsContainer`](./TensorsContainer.md) **`load_safetensors`**(`std::string_view` `path`, [`LoadPolicy`](./LoadPolicy.md) `policy`)

</div>

Open a safetensors checkpoint (single-file or sharded `*.index.json`) as a lazy [`TensorsContainer`](./TensorsContainer.md) materializing per `policy` ([`ClikaRT/io/tensors_container.h`](./index.md#tensors_container-h)). `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 212

</div>

### peek\_safetensors\_metadata() {#peek_safetensors_metadata}

<div class="api-signature">

[`json::Json`](../json/Json.md) **`peek_safetensors_metadata`**(`std::string_view` `path`)

</div>

Header-only peek at a safetensors checkpoint's CHECKPOINT-LEVEL metadata: eager, and no tensor payload is read. A single `.safetensors` file yields the header's reserved `__metadata__` object (an empty object when the file carries none, not an error); a sharded checkpoint (`*.index.json`, or a directory carrying the index) yields the index document's own top-level "metadata" object, absent likewise meaning empty. A malformed header, a non-object metadata entry, or an unresolvable path fails with a typed error naming the file. `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 223

</div>

### save\_safetensors(Span\< pair\<string, Tensor\>\>, string\_view, Span\< pair\<string, string\>\>) {#save_safetensors-2}

<div class="api-signature">

`void` **`save_safetensors`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const std::pair<std::string,` [`Tensor`](../Tensor.md)`>>` `entries`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `path`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const std::pair<std::string, std::string>>` `metadata` `=` `{}`<br />
)

</div>

Write `entries` to a single-file safetensors checkpoint at `path` (created / truncated) IN THE GIVEN ORDER: the header lists the tensors as passed and the payload follows the same order, so [`load_safetensors_entries`](./index.md#load_safetensors_entries) (or any reader walking the header) sees them as written. `metadata`, when given, populates the checkpoint-level `__metadata__` map in the given order; safetensors metadata values are strings. A repeated name (or the reserved `__metadata__`) is a failure [`Result`](../Result.md) (`INVALID_ARGUMENT`) with nothing written. A quantized tensor is refused with `INVALID_ARGUMENT` and nothing is written; dequantize it first ([`ops::dequantize`](../ops/dequantize.md#dequantize)). `path` is copied. The [`NamedTensors`](../NamedTensors.md) overload above writes the same file in its map's own order.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 253

</div>

### load\_safetensors\_entries() {#load_safetensors_entries}

<div class="api-signature">

[`SafetensorsEntries`](./SafetensorsEntries.md) **`load_safetensors_entries`**(`std::string_view` `path`, [`Device`](../Device.md) `device` `=` [`Device::cpu`](../Device.md#cpu)`()`)

</div>

Load a safetensors checkpoint (single-file or sharded `*.index.json`) onto [`device`](../device-namespace/index.md) in the file's own order: `entries` as the header states them (a sharded checkpoint: the index's `weight_map` order) and `metadata` as [`peek_safetensors_metadata`](./index.md#peek_safetensors_metadata) reports it (a single file's `__metadata__`, a sharded checkpoint's index "metadata"), as text pairs. [`load_safetensors`](./index.md#load_safetensors) is the unordered [`NamedTensors`](../NamedTensors.md) view of the same file. `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 262

</div>

### load\_torch\_checkpoint(string\_view, Device) {#load_torch_checkpoint}

<div class="api-signature">

[`NamedTensors`](../NamedTensors.md) **`load_torch_checkpoint`**(`std::string_view` `path`, [`Device`](../Device.md) `device` `=` [`Device::cpu`](../Device.md#cpu)`()`)

</div>

Load a torch checkpoint (the modern zip container: `pytorch_model.bin` single-file or sharded `*.bin.index.json`) into a [`NamedTensors`](../NamedTensors.md) on [`device`](../device-namespace/index.md). The metadata pickle is parsed by a RESTRICTED interpreter that never executes code (a closed allowlist of state-dict constructors); the legacy pre-zip stream and compressed archives are rejected with a clear error. `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 271

</div>

### load\_torch\_checkpoint(string\_view, LoadPolicy) {#load_torch_checkpoint-2}

<div class="api-signature">

[`TensorsContainer`](./TensorsContainer.md) **`load_torch_checkpoint`**(`std::string_view` `path`, [`LoadPolicy`](./LoadPolicy.md) `policy`)

</div>

Open a torch checkpoint as a lazy [`TensorsContainer`](./TensorsContainer.md) materializing per `policy`: zero-copy per tensor on a CPU target (the archive's STORED entries mmap in place).

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 277

</div>

### load\_gguf(string\_view, Device) {#load_gguf}

<div class="api-signature">

[`GgufModel`](./GgufModel.md) **`load_gguf`**(`std::string_view` `path`, [`Device`](../Device.md) `device` `=` [`Device::cpu`](../Device.md#cpu)`()`)

</div>

Load a GGUF checkpoint (tensors + metadata) onto [`device`](../device-namespace/index.md). `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 281

</div>

### load\_gguf(string\_view, LoadPolicy) {#load_gguf-2}

<div class="api-signature">

[`GgufCheckpoint`](./GgufCheckpoint.md) **`load_gguf`**(`std::string_view` `path`, [`LoadPolicy`](./LoadPolicy.md) `policy`)

</div>

Open a GGUF checkpoint as a lazy [`GgufCheckpoint`](./GgufCheckpoint.md) materializing per `policy`: the [`TensorsContainer`](./TensorsContainer.md) analog of [`load_gguf`](./index.md#load_gguf). `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 292

</div>

### peek\_gguf() {#peek_gguf}

<div class="api-signature">

[`GgufCheckpoint`](./GgufCheckpoint.md) **`peek_gguf`**(`std::string_view` `path`, `std::uint64_t` `checkpoint_bytes` `=` `0`)

</div>

Read a GGUF checkpoint's header only: the metadata and the tensor table (`tensors.names()`, `tensors.entry(name)`, `tensors.total_bytes()`), with no tensor data read and no file kept open. A call that reads tensor data from `tensors` (`get`, `load_all`, `load_into`, `prefetch`) fails with [`Status::InvalidArgument`](../../index.md#Status); [`load_gguf`](./index.md#load_gguf) opens the same file for its tensors.

`path` may hold only the first bytes of the checkpoint, such as a ranged download of its header, when `checkpoint_bytes` gives the size of the whole checkpoint. Each tensor's data range is then checked against that size, and a file that ends inside the header fails with [`Status::Unavailable`](../../index.md#Status): read more of the checkpoint and call again. A `checkpoint_bytes` of 0 means `path` is the whole checkpoint. Any other failure is the one [`load_gguf`](./index.md#load_gguf) reports for the same header. `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 308

</div>

### peek\_video(string\_view) {#peek_video}

<div class="api-signature">

[`VideoInfo`](./VideoInfo.md) **`peek_video`**(`std::string_view` `path`)

</div>

Peek a video stream's header WITHOUT decoding frames. `path` is copied.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 352

</div>

### peek\_video(Span\< uint8\_t\>) {#peek_video-2}

<div class="api-signature">

[`VideoInfo`](./VideoInfo.md) **`peek_video`**([`ClikaRT::Span`](../Span.md)`<const std::uint8_t>` `bytes`)

</div>

Header peek over in-memory encoded video bytes. `bytes` is not retained.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 355

</div>

### load\_video(string\_view) {#load_video}

<div class="api-signature">

[`VideoData`](./VideoData.md) **`load_video`**(`std::string_view` `path`)

</div>

Decode the whole video at `path`: every frame `[T, H, W, 3]` UInt8 on host, plus the stream info.

**Throws**

- `ClikaRT::Error`: on a missing or undecodable file, or when no decode backend exists (see [`video_capability`](./index.md#video_capability)).

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 369

</div>

### load\_video(Span\< uint8\_t\>) {#load_video-2}

<div class="api-signature">

[`VideoData`](./VideoData.md) **`load_video`**([`ClikaRT::Span`](../Span.md)`<const std::uint8_t>` `bytes`)

</div>

Decode an in-memory encoded video. `bytes` is not retained.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 372

</div>

### video\_capability() {#video_capability}

<div class="api-signature">

`bool` **`video_capability`**()

</div>

Whether a usable video decode backend exists on this host (e.g. an `ffmpeg` discoverable on `PATH` for the Linux backend). The video decode entries raise a readable error when this is false. Infallible.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 378

</div>

### temp\_directory\_path() {#temp_directory_path}

<div class="api-signature">

`std::string` **`temp_directory_path`**()

</div>

The system temporary directory (honoring `TMPDIR` / the platform default), as a string; a `std::filesystem::path` cannot cross the ABI. Raises [`ClikaRT::Error`](../Error.md) if no temporary directory can be resolved.

<div class="api-declared">

Declared in `ClikaRT/io/io.h`, line 386

</div>

### adapt() {#adapt}

<div class="api-signature">

[`TensorsContainer`](./TensorsContainer.md) **`adapt`**([`TensorsContainer`](./TensorsContainer.md) `source`, [`TensorsAdapter`](./TensorsAdapter.md) `adapter`)

</div>

<div class="api-declared">

Declared in `ClikaRT/io/tensors_container.h`, line 349

</div>

### recommended\_load\_policy() {#recommended_load_policy}

<div class="api-signature">

[`LoadPolicy`](./LoadPolicy.md) **`recommended_load_policy`**(`const` [`TensorsContainer`](./TensorsContainer.md)`&` `container`, [`StreamOrDevice`](../StreamOrDevice.md) `device`)

</div>

<div class="api-declared">

Declared in `ClikaRT/io/tensors_container.h`, line 365

</div>

### recommended\_load\_plan() {#recommended_load_plan}

<div class="api-signature">

[`LoadPlan`](./LoadPlan.md) **`recommended_load_plan`**(`const` [`TensorsContainer`](./TensorsContainer.md)`&` `container`, [`StreamOrDevice`](../StreamOrDevice.md) `device`)

</div>

<div class="api-declared">

Declared in `ClikaRT/io/tensors_container.h`, line 385

</div>

## `ClikaRT/io/io.h` {#io-h}

```cpp
#include <ClikaRT/io/io.h>
```

File I/O for tensors and media: the header-only metadata probes (`peek_*`), the weight/checkpoint loaders (safetensors, gguf, npy), the image/audio decoders, and their writers (`encode_image` to PNG and `save_image` to the format the path's extension asks for; `encode_audio` / `save_audio` to 16-bit PCM WAV). Loaders return a `Tensor` (single array) or a `NamedTensors` (a checkpoint's name-to-tensor map). The `target` device places the result; the image/audio decoders produce a host `Tensor` (move it with `.to(...)`).

## `ClikaRT/io/onnx_model.h` {#onnx_model-h}

```cpp
#include <ClikaRT/io/onnx_model.h>
```

`io::OnnxModel`: an ONNX model as a FORMAT-LEVEL object: open an existing `.onnx` file, create one from scratch or build one from a graph, inspect and edit it (inputs, outputs, initializers, nodes), save it back, and, when you want to run it, `compile` it into an executable `ClikaRT::ModelGraph`.

The split is deliberate: `OnnxModel` is the REPRESENTATION (the ONNX graph as data; no inference happens here); `graph::ModelGraph` is the EXECUTION form. `compile` crosses from the model to the graph, and `from_graph` crosses back.

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

## `ClikaRT/io/tensors_container.h` {#tensors_container-h}

```cpp
#include <ClikaRT/io/tensors_container.h>
```

Lazy checkpoint access: a `TensorsContainer` is what the policy-taking checkpoint loaders return. Construction parses HEADERS only, walking a large checkpoint's names, shapes, and byte sizes costs no payload IO; a tensor materializes on `get(name)` (zero-copy from the file mapping on CPU; uploaded on a device target). Evicted tensors restore transparently from the checkpoint on their next use, so a model's weights can be streamed rather than held resident.

## `ClikaRT/io/video.h` {#video-h}

```cpp
#include <ClikaRT/io/video.h>
```

Lazy video decode / encode: a torchcodec-shaped `VideoReader` (open → metadata → index/timestamp frame access → iterable batches) and a `VideoWriter`. The one-shot `load_video` / `peek_video` / `video_capability` live on the umbrella [`ClikaRT/io/io.h`](./index.md#io-h); reach for `VideoReader` when a clip is large or you want per-index / batched access.

Frames are host `[K, H, W, 3]` UInt8 (channels-last RGB); move to a device with `.to(...)`. Every returned `FrameBatch` carries the source `indices` + per-frame `pts_seconds`, which a video model needs upstream to align frames (grid, timestamp tokens). The decode backend is first-party per OS (an `ffmpeg` subprocess on Linux); `io::video_capability()` reports availability.