--- title: "clika_runtime.io functions" sidebar_label: "Functions" description: "Module-level functions of clika_runtime.io." --- ## `encode_audio` ```python encode_audioencode_audio(samples: clika_runtime._core.Tensor, sample_rate: int) -> bytes ``` encode_audio(samples: clika_runtime._core.Tensor, sample_rate: int) -> bytes encode_audio(samples, sample_rate) -> bytes Encode a waveform as a 16-bit PCM WAV payload; the same accepted shapes and dtypes as save_audio, and save_audio writes exactly these bytes. ## `encode_image` ```python encode_imageencode_image(image: clika_runtime._core.Tensor) -> bytes ``` encode_image(image: clika_runtime._core.Tensor) -> bytes encode_image(image) -> bytes Encode a host image as an untagged PNG payload (IHDR, IDAT and IEND only, so a color-managing decoder never perturbs the values; a class-index mask or a depth map round-trips exactly). `image` is [H, W] or [H, W, C] channels-last: uint8 with 1, 3 or 4 channels, or uint16 single-channel. A strided view or a device tensor is read through the runtime. A quantized tensor raises InvalidArgumentError (dequantize it first). ## `load_audio` ```python load_audioload_audio(path: str, target_sample_rate: int = 0, target_channels: int = 0) -> tuple ``` load_audio(path: str, target_sample_rate: int = 0, target_channels: int = 0) -> tuple load_audio(path, target_sample_rate=0, target_channels=0) -> tuple[Tensor, int, int, int] Decode an audio file (WAV, FLAC, MP3 or OGG Vorbis) to a host Float32 tensor: returns (samples, sample_rate, channels, frames); `samples` is [frames] for mono or [frames, channels] interleaved. A `target_sample_rate` / `target_channels` of 0 keeps the file's native value; a non-zero value resamples / remixes to it. A container outside that set (OGG Opus, M4A/AAC, ...) raises with the file and the container named; damaged data, or a file that is not audio, raises naming what the file holds. ## `load_gguf` ```python load_ggufload_gguf(path: str, device: clika_runtime._core.Device = device(type='cpu')) -> tuple ``` load_gguf(path: str, device: clika_runtime._core.Device = device(type='cpu')) -> tuple load_gguf(path, device='cpu') -> tuple[dict[str, Tensor], str] Load a .gguf checkpoint: returns (tensors as `dict[str, Tensor]`, the file's metadata key/value pairs as JSON text, e.g. `general.architecture`). ## `load_image` ```python load_imageload_image(source: object, channels: int = 0) -> clika_runtime._core.Tensor ``` load_image(source: object, channels: int = 0) -> clika_runtime._core.Tensor load_image(source, channels=0) -> Tensor Decode an image to a host uint8 Tensor of shape [H, W, C] (channels-last), the image as displayed (an EXIF orientation applied, as peek_image reports it). `source` is a path (a str or an os.PathLike) or the encoded image as bytes, a bytearray or a memoryview. `channels` 0 keeps the native count; 1, 3 or 4 force gray, RGB or RGBA. The same formats and refusals as peek_image. Move the tensor with .to(). ## `load_npy` ```python load_npyload_npy(path: str, device: clika_runtime._core.Device = device(type='cpu')) -> clika_runtime._core.Tensor ``` load_npy(path: str, device: clika_runtime._core.Device = device(type='cpu')) -> clika_runtime._core.Tensor load_npy(path, device='cpu') -> Tensor Load a .npy file as one tensor. ## `load_safetensors` ```python load_safetensorsload_safetensors(path: str, device: clika_runtime._core.Device = device(type='cpu')) -> dict ``` load_safetensors(path: str, device: clika_runtime._core.Device = device(type='cpu')) -> dict load_safetensors(path, device='cpu') -> dict[str, Tensor] Load a .safetensors file as a dict of tensors on `device` (unordered; load_safetensors_entries keeps the file's order and its metadata). ## `load_safetensors_entries` ```python load_safetensors_entriesload_safetensors_entries(path: str, device: clika_runtime._core.Device = device(type='cpu')) -> clika_runtime._core.io.SafetensorsEntries ``` load_safetensors_entries(path: str, device: clika_runtime._core.Device = device(type='cpu')) -> clika_runtime._core.io.SafetensorsEntries load_safetensors_entries(path, device='cpu') -> SafetensorsEntries Load a .safetensors file, or a sharded checkpoint through its .index.json, onto `device` in the file's own order: `.entries` lists the (name, tensor) pairs as the header states them (a sharded checkpoint: the index's weight_map order) and `.metadata` the checkpoint-level metadata as (key, value) string pairs in header order (a single file's __metadata__; a sharded checkpoint's index document metadata; a non-string value arrives as its JSON text). ## `load_torch_checkpoint` ```python load_torch_checkpointload_torch_checkpoint(path: str, device: clika_runtime._core.Device = device(type='cpu')) -> dict ``` load_torch_checkpoint(path: str, device: clika_runtime._core.Device = device(type='cpu')) -> dict load_torch_checkpoint(path, device='cpu') -> dict[str, Tensor] Load a torch checkpoint (.pt / .pth / .bin / .ckpt, a saved state dict) as a dict of tensors on `device`. ## `load_video` ```python load_videoload_video(source: object) -> clika_runtime._core.io.VideoData ``` load_video(source: object) -> clika_runtime._core.io.VideoData load_video(source) -> VideoData Decode a whole clip: every frame as one host uint8 Tensor [T, H, W, 3] with its indices and timestamps (VideoData.batch), plus the stream's VideoInfo (VideoData.info). `source` is a path (a str or an os.PathLike) or the encoded clip as bytes, a bytearray or a memoryview (read during the call, not retained). The decode is bounded against a decompression bomb; a long clip is read through VideoReader instead. Raises on a missing or undecodable file, and when no decode backend exists (video_capability() is False). ## `open_gguf` ```python open_ggufopen_gguf(path: str, *, device: object | None = None, sticky: bool = False) -> tuple ``` open_gguf(path: str, *, device: object | None = None, sticky: bool = False) -> tuple open_gguf(path, *, device=None, sticky=False) -> tuple[TensorsContainer, str] Open a .gguf checkpoint as (a container whose entries materialize on first use, the file's metadata as JSON text). ## `open_safetensors` ```python open_safetensorsopen_safetensors(path: str, *, device: object | None = None, sticky: bool = False) -> clika_runtime._core.io.TensorsContainer ``` open_safetensors(path: str, *, device: object | None = None, sticky: bool = False) -> clika_runtime._core.io.TensorsContainer open_safetensors(path, *, device=None, sticky=False) -> TensorsContainer Open a .safetensors file as a container whose entries materialize on first use, on `device` (None = the CPU). ## `open_torch_checkpoint` ```python open_torch_checkpointopen_torch_checkpoint(path: str, *, device: object | None = None, sticky: bool = False) -> clika_runtime._core.io.TensorsContainer ``` open_torch_checkpoint(path: str, *, device: object | None = None, sticky: bool = False) -> clika_runtime._core.io.TensorsContainer open_torch_checkpoint(path, *, device=None, sticky=False) -> TensorsContainer Open a torch checkpoint as a container whose entries materialize on first use, on `device` (None = the CPU). ## `peek_gguf` ```python peek_ggufpeek_gguf(path: str, *, checkpoint_bytes: int = 0) -> tuple ``` peek_gguf(path: str, *, checkpoint_bytes: int = 0) -> tuple peek_gguf(path, *, checkpoint_bytes=0) -> tuple[TensorsContainer, str] Read a .gguf checkpoint's header only: (a container that answers `names()`, `entry(name)` and the byte sizes but reads no tensor data, the file's metadata as JSON text). A tensor read from the container raises InvalidArgumentError. `path` may hold only the first bytes of the checkpoint when `checkpoint_bytes` gives the whole checkpoint's size; a file that ends inside the header raises UnavailableError (read more of the checkpoint and call again). ## `peek_image` ```python peek_imagepeek_image(source: object) -> clika_runtime._core.io.ImageInfo ``` peek_image(source: object) -> clika_runtime._core.io.ImageInfo peek_image(source) -> ImageInfo Read an image's header, decoding no pixel: `source` is a path (a str or an os.PathLike) or the encoded image as bytes, a bytearray or a memoryview (read during the call, not retained). Decodes JPEG, PNG, GIF, BMP, TGA, PSD, HDR, PNM and PIC headers; a missing file raises, a format outside that set (WebP, TIFF, AVIF) raises UnsupportedError, damaged data or a file of another kind raises InvalidArgumentError. ## `peek_video` ```python peek_videopeek_video(source: object) -> clika_runtime._core.io.VideoInfo ``` peek_video(source: object) -> clika_runtime._core.io.VideoInfo peek_video(source) -> VideoInfo Read a video's header, decoding no frame: `source` is a path (a str or an os.PathLike) or the encoded clip as bytes, a bytearray or a memoryview (read during the call, not retained). Raises on a missing or unreadable file, and when no decode backend exists (video_capability() is False). ## `save_audio` ```python save_audiosave_audio(samples: clika_runtime._core.Tensor, sample_rate: int, path: str) -> None ``` save_audio(samples: clika_runtime._core.Tensor, sample_rate: int, path: str) -> None save_audio(samples, sample_rate, path) -> None Write a waveform as a 16-bit PCM WAV file at `path` (created / truncated). `samples` is [frames] (mono) or [frames, channels] interleaved: a float tensor holds values in [-1, 1] (values outside clip); an Int16 tensor is written as is. `sample_rate` is in Hz. The extension is the format request: `.wav` (or none) writes; a name asking for another container (`.mp3`, `.ogg`, ...) raises with nothing written. ## `save_image` ```python save_imagesave_image(image: clika_runtime._core.Tensor, path: object) -> None ``` save_image(image: clika_runtime._core.Tensor, path: object) -> None save_image(image, path) -> None Write an image to `path` (a str or an os.PathLike; created or truncated) in the format its suffix asks for: .png, or no suffix, the PNG encode_image produces; .jpg / .jpeg, .bmp and .tga those formats (8-bit; JPEG drops an alpha plane); a 16-bit image as PNG only. A suffix this writer does not produce (.webp, .gif, .tiff) raises UnsupportedError with nothing written. The same shapes, dtypes and quantized refusal as encode_image. ## `save_npy` ```python save_npysave_npy(tensor: clika_runtime._core.Tensor, path: str) -> None ``` save_npy(tensor: clika_runtime._core.Tensor, path: str) -> None save_npy(tensor, path) -> None Write one tensor to a .npy file. ## `save_safetensors` ```python save_safetensorssave_safetensors(entries: object, path: str, metadata: object | None = None) -> None ``` save_safetensors(entries: object, path: str, metadata: object | None = None) -> None save_safetensors(entries, path, metadata=None) -> None Write tensors to a .safetensors file in the given order: `entries` is a dict (walked in insertion order) or a sequence of (name, tensor) pairs, and the header lists them as passed. `metadata`, a dict or a sequence of (key, value) string pairs, becomes the file's __metadata__ in the given order. A repeated name, or the name __metadata__, is an error and nothing is written. ## `video_capability` ```python video_capabilityvideo_capability() -> bool ``` video_capability() -> bool video_capability() -> bool Whether a video decode and encode backend exists on this host (on Linux, an `ffmpeg` found on PATH). When False, the video calls raise a readable error naming what is missing.