AvifKit

0.3.1indexed

AVIF encoding and decoding with native libavif, adaptive SMART/STRICT compression, automatic JPEG fallback, multi-threaded processing, priority presets, format detection, resizing and metadata preservation.

AndroidNative·alfikri-rizky/AvifKit

Stars

—

Used by

dependents

—

Health

/ 100

This is a Kotlin Multiplatform project targeting Android and iOS, built with Android Gradle Plugin 9.2 (requires Gradle 9.4.1+ and JDK 17+).

/shared — the AvifKit library itself. The cross-platform API lives in commonMain; platform code is in androidMain (Kotlin JNI bindings) and iosMain (Kotlin/Native cinterop straight to libavif's C API — no Swift). Published to Maven Central as io.github.alfikri-rizky:avifkit. Uses the AGP 9 KMP library plugin (com.android.kotlin.multiplatform.library).
/shared-native — the Android native build (libavif/AOM + JNI wrapper), compiled with CMake/NDK. It's a plain com.android.library because the KMP library plugin can't build native code. Published as the companion artifact avifkit-native, which :shared pulls in transitively — so consumers only ever depend on avifkit.
/composeApp — AVIF Studio, the shared Compose Multiplatform UI for the Android and iOS apps. A KMP library module (AGP 9 forbids the KMP plugin alongside com.android.application in one module), producing the ComposeApp framework for iOS. Not published.
/androidApp — the Android application shell: one Activity, a manifest and launcher resources. Everything the user sees comes from :composeApp. Not published.
/iosApp — the iOS application shell: a SwiftUI @main that hosts MainViewController() from the ComposeApp framework. Not published.

AVIF Studio (the app)

A free, offline image converter built on AvifKit — the reference app for the library, and a real app in its own right. No ads, no accounts, no network permission.

Run it with ./gradlew :androidApp:installDebug, or open iosApp/iosApp.xcodeproj in Xcode. Both build the same UI from :composeApp.

Home	Pick a recipe	Converting

Results	Settings	Bahasa Indonesia + dark

Picking a folder once, so Save stops asking:

The same Compose UI on iOS, from the same :composeApp module:

Build and Run Android Application

To build and run the development version of the Android app, use the run configuration from the run widget in your IDE’s toolbar or build it directly from the terminal:

on macOS/Linux
```
./gradlew :androidApp:assembleDebug
```

on Windows

.\gradlew.bat :androidApp:assembleDebug

Build and Run iOS Application

To build and run the development version of the iOS app, use the run configuration from the run widget in your IDE’s toolbar or open the /iosApp directory in Xcode and run it from there.

AvifKit Library

AvifKit is a production-ready Kotlin Multiplatform library for AVIF image encoding and decoding on Android and iOS.

Features

Core Functionality

Advanced Features

Image resizing with dimension constraints
Chroma subsampling options (YUV444, YUV422, YUV420)
Alpha channel quality control
Metadata preservation (optional)
Multiple input types (ByteArray, Bitmap/UIImage, file path)

Architecture

AvifKit uses native AVIF libraries on both platforms with explicit error reporting:

Android: libavif (v1.4.2) + AOM via JNI — pre-built native binaries included in the AAR
iOS: the same libavif + AOM, linked directly into the Kotlin/Native framework via cinterop — the Shared XCFramework is self-contained (no avif.swift, no Swift bridge, no registration step). See docs/IOS_CINTEROP_SOLUTION.md.
Error Handling: clear AvifError exceptions are thrown on failure (no silent fallbacks)

Usage

Basic Conversion

val converter = AvifConverter()

// Convert to AVIF with priority preset
val result = converter.convertToFile(
    input = ImageInput.from("/path/to/image.jpg"),
    outputPath = "/path/to/output.avif",
    priority = Priority.BALANCED
)

Advanced Compression with Target Size

When you need to compress images to meet a specific file size limit, AvifKit offers two compression strategies:

SMART Compression (Recommended)

Finds the highest quality image that still meets your target file size. This is the default and recommended strategy for most use cases.

val options = EncodingOptions(
    maxSize = 200 * 1024, // 200KB target
    compressionStrategy = CompressionStrategy.SMART  // Default
)

val result = converter.convertToFile(
    input = ImageInput.from("/path/to/image.jpg"),
    outputPath = "/path/to/output.avif",
    priority = Priority.BALANCED,
    options = options
)

How it works:

Uses binary search to find optimal quality setting
Typically completes in 6-8 attempts
If target is 200KB, it might produce a 198KB image at quality 85
Faster and produces better-looking results

Best for:

General image compression
User-facing images where quality matters
Web optimization with size constraints
Profile pictures, thumbnails with size limits

STRICT Compression (Maximum Compression)

Finds the smallest possible image by continuing compression even after meeting the target size.

val options = EncodingOptions(
    maxSize = 200 * 1024, // 200KB target
    compressionStrategy = CompressionStrategy.STRICT
)

val result = converter.convertToFile(
    input = ImageInput.from("/path/to/image.jpg"),
    outputPath = "/path/to/output.avif",
    priority = Priority.BALANCED,
    options = options
)

How it works:

Tries multiple compression levels progressively
Continues even after meeting target to maximize compression
May take up to 10 attempts
If target is 200KB, might compress down to 120KB

Best for:

Storage-critical scenarios
Batch processing where smallest size matters
Archival systems
Applications with strict storage quotas

Comparison: SMART vs STRICT

Example with 500KB target:

SMART: Produces 495KB at quality 88
STRICT: Produces 320KB at quality 62

Priority Presets

Priority.SPEED    // Fast encoding, lower quality
Priority.QUALITY  // Best quality, slower encoding
Priority.STORAGE  // Minimum file size
Priority.BALANCED // Good balance (default)

Encoding Options

EncodingOptions(
    quality = 75,                                    // Base quality (0-100)
    speed = 6,                                       // Encoding speed (0-10)
    subsample = ChromaSubsample.YUV420,             // Chroma subsampling
    alphaQuality = 90,                              // Alpha channel quality
    maxDimension = 2048,                            // Auto-resize if larger
    maxSize = 200 * 1024,                           // Target size in bytes
    compressionStrategy = CompressionStrategy.SMART  
)

Installation

AvifKit is published as a Kotlin Multiplatform library with seamless integration for both Android and iOS platforms.

Toolchain: built with Kotlin 2.3.21, so the klibs carry ABI version 2.3.0 — KMP consumers need Kotlin 2.3 or newer. Android bytecode targets Java 11.

Android (Gradle)

Add the dependency to your build.gradle.kts:

dependencies {
    implementation("io.github.alfikri-rizky:avifkit:0.3.2")
}

That's it! The library includes pre-built native binaries for all ABIs (arm64-v8a, armeabi-v7a, x86, x86_64) with full AVIF support via libavif.

iOS (Swift Package Manager) - Recommended ⭐

In Xcode:

File → Add Packages...
Enter repository URL: https://github.com/alfikri-rizky/AvifKit
Select version: 0.3.2 or higher
Important: After adding the package, clean build folder (Cmd+Shift+K) before first build

Or add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/alfikri-rizky/AvifKit", from: "0.3.2")
]

Setup Notes:

✅ SPM downloads a single, self-contained pre-built XCFramework from GitHub Releases (the AVIF codec is linked in via cinterop — no extra dependency, no source compilation)
✅ No registration code needed — import Shared and use AvifConverter() directly
⚠️ First-time setup: the XCFramework may take a moment to download on first resolve
⚠️ Important: Always do a clean build (Product → Clean Build Folder) after adding the package

Usage:

import Shared

let converter = AvifConverter()
print("AVIF available:", converter.isAvifSupported())  // true

Troubleshooting:

Clean caches if resolution misbehaves:

rm -rf ~/Library/Caches/org.swift.swiftpm ~/Library/org.swift.swiftpm
rm -rf ~/Library/Developer/Xcode/DerivedData

In Xcode: File → Packages → Reset Package Caches; Product → Clean Build Folder (Cmd+Shift+K); Build.

Download from GitHub Releases: v0.3.2

iOS (CocoaPods) - Not Recommended ⚠️

CocoaPods support is technically available but not recommended due to validation issues:

pod 'AvifKit', '~> 0.3.2'

Important Notes:

CocoaPods validation may fail due to transitive dependency configuration issues
However, actual usage works fine when users install via pod install since app deployment targets (iOS 15.0+) override pod settings
Our code and XCFramework are fully compatible

Recommended alternatives:

Swift Package Manager (fully supported, recommended)
Direct XCFramework from GitHub Releases

Platform Implementation Details

Android

Native C++ implementation via JNI (shared-native/src/main/cpp/, the :shared-native module)
Pre-built libavif binaries included for all ABIs
EXIF orientation support (preserves portrait/landscape orientation)

Technical Details:

NDK with CMake build system
Conditional compilation support
Optimized with -O3 compiler flags
Symbol stripping for smaller binary size

iOS

Technical Details:

iOS 15.0+ deployment target
libavif v1.4.2 + aom v3.14.1 (encode + decode)
Codec static libs built by scripts/build-ios-libavif.sh; linked via cinterop linkerOpts
XCFramework support for iosArm64 / iosSimulatorArm64 / iosX64

Implementation Status

Known Limitations

Verifying Setup

Check if native AVIF is available:

val converter = AvifConverter()
val isSupported = converter.isAvifSupported() // true on both platforms (codec statically linked)

Testing Fallback Behavior

The library automatically uses fallback when native library is unavailable:

Encoding/Decoding: Throws AvifError.EncodingFailed or AvifError.DecodingFailed with actionable error messages
Swift (iOS): Errors propagate as NSError via @Throws — caught by Swift's

For Library Authors & Contributors

If you want to build the library from source or contribute to development:

Prerequisites

Android: NDK, CMake 3.18.1+
iOS: Xcode (verified on 26.1), CocoaPods or SPM
Both: JDK 17 — what CI builds on. Kotlin comes from the version catalog, so there is nothing to install separately.

Do not pair a new Xcode with an old Kotlin. cinterop is generated from the SDK headers you have installed, while platform.* klibs ship prebuilt inside the Kotlin/Native distribution. If Xcode is newer than the SDK that distribution was built against, cinterop references types those klibs do not contain and commonizeCInterop dies on Unresolved classifier: platform/.... Xcode 26 needs Kotlin 2.2.21 or newer for this reason.

Setup Development Environment

# 1. Clone the repository
git clone https://github.com/alfikri-rizky/AvifKit.git
cd AvifKit

# 2. Run the preparation script (downloads libavif, builds everything)
./scripts/prepare-for-publish.sh

# 3. Build the project
./gradlew :shared:build

Publishing

The library uses a comprehensive publishing setup:

To Maven Central (publishes the library and its native companion — both required):

./gradlew :shared-native:publishToMavenCentral :shared:publishToMavenCentral

To local Maven (for testing):

./gradlew :shared-native:publishToMavenLocal :shared:publishToMavenLocal

To CocoaPods:

pod trunk push AvifKit.podspec

Scripts Reference

scripts/setup-android-libavif.sh - Downloads libavif for Android development
scripts/setup-ios-avif.sh - Sets up iOS dependencies (CocoaPods/SPM)
scripts/prepare-for-publish.sh - Prepares everything for release (runs both setup scripts + builds)
scripts/verify-integration.sh - Verifies the integration is working correctly

Note: End users of your published library don't need these scripts - they're only for development and publishing.

Changelog

Release notes for every version live on the Releases page.

Learn more about Kotlin Multiplatform…

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

SaltAudioTag★ 161

MoriaflyCross-platform audio tag editor in early development, leveraging Compose for UI and kotlinx-io for IO operations, supporting FLAC format metadata reading and writing.Shared: image, fileformat, compose-multiplatform

ParticleEmitter★ 91

PiotrPrusPhysics-driven particle effects with two renderers: layout-based custom particle content and high-performance canvas; directional gravity, edge behaviors (bounce/stick/wrap), blend modes, multi-emitter orchestration.Shared: image, compose-multiplatform, compose

material3-windowsizeclass-multiplatform★ 361

chrisbanesFacilitates responsive UI design by implementing Material 3 window size classes across multiple platforms, ensuring layouts adapt to various screen sizes. Supports Android, iOS, desktop, and web environments.Shared: compose-multiplatform, compose, apple

KScan★ 336

ismai117Enables easy barcode scanning in apps using Google’s MLKit on Android and Apple's AVFoundation on iOS, supporting QR and EAN-13 formats with simple integration.Shared: compose-multiplatform, compose, apple

kubriko★ 249

pandulapeterLightweight 2D game engine enables creation of simple games with modular plugins for scaling, object management, audio, shaders, and physics. Offers tools like Scene Editor and Debug Menu.Shared: compose-multiplatform, compose, apple

krop★ 178

tamimattafiFacilitates image cropping with support for shapes, aspect ratios, transformations, and large images. Offers out-of-the-box or custom UI options and easy integration with image sources.Shared: image, compose-multiplatform, compose

Goal	Best quality within limit	Smallest possible size
Speed	Faster (6-8 attempts)	Slower (up to 10 attempts)
Result Quality	Higher quality	Lower quality
Result Size	Near target size	Well below target
Use Case	General use	Storage-critical

Core Library	✅ Complete	`shared/src/commonMain/`	Cross-platform API
Android Native	✅ Complete	`shared-native/src/main/cpp/`	JNI + libavif (`:shared-native` module)
iOS Native	✅ Complete	`shared/src/iosMain/kotlin/` + `shared/src/nativeInterop/`	cinterop + libavif (no Swift)
Adaptive Compression	✅ Complete	Both platforms	SMART & STRICT strategies
Orientation Support	✅ Complete	Both platforms	EXIF (Android), UIImage (iOS)
Fallback Mode	❌ Removed	Both platforms	Replaced with explicit `AvifError` exceptions
Distribution	✅ Complete	`Package.swift`	SPM support (CocoaPods coming soon)
Build Configuration	✅ Complete	`shared/build.gradle.kts`	Ready for publishing