Skip to main content

ClikaRT::io

namespace

Classes​

NameDescription
AdaptComposeN 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).
AdaptDropOne key removed from the adapted key space (consumed, never bound), how a checkpoint's unread extras leave the strict walk's accounting.
AdaptRenameOne 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.
AudioDataA decoded waveform plus its effective layout.
AudioInfoAn 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).
AudioTrackThe 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.
FrameBatchA 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.
GgufCheckpointA GGUF checkpoint opened lazily: the tensors as a TensorsContainer (materialize-on-get) plus the file's metadata key/value pairs as JSON.
GgufModelA loaded GGUF checkpoint: the tensors plus the file's metadata key/value pairs as a JSON object (e.g. metadata.at("general.architecture")).
ImageInfoAn 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.
LoadPlanThe 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.
LoadPolicyHow a policy-taking loader materializes tensors.
OnnxAttrA typed node attribute for add_node: the attribute name plus one of the ONNX attribute kinds: INT, FLOAT, STRING, INTS, or FLOATS.
OnnxModelAn ONNX model, opened from disk or built from scratch. Move-only.
OnnxModelOptionsOptions governing an OnnxModel's editing and serialization behavior; pass to open / create, they hold for the model's lifetime.
OnnxNodeInfoOne 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).
SafetensorsEntriesA 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.
SubsetSpecWhich entries TensorsContainer::subset takes, and under which names the sub-container serves them.
TensorsAdapterThe declarative adaptation adapt applies. Keys no entry references pass through under their own names.
TensorsContainerA 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 (a sub-container from subset shares the cache of the entries it carries). A container from io::peek_gguf holds a header only: the queries (names, entry, size, total_bytes, entry_bytes, contains) answer, and every call that reads tensor data fails with Status::InvalidArgument.
VideoDataA 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.
VideoInfoA 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.
VideoReaderA 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.
VideoWriterEncode 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). A quantized tensor (is_quantized()) is a failure Result (INVALID_ARGUMENT) with nothing written: the array would hold its codes and lose its scale, so dequantize it first (ops::dequantize).

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

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 118

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 122

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. A quantized tensor is a failure Result (INVALID_ARGUMENT): its codes are not pixel values, so dequantize it first (ops::dequantize).

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

deflate_size()​

std::size_t deflate_size(ClikaRT::Span<const std::uint8_t> bytes)

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 (INVALID_ARGUMENT). bytes is not retained.

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

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, and a quantized tensor is refused the same way, with nothing written.

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

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 166

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 170

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), and so is a quantized tensor: its codes are not sample values, so dequantize it first (ops::dequantize). To write a decoded clip back, pass audio.samples with audio.info.sample_rate.

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

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, and a quantized tensor is refused the same way, with nothing written; 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 196

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 201

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). A quantized tensor is refused with INVALID_ARGUMENT and nothing is written; dequantize it first (ops::dequantize).

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

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 212

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 223

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. A quantized tensor is refused with INVALID_ARGUMENT and nothing is written; dequantize it first (ops::dequantize). path is copied. The NamedTensors overload above writes the same file in its map's own order.

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

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 262

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 271

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 277

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 281

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 292

peek_gguf()​

GgufCheckpoint peek_gguf(std::string_view path, std::uint64_t checkpoint_bytes = 0)

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; 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: 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 reports for the same header. path is copied.

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

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 352

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 355

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 369

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 372

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 378

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 386

adapt()​

TensorsContainer adapt(TensorsContainer source, TensorsAdapter adapter)

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

LoadPolicy recommended_load_policy(const TensorsContainer& container, StreamOrDevice device)

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

LoadPlan recommended_load_plan(const TensorsContainer& container, StreamOrDevice device)

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

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