---
title: "Io"
sidebar_label: "Io"
description: "Kotlin binding reference: Io."
---

<!-- Generated by tools/api_reference/generate_api_docs.py. Do not edit. -->

//[clika-runtime](../../../index.md)/[io.clika.runtime](../index.md)/[Io](index.md)

# Io

[common]\
object [Io](index.md)

Decoding and encoding of images, audio and video, and the NumPy `.npy` entry and exit forms of a tensor.

Images decode from JPEG, PNG, GIF, BMP, TGA, PSD, HDR, PNM and PIC to a host `[H, W, C]` UInt8 tensor, the image as displayed; audio decodes from WAV, FLAC, MP3 and OGG (Vorbis) to a host Float32 waveform; a video decodes through the ffmpeg command the host provides (nothing in the runtime links a decoder), so [videoCapability](videoCapability.md) says whether video decode works on this device. Every failure is a [ClikaRtException](../ClikaRtException/index.md) with its status and code name: a missing file, a format outside the set (`UNSUPPORTED`), damaged data or a file of another kind (`INVALID_ARGUMENT`).

```kotlin
val image = Io.loadImage("/path/photo.jpg")           // [H, W, 3] UInt8
val png = Io.encodeImage(image)                       // a PNG payload
val clip = Io.loadAudio("/path/speech.wav", targetSampleRate = 16000, targetChannels = 1)
```

## Functions

| Name | Summary |
|---|---|
| [encodeAudio](encodeAudio.md) | [common]<br>fun [encodeAudio](encodeAudio.md)(samples: [Tensor](../Tensor/index.md), sampleRate: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)): [ByteArray](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html)<br>Encode a waveform as a 16-bit PCM WAV payload. [samples](encodeAudio.md) is `[frames]` (mono) or `[frames, channels]` interleaved: a float tensor holds values in -1, 1 (a value outside clips), an Int16 tensor is written as is. [sampleRate](encodeAudio.md) is in Hz. [loadAudio](loadAudio.md) reads the payload back with the same layout. |
| [encodeImage](encodeImage.md) | [common]<br>fun [encodeImage](encodeImage.md)(image: [Tensor](../Tensor/index.md)): [ByteArray](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html)<br>Encode a host image tensor as a PNG payload: `[H, W]` or `[H, W, C]` channels-last, UInt8 with 1, 3 or 4 channels, or a UInt16 single channel (16-bit gray). The PNG carries no color profile, so a decoder never changes the pixel values; a class-index mask or a depth map round-trips exactly. |
| [loadAudio](loadAudio.md) | [common]<br>fun [loadAudio](loadAudio.md)(bytes: [ByteArray](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html), targetSampleRate: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) = 0, targetChannels: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) = 0): [AudioData](../AudioData/index.md)<br>Decode an encoded audio payload in memory; the same targets as the file form.<br>[common]<br>fun [loadAudio](loadAudio.md)(path: [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html), targetSampleRate: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) = 0, targetChannels: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) = 0): [AudioData](../AudioData/index.md)<br>Decode an audio file to a host Float32 waveform plus its layout. [targetSampleRate](loadAudio.md) and [targetChannels](loadAudio.md) of 0 keep the file's own values; a non-zero channel count mixes to it (mono is the equal-weight average of the source channels) and a non-zero rate resamples, so [peekAudio](peekAudio.md) with the same targets reports the frame count this returns. |
| [loadImage](loadImage.md) | [common]<br>fun [loadImage](loadImage.md)(bytes: [ByteArray](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html), channels: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) = 0): [Tensor](../Tensor/index.md)<br>Decode an encoded image payload in memory; the same contract as the file form.<br>[common]<br>fun [loadImage](loadImage.md)(path: [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html), channels: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) = 0): [Tensor](../Tensor/index.md)<br>Decode an image file to a host `[H, W, C]` UInt8 tensor. [channels](loadImage.md) of 0 keeps the file's own channel count; 1, 3 or 4 forces gray, RGB or RGBA. An EXIF orientation tag is applied, so the tensor is the image as displayed. Move it to a device with [Tensor.to](../Tensor/to.md). |
| [loadNpy](loadNpy.md) | [common]<br>fun [loadNpy](loadNpy.md)(path: [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html), device: [Device](../Device/index.md)? = null): [Tensor](../Tensor/index.md)<br>Load a NumPy `.npy` array as a tensor on [device](loadNpy.md) (the CPU when null). |
| [loadVideo](loadVideo.md) | [common]<br>fun [loadVideo](loadVideo.md)(bytes: [ByteArray](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html)): [VideoData](../VideoData/index.md)<br>Decode a whole video from encoded bytes in memory.<br>[common]<br>fun [loadVideo](loadVideo.md)(path: [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)): [VideoData](../VideoData/index.md)<br>Decode a whole video file: every frame as `[T, H, W, 3]` UInt8 on the host plus the stream facts. A large clip reads through [VideoReader](../VideoReader/index.md) instead, which decodes the frames it is asked for. |
| [peekAudio](peekAudio.md) | [common]<br>fun [peekAudio](peekAudio.md)(bytes: [ByteArray](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html), targetSampleRate: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) = 0, targetChannels: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) = 0): [AudioInfo](../AudioInfo/index.md)<br>Read an audio header from an encoded payload in memory; the same targets as the file form.<br>[common]<br>fun [peekAudio](peekAudio.md)(path: [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html), targetSampleRate: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) = 0, targetChannels: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) = 0): [AudioInfo](../AudioInfo/index.md)<br>Read an audio header from a file. [targetSampleRate](peekAudio.md) and [targetChannels](peekAudio.md) of 0 report the file's own values; a non-zero value reports the effective figures after the resample or downmix a decode applies. |
| [peekImage](peekImage.md) | [common]<br>fun [peekImage](peekImage.md)(bytes: [ByteArray](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html)): [ImageInfo](../ImageInfo/index.md)<br>Read an image header from an encoded payload in memory.<br>[common]<br>fun [peekImage](peekImage.md)(path: [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)): [ImageInfo](../ImageInfo/index.md)<br>Read an image header from a file: its displayed height, width and channel count. |
| [peekVideo](peekVideo.md) | [common]<br>fun [peekVideo](peekVideo.md)(bytes: [ByteArray](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html)): [VideoInfo](../VideoInfo/index.md)<br>Read a video header from encoded bytes in memory.<br>[common]<br>fun [peekVideo](peekVideo.md)(path: [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)): [VideoInfo](../VideoInfo/index.md)<br>Read a video file's header without decoding a frame. |
| [saveAudio](saveAudio.md) | [common]<br>fun [saveAudio](saveAudio.md)(samples: [Tensor](../Tensor/index.md), sampleRate: [Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html), path: [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html))<br>Write a waveform as a 16-bit PCM WAV file at [path](saveAudio.md); the bytes are exactly [encodeAudio](encodeAudio.md)'s. A name asking for another container (`.mp3`, `.ogg`, `.flac`, ...) is refused (`UNSUPPORTED`) with nothing written. |
| [saveImage](saveImage.md) | [common]<br>fun [saveImage](saveImage.md)(image: [Tensor](../Tensor/index.md), path: [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html))<br>Write an image tensor to [path](saveImage.md) in the format its extension asks for: `.png` (or none), `.jpg` / `.jpeg`, `.bmp` or `.tga`; a 16-bit image writes as PNG only. Another extension is refused (`UNSUPPORTED`) with nothing written. |
| [saveNpy](saveNpy.md) | [common]<br>fun [saveNpy](saveNpy.md)(tensor: [Tensor](../Tensor/index.md), path: [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html))<br>Write a tensor as a `.npy` file at [path](saveNpy.md) (materialized contiguous on the host). A quantized tensor is refused with nothing written: dequantize it first. |
| [temporaryDirectoryPath](temporaryDirectoryPath.md) | [common]<br>fun [temporaryDirectoryPath](temporaryDirectoryPath.md)(): [String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)<br>The system's temporary directory, as the runtime resolves it. |
| [videoCapability](videoCapability.md) | [common]<br>fun [videoCapability](videoCapability.md)(): [Boolean](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)<br>Whether video decode works on this device: the runtime drives the ffmpeg command the host provides and links no decoder, so this is false where none is found. The video entries then fail with a readable [ClikaRtException](../ClikaRtException/index.md). |