ClikaRT::io

namespace

Classes

Name	Description
AdaptCompose	N source parts produce ONE adapted entry under to, the value view. The parts are CONSUMED (their names leave the adapted key space); to may equal one of the parts (the weight + weight_scale → weight shape).
AdaptDrop	One key removed from the adapted key space (consumed, never bound), how a checkpoint's unread extras leave the strict walk's accounting.
AdaptRename	One key rename: the entry under from appears under to; metadata only (byte range, laziness, and quantization metadata are preserved). 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	A decoded waveform plus its effective layout.
AudioInfo	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 is exactly the count load_audio with the same targets returns (duration in seconds = frames/sample_rate).
AudioTrack	The audio track a clip carries beside its frames: sample_rate in Hz, channels (1 mono, 2 stereo, ...) and the audio codec; an empty codec picks the container's default encoder (AAC in an MP4). Declared at VideoWriter::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	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 they were taken from, and per-frame pts_seconds / duration_seconds. Indexable / iterable: operator[] yields a single-frame view, and begin()/end() iterate single-frame views in order.
GgufCheckpoint	A GGUF checkpoint opened lazily: the tensors as a TensorsContainer (materialize-on-get) plus the file's metadata key/value pairs as JSON.
GgufModel	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	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 returns.
LoadPlan	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	How a policy-taking loader materializes tensors.
OnnxAttr	A typed node attribute for add_node: the attribute name plus one of the ONNX attribute kinds: INT, FLOAT, STRING, INTS, or FLOATS.
OnnxModel	An ONNX model, opened from disk or built from scratch. Move-only.
OnnxModelOptions	Options governing an OnnxModel's editing and serialization behavior; pass to open / create, they hold for the model's lifetime.
OnnxNodeInfo	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	A safetensors checkpoint read in the file's own order: 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 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.
TensorsAdapter	The declarative adaptation adapt applies. Keys no entry references pass through under their own names.
TensorsContainer	A lazily-materializing view of a checkpoint's tensors. Move-only: the container caches each materialized tensor so repeated gets share one storage, and that cache must have a single owner.
VideoData	A decoded clip plus its stream info: the returned FrameBatch carries every frame [T, H, W, 3] UInt8 (host). Guarded against a decompression bomb; a large clip should use VideoReader (ClikaRT/io/video.h) for per-index access. path is copied.
VideoInfo	A video stream's static geometry / timing, read from its header. Named VideoInfo (NOT VideoMetadata, which is the processor's 3-field timing struct) since it is a superset: geometry + codec identity too.
VideoReader	A lazily-opened video. open reads the header only; info() reports the stream metadata; the frames_* getters decode on demand. frames_at is the primitive; a custom sampling policy computes its own indices against info() and calls it. Move-only.
VideoWriter	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 on failure.

Functions

peek_image(string_view)

ImageInfo peek_image(std::string_view path)

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 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 naming the path; a format outside that set (WebP, TIFF, AVIF, ...) → Status::Unsupported naming the file and the format; damaged data, or a file of another family (audio handed to the image reader) → Status::InvalidArgument naming the file and what it holds. path is copied, not retained.

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

peek_image(Span< uint8_t>)

ImageInfo peek_image(ClikaRT::Span<const std::uint8_t> bytes)

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

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

peek_audio(string_view, int, int)

AudioInfo peek_audio(
    std::string_view path,
    int target_sample_rate = 0,
    int target_channels = 0
)

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 with the same targets returns. A missing/unreadable file → a failure Result naming the path; a container outside that set (OGG Opus, MP4/M4A AAC, ...) → Status::Unsupported naming the file and the container; damaged data, or a file of another family (an image handed to the audio reader) → Status::InvalidArgument naming the file and what it holds. path is copied, not retained.

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

peek_audio(Span< uint8_t>, int, int)

AudioInfo peek_audio(
    ClikaRT::Span<const std::uint8_t> bytes,
    int target_sample_rate = 0,
    int target_channels = 0
)

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

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

load_npy()

Tensor load_npy(std::string_view path, Device device = Device::cpu())

Load a NumPy .npy array as a Tensor on device. path is copied.

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

save_npy()

void save_npy(const Tensor& tensor, std::string_view path)

Write tensor as a .npy file at path (materialized contiguous on host).

Declared in ClikaRT/io/io.h, line 105

load_image(string_view, int)

Tensor load_image(std::string_view path, int requested_channels = 0)

Decode an image to a host Tensor [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; a missing, malformed or out-of-range tag reads as upright; an orientation carried only in XMP metadata is not read.

Declared in ClikaRT/io/io.h, line 115

load_image(Span< uint8_t>, int)

Tensor load_image(ClikaRT::Span<const std::uint8_t> bytes, int requested_channels = 0)

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

Declared in ClikaRT/io/io.h, line 119

encode_image()

std::vector<std::uint8_t> encode_image(const Tensor& image)

Encode a host image Tensor 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.

Declared in ClikaRT/io/io.h, line 129

save_image()

void save_image(const Tensor& image, std::string_view path)

Write an image Tensor to path (created / truncated) in the format the extension asks for: .png (or no extension) writes the untagged PNG 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 naming the path and the format, with nothing written. Same accepted shapes/dtypes as encode_image.

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

load_audio(string_view, int, int)

AudioData load_audio(
    std::string_view path,
    int target_sample_rate = 0,
    int target_channels = 0
)

Decode audio to a host Float32 Tensor + 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 (output frames = ceil(frames · L / M) over the gcd-reduced rate pair), so peek_audio with the same targets reports the frame count this returns.

Declared in ClikaRT/io/io.h, line 148

load_audio(Span< uint8_t>, int, int)

AudioData load_audio(
    ClikaRT::Span<const std::uint8_t> bytes,
    int target_sample_rate = 0,
    int target_channels = 0
)

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

Declared in ClikaRT/io/io.h, line 152

encode_audio()

std::vector<std::uint8_t> encode_audio(const Tensor& samples, int sample_rate)

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 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 (INVALID_ARGUMENT). To write a decoded clip back, pass audio.samples with audio.info.sample_rate.

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

save_audio()

void save_audio(
    const Tensor& samples,
    int sample_rate,
    std::string_view path
)

Write a waveform as a 16-bit PCM WAV file at path (created / truncated); the file's bytes are exactly 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 naming the path and the container, with nothing written. Same accepted shapes and dtypes as encode_audio; a file that cannot be opened or written is a failure Result naming the path. path is copied, not retained.

Declared in ClikaRT/io/io.h, line 175

load_safetensors(string_view, Device)

NamedTensors load_safetensors(std::string_view path, Device device = Device::cpu())

Load a safetensors checkpoint (single-file or sharded *.index.json) into a NamedTensors on device. path is copied.

Declared in ClikaRT/io/io.h, line 180

save_safetensors(NamedTensors, string_view)

void save_safetensors(const NamedTensors& tensors, std::string_view path)

Write tensors to a single-file safetensors checkpoint at path (created / truncated).

Declared in ClikaRT/io/io.h, line 183

load_safetensors(string_view, LoadPolicy)

TensorsContainer load_safetensors(std::string_view path, LoadPolicy policy)

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

Declared in ClikaRT/io/io.h, line 189

peek_safetensors_metadata()

json::Json peek_safetensors_metadata(std::string_view path)

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.

Declared in ClikaRT/io/io.h, line 200

save_safetensors(Span< pair<string, Tensor>>, string_view, Span< pair<string, string>>)

void save_safetensors(
    ClikaRT::Span<const std::pair<std::string, Tensor>> entries,
    std::string_view path,
    ClikaRT::Span<const std::pair<std::string, std::string>> metadata = {}
)

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 (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 (INVALID_ARGUMENT) with nothing written. path is copied. The NamedTensors overload above writes the same file in its map's own order.

Declared in ClikaRT/io/io.h, line 229

load_safetensors_entries()

SafetensorsEntries load_safetensors_entries(std::string_view path, Device device = Device::cpu())

Load a safetensors checkpoint (single-file or sharded *.index.json) onto device 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 reports it (a single file's __metadata__, a sharded checkpoint's index "metadata"), as text pairs. load_safetensors is the unordered NamedTensors view of the same file. path is copied.

Declared in ClikaRT/io/io.h, line 238

load_torch_checkpoint(string_view, Device)

NamedTensors load_torch_checkpoint(std::string_view path, Device device = Device::cpu())

Load a torch checkpoint (the modern zip container: pytorch_model.bin single-file or sharded *.bin.index.json) into a NamedTensors on device. 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.

Declared in ClikaRT/io/io.h, line 247

load_torch_checkpoint(string_view, LoadPolicy)

TensorsContainer load_torch_checkpoint(std::string_view path, LoadPolicy policy)

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

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

load_gguf(string_view, Device)

GgufModel load_gguf(std::string_view path, Device device = Device::cpu())

Load a GGUF checkpoint (tensors + metadata) onto device. path is copied.

Declared in ClikaRT/io/io.h, line 257

load_gguf(string_view, LoadPolicy)

GgufCheckpoint load_gguf(std::string_view path, LoadPolicy policy)

Open a GGUF checkpoint as a lazy GgufCheckpoint materializing per policy: the TensorsContainer analog of load_gguf. path is copied.

Declared in ClikaRT/io/io.h, line 268

peek_video(string_view)

VideoInfo peek_video(std::string_view path)

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

Declared in ClikaRT/io/io.h, line 312

peek_video(Span< uint8_t>)

VideoInfo peek_video(ClikaRT::Span<const std::uint8_t> bytes)

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

Declared in ClikaRT/io/io.h, line 315

load_video(string_view)

VideoData load_video(std::string_view path)

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).

Declared in ClikaRT/io/io.h, line 329

load_video(Span< uint8_t>)

VideoData load_video(ClikaRT::Span<const std::uint8_t> bytes)

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

Declared in ClikaRT/io/io.h, line 332

video_capability()

bool video_capability()

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.

Declared in ClikaRT/io/io.h, line 338

temp_directory_path()

std::string temp_directory_path()

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

Declared in ClikaRT/io/io.h, line 346

adapt()

TensorsContainer adapt(TensorsContainer source, TensorsAdapter adapter)

Declared in ClikaRT/io/tensors_container.h, line 278

recommended_load_policy()

LoadPolicy recommended_load_policy(const TensorsContainer& container, StreamOrDevice device)

Declared in ClikaRT/io/tensors_container.h, line 294

recommended_load_plan()

LoadPlan recommended_load_plan(const TensorsContainer& container, StreamOrDevice device)

Declared in ClikaRT/io/tensors_container.h, line 314

ClikaRT/io/io.h

#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

#include <ClikaRT/io/onnx_model.h>

io::OnnxModel: an ONNX model as a FORMAT-LEVEL object: open an existing .onnx file or create one from scratch, 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 is the one crossing between them.

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

ClikaRT/io/tensors_container.h

#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

#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; 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.