nanocodec

C API

The nc-capi crate builds nanocodec as a C library: an encoder for H.264, HEVC, AV1 and VP9, and our decoders for the same four. Every function returns an nc_status; nothing is thrown or aborted across the interface. An encoder or decoder is not thread-safe: use one per thread.

Build and link

cargo build --release -p nanocodec-capi
# static: target/release/libnanocodec.a (also needs -lpthread -ldl -lm)
cc -std=c99 -I crates/nc-capi/include app.c target/release/libnanocodec.a -lpthread -ldl -lm -o app
# shared: target/release/libnanocodec.so
cc -std=c99 -I crates/nc-capi/include app.c -L target/release -lnanocodec -lm -o app
LD_LIBRARY_PATH=target/release ./app

The header, crates/nc-capi/include/nanocodec.h, mirrors the Rust definitions in crates/nc-capi/src/ffi.rs; tools/ci/capi_check.sh compiles the examples against it and requires the C API's streams to be byte-identical to the command line's.

Life cycle

  1. nc_encoder_config_default fills a configuration for a codec and size (30 fps, a key frame every 300 frames, fixed quantiser); set target_kbps for rate control, and the resilience fields (temporal_layers, ltr_interval, intra_refresh_period) as needed.
  2. nc_encoder_create, with optional nc_param overrides (the names nanocodec params lists). The C API has no preset argument: a preset's parameters can be passed as nc_param entries.
  3. nc_encoder_encode per frame (I420, YV12 or NV12, any strides). The packet is borrowed until the next call; size 0 means the frame was dropped or held and nothing is sent. The encoder never buffers frames.
  4. Between frames: nc_encoder_request_keyframe, nc_encoder_set_rate, nc_encoder_set_intra_refresh, nc_encoder_set_resolution, and the receiver's feedback, nc_encoder_acknowledge and nc_encoder_report_loss.
  5. On the receiving side, nc_decoder_decode gives each packet one outcome: decoded, or frozen on the last picture with the reason and the frame to report lost.

Minimal encode and decode loop

This program codes a synthetic picture at 300 kbps, decodes every packet and prints the mean luma PSNR. It is crates/nc-capi/examples/roundtrip.c, built and run for all four codecs by tools/ci/capi_check.sh:

Loading…

A file-to-file encoder with the optional start-up lookahead is examples/encode.c.

Loading…