# Encoding

> UForm for C

Every encode verb runs the same tower, the modality's entry, the transformer blocks and the final norm, and keeps whichever surfaces the caller names from one forward:

- `embeddings` land one pooled row per item, past the attention pool and the projection head.
- `states` land one row per token each item kept, the surface rerankers and masked heads read.
- `token_vectors` land the token head's unit vectors, `token_width` wide, on the same offsets as the states, for late-interaction reranking.

A `NULL` output skips its surface, naming none is refused with `uform_status_invalid_argument_k`, and a model without a token head refuses `token_vectors` with `uform_status_unsupported_k`.
Every surface lands in the arena as `outputs_scalar`, and an item longer than the model's `context` is truncated and counted in the stats.
One verb per input form takes only the fields that form needs:

- `uform_text_encode` takes UTF-8 texts, a byte per token, since models are tokenizer-free.
- `uform_image_encode` takes JPEG, PNG or WebP files, and `uform_image_encode_pixels` interleaved 8-bit RGB.
- `uform_video_encode` takes MP4 or WebM clips.
- `uform_audio_encode` takes WAV, FLAC, MP3 or Opus files, and `uform_audio_encode_samples` mono samples at a rate.

```c
uform_rows_view_t embeddings = {0};
uform_rows_tape_view_t states = {0};
uform_text_encode(&(uform_text_encode_t){
    .model = model, .executor = executor, .outcome = &outcome, .count = n,
    .texts = {bytes, offsets, uform_scalar_u8_k}, .embeddings = &embeddings, .states = &states,
    .arena = arena, .outputs_scalar = uform_scalar_bf16_k});
```

`#include <uform/types.h>`

`#include <uform/encode.h>`

## uform_bytes_view_t

A borrowed run of bytes and its length, never null-terminated by contract - the shape every path, checkpoint buffer and name arrives in.

```c
struct uform_bytes_view_t
```

- `data` `uint8_t const *`: First byte of the run.
- `length` `size_t`: Bytes the run spans, with no terminator assumed or written.

## uform_scalar_t

Scalar types a model computes in and its outputs land as, numbered as USearch's `usearch_scalar_t`, so a run of embeddings is a run USearch indexes without conversion.

```c
enum uform_scalar_t
```

Sub-byte types pack several dimensions per byte, as their `xN` suffixes spell.

- `uform_scalar_unknown_k` = `0`: No scalar named - an unset field, refused rather than written at the wrong width.
- `uform_scalar_f64_k` = `1`: IEEE-754 binary64.
- `uform_scalar_f32_k` = `2`: IEEE-754 binary32.
- `uform_scalar_bf16_k` = `3`: Truncated f32 with an 8-bit exponent and a 7-bit mantissa.
- `uform_scalar_f16_k` = `4`: IEEE-754 binary16.
- `uform_scalar_e5m2_k` = `5`: FP8 with a 5-bit exponent: ±57344, with infinities and NaNs.
- `uform_scalar_e4m3_k` = `6`: FP8 with a 4-bit exponent: ±448, no infinities, and two NaN codes.
- `uform_scalar_e3m2_k` = `7`: FP6 with a 3-bit exponent, byte-aligned with two padding bits.
- `uform_scalar_e2m3_k` = `8`: FP6 with a 2-bit exponent, byte-aligned with two padding bits.
- `uform_scalar_i8_k` = `10`: 8-bit signed integer.
- `uform_scalar_i4x2_k` = `11`: Two signed nibbles per byte, even dimensions in the low nibble.
- `uform_scalar_i32_k` = `12`: 32-bit signed integer.
- `uform_scalar_u8_k` = `20`: 8-bit unsigned integer - the element of UTF-8 text and of encoded files.
- `uform_scalar_u4x2_k` = `21`: Two unsigned nibbles per byte, even dimensions in the low nibble.
- `uform_scalar_u1x8_k` = `22`: Eight single-bit dimensions per byte, the sign of each embedding dimension - the form USearch's Hamming and Jaccard metrics score.

Spellings: ```
char const * uform_scalar_name(uform_scalar_t scalar);
```

```
uform_scalar_t uform_scalar_from_name(uform_bytes_view_t name);
```

## uform_rows_view_t

A run of rows along a call's batch axis - written packed into an arena as an output, one row per item, field for field USearch's `usearch_rows_view_t`, so pooled embeddings feed an index as they are.

```c
struct uform_rows_view_t
```

The call writes one row's bytes as `stride`, and `columns` and `scalar` as it wrote them.

- `data` `void const *`: Base pointer of the first row.
- `stride` `size_t`: Bytes between the starts of consecutive rows.
- `columns` `size_t`: Values per row, the model's embedding `dimensions`.
- `scalar` `uform_scalar_t`: The scalar type the rows hold.

## uform_tape_view_t

A borrowed ragged batch as Apache Arrow lays one out: elements end to end, and `count` + 1 offsets around them.

```c
struct uform_tape_view_t
```

Entry `i` spans elements `offsets`[i] up to `offsets`[i+1]. What an element is belongs to the verb: a byte of an encoded file or of UTF-8 text, a byte of an RGB pixel row, a sample of a recording. The data may live on the executor's device or in host memory; the offsets always live in host memory, since they drive host-side dispatch.

- `data` `void const *`: First element of the tape, which every offset counts from.
- `offsets` `size_t const *`: The call's `count` + 1 non-decreasing offsets, in elements.
- `scalar` `uform_scalar_t`: The scalar type the elements hold: `u8` for text and encoded files, `f32` for decoded samples.

## uform_rows_tape_view_t

A ragged run of rows a call wrote into its arena, for outputs with as many rows per item as the item had tokens left after truncation: rows end to end, and one more offset than items.

```c
struct uform_rows_tape_view_t
```

Item `i` spans rows `offsets`[i] up to `offsets`[i+1], so the last offset is the total.

- `rows` `uform_rows_view_t`: Every item's rows, end to end, packed.
- `offsets` `size_t const *`: The call's `count` + 1 non-decreasing offsets into `rows`, in rows.

## uform_text_encode_stats_t

What a text call reports beside its outputs.

```c
struct uform_text_encode_stats_t
```

- `truncated` `size_t`: Items cut at the model's `context`.
- `tokens` `size_t`: Tokens the call encoded, after truncation.

## uform_image_encode_stats_t

What an image call reports beside its outputs.

```c
struct uform_image_encode_stats_t
```

- `truncated` `size_t`: Items whose patch grid was cut at the model's `context`.
- `tokens` `size_t`: Patches the call encoded, after truncation.

## uform_video_encode_stats_t

What a video call reports beside its outputs.

```c
struct uform_video_encode_stats_t
```

- `truncated` `size_t`: Items cut at the model's `context` in tubes.
- `tokens` `size_t`: Tubes the call encoded, after truncation.

## uform_audio_encode_stats_t

What an audio call reports beside its outputs.

```c
struct uform_audio_encode_stats_t
```

- `truncated` `size_t`: Items cut at the model's `context` in frames.
- `tokens` `size_t`: Frames the call encoded, after truncation.

## uform_text_encode

Encodes `count` texts through one forward, keeping the surfaces the caller names.

```c
void uform_text_encode(uform_text_encode_t *arguments);
```

- `model`: The model to encode with.
- `executor`: The executor the call runs on; it must share the model's residency.
- `outcome`: Output for the outcome, final once its status leaves [`uform_status_deferred_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_deferred_k).
- `completion`: Whether the call blocks or returns once queued; zero blocks.
- `count`: Items in `texts`, and the batch axis of every output.
- `texts`: UTF-8 texts, one item per entry, in bytes.
- `embeddings`: The __optional__ output for one pooled embedding of the model's `dimensions` per item, inside `arena`; `NULL` skips the pool and the head.
- `states`: The __optional__ output for the final-norm states, one row of the model's `dimensions` per token left after truncation, inside `arena`; `NULL` skips them.
- `token_vectors`: The __optional__ output for the token head's unit vectors, one row of the model's `token_width` per token left after truncation, the prefix included, inside `arena`; a model without a token head reports [`uform_status_unsupported_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_unsupported_k).
- `arena`: Memory for every output, rewound by the call.
- `outputs_scalar`: The scalar type every output lands as.
- `progress`: The __optional__ handler, called with items encoded.
- `stats`: The __optional__ report; `NULL` skips it.

## uform_image_encode

Decodes and encodes `count` image files; an undecodable file fails the call with [`uform_status_malformed_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_malformed_k).

```c
void uform_image_encode(uform_image_encode_t *arguments);
```

- `model`: The model to encode with.
- `executor`: The executor the call runs on; it must share the model's residency.
- `outcome`: Output for the outcome, final once its status leaves [`uform_status_deferred_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_deferred_k).
- `completion`: Whether the call blocks or returns once queued; zero blocks.
- `count`: Items in `images`, and the batch axis of every output.
- `images`: JPEG, PNG or WebP files, one item per entry, in bytes.
- `embeddings`: The __optional__ output for one pooled embedding per item, inside `arena`.
- `states`: The __optional__ output for the final-norm states, one row per patch, inside `arena`.
- `token_vectors`: The __optional__ output for the token head's unit vectors, one row per patch, inside `arena`.
- `arena`: Memory for every output, rewound by the call.
- `outputs_scalar`: The scalar type every output lands as.
- `progress`: The __optional__ handler, called with items encoded.
- `stats`: The __optional__ report; `NULL` skips it.

## uform_image_encode_pixels

Encodes `count` decoded images, resizing on the executor's side; a tape entry whose length isn't `heights`[i] × `widths`[i] × 3 fails with [`uform_status_shape_mismatch_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_shape_mismatch_k).

```c
void uform_image_encode_pixels(uform_image_encode_pixels_t *arguments);
```

- `model`: The model to encode with.
- `executor`: The executor the call runs on; it must share the model's residency.
- `outcome`: Output for the outcome, final once its status leaves [`uform_status_deferred_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_deferred_k).
- `completion`: Whether the call blocks or returns once queued; zero blocks.
- `count`: Items in `pixels`, and the batch axis of every output.
- `pixels`: Interleaved 8-bit RGB, one item per entry, in bytes: item `i` holds `heights`[i] rows of `widths`[i] pixels, three bytes each, rows end to end.
- `heights`: Rows of each item, `count` of them in host memory.
- `widths`: Pixels per row of each item, `count` of them in host memory.
- `embeddings`: The __optional__ output for one pooled embedding per item, inside `arena`.
- `states`: The __optional__ output for the final-norm states, one row per patch, inside `arena`.
- `token_vectors`: The __optional__ output for the token head's unit vectors, one row per patch, inside `arena`.
- `arena`: Memory for every output, rewound by the call.
- `outputs_scalar`: The scalar type every output lands as.
- `progress`: The __optional__ handler, called with items encoded.
- `stats`: The __optional__ report; `NULL` skips it.

## uform_video_encode

Decodes and encodes `count` clips.

```c
void uform_video_encode(uform_video_encode_t *arguments);
```

- `model`: The model to encode with.
- `executor`: The executor the call runs on; it must share the model's residency.
- `outcome`: Output for the outcome, final once its status leaves [`uform_status_deferred_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_deferred_k).
- `completion`: Whether the call blocks or returns once queued; zero blocks.
- `count`: Items in `videos`, and the batch axis of every output.
- `videos`: MP4 or WebM files, one item per entry, in bytes, demuxed on the host and decoded by NVDEC.
- `embeddings`: The __optional__ output for one pooled embedding per item, inside `arena`.
- `states`: The __optional__ output for the final-norm states, one row per tube, inside `arena`.
- `token_vectors`: The __optional__ output for the token head's unit vectors, one row per tube, inside `arena`.
- `arena`: Memory for every output, rewound by the call.
- `outputs_scalar`: The scalar type every output lands as.
- `progress`: The __optional__ handler, called with items encoded.
- `stats`: The __optional__ report; `NULL` skips it.

## uform_audio_encode

Decodes and encodes `count` recordings.

```c
void uform_audio_encode(uform_audio_encode_t *arguments);
```

- `model`: The model to encode with.
- `executor`: The executor the call runs on; it must share the model's residency.
- `outcome`: Output for the outcome, final once its status leaves [`uform_status_deferred_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_deferred_k).
- `completion`: Whether the call blocks or returns once queued; zero blocks.
- `count`: Items in `recordings`, and the batch axis of every output.
- `recordings`: WAV, FLAC, MP3 or Opus files, one item per entry, in bytes, decoded and resampled to mono on the host.
- `embeddings`: The __optional__ output for one pooled embedding per item, inside `arena`.
- `states`: The __optional__ output for the final-norm states, one row per frame, inside `arena`.
- `token_vectors`: The __optional__ output for the token head's unit vectors, one row per frame, inside `arena`.
- `arena`: Memory for every output, rewound by the call.
- `outputs_scalar`: The scalar type every output lands as.
- `progress`: The __optional__ handler, called with items encoded.
- `stats`: The __optional__ report; `NULL` skips it.

## uform_audio_encode_samples

Encodes `count` decoded recordings.

```c
void uform_audio_encode_samples(
    uform_audio_encode_samples_t *arguments);
```

- `model`: The model to encode with.
- `executor`: The executor the call runs on; it must share the model's residency.
- `outcome`: Output for the outcome, final once its status leaves [`uform_status_deferred_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_deferred_k).
- `completion`: Whether the call blocks or returns once queued; zero blocks.
- `count`: Items in `samples`, and the batch axis of every output.
- `samples`: Mono samples, one item per entry, in samples, of [`uform_scalar_f32_k`](#uform_scalar_f32_k).
- `sample_rate`: Samples per second shared by every item; resampled to the model's rate where it differs.
- `embeddings`: The __optional__ output for one pooled embedding per item, inside `arena`.
- `states`: The __optional__ output for the final-norm states, one row per frame, inside `arena`.
- `token_vectors`: The __optional__ output for the token head's unit vectors, one row per frame, inside `arena`.
- `arena`: Memory for every output, rewound by the call.
- `outputs_scalar`: The scalar type every output lands as.
- `progress`: The __optional__ handler, called with items encoded.
- `stats`: The __optional__ report; `NULL` skips it.