HagiCode.Libs.Imaging 0.4.1-dev.132.1

HagiCode.Libs.Imaging

In-process AVIF conversion for .NET hosts. It converts PNG, JPEG, WebP, GIF (first frame) and AVIF sources to still AVIF images using native libvips libraries bundled in the package.

• No ffmpeg, avifenc or other command-line tool is needed, or looked up on PATH.
• The package never starts a child process.
• The native libraries load from the package. No environment variable or library path setting is needed.

Install

dotnet add package HagiCode.Libs.Imaging

Usage

using HagiCode.Libs.Imaging;

// Dependency injection (singleton converter, limits applied from the configure delegate)
services.AddHagiCodeImaging(options =>
{
    options.MaxInputBytes = 64 * 1024 * 1024;
    options.MaxConcurrentConversions = 4;
});

// Buffer to buffer: AVIF bytes are in result.Data
var result = await converter.ConvertAsync(uploadBytes, new AvifConversionOptions
{
    Resize = new AvifResize(AvifResizeMode.Fit, 200, 200),
    Alpha = AvifAlphaMode.Flatten,
    FlattenColor = "#64748b",
});

// Stream to stream: nothing is written to the destination unless the conversion succeeds
await converter.ConvertAsync(sourceStream, destinationStream, options, cancellationToken);

// File to file: written to a temporary file, then moved into place
await converter.ConvertFileAsync("in.png", "out.avif", options, overwrite: true, cancellationToken);

Check the runtime at start-up if you need a health signal:

var status = AvifRuntime.Probe(); // cached; never throws
if (!status.IsAvailable) { /* log status.UnavailableReason and fall back */ }

Options

AvifConversionOptions (per call):

AvifConverterOptions (per converter):

Result

AvifConversionResult reports SourceFormat, SourceWidth and SourceHeight (after orientation, before resize), OutputWidth, OutputHeight, OutputByteLength, HasAlpha, Elapsed and Data (filled only by the buffer overload).

Errors

Every failure is an AvifConversionException with a stable ErrorCode. Branch on the code, not the message.

Cancellation ends as OperationCanceledException, not as an AvifConversionException, and leaves no output behind.

Supported platforms

The Linux build needs the standard C++ runtime (libstdc++) that glibc distributions provide. Other platforms, including linux-musl-x64, linux-arm64 and win-arm64, report NativeRuntimeUnavailable. Signature detection (AvifFormat.IsAvif) keeps working on every platform.

Limits and behavior

• Input and pixel limits protect memory. The pixel check reads the header and does not decode the pixels.
• Loaders are explicit and use failOn: Error, so a truncated file is rejected instead of decoded partially.
• Concurrent encodes are bounded by MaxConcurrentConversions.
• Animated GIF input yields a single still image built from the first frame. Animated AVIF output is not supported.
• A running native encode cannot be interrupted. Cancellation takes effect when the encode returns, and the output is discarded.

Package contents and size

The package carries the four native libraries (about 18 to 20 MB each). A publish for one runtime identifier copies only that platform's library. The nupkg is about 34 MB. It contains README.md, icon.png and THIRD-PARTY-NOTICES.md.

Third-party notices

The bundled native components (libvips, libheif, aom and others) are listed with versions and licenses in THIRD-PARTY-NOTICES.md, packed at the root of this package.

Integration

The backend integration guide, with option mappings from the current ffmpeg-based AVIF path and the thumbnail mapping, is in the monorepo at docs/avif-backend-integration-guide.md.