Skip to main content

edgefirst-codec

JPEG and PNG decoding straight into pre-allocated tensors, JPEG encoding, and hardware H.264 and MJPEG video with tensors as the pictures — no per-frame allocations, zero-copy where the platform allows.

PyPI License

Part of the EdgeFirst HAL

edgefirst-codec is one of five Python packages built from the EdgeFirst Hardware Abstraction Layer.

The EdgeFirstAI/hal repository is the home for all of them — source, issue tracker, architecture documentation and release notes.

Package Provides
edgefirst-tensor Zero-copy tensor allocation and host/GPU/CUDA mapping
edgefirst-codec JPEG and PNG decoding into pre-allocated tensors, JPEG encoding, and H.264 and MJPEG video (this package)
edgefirst-image GPU-accelerated colour conversion, resize, letterbox, tiling and drawing
edgefirst-decoder YOLO and ModelPack output decoding
edgefirst-tracker ByteTrack multi-object tracking

Installation

pip install edgefirst-codec

Requires Python 3.8 or newer; edgefirst-tensor and NumPy are installed automatically. Wheels are published for Linux (x86_64, aarch64), macOS (arm64), and Windows (x86_64), and are self-contained — there is no system JPEG library to install.

Packages install under the PEP 420 edgefirst.* namespace, so the import is edgefirst.codec.

Quick start

For maximum performance, decode straight into a tensor allocated by edgefirst.image's ImageProcessor.create_image() — DMA/PBO-backed and GPU-pitch-aligned — then hand it to ImageProcessor.convert() for colour conversion and resize. decode_file_into / decode_into are free functions rather than Tensor methods precisely so they can take a tensor from another edgefirst.* package:

import numpy as np
from edgefirst.codec import Tensor, decode_file_into
from edgefirst.image import Flip, ImageProcessor, PixelFormat, Rotation

processor = ImageProcessor()

# peek_image_info_file reads the header only — no pixels are decoded.
info = Tensor.peek_image_info_file("frame.jpg")
print(info.width, info.height, info.format)  # e.g. 1280 720 PixelFormat.Nv16

# Allocate once, outside the loop. The decoder reconfigures the tensor's
# dimensions and format within this allocation, so one tensor sized for the
# largest expected frame can receive smaller images without reallocating.
src = processor.create_image(
    info.width, info.height, PixelFormat.Nv12, "uint8", "readwrite"
)
dst = processor.create_image(640, 640, PixelFormat.Rgb, "uint8", "readwrite")

info = decode_file_into(src, "frame.jpg")  # or decode_into(src, jpeg_bytes)
# convert() performs colour conversion (native → RGB) and resize; the codec
# reports EXIF orientation in `info` but does not apply it, so pass it on.
rotation = Rotation.degrees_clockwise(info.rotation_degrees)
flip = Flip.Horizontal if info.flip_horizontal else Flip.NoFlip
processor.convert(src, dst, rotation, flip)

with dst.map() as view:
    data = np.frombuffer(view, dtype=np.uint8)

Same-package pipelines that never leave edgefirst.codec can use the equivalent Tensor.decode_image_file() method instead — tensor.decode_image_file("frame.jpg") — but decode_image_file is a method, and its self must literally be an edgefirst.codec.Tensor; a DMA/PBO-backed destination from edgefirst.image.ImageProcessor.create_image() is a different package's type and can never be that self, so it must go through the free functions decode_into / decode_file_into instead.

Images decode in their native pixel format and are never colour-converted, rotated or resized. A colour JPEG lands on the NV format matching its own chroma sampling (4:2:0 → Nv12, 4:2:2 → Nv16, 4:4:4 → Nv24), greyscale on Grey, and PNG on Rgb / Rgba / Grey. Nothing is resampled on the way out.

EXIF orientation is reported, never applied: info.rotation_degrees and info.flip_horizontal carry the transform your pipeline should apply downstream, and the reported dimensions are unrotated.

Tuning the decode

from edgefirst.codec import DctMethod, PixelFormat, set_dct_method, set_output_format

set_dct_method(DctMethod.Fast)  # faster IDCT, small bounded accuracy cost
set_output_format(PixelFormat.Rgb)  # fused colour conversion inside the decode

Both settings are thread-local — apply them on every thread that decodes. set_output_format fuses colour conversion into the decode's MCU write stage, which is a pure-CPU single-pass path; pass None to restore native output.

PixelFormat and the other value types (TensorMemory, Region, the colour axis enums) are accepted from any edgefirst.* package, not just this one — they compare and hash equal across packages by value, so ==, dict keys and set membership all work regardless of which package's copy you pass. Tensors, Decoder and ProtoData cross packages too, through the capsule protocols. Importing PixelFormat from edgefirst.codec when calling into this package is still good style for readability, not a requirement. See the Interoperability section below for the one thing that does not cross: isinstance against a concrete class.

Encoding JPEG

from edgefirst.codec import ImageEncoder

encoder = ImageEncoder(quality=90)
jpeg = encoder.encode(image)  # bytes; image is a tensor from any edgefirst.* package

The CPU encodes uint8 NV12, NV16, YUYV, GREY, RGB and RGBA images at any row stride; under Engine.Auto a V4L2 JPEG encoder takes the DMA-BUF sources it can read.

Video

H.264 and MJPEG streams are encoded and decoded on the platform's hardware: V4L2 memory-to-memory devices on Linux, Media Foundation on Windows. There is no software video codec, so where no engine runs a codec, opening it raises NoDeviceError or UnsupportedError.

from edgefirst.codec import (
    Codec,
    PixelFormat,
    StreamInfo,
    VideoDecoder,
    VideoEncoder,
    access_units,
)

encoder = VideoEncoder(
    Codec.H264, 1920, 1080, PixelFormat.Nv12, 30.0, bitrate=8_000_000
)
for pts, picture in enumerate(pictures):
    packet = encoder.encode(picture, pts, keyframe=pts == 0)
    if packet is not None:
        out.write(packet.data)
for packet in encoder.flush():
    out.write(packet.data)

decoder = VideoDecoder(Codec.H264)
for pts, unit in enumerate(access_units(stream)):
    for event in decoder.decode(unit, pts):
        if isinstance(event, StreamInfo):
            print(event.width, event.height, event.transfer)
        else:
            use(event)  # a Frame: a Tensor with .pts, read in place

Sources are read in place where the engine can (DMA-BUF on Linux, D3D11 textures on Windows), and encoder.info says how they reach it. A decoded Frame is a Tensor over a buffer of the decoder's pool: pass it to ImageProcessor.convert() or map() it like any tensor. The buffer goes back to the decoder when the frame is no longer referenced, so hold frames only as long as their pictures are needed; a decoder whose every buffer is held raises PoolExhaustedError. VideoDecoder(..., pool=[...]) decodes into the caller's own tensors instead. Feed H.264 as Annex B access units in decode order (access_units() splits a byte stream) and MJPEG as one JPEG picture per call.

Engines and capabilities

Every codec runs on an Engine. Engine.Auto takes the first engine that can do the request; the environment variable EDGEFIRST_CODEC_ENGINE (for example v4l2,cpu) narrows and orders that choice. An engine passed explicitly is used alone. capabilities() lists what this machine's engines do, with each one's device, pixel formats and how pictures move (Transfer.ZeroCopy, GpuCopy, CpuCopy). Probing opens devices, so call it once.

Errors

Codec failures raise CodecError, a RuntimeError, through one subclass per kind: NoDeviceError, UnsupportedError, PoolExhaustedError, CodecTimeoutError, InvalidConfigError, InvalidInputError and InvalidDataError. A CPU access a tensor's declaration does not cover raises PermissionError, as it does across every edgefirst.* package.

What this package provides

API Purpose
Tensor.peek_image_info() / peek_image_info_file() Read dimensions, format and EXIF orientation from the header alone
Tensor.decode_image() / decode_image_file() Decode into a pre-allocated edgefirst.codec.Tensor
decode_into() / decode_file_into() Decode into a tensor from any edgefirst.* package (e.g. edgefirst.image.ImageProcessor.create_image())
ImageInfo Decoded dimensions, native format, row stride, EXIF orientation
set_dct_method() / DctMethod IDCT accuracy/speed selection
set_output_format() Fused Rgb / Nv12 decode output
is_v4l2_available() Whether a V4L2 hardware JPEG decoder is present
ImageEncoder JPEG encoding from a tensor
VideoEncoder / EncodedFrame / EncoderInfo H.264 and MJPEG encoding on hardware
VideoDecoder / Frame / StreamInfo H.264 and MJPEG decoding on hardware into tensor frames
access_units() Split an H.264 Annex B byte stream into access units
capabilities() / Capability / Engine / Codec / Transfer What this machine's codec engines do
CodecError and its subclasses Typed codec failures

Hardware acceleration

On Linux the decoder transparently tries hardware backends before the software path and falls back without any API change:

  • V4L2 mem2mem — SoC JPEG blocks such as the i.MX mxc-jpeg. Discovery is capability-based, with no hardcoded device node. Opt out with EDGEFIRST_DISABLE_V4L2=1.
  • nvJPEG — CUDA GPU decode on NVIDIA platforms such as Jetson Orin. Loaded via dlopen, so there is no link-time CUDA dependency. Opt in with EDGEFIRST_ENABLE_NVJPEG=1.

Footprint

Adding edgefirst-codec to a project costs roughly 1.5 MB of downloads (this package plus edgefirst-tensor), excluding NumPy. That is roughly an order of magnitude smaller than Pillow or OpenCV, and a few times larger than a bare libjpeg-turbo binding — while bundling PNG, EXIF and the hardware backends, with no system libraries to install. See the Rust crate README for the comparison table.

Supported inputs

JPEG decoding covers baseline DCT, 8-bit precision, 1 or 3 components. Progressive, lossless, hierarchical and arithmetic-coded JPEG, CMYK/YCCK and non-8-bit precision are rejected with a typed error rather than mis-decoded. PNG goes through zune-png and supports 8-bit and 16-bit Luma / LumaA / RGB / RGBA. The Rust crate README documents the full matrix.

Interoperability

decode_into / decode_file_into accept a tensor from any edgefirst.* package because each extension module registers its own Tensor type object (a known PyO3 limitation — isinstance across packages is always False, even for two objects wrapping the same Rust type). Acceptance goes through the __edgefirst_tensor__ capsule protocol every Tensor implements:

# Correct — works regardless of which edgefirst.* package produced obj
if hasattr(obj, "__edgefirst_tensor__"):
    ...

# Wrong — always False for a tensor from a sibling package
if isinstance(obj, edgefirst.image.Tensor):
    ...

edgefirst.tensor.EdgeFirstTensorExportable (re-exported here as edgefirst.codec.EdgeFirstTensorExportable) is a typing.Protocol you can annotate a cross-package parameter with. See crates/python-common/INTEROP.md for the full protocol.

Versioning and changelog

All four edgefirst-* packages are versioned and released together with the HAL itself, so a given version number refers to the same source tree in every language. Because of that there is no per-package changelog: release notes for every version live in the single CHANGELOG.md in the hal repository, which follows Keep a Changelog and Semantic Versioning.

License

Apache-2.0

Metadata

Release files for edgefirst-codec 0.41.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for edgefirst-codec 0.41.0
File Actions
edgefirst_codec-0.41.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for edgefirst_codec-0.41.0-cp311-abi3-win_amd64.whl
edgefirst_codec-0.41.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.11 abi3 Linux glibc 2.17+ x86-64 Details for edgefirst_codec-0.41.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
edgefirst_codec-0.41.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.11 abi3 Linux glibc 2.17+ ARM64 Details for edgefirst_codec-0.41.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
edgefirst_codec-0.41.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for edgefirst_codec-0.41.0-cp311-abi3-macosx_11_0_arm64.whl
edgefirst_codec-0.41.0-cp38-abi3-win_amd64.whl CPython 3.8 abi3 Windows x86-64 Details for edgefirst_codec-0.41.0-cp38-abi3-win_amd64.whl
edgefirst_codec-0.41.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.8 abi3 Linux glibc 2.17+ x86-64 Details for edgefirst_codec-0.41.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
edgefirst_codec-0.41.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.8 abi3 Linux glibc 2.17+ ARM64 Details for edgefirst_codec-0.41.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
edgefirst_codec-0.41.0-cp38-abi3-macosx_11_0_arm64.whl CPython 3.8 abi3 macOS 11.0+ ARM64 Details for edgefirst_codec-0.41.0-cp38-abi3-macosx_11_0_arm64.whl

Total release size: 7.3 MB

Release files / edgefirst_codec-0.41.0-cp311-abi3-win_amd64.whl

Download URL edgefirst_codec-0.41.0-cp311-abi3-win_amd64.whl
Size 880.1 kB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
f4fc3fca57444acc747890c272fae6fad50c3df70261935406e4dc180b5a8d4b
BLAKE2b-256 checksum
How to use checksums
8c2f9ad2ba976cc7aac57885bb9dab8ab717666ec8b8be85d127707e8fcbd5e7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_codec-0.41.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL edgefirst_codec-0.41.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 969.0 kB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
233ca1cc3f1369faf1db08ffec43e058e1398f9d271e427051f4901e677a5fbd
BLAKE2b-256 checksum
How to use checksums
9103bac43f33aa4faba65e28ce578c7b4c1527249d1805a84f801e14ba043da5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_codec-0.41.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL edgefirst_codec-0.41.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 936.6 kB
Tags CPython 3.11 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
65bd2109a8b660efd6aa7ff9f53fd044f9b3d85204d7f2355c70a11dfb39b924
BLAKE2b-256 checksum
How to use checksums
d3e7ae951e239cd6c9cc9dfc8e02f13ee5160761f0a06bf55d155bd79b6cda58
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_codec-0.41.0-cp311-abi3-macosx_11_0_arm64.whl

Download URL edgefirst_codec-0.41.0-cp311-abi3-macosx_11_0_arm64.whl
Size 846.6 kB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
d1d64b9a5a531c9fa5658a50b86c1b875097c9af50bd972b1655dc84990f0997
BLAKE2b-256 checksum
How to use checksums
0d3fafbaa50bc694663d19cfb5b9778beeb2e094728d5b89a424fa4a7ee14633
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_codec-0.41.0-cp38-abi3-win_amd64.whl

Download URL edgefirst_codec-0.41.0-cp38-abi3-win_amd64.whl
Size 886.6 kB
Tags CPython 3.8 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
5c9632164656ec4bf3d829cb616d4b30d293a00ffc9be60b6d859d0493d6876a
BLAKE2b-256 checksum
How to use checksums
095a05c2896041686f1714dd36e530116a3e2dc55bed36463d7e204da8001a17
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_codec-0.41.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL edgefirst_codec-0.41.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 973.6 kB
Tags CPython 3.8 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
24d4ebaf80b826c8fba913f27865886038dc092dd31ead143ba7cdf680fcaf67
BLAKE2b-256 checksum
How to use checksums
21747ad090c7bd47349a10211f9edf6d79b23e620c6db9290a4dccb0fd48a60a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_codec-0.41.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL edgefirst_codec-0.41.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 941.2 kB
Tags CPython 3.8 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
b5e530662772558c8e8599c1f5a41df033e01a08d2bef4b12d2fc0e3026d85fa
BLAKE2b-256 checksum
How to use checksums
8f4a4c8cdb3e1842e4a129b5a0818e637821f8119f34ac4938f33ede46d2ae18
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_codec-0.41.0-cp38-abi3-macosx_11_0_arm64.whl

Download URL edgefirst_codec-0.41.0-cp38-abi3-macosx_11_0_arm64.whl
Size 850.7 kB
Tags CPython 3.8 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
48fb13eb46360e4276b160eef33cca788317a18e9ba9f80f76bd5dd9f5a4ac9a
BLAKE2b-256 checksum
How to use checksums
aac59e450718f737225282634cb8ce78d38a46522cdbe04e0167dc03ba863adf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for edgefirst-codec 0.41.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 8 files in this release have been uploaded with provenance metadata.

Select from 8 files

Attestation for edgefirst_codec-0.41.0-cp311-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page