AvifKit

This is a Kotlin Multiplatform project targeting Android, iOS.

• /composeApp is for code that will be shared across your Compose Multiplatform applications. It contains several subfolders:

  • commonMain is for code that’s common for all targets.
  • Other folders are for Kotlin code that will be compiled for only the platform indicated in the folder name. For example, if you want to use Apple’s CoreCrypto for the iOS part of your Kotlin app, the iosMain folder would be the right place for such calls. Similarly, if you want to edit the Desktop (JVM) specific part, the jvmMain folder is the appropriate location.

• /iosApp contains iOS applications. Even if you’re sharing your UI with Compose Multiplatform, you need this entry point for your iOS app. This is also where you should add SwiftUI code for your project.

• /shared is for the code that will be shared between all targets in the project. The most important subfolder is commonMain. If preferred, you can add code to the platform-specific folders here too.

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 native libavif integration
• ✅ 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
• ✅ Graceful Fallback - JPEG encoding when native library unavailable
• ✅ 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 a two-tier architecture with automatic fallback:

1. Native Mode (Default):

   • Uses libavif for true AVIF encoding/decoding
   • Automatically included when you add the library dependency
   • Production-quality AVIF output with full feature support

2. Fallback Mode (Automatic):

   • Activates automatically if native library fails to load
   • Uses JPEG encoding with equivalent quality settings
   • Ensures your app never crashes due to missing dependencies

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.

Add the dependency to your build.gradle.kts:

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

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.2.0 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.2.0")
]

Setup Notes:

• ✅ SPM automatically downloads the pre-built XCFramework from GitHub Releases
• ✅ Resolves all dependencies including libavif (requires ~500MB disk space for dependencies)
• ✅ Integrates seamlessly with your Xcode project
• ⚠️ First-time setup: The libavif dependency includes AOM codec submodules which can take 5-10 minutes to download
• ⚠️ Important: Always do a clean build (Product → Clean Build Folder) after adding the package to ensure canImport(libavif) evaluates correctly

Troubleshooting:

If you see "⚠️ libavif not available, using JPEG fallback":

1. Ensure sufficient disk space (at least 1GB free for SPM dependencies)

2. Clean all caches:

   # Clear SPM cache
   rm -rf ~/Library/Caches/org.swift.swiftpm
   rm -rf ~/Library/org.swift.swiftpm
   
   # Clear Xcode derived data
   rm -rf ~/Library/Developer/Xcode/DerivedData

3. In Xcode:

   • File → Packages → Reset Package Caches
   • File → Packages → Update to Latest Package Versions
   • Product → Clean Build Folder (Cmd+Shift+K)
   • Product → Build (Cmd+B)

4. Verify libavif is loaded:

   import AvifKit
   
   print("AVIF available:", AVIFNativeConverter.isAvifAvailable)  // Should be true
   print("AVIF version:", AVIFNativeConverter.avifVersion)        // Should be "0.11.1"

Download from GitHub Releases: v0.2.0

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

pod 'AvifKit', '~> 0.2.0'

Important Notes:

• pod spec lint validation fails due to libavif dependency's old iOS deployment targets (8.0-9.0)
• The libavif CocoaPods pod has hardcoded deployment targets that require libarclite, which was removed from Xcode 14+
• However, actual usage works fine when users install via pod install since app deployment targets (iOS 13.0+) override pod settings
• Our code and XCFramework are fully compatible - the issue is external (libavif pod configuration)

Recommended alternatives:

1. Swift Package Manager (fully supported, uses different libavif distribution)
2. Direct XCFramework from GitHub Releases

We cannot fix this without the libavif CocoaPods maintainers updating their pod's deployment targets.

• Native C++ implementation via JNI (shared/src/androidMain/cpp/)
• 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)
• Automatic fallback to JPEG if native library fails to load

Technical Details:

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

• Native Swift implementation (AVIFNativeConverter.swift)
• Conditional compilation using #if canImport(libavif)
• UIImage orientation handling (properly encodes portrait photos)
• Optimized pixel extraction — fast path for .up orientation skips double-render
• Smart alpha handling — uses noneSkipLast for opaque images to skip premultiplication
• Auto-tiling — parallel encoding across all CPU cores
• Automatic fallback to JPEG when libavif unavailable

Technical Details:

• iOS 13.0+ deployment target
• Swift 5.0+
• libavif 0.11.x via SDWebImage/libavif-Xcode SPM (pinned below 1.0.0 for API compatibility)
• Framework-based distribution
• XCFramework support for multiple architectures

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. Decoding on iOS (Fallback Mode):

   • Without libavif: uses standard UIImage(data:) decoding
   • Cannot decode actual AVIF files in fallback mode
   • With libavif (default): full AVIF decoding works

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

// Android: check library version
val version = converter.getLibraryVersion() // Shows libavif version or "Placeholder"

// iOS: check in AVIFNativeConverter.swift
AVIFNativeConverter.isAvifAvailable // true if libavif linked

The library automatically uses fallback when native library is unavailable:

• Encoding: JPEG with equivalent quality settings
• Decoding: Standard image decoder (JPEG, PNG, etc.)
• Logs: Check for "Using JPEG fallback" or "libavif not available" messages

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:

./gradlew :shared:publishAllPublicationsToSonatypeRepository

To local Maven (for testing):

./gradlew :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 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…