AvifKit

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 (Swift bridge). 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 — the Android demo app, a plain com.android.application module with Compose Multiplatform UI. Not published.

• /iosApp — the iOS demo app (SwiftUI entry point). Not published.

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 :composeApp:assembleDebug

• on Windows

  .\gradlew.bat :composeApp:assembleDebug

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 is a production-ready Kotlin Multiplatform library for AVIF image encoding and decoding on Android and iOS.

• ✅ AVIF Encoding & Decoding - Full support via libavif + AOM on both platforms (cinterop on iOS, JNI on Android)
• ✅ Android 15+ Compatible - 16 KB page size alignment (Google Play requirement)
• ✅ Adaptive Compression - Intelligent file size targeting with two strategies
• ✅ Priority Presets - Quick configuration for common use cases
• ✅ Multi-threaded Processing - Parallel encoding/decoding with auto-tiling across all CPU cores
• ✅ Format Detection - Automatic image format identification
• ✅ Orientation Support - EXIF orientation handling on Android, UIImage orientation on iOS
• ✅ Auto-Registration (iOS) - Native handler registers automatically via __attribute__((constructor)) — no manual setup needed
• ✅ Swift Error Handling - @Throws annotations propagate errors as NSError to Swift's do/catch
• ✅ Explicit Error Reporting - Clear AvifError exceptions when dependencies are missing (no silent fallbacks)
• ✅ Memory Safety - OutOfMemory error handling

• 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)

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

• Android: libavif (v1.2.1) + 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)

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
)

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

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

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

Example with 500KB target:

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

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

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  // SMART or STRICT
)

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

Pick ONE iOS channel — do not mix.

• KMP / Compose Multiplatform apps → Gradle only. Add the commonMain Gradle dependency below. The iOS AVIF codec (libavif + AOM) is embedded in the Kotlin/Native artifact, so iOS links with no SPM package and no extra setup — exactly like Android. This is the recommended path for shared KMP code.
• Pure SwiftUI / iOS-only apps → SPM (import Shared; see iOS section).
• Never add both Gradle and SPM in the same project. That links two separate copies of the Shared module into two different frameworks with disjoint symbol namespaces, which fails with Undefined symbol: _avif* at link time. If your app uses the shared KMP module via Gradle, remove the SPM AvifKit package reference from the iOS app target.

Add the dependency to your build.gradle.kts:

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

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.

In Xcode:

1. File → Add Packages...
2. Enter repository URL: https://github.com/alfikri-rizky/AvifKit
3. Select version: 0.3.1 or higher
4. 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.1")
]

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:

1. Clean caches if resolution misbehaves:

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

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

Download from GitHub Releases: v0.3.1

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

pod 'AvifKit', '~> 0.3.1'

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:

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

• 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)
• Multi-threaded encoding/decoding with auto-tiling (uses all CPU cores)
• Explicit errors when native library is missing (no silent JPEG fallback)

Technical Details:

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

• Direct libavif binding via Kotlin/Native cinterop (AvifConverter.ios.kt → libavif) — the same C API as Android, no Swift bridge
• libavif v1.2.1 + AOM statically linked into Shared.framework (self-contained XCFramework)
• UIImage ⇄ RGBA via CoreGraphics — orientation handled by drawing through a bitmap context
• No registration step — the codec is always present (isAvifSupported() returns true)
• @Throws annotations — errors propagate as NSError to Swift's do/catch
• Explicit errors on failure (no silent JPEG fallback)

Technical Details:

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

1. Library Size:

   • Including libavif increases app size (~2-3MB per architecture on Android, ~1-2MB on iOS)
   • This is standard for any AVIF library and necessary for native performance
   • Fallback mode available if size is critical

2. No Fallback Mode (v0.2.3+):

   • Library no longer silently falls back to JPEG
   • Missing dependencies throw clear AvifError exceptions
   • Ensures consumers are aware of configuration issues

3. Platform API Differences:

   • Android uses android.graphics.Bitmap
   • iOS uses UIImage
   • Abstracted via PlatformBitmap expect/actual pattern

4. Build Requirements (for library authors only):

   • Android: Requires NDK and CMake to build from source
   • iOS: Requires Xcode and CocoaPods/SPM
   • End users don't need these - they get pre-built binaries

Check if native AVIF is available:

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

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 do/catch
• Android: Errors thrown as standard Kotlin exceptions

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

• Android: NDK, CMake 3.18.1+
• iOS: Xcode, CocoaPods or SPM
• Both: JDK 11+, Kotlin 1.9+

# 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

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/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.

• iOS Maven-channel fix: the v0.3.0 Kotlin/Native artifact shipped the cinterop bindings but not the native codec, so pure-Gradle KMP consumers failed to link with Undefined symbol: _avifEncoderCreate (the codec flags lived in our build, not in the published klib). The static codec libs (libavif.a + libaom.a) are now embedded into the cinterop klib via -staticLibrary, so a Gradle/Maven consumer links cleanly with only the commonMain dependency — no SPM, no manual Xcode setup. See docs/AVIFKIT_FEEDBACK.md.
• Docs: clarified that the Gradle and SPM channels are mutually exclusive per project (mixing them links two Shared modules → undefined symbols).

• iOS architecture rewrite — direct libavif via cinterop. iOS now calls libavif (v1.2.1) + AOM directly from Kotlin/Native through cinterop, exactly like the Android JNI path. This permanently fixes the Compose Multiplatform failure where the Swift-registered handler landed in a different AvifKitIos singleton than the consumer read from (full analysis in docs/IOS_CINTEROP_SOLUTION.md). One framework, one Kotlin runtime, one code path.
• Self-contained XCFramework: the AVIF codec static libs are linked into Shared.framework; no avif.swift dependency, no Swift bridge, no auto-registration.
• ⚠️ Breaking for iOS consumers:
  • Removed the Swift AvifKit product internals (AVIFNativeConverter, AvifKitSetup, AvifKitAutoRegister) and the Kotlin AvifKitIos / IosAvifNativeHandler registry.
  • Remove any AvifKitSetup.registerNativeHandler() call from your app's init().
  • Swift consumers use import Shared and AvifConverter() directly. (The SPM AvifKit product now simply re-vends the self-contained Shared XCFramework.)
• Non-breaking for KMP/Android consumers: add the one Gradle dependency and go — iOS now matches Android.

• iOS Critical Fix (actual): Switched the Kotlin Shared iOS framework from static (isStatic = true) to dynamic (isStatic = false). v0.2.9's Package.swift cleanup was the right direction but not sufficient — SPM still produced two link edges to the static Shared.xcframework (one through the AvifKit Swift target, one through the binary product itself), leaving two copies of the Kotlin runtime in the consumer binary and two AvifKitIos singletons. A dynamic framework is dyld-loaded once per process, so every link edge resolves to the same image and the same singleton.
• Consumer impact: keep import AvifKit (added in v0.2.9). No code changes required.

• iOS Critical Fix: Fixed iOS AVIF encoding/decoding actually failing in production with AvifError.EncodingFailed: Native AVIF handler not available, even after v0.2.7's claimed fix. Root cause was the static Shared.xcframework being linked into the consumer binary along two paths (once as a direct product target, once via the AvifKit Swift target's dependency), which produced two copies of the Kotlin runtime — and therefore two separate AvifKitIos singletons. The Swift bridge registered into one; consumer call sites read from the other; the read always returned null.
• iOS Fix details:
  • Removed "Shared" from the AvifKit library product in Package.swift. Shared is still a .binaryTarget and is still reachable, but only through AvifKit's dependency closure — eliminating the duplicate link path.
  • Added @_exported import Shared in a new AvifKitExports.swift so consumers see all Kotlin types (AvifConverter, EncodingOptions, ImageInput, AvifError, Priority, KotlinByteArray, …) by writing import AvifKit only.
  • Reverted the v0.2.7 .shared → .companion change in AVIFNativeConverter.swift. The original v0.2.7 diagnosis was wrong: top-level Kotlin objects are exposed to Swift as .shared (confirmed in the generated framework header). .companion is only valid for a companion object declared inside a class.
• ⚠️ Breaking change for iOS consumers: replace import Shared with import AvifKit in your Swift sources. No other call-site changes are required — every Kotlin type previously available under Shared is now re-exported through AvifKit.

• iOS: Raised minimum deployment target from iOS 13.0 → iOS 15.0 (and macOS 10.15 → 12.0) consistently across Package.swift, AvifKit.podspec, and the XCFramework linker (build.gradle.kts).
• Build: Downgraded filekit-core 0.14.1 → 0.12.0 and kotlinx-io-core 0.9.0 → 0.8.2 for Kotlin 2.2.x KLIB ABI compatibility (rolled forward from v0.2.7).

• iOS Critical Fix: Fixed handler never registering — changed AvifKitIos.shared → AvifKitIos.companion in AVIFNativeConverter.swift. Kotlin object singletons are exposed to Swift/ObjC as .companion, not .shared. This bug caused 100% iOS AVIF encoding/decoding failure in v0.2.6.

• iOS: Added @OptIn annotations for experimental Kotlin/Native APIs
• iOS: Fixed ObjC interop casts in lazy handler discovery
• iOS: Lazy ObjC runtime discovery of native handler as fallback (in addition to __attribute__((constructor)) auto-registration)

• iOS: Lazy auto-discovery of native handler via ObjC runtime (fallback path)
• SPM: Fixed Swift Package Manager integration issues

• SPM: Separate AvifKitObjC target to satisfy SPM mixed-language constraint (Swift + ObjC cannot be in the same target folder)

• iOS: Auto-registration via __attribute__((constructor)) — consumers no longer need manual AvifKitSetup.registerNativeHandler() calls
• iOS/Android: Added @Throws(Exception::class) to all public methods — errors now propagate as NSError to Swift's do/catch instead of crashing
• iOS/Android: Removed silent JPEG fallback — missing native dependencies now throw explicit AvifError.EncodingFailed / AvifError.DecodingFailed with actionable messages
• iOS: Single source of truth for AVIFNativeConverter.swift — demo app uses symlinks to shared/src/iosMain/swift/
• iOS: Updated demo app SPM dependency from libavif-Xcode to avif.swift

• iOS: Fixed distribution — removed #if canImport conditionals that caused silent JPEG fallback in production

• iOS: Replaced libavif-Xcode (raw C API) with avif.swift — high-level Swift AVIF encoder/decoder
• iOS: Uses pre-built aom encoder + dav1d decoder (no source compilation, faster SPM resolution)
• iOS: Massively simplified AVIFNativeConverter.swift — removed ~250 lines of manual pixel buffer management
• iOS: Simplified orientation handling via normalizeOrientation() before encoding
• CocoaPods: Updated dependency from libavif ~> 0.11 to avif ~> 2.1
• SPM: Updated dependency from SDWebImage/libavif-Xcode to awxkee/avif.swift 2.1.x

• iOS Fix: Fixed libavif not available on production — pinned libavif-Xcode to 0.11.x (1.0.0 had breaking API changes)
• Android Fix: Fixed libaom download failure in CI — pre-clone libaom source to avoid unreliable googlesource tarball endpoint
• Android: Pinned libavif to stable v1.2.1 tag for reproducible builds
• Android: Patched LocalAom.cmake for CMake 3.22 compatibility (NDK default)

• iOS Performance: Enabled auto-tiling for parallel multi-core AVIF encoding (significant speedup)
• iOS Performance: Optimized pixel extraction — fast path skips UIGraphics double-render for .up orientation
• iOS Performance: Smart alpha handling — avoids premultiplication overhead for opaque images (JPEG, etc.)
• iOS: Upgraded libavif-Xcode SPM dependency from 0.11.1 to 1.0.0
• iOS Fix: Fixed EncodingFailed crash when using SPEED preset (speed ≥ 7 triggered incompatible REALTIME mode in libaom)
• iOS Fix: Fixed protocol conformance error in AvifKitNativeHandler (Swift method signature mismatch)
• iOS: Improved error logging with avifResultToString for native encoding failures

• Initial production release with full AVIF encoding/decoding
• Android and iOS native support via libavif
• Adaptive compression strategies (SMART/STRICT)
• Priority presets (SPEED/BALANCED/QUALITY/STORAGE)
• SPM and Maven Central distribution

Learn more about Kotlin Multiplatform…