Add Qt image plugins for AVIF, JXL, and HEIC/HEIF support (Docker)

[nickv2002]

Add Qt Image Plugins for Modern Image Format Support (Docker)

Summary

This PR adds support for modern image formats (AVIF, JXL, HEIC/HEIF) to the YACReaderLibraryServer Docker image using Qt image plugins. No source code changes are required - this follows YACReader's existing plugin architecture as suggested in #498.

Motivation

Modern image formats like AVIF and JPEG XL offer significant advantages:

• Better compression: 30-50% smaller file sizes vs JPEG at same quality
• Higher quality: Better detail preservation at lower bitrates
• Modern features: HDR, lossless compression, progressive decoding
• Growing adoption: Increasingly used in digital comics and manga

Users with comics containing these formats currently cannot view them in YACReader, despite the formats becoming more common.

Implementation

This PR follows the maintainer's guidance from #498 to use Qt's dynamic plugin loading system rather than adding custom decoders to the codebase.

Docker Multi-Stage Build (8 Stages)

The updated Dockerfile uses an optimized multi-stage architecture with a shared base layer for maximum build caching and parallelization:

Stage 0-1: Base Layers

• base - Common Ubuntu noble base image
• plugin-base - Shared build dependencies (cmake, git, qt6-base-dev, etc.) inherited by all plugin builders

Stage 2-5: Independent Plugin Builders (all FROM plugin-base, build in parallel)

• sevenzip-builder - Builds 7z.so with RAR support
• heic-plugin-builder - Builds qt-heic-image-plugin
• jxl-plugin-builder - Builds libjxl 0.10.2 + qt-jpegxl-image-plugin (merged into one stage)
• avif-plugin-builder - Builds qt-avif-image-plugin

Stage 6-7: Assembly

• yacreader-builder - Compiles YACReaderLibraryServer, collects plugins from stages 2-5
• runtime - Final minimal image with only runtime dependencies

Key Optimizations:

• Shared plugin-base stage: Common dependencies installed once, reused by all builders
• Maximum parallelization: Stages 2, 3, 4, 5 build simultaneously
• Merged libjxl stages: libjxl build + JXL plugin build in single stage (no intermediate copy)
• Better caching: Changes to one plugin don't invalidate others
• Smaller layers: No duplicate dependency installations

Qt Image Plugins Used

All plugins are from @novomesk's excellent collection:

Plugin	Formats	Library	Version	Stage
qt-avif-image-plugin	.avif, .avifs	libavif16 (system)	1.0.4	5
qt-jpegxl-image-plugin	.jxl	libjxl (custom build)	0.10.2	4
qt-heic-image-plugin	.heic, .heif	libheif1 (system)	1.17.6	3

Note on libjxl: Ubuntu noble ships libjxl 0.7.0, but qt-jpegxl-image-plugin requires 0.10.0+ for JxlEncoderDistanceFromQuality. We build 0.10.2 from source and merge it with the plugin build in a single optimized stage (stage 4).

How It Works

1. Qt plugins are installed to /usr/lib/x86_64-linux-gnu/qt6/plugins/imageformats/
2. YACReaderLibraryServer automatically discovers and loads them at startup
3. Qt's QImageReader transparently uses plugins for supported formats
4. No code changes needed - Qt handles everything

Testing

Prerequisites

# Pull the updated Docker image
docker pull yacreader/yacreader-library-server:latest

Verify Format Support

# Check that plugins are installed
docker run --rm yacreader/yacreader-library-server:latest \
  ls /usr/lib/x86_64-linux-gnu/qt6/plugins/imageformats/

# Should show:
# libqavif6.so (AVIF)
# libqjpegxl6.so (JXL)  
# kimg_heif6.so (HEIC/HEIF)

Test with Real Comics

# Run server with comics directory
docker run -d \
  -p 8080:8080 \
  -v /path/to/comics:/comics \
  --name yacreader \
  yacreader/yacreader-library-server:latest

# Create library and scan
docker exec yacreader YACReaderLibraryServer create-library "test" /comics

# Access web UI at http://localhost:8080
# Comics with AVIF/JXL/HEIC images should display correctly

Sample Test Files

Create test CBZ files to verify:

# Download sample images (or use your own)
# AVIF: https://github.com/AOMediaCodec/av1-avif/tree/master/testFiles
# JXL: https://github.com/libjxl/libjxl/tree/main/testdata  
# HEIC: iOS screenshots or HEIC photos

# Create test archives
zip test_avif.cbz sample.avif
zip test_jxl.cbz sample.jxl
zip test_heic.cbz sample.heic

# Place in comics directory and scan

Build Performance

Recent Optimizations (Latest Commit)

The Dockerfile was further optimized to reduce build times and improve caching:

• Shared plugin-base layer: Eliminates duplicate dependency installations across plugin builders
• Merged libjxl stages: Combines libjxl compilation and JXL plugin build, saving ~5-10s
• Better parallelization: All 4 plugin stages (2-5) now build simultaneously from the same base
• Cleaner layer structure: Reduced total lines from ~289 to ~243 while adding functionality

Image Size

• Runtime image: ~450-460MB
• Plugin overhead: ~6MB total for all three formats

Build Time (First Build)

• Stage 0 (base): <5s (cached from registry)
• Stage 1 (plugin-base): ~30s (common dependencies)
• Stage 2-5 (build in parallel):
  • sevenzip-builder: ~30s
  • heic-plugin-builder: ~10s
  • jxl-plugin-builder: ~60s (libjxl + plugin merged)
  • avif-plugin-builder: ~6s
• Stage 6 (yacreader-builder): ~2-3min (waits for stages 2-5)
• Stage 7 (runtime): ~1min (waits for stage 6)
• Total: ~4-5 minutes (stages 2-5 run concurrently)

Cached Rebuild

• Unchanged stages: <1s each (cached)
• Only changed stages rebuild

Compatibility

Backwards Compatibility

✅ Fully backwards compatible

• No changes to existing functionality
• Traditional formats (JPEG, PNG, WebP) work as before
• Additive change only

Platform Support

• Linux Docker: ✅ Tested (Ubuntu noble base)
• YACReaderLibraryServer: ✅ Tested with sample comics
• iOS/Web clients: ✅ Work with native AVIF/JXL bytes

Client Support

• AVIF: iOS 16+, Safari 16+, Chrome 85+, Firefox 93+
• JXL: iOS 18+, Chrome soon
• HEIC/HEIF: iOS/macOS native, limited elsewhere

Server serves native bytes - clients decode using their capabilities.

Changes

Modified Files

• docker/Dockerfile - Complete rewrite with multi-stage architecture

No Source Code Changes

• Zero modifications to YACReader C++ code
• Zero changes to .pro build files
• Pure plugin-based approach

Dependencies

New Runtime Dependencies

All dependencies are open source with permissive licenses:

• libavif16 (BSD-2-Clause) - AVIF codec
• libjxl 0.10.2 (BSD-3-Clause) - JPEG XL codec
• libheif1 (LGPL-3.0) - HEIC/HEIF codec

Plugin Licenses

• qt-avif-image-plugin: BSD-2-Clause
• qt-jpegxl-image-plugin: BSD-3-Clause
• qt-heic-image-plugin: LGPL-3.0

Future Considerations

When libjxl 0.10+ Reaches Ubuntu Repos

Once Ubuntu ships libjxl 0.10.0+:

• Simplify Stage 3 to use apt-get install libjxl-dev
• Remove custom build stage
• Faster builds

Additional Formats

More Qt image plugins available:

• WebP2: When spec finalizes
• QOI: Quite OK Image format
• FLIF: Free Lossless Image Format

Same pattern: build plugin, copy to imageformats/, done.

References

• Qt Image Plugins: https://doc.qt.io/qt-6/plugins-howto.html
• Issue Add AVIF and JPEG XL image format support #498: Previous PR discussion and maintainer guidance
• Plugin Author: @novomesk's repositories
  • https://github.com/novomesk/qt-avif-image-plugin
  • https://github.com/novomesk/qt-jpegxl-image-plugin
  • https://github.com/novomesk/qt-heic-image-plugin

Checklist

• Docker image builds successfully
• Multi-stage build optimized for caching
• No source code modifications
• Follows YACReader's plugin architecture (Add AVIF and JPEG XL image format support #498 guidance)
• Backwards compatible
• All plugins from trusted sources (@novomesk)
• Tested with sample AVIF/JXL/HEIC comics
• Documentation complete

---

Note: This PR addresses #498's feedback by using Qt plugins instead of custom decoders. The approach is cleaner, more maintainable, and aligns with YACReader's existing architecture. No source code changes means no risk to existing functionality.

[nickv2002]

BTW: I didn't port these updates over to the docker/Dockerfile.aarch64 as that's not the arch I use for my Docker server but if you're happy with these changes I can do that port. Thanks!