Главная Программы Софт для разработки libavif: гайд от гика, кодирование, декодирование AVIF и интеграция в приложения

libavif: гайд от гика, кодирование, декодирование AVIF и интеграция в приложения

libavif — открытая переносимая C-библиотека проекта AOMediaCodec для чтения и записи AVIF, дополненная консольными утилитами avifenc, avifdec и avifgainmaputil. Это не графический редактор, не браузерный конвертер и не системный пакет кодеков: основной сценарий — встроить поддержку AVIF в приложение либо управлять кодированием и декодированием из командной строки. На 4 сентября 2026 года актуальный стабильный выпуск — 1.4.2 от 26 мая 2026 года. Ниже разобраны устройство библиотеки, реальные форматы ввода и вывода, параметры качества и цвета, последовательности изображений, HDR gain map, сборка, безопасность, ограничения и ситуации, в которых удобнее взять более универсальный инструмент.

Что такое libavif и чем библиотека отличается от AVIF и AV1

AVIF — формат изображений, определённый Alliance for Open Media. Он хранит изображения, закодированные AV1, в структуре на базе HEIF/ISO Base Media File Format и допускает не только одиночное изображение, но и последовательности, вспомогательные изображения и связанные свойства. libavif — одна из программных реализаций этого формата: библиотека создаёт и разбирает AVIF-контейнер, управляет изображениями, метаданными и преобразованием цветовых представлений, а собственно AV1-кодирование и декодирование передаёт подключаемым codec backend.

Поэтому название libavif не следует смешивать с AV1-кодеком как таковым. AV1 отвечает за сжатие изображения внутри AVIF, а libavif связывает этот битстрим с правилами AVIF и предоставляет C API. Аналогично, libavif не является набором кодеков Windows: установка библиотеки сама по себе не добавляет универсальный системный интерфейс воспроизведения для всех приложений.

Проект размещён в организации AOMediaCodec/libavif. Исходные файлы используют лицензию BSD-2-Clause; ранний код содержит copyright Joe Drago, дальнейшие части — Google LLC и других участников. Для читателя важнее практическое следствие: это исходный проект и библиотека для разработчиков, а не коммерческий сервис с аккаунтом, тарифами и облачным кабинетом.

Основные параметры libavif

Параметр	Актуальное состояние
Тип продукта	Переносимая C-библиотека и консольные приложения
Проект	AOMediaCodec/libavif
Назначение	Кодирование, декодирование и программная обработка AVIF
Стабильная версия	1.4.2, выпущена 26 мая 2026 года
Лицензия	BSD-2-Clause
Основной API	C; публичные заголовки остаются C99-совместимыми
Требование к компиляции библиотеки 1.4.2	C11
Консольные приложения	avifenc, avifdec, avifgainmaputil при сборке приложений
Ввод avifenc	JPEG, PNG, YUV4MPEG2 (Y4M)
Вывод avifenc	AVIF
Ввод avifdec	AVIF
Вывод avifdec	JPEG, PNG, Y4M
AV1 encoder backend	aom, rav1e, svt — доступность зависит от сборки
AV1 decoder backend	aom, dav1d, libgav1 — доступность зависит от сборки
Облако и аккаунт	Не являются частью libavif; основные операции выполняются локально
Мобильная поставка	Есть Android JNI binding для декодера, но нет пользовательского мобильного приложения
ИИ-функции	В libavif отсутствуют
Цена	Платного тарифа, подписки и пробного режима у проекта нет

Платформы, распространение и текущий статус

libavif рассчитана на переносимую сборку, а официальный README перечисляет готовые пути установки для Windows, macOS и Linux. В Windows библиотека доступна через vcpkg; на странице релизов публикуются официальные готовые Windows-бинарники avifenc.exe и avifdec.exe. В macOS предусмотрены Homebrew и MacPorts. Для Debian-подобных систем указан пакет libavif-dev, для Red Hat-подобных — libavif, а в MSYS2 доступен UCRT64-пакет. Точные версии операционных систем как обязательный минимум проект не фиксирует одной универсальной строкой, поэтому совместимость конкретного пакета определяется его репозиторием и toolchain.

Для Linux установка через пакетный менеджер принципиально отличается от ручной сборки. Если нужна общая база по этому механизму, полезно отдельно посмотреть как устанавливаются приложения в Linux; для libavif при этом нужно выбирать пакет из своего дистрибутива либо собирать исходники с нужными AV1 backend.

Стабильный выпуск 1.4.2 изменил требование к языку компиляции самой библиотеки на C11, сохранив публичные заголовки C99. Это важное различие для встраивания: проект, который включает avif/avif.h, не обязан из-за одного заголовка переписывать весь C-код под C11, но сборка libavif 1.4.2 должна использовать компилятор с поддержкой C11. Когда включаются консольные приложения, CMake также активирует C++ и задаёт C++17 для соответствующей части сборки.

Сборочная система — CMake. Базовая сборка исходников не включает ни один AV1 codec backend автоматически: нужно выбрать хотя бы один из поддерживаемых вариантов. libaom умеет кодировать и декодировать, dav1d и libgav1 используются для декодирования, rav1e и SVT-AV1 — для кодирования. Конкретный набор виден в avifenc —version, avifenc —help и avifdec —version. Это объясняет, почему две сборки одной версии libavif могут предлагать разные значения параметра —codec.

libyuv является необязательной зависимостью, но проект рекомендует её для ускорения преобразований цветовых пространств. Консольные приложения требуют PNG, JPEG и Zlib; сборка приложений через AVIF_BUILD_APPS=ON проверяет эти зависимости. Для разработчика Windows, который собирает проект самостоятельно, отдельный материал про Microsoft Visual Studio C/C++ помогает разобраться с самим toolchain, но параметры CMake и AV1 backend всё равно задаются по документации libavif.

Интерфейс: C API вместо окна программы

У libavif нет главного окна, панели инструментов, меню «Файл» и локализованного графического интерфейса. У продукта два рабочих уровня: программный C API и командная строка. Поэтому понятие интерфейса здесь означает набор структур и функций в avif/avif.h, а для ручных операций — синтаксис avifenc, avifdec и avifgainmaputil. Названия параметров и встроенная справка консольных инструментов используются на английском.

C API

API строится вокруг avifImage, avifEncoder и avifDecoder. avifImage хранит размеры, глубину, YUV-формат, цветовые характеристики, alpha plane, ICC, Exif, XMP и свойства контейнера. avifEncoder управляет качеством, скоростью, потоками, тайлами, последовательностями и выбранным encoder backend. avifDecoder сначала разбирает структуру файла, после чего выдаёт кадры и их YUV/alpha-данные; при необходимости библиотека преобразует их в RGB.

Такое разделение позволяет приложению не зависеть от JPEG или PNG как входного формата. Ограничение JPEG/PNG/Y4M относится к готовому avifenc. Через API разработчик может сформировать avifImage из собственных пиксельных данных, заполнить RGB-буфер, преобразовать его в YUV и передать энкодеру. Аналогично декодер возвращает изображение приложению в памяти, а сохранение в конкретный внешний формат уже может выполнять собственный код программы.

avifenc

avifenc — CLI-оболочка для создания AVIF из JPEG, PNG и Y4M. Базовая команда принимает входное имя и выходной .avif, а параметры регулируют цветовое качество, alpha, скорость, число рабочих потоков, bit depth, subsampling, диапазон, метаданные и свойства изображения. Для сложных контейнеров предусмотрены progressive/layered encoding, image grid и image sequence.

Шкала -q/—qcolor идёт от 0 до 100, где 100 соответствует lossless для цветовых данных; отдельный —qalpha делает то же для альфа-канала. Параметр -s/—speed идёт от 0 до 10: 0 — самый медленный режим, 10 — самый быстрый, а значение по умолчанию у avifenc равно 6. Это относительная настройка энкодера, а не гарантия определённого времени обработки.

-j/—jobs задаёт число worker threads или all; по умолчанию используется all. Этот параметр часто принимают за пакетную обработку, но он управляет параллелизмом одной операции. Для независимого преобразования каталога файлов в отдельные AVIF нужен внешний цикл оболочки, build system, скрипт или CI-задача.

avifdec

avifdec выполняет обратную операцию: читает AVIF и сохраняет JPEG, PNG или Y4M. Помимо вывода пикселей он умеет печатать сведения о контейнере через —info, выбирать decoder backend, управлять потоками и chroma upsampling. Для PNG разрешён выход 8 или 16 бит; JPEG всегда сохраняется как 8-bit output, поэтому JPEG нельзя считать нейтральным контейнером для проверки AVIF с большей глубиной.

Декодер имеет встроенные ограничения на размер входного изображения: total pixel limit по умолчанию 268435456 и dimension limit 32768. Эти предохранители важны при обработке непроверенных файлов. Параметр —no-strict отключает строгую валидацию, поэтому использовать его как постоянное средство «починить любой файл» не стоит: сначала лучше выяснить, почему контейнер не проходит стандартные проверки.

avifgainmaputil

avifgainmaputil предназначен для AVIF с HDR gain map. При сборке приложений он устанавливается вместе с avifenc и avifdec и предоставляет команды combine, convert, tonemap, swapbase, extractgainmap и printmetadata. Gain map связывает базовое изображение с альтернативным отображением для другого HDR headroom; просмотрщик без поддержки gain map показывает base image.

Команда combine строит AVIF с gain map из base image и alternate image. Для gain map можно задать качество 0–100, глубину 8/10/12 бит и YUV 444/422/420/400. Конвертация JPEG с gain map в AVIF зависит от libxml2: сборка без этой зависимости сообщает, что JPEG gain-map conversion недоступна. Это не влияет на обычное кодирование PNG или JPEG без такой карты.

Основные функции и то, как они связаны

Кодирование одиночных изображений

Главная функция libavif — превратить пиксельные данные и связанные свойства в корректный AVIF. В avifenc источником выступают JPEG, PNG или Y4M. Для RGB-источников утилита выбирает YUV-представление: auto старается сохранить внутренний формат JPEG, для grayscale PNG выбирает 400, а для других случаев по умолчанию приходит к 444. Пользователь может явно выбрать 444, 422, 420 или 400.

Bit depth для JPEG/PNG можно задать как 8, 10 или 12. Y4M ведёт себя иначе: глубина и YUV-формат сохраняются из входного потока, поэтому принудительное несовместимое значение не является обычным способом изменить его характеристики. Присутствующий alpha channel кодируется отдельно и имеет собственную настройку качества.

Контроль качества, скорости и размера

libavif не сводит кодирование к одному «проценту качества». avifenc разделяет quality color и quality alpha, предоставляет speed и выбор codec backend, а для точного ограничения объёма есть —target-size в байтах. Документация прямо предупреждает, что режим target-size способен увеличить время кодирования до семи раз, поэтому для регулярной обработки без жёсткой границы файла проще использовать quality-based режим.

Значение speed не следует сравнивать как абсолютный benchmark между aom, rav1e и svt: это управляющий параметр, а доступный backend и его реализация влияют на итог. По этой же причине корректный обзор libavif не приписывает библиотеке универсальную скорость в мегапикселях в секунду без привязки к процессору, backend, версии зависимостей и настройкам.

Цвет, alpha и метаданные

AVIF способен хранить данные глубже привычного 8-bit RGB, а libavif работает с AV1-поддерживаемыми YUV-форматами и bit depth, включая alpha. Для описания цвета доступны CICP/nclx, ICC profile и YUV range. В avifenc JPEG и PNG по умолчанию рассматриваются с full range, а для Y4M range сохраняется из источника.

Exif, XMP и ICC можно взять из исходного файла, игнорировать либо заменить внешним payload. Параметры —exif, —xmp и —icc связывают заданный payload с primary item и одновременно означают, что соответствующее встроенное содержимое входного файла не используется. Это даёт контроль над приватными метаданными, но требует осознанного решения: удаление Exif может убрать дату, ориентационные сведения и данные камеры, а игнорирование ICC меняет способ интерпретации цвета.

—irot и —imir добавляют AVIF transform properties, а —crop рассчитывает clean-aperture property clap по прямоугольнику. Это свойства контейнера, а не обещание физически перерисовать и обрезать исходный bitmap до нового размера. Для программы-потребителя важна поддержка соответствующих AVIF properties.

Progressive, layered, grid и последовательности

—progressive создаёт из одного кадра простой layered AVIF, рассчитанный на progressive rendering. —layered даёт явный контроль: каждый вход кодируется как слой, а максимум составляет четыре слоя. Image grid через —grid MxN хранит изображение как сетку: можно передать M×N одинаковых по размерам/глубине tiles либо одно изображение, которое делится на сетку с соблюдением ограничений AVIF.

Отдельный режим — image sequence. avifenc использует timescale/fps, duration, keyframe interval и repetition count. Если длительность и timescale не заданы, утилита пытается прочитать framerate из Y4M header. Повтор по умолчанию для animated sequence — infinite. Эти функции делают libavif пригодной не только для статичных фотографий, но и для программ, которым нужен один AVIF-контейнер с несколькими кадрами.

Декодирование и анализ контейнера

avifdec может работать как конвертер и как диагностический инструмент. Режим —info декодирует информацию и показывает свойства без необходимости выбирать внешний растровый формат. Для sequence или progressive content параметр —index выбирает изображение по индексу, начиная с нуля. Через C API avifDecoderParse даёт структуру и метаданные до декодирования пикселей, а avifDecoderNextImage последовательно отдаёт кадры.

Преобразование YUV(A) в RGB(A) отделено от разбора контейнера. В API приложение задаёт avifRGBImage, может изменить depth, format и chroma upsampling, затем вызывает avifImageYUVToRGB. Такое устройство удобно в графическом движке: AVIF можно разобрать, проверить характеристики, а реальное преобразование пикселей выполнить только тогда, когда кадр нужен.

HDR gain map

Поддержка gain map в 1.4.x вынесена не только в API, но и в отдельную утилиту. combine формирует карту по паре base/alternate, printmetadata выводит параметры карты, extractgainmap сохраняет саму карту как изображение, tonemap создаёт результат под заданный HDR headroom, а swapbase меняет базовое представление. Для обычного SDR-конвертирования эта часть не нужна, но при разработке HDR-пайплайна она избавляет от самостоятельной реализации контейнерной логики gain map.

Интеграция в собственное приложение

Пример кодирования из репозитория показывает типичный API-поток: создать avifImage, подготовить RGB-представление и пиксели, выполнить avifImageRGBToYUV, создать avifEncoder, задать параметры, добавить изображение и завершить кодирование через avifEncoderFinish. Декодирование симметрично: создать avifDecoder, назначить файл или другой источник IO, вызвать avifDecoderParse, получить кадр через avifDecoderNextImage и при необходимости преобразовать его в RGB.

Именно этот уровень отличает libavif от пользовательского конвертера. Разработчик решает, где хранить байты, как обрабатывать ошибки, чем управлять памятью, какой AV1 backend поставлять и какие метаданные разрешать. libavif предоставляет форматный слой и готовые преобразования, но не создаёт за приложение файловый браузер, очередь задач или медиатеку.

Карта форматов и совместимости

Путь	Что поддерживается	Что сохраняется или меняется	Практическое ограничение
JPEG → avifenc → AVIF	JPEG/JPEG input, AVIF output	Можно управлять quality, YUV, depth, CICP/ICC, Exif/XMP	Lossless AVIF не возвращает исходное JPEG-сжатие как байт-в-байт оригинал
PNG → avifenc → AVIF	PNG input, включая alpha	Цвет и alpha настраиваются отдельно	Выбор YUV subsampling может изменить цветовые детали даже при высоком quality
Y4M → avifenc → AVIF	YUV4MPEG2	YUV format, bit depth и range берутся из Y4M	Не используется как произвольный RGB-конвертер; параметры источника имеют особое значение
AVIF → avifdec → PNG	PNG 8/16-bit output	Подходит для сохранения большей глубины, чем JPEG	PNG уже не хранит AVIF-layering/sequence как тот же контейнер
AVIF → avifdec → JPEG	JPEG 8-bit output	Есть JPEG quality 0–100	8-bit и отсутствие alpha делают путь заведомо потерянным для части AVIF-содержимого
AVIF → avifdec → Y4M	Y4M output	Сохраняется YUV-oriented представление для медиапайплайна	Это технический формат, а не универсальный формат обмена фотографиями
Собственные pixels → C API → AVIF	avifImage и RGB/YUV memory	Приложение само задаёт pixels, color, alpha и metadata	Декодирование исходного WebP/TIFF и других файлов должен выполнить другой компонент
AVIF → C API → собственный формат	Decoded YUV/alpha или RGB buffer	Приложение получает кадры и свойства	Запись конечного TIFF/WebP и других контейнеров не входит в libavif API как файловый exporter

Главная граница совместимости проходит между библиотекой и готовыми CLI-приложениями. libavif как API работает с image buffers и AVIF-структурами; avifenc и avifdec добавляют конкретные JPEG/PNG/Y4M readers/writers. Поэтому отсутствие WebP в синтаксисе avifenc не означает, что AVIF нельзя получить из WebP вообще: сначала WebP должен быть декодирован другим компонентом, после чего пиксели передаются libavif.

Задача → инструмент → результат → что проверить

Задача	Инструмент	Результат	Что проверить
Сжать PNG/JPEG в AVIF	avifenc	Одиночный .avif	Разрешение, bit depth, YUV, alpha, цветовой профиль и визуальные артефакты
Получить растровую копию AVIF	avifdec	PNG, JPEG или Y4M	Не потеряны ли alpha и глубина при выборе JPEG
Проверить структуру AVIF	avifdec —info	Диагностическая информация	Количество кадров, размеры, depth, color properties и transforms
Сделать progressive AVIF	avifenc —progressive	Layered image из одного исходника	Корректность слоёв в целевом декодере
Создать image grid	avifenc —grid	Grid AVIF	Одинаковы ли tiles и соблюдаются ли grid restrictions
Создать image sequence	avifenc с fps/duration/repetition	Многокадровый AVIF	Порядок кадров, timing, keyframe interval и повтор
Сформировать HDR gain map	avifgainmaputil combine	AVIF с base, alternate и gain map	Наличие gain map и её metadata
Встроить AVIF в приложение	C API	Кодирование/декодирование в memory	Lifecycle объектов, ошибки, выбранный codec backend и границы входных данных

Производительность, зависимости и работа без интернета

Производительность libavif определяется не одной библиотекой. На кодирование влияют AV1 encoder backend, его версия, speed, quality, image size, bit depth, YUV format, количество потоков и выбранные режимы. Декодирование аналогично зависит от decoder backend, формата кадра и последующего YUV-to-RGB conversion. Поэтому корректная настройка начинается не с абстрактного обещания «быстрее», а с фиксации backend и параметров, которые можно воспроизвести на целевом оборудовании.

avifenc по умолчанию использует speed 6 и —jobs all. Автоматический tiling включён по умолчанию; ручные —tilerowslog2 и —tilecolslog2 переводят работу в manual tiling. Для проекта с собственными требованиями можно передавать codec-specific advanced options через -a, но это уже связывает конфигурацию с конкретным encoder backend: неизвестные выбранному backend параметры avifenc не должен молча считать универсальными.

Операция —target-size отличается от обычного quality mode: утилита подбирает настройки ради заданного размера файла, и документация предупреждает о потенциальном замедлении до семи раз. Если ограничение на байты не является обязательным, этот режим создаёт лишнюю вычислительную цену. Для серверного конвейера также важно отличать —jobs all от одновременного запуска десятков процессов: оба способа используют CPU, и внешняя система должна сама управлять суммарной конкуренцией.

После установки готовых бинарников и зависимостей основное кодирование и декодирование не требует сети, аккаунта или обращения к облачному API. Интернет нужен внешним этапам: загрузке пакета, исходников либо зависимостей. При сборке с dependency mode LOCAL CMake может получать выбранные зависимости как часть build process; при SYSTEM используются уже установленные системные библиотеки. На приватность исходных изображений это влияет существенно: обычный локальный вызов avifenc/avifdec не отправляет файл на сторонний сервер.

Для Y4M-сценариев libavif часто становится частью более длинного медиаконвейера, где подготовку кадров выполняет другое ПО. На GeekHow есть отдельная подборка программ для конвертирования видео; она относится к пользовательским конвертерам и не заменяет libavif, но показывает другой класс инструментов для подготовки медиа без собственного кода.

Безопасность, приватность и предсказуемость результата

Локальная архитектура убирает характерный для веб-конвертеров риск передачи изображения стороннему сервису, но не делает любой входной файл автоматически безопасным. libavif разбирает контейнер, вызывает AV1 decoder backend и при CLI-работе использует readers/writers JPEG, PNG и Y4M. С точки зрения эксплуатации это обычная цепочка нативного кода, которую следует обновлять вместе с зависимостями и запускать с разумными ограничениями ресурсов.

avifdec включает два явных защитных лимита: общее число пикселей по умолчанию ограничено 268435456, а максимальный dimension — 32768. Их назначение — не качество изображения, а предел входа. Снимать лимиты для неизвестного файла без анализа неразумно: огромные размеры могут привести к значительному расходу памяти и CPU даже при корректном формате.

Строгая проверка также имеет практический смысл. —no-strict отключает strict validation AVIF, поэтому это диагностический компромисс совместимости, а не улучшатель качества. Если файл отклонён штатной проверкой, безопаснее сначала получить его заново или пересоздать корректным encoder, чем превращать non-strict decode в постоянное поведение сервиса, принимающего чужие файлы.

Приватные сведения могут находиться не в пикселях, а в Exif/XMP/ICC. avifenc имеет отдельные параметры для игнорирования Exif, XMP и профиля, а также для установки новых payload. Перед публикацией изображений стоит определить политику metadata заранее: либо сохранять нужные данные, либо целенаправленно исключать их. Слепое удаление ICC ради «очистки» тоже нежелательно, потому что ICC описывает цвет, а не только персональные сведения.

При интеграции C API разработчик несёт ответственность за память и lifecycle объектов. Официальные примеры освобождают RGB pixels, уничтожают decoder и encoder, а encoded data освобождают после записи. Это не графический sandbox: ошибки управления памятью в коде приложения остаются ошибками приложения. Для входа из сети разумно ограничивать размер данных ещё до передачи декодеру и не полагаться только на один внутренний предел.

Цена, лицензирование и ограничения бесплатного режима

У libavif нет платной редакции, личного кабинета, пробного периода, лимита бесплатных экспортов, водяного знака или подписки. Исходный код распространяется по BSD-2-Clause. Это модель open-source library, а не freemium: цена использования определяется инфраструктурой вокруг неё — разработкой, тестированием, вычислительными ресурсами и сопровождением собственных бинарников.

Отсутствие тарифа не означает отсутствие обязательств. При распространении модифицированного или встроенного ПО нужно соблюдать текст BSD-2-Clause и отдельно учитывать лицензии AV1 backend и прочих зависимостей, выбранных в конкретной сборке. libavif позволяет переключать backend именно потому, что он не является единственным AV1 codec implementation внутри программы.

Фактические расходы проекта появляются прежде всего в инженерной работе. Команда должна поддерживать build matrix, обновлять libaom/dav1d/libgav1/rav1e/SVT-AV1 по выбранной архитектуре, проверять выходные файлы в целевых декодерах и следить за regression tests. Для разового ручного преобразования нескольких изображений такой уровень контроля создаёт лишнюю инженерную нагрузку; для продукта, которому нужен встроенный AVIF, он как раз является смыслом библиотеки.

Что перестанет работать первым при неполной сборке или окружении

Нет AV1 backend. Базовый source build libavif не включает codec автоматически. В таком состоянии контейнерный код присутствует, но практическое кодирование или декодирование AV1 не имеет исполнителя. Для готового приложения это проявляется раньше любых тонких настроек quality.

Не собраны CLI-приложения. AVIF_BUILD_APPS по умолчанию выключен. Библиотека может успешно установиться, а команды avifenc и avifdec в PATH не появятся. Это не повреждённая установка: сборка просто создала library target без приложений.

Нет PNG/JPEG/Zlib при AVIF_BUILD_APPS=ON. CMake требует эти компоненты для приложений. В отличие от API, который работает с memory image, CLI должен уметь читать и записывать указанные внешние форматы.

Нет libxml2. Обычные AVIF-функции остаются, но JPEG gain-map conversion в avifgainmaputil недоступна; avifenc при соответствующей сборке не переносит gain map из JPEG. Для HDR workflow это локальное, а не глобальное ограничение.

Нет сети после установки. Ничего в core encode/decode не обязано прекращаться: облачного endpoint и license server у libavif нет. Сеть снова становится нужна, когда внешняя система обновляет пакеты, получает исходники или загружает результат куда-то ещё.

Нет поддержки AVIF у программы-получателя. Даже корректно созданный libavif файл должна открыть другая программа. Совместимость конечного viewer не является функцией библиотеки-энкодера, поэтому production pipeline обязан проверять именно целевых потребителей.

Как пользоваться программой — советы гика

Установить libavif и проверить, какие codecs доступны

Цель. Получить avifenc/avifdec и сразу зафиксировать реальную конфигурацию сборки, потому что список aom, rav1e, svt, dav1d и libgav1 зависит от пакета.

Подготовка. На Windows можно поставить пакет через vcpkg командой vcpkg install libavif либо взять официальные Windows binaries из релиза. На macOS доступны brew install libavif и sudo port install libavif. На Debian-подобной системе официальный README приводит sudo apt install libavif-dev, на Red Hat-подобной — sudo yum -y install libavif. Для самостоятельной сборки включите приложения параметром CMake AVIF_BUILD_APPS=ON и выберите как минимум один AV1 codec backend.

Откройте терминал, доступный в вашей системе.
Выполните avifenc —version, затем avifdec —version.
Выполните avifenc —help и avifdec —help; зафиксируйте список доступных codecs и поддерживаемые вашей сборкой параметры.
Если нужен avifgainmaputil, выполните avifgainmaputil help. При source build он создаётся в составе AVIF_BUILD_APPS=ON; наличие именно этой команды в конкретном готовом пакете нужно проверять фактически.

Проверка результата. Обе основные команды должны печатать версию, а справка — синтаксис без сообщения command not found.

Типичная ошибка. Библиотека установлена, но avifenc отсутствует. Причина — сборка без apps либо пакет содержит только development library.

Безопасный откат. Не удаляйте рабочую библиотеку. Добавьте apps отдельной сборкой или установите пакет, в котором они включены; для проекта, использующего только C API, CLI вообще не обязателен.

Закодировать JPEG или PNG в обычный AVIF

Цель. Получить одиночный AVIF из файла, который avifenc понимает напрямую.

Подготовка. Возьмите input.png или input.jpg и сохраните оригинал отдельно. Для воспроизводимого примера ниже quality задано 70; это пример настройки, а не универсально рекомендуемое значение.

В каталоге с изображением выполните avifenc -q 70 —no-overwrite input.png output.avif.
Если источник JPEG, замените input.png на input.jpg; синтаксис выхода остаётся тем же.
Для контроля структуры выполните avifdec —info output.avif.

Важные параметры. -q/—qcolor принимает 0–100, где 100 соответствует lossless color; —qalpha отдельно регулирует alpha. —no-overwrite запрещает случайно заменить существующий output.

Проверка результата. avifdec —info должен разобрать output.avif и показать его параметры без ошибки.

Типичная ошибка. В avifenc передают WebP, TIFF или другой файл, которого нет в документированном CLI input. Утилита не является универсальным image importer.

Безопасный откат. Исходник не изменяется; удалите неудачный output.avif и повторите кодирование из оригинала после преобразования неподдерживаемого источника внешним decoder.

Получить lossless AVIF и не спутать режим с простым quality 100

Цель. Попросить avifenc установить совокупность lossless defaults и получить предупреждение, когда source/settings не позволяют выполнить условие полностью.

Подготовка. Для прозрачной графики лучше сохранить исходный PNG, чтобы после операции оставалась независимая эталонная копия.

Выполните avifenc —lossless —no-overwrite input.png output-lossless.avif.
Прочитайте сообщения avifenc: режим —lossless специально предупреждает о параметрах или входе, которые мешают lossless encoding.
Проверьте контейнер командой avifdec —info output-lossless.avif.
Для пиксельной проверки декодируйте в PNG: avifdec output-lossless.avif roundtrip.png.

Важные параметры. Один -q 100 относится к color quality, а alpha имеет отдельный —qalpha. —lossless нужен именно как согласованный режим, который выставляет lossless defaults.

Проверка результата. Сначала убедитесь, что avifenc не сообщил о несовместимости lossless settings. Затем сравнивайте декодированный PNG с исходником тем методом, который принят в вашем workflow.

Типичная ошибка. Считать любой AVIF при -q 100 полностью обратимым независимо от subsampling, alpha и преобразования RGB↔YUV.

Безопасный откат. Не заменяйте исходный PNG AVIF-файлом до проверки. При предупреждении вернитесь к исходнику и исправьте параметры вместо повторного перекодирования уже созданного AVIF.

Настроить quality, speed, threads, YUV и bit depth

Цель. Управлять компромиссом качества, времени и представления цвета без вымышленных «лучших» пресетов.

Подготовка. Сначала выполните avifenc —version и убедитесь, что нужный encoder backend доступен. Для примера используйте отдельный выходной файл.

Для явной конфигурации выполните avifenc -q 60 -s 6 -j all -y 420 -d 10 —no-overwrite input.png output-10bit.avif.
Если нужен другой backend и он перечислен вашей сборкой, добавьте -c aom, -c rav1e или -c svt.
Когда есть строгий лимит на объём, вместо обычного подбора quality можно добавить —target-size 200000, где число задаётся в байтах.
После кодирования выполните avifdec —info output-10bit.avif и сверьте depth/YUV с ожидаемыми.

Важные параметры. speed 0 — самый медленный, 10 — самый быстрый, default avifenc — 6. -j all разрешает использовать столько worker threads, сколько выберет реализация. Для YUV доступны auto, 444, 422, 420 и 400. Для JPEG/PNG depth задаётся 8/10/12.

Проверка результата. Помимо —info нужен визуальный либо автоматизированный контроль качества на характерных изображениях проекта. Размер файла сам по себе не показывает отсутствие chroma artifacts.

Типичная ошибка. Применять —target-size ко всей библиотеке как «ускоритель». Этот режим, напротив, способен работать до семи раз дольше обычного кодирования.

Безопасный откат. Сохраните исходник и старый AVIF; меняйте один параметр за итерацию, чтобы было понятно, какое изменение повлияло на размер, цвет или скорость.

Создать progressive, layered или grid AVIF

Цель. Использовать контейнерные возможности AVIF для прогрессивного отображения, слоёв или сетки tiles.

Подготовка. Для layered inputs подготовьте изображения, которые представляют последовательные слои; для grid — одинаковые по ширине, высоте и глубине tiles либо одно изображение, делимое на указанную сетку.

Для автоматического progressive варианта выполните avifenc —progressive —no-overwrite input.png progressive.avif.
Для явного layered файла из двух inputs выполните avifenc —layered —no-overwrite -o layered.avif layer0.png layer1.png. У avifenc допускается максимум четыре слоя.
Для сетки 2×2 из четырёх tiles выполните avifenc —grid 2×2 —no-overwrite -o grid.avif tile00.png tile01.png tile10.png tile11.png.
Проверьте каждый файл через avifdec —info.

Важные параметры. —progressive сам настраивает простой layered image из одного frame. —layered трактует каждый input как layer. —grid принимает MxN; grid получает color profile первого input.

Проверка результата. —info должен подтверждать, что контейнер читается. Для production отдельно проверьте целевые decoders/viewers: поддержка всех container features у потребителя является отдельным условием совместимости.

Типичная ошибка. Передать в grid tiles разного размера или нарушить ограничения AVIF grid.

Безопасный откат. При проблемах совместимости оставьте исходные tiles и создайте обычный single-image AVIF без grid/layering; это не требует преобразовывать уже проблемный контейнер.

Собрать image sequence с частотой кадров и повтором

Цель. Упаковать несколько кадров в AVIF image sequence.

Подготовка. Подготовьте frame01.png, frame02.png и frame03.png с согласованной геометрией и нужным порядком.

Выполните avifenc —fps 24 —repetition-count infinite —no-overwrite -o animation.avif frame01.png frame02.png frame03.png.
Если кадрам нужна разная длительность, используйте —duration перед теми последующими inputs, к которым должно применяться соответствующее значение.
Для ограничения keyframe interval добавьте -k с нужным целым интервалом; 0 отключает это ограничение.
Проверьте контейнер через avifdec —info animation.avif.

Важные параметры. —fps/—timescale задаёт timescale; при единичной длительности каждого frame это соответствует frames per second. Если timescale и duration не заданы, avifenc пытается взять framerate из Y4M header. repetition count принимает число или infinite.

Проверка результата. Убедитесь, что количество изображений и timing соответствуют ожиданию, а первый и последний кадры стоят на своих местах.

Типичная ошибка. Принять —jobs за число кадров. —jobs управляет worker threads, тогда как sequence образуется входными frames и timing options.

Безопасный откат. Храните исходные frames отдельно. При неверном timing пересоздайте контейнер из них, не извлекая и не перекодируя кадры из ошибочного sequence.

Управлять Exif, XMP, ICC и transform properties

Цель. Явно определить, какие metadata попадут в публикуемый AVIF, и задать поддерживаемые свойства ориентации/апертуры.

Подготовка. Решите, какие сведения должны сохраниться. Если профиль цвета нужен, не удаляйте его только ради уменьшения metadata.

Для файла без исходных Exif/XMP/ICC выполните avifenc —ignore-exif —ignore-xmp —ignore-profile —no-overwrite input.jpg clean.avif.
Чтобы назначить внешний ICC вместо встроенного, используйте avifenc —icc profile.icc —no-overwrite input.jpg profiled.avif. Параметр —icc сам подразумевает игнорирование input profile.
Чтобы добавить поворот как AVIF property, используйте —irot 1 для 90 градусов против часовой стрелки; допустимы значения 0–3.
Проверьте итоговые свойства через avifdec —info.

Важные параметры. —ignore-exif и —ignore-xmp действуют только когда соответствующие payload присутствуют. —crop создаёт clean aperture property clap по CROPX,CROPY,CROPW,CROPH; это отличается от физического ресайза raster data.

Проверка результата. Сверьте color information и transforms в —info, а изображение откройте в целевом decoder, чтобы убедиться, что он применяет эти properties ожидаемо.

Типичная ошибка. Удалить ICC и затем объяснять изменение цвета «качеством AVIF». Без корректной color interpretation сравнение становится некорректным.

Безопасный откат. Держите оригинал с полными metadata и создавайте публикуемый derivative. Возвратить удалённые Exif/XMP из уже очищенного файла без исходного payload нельзя.

Декодировать AVIF, выбрать глубину PNG и проверить индекс кадра

Цель. Получить внешний raster и при этом не потерять глубину только из-за неверного формата выхода.

Подготовка. Сначала узнайте характеристики файла командой avifdec —info input.avif.

Для PNG 16-bit output выполните avifdec -d 16 input.avif output.png.
Для JPEG выполните avifdec -q 90 input.avif output.jpg; помните, что JPEG output у avifdec всегда 8-bit.
Для первого изображения sequence или progressive content используйте avifdec —index 0 input.avif first.png.
Если нужно изменить chroma upsampling, выберите -u automatic, fastest, best, nearest или bilinear согласно задаче и затем сравните результат.

Важные параметры. PNG допускает depth 8 или 16; Y4M сохраняет input depth; JPEG всегда 8. JPEG quality задаётся 0–100 и по умолчанию равен 90. Индексация начинается с 0.

Проверка результата. Сверьте размер изображения, alpha и bit depth полученного raster с исходным AVIF. Для alpha выбирайте PNG, а не JPEG.

Типичная ошибка. Декодировать 10/12-bit AVIF в JPEG, а затем считать 8-bit результат доказательством ограничений libavif.

Безопасный откат. AVIF не изменяется при декодировании. Удалите неверный derivative и повторите вывод в PNG/Y4M с подходящей глубиной.

Создать и проверить HDR gain map

Цель. Сформировать AVIF, который хранит base image, alternate image и gain map между ними.

Подготовка. Нужны два согласованных изображения одной сцены: base.png для базового отображения и alternate.png для альтернативного HDR-представления. Команда avifgainmaputil должна присутствовать в сборке.

Посмотрите доступные параметры через avifgainmaputil help combine.
Для воспроизводимого примера выполните avifgainmaputil combine —qgain-map 80 —jobs all base.png alternate.png output-gainmap.avif.
Проверьте, что gain map действительно записана: avifgainmaputil printmetadata output-gainmap.avif.
Для JPEG, уже содержащего gain map, команда convert требует сборку avifgainmaputil с libxml2; отсутствие libxml2 будет сообщено как недоступность JPEG gainmap conversion.

Важные параметры. —qgain-map принимает 0–100, где 100 lossless. combine также имеет —depth-gain-map 8/10/12, —yuv-gain-map 444/422/420/400 и —downscaling.

Проверка результата. printmetadata должна вывести base/alternate headroom и параметры gain map, а не сообщение о том, что карта отсутствует.

Типичная ошибка. Пытаться выполнить JPEG gain-map conversion сборкой без libxml2 и воспринимать это как повреждение исходного JPEG.

Безопасный откат. base.png и alternate.png остаются независимыми файлами. При неверной карте удалите output-gainmap.avif и пересоздайте его из исходной пары после проверки color/HDR metadata.

Встроить libavif через C API

Цель. Использовать AVIF без запуска внешнего процесса и самостоятельно контролировать memory buffers.

Подготовка. Подключите avif/avif.h, слинкуйте libavif и обеспечьте выбранный AV1 backend. Для исходников приложения подготовьте тесты на ошибочные файлы и освобождение памяти.

Для кодирования создайте avifImage через avifImageCreate либо avifImageCreateEmpty, заполните размеры/depth/YUV и metadata.
Если исходные pixels находятся в RGB(A), вызовите avifRGBImageSetDefaults, назначьте или выделите RGB buffer и выполните avifImageRGBToYUV.
Создайте avifEncoder через avifEncoderCreate, установите quality, qualityAlpha, maxThreads, speed и другие требуемые поля.
Для одиночного изображения добавьте image через avifEncoderAddImage с AVIF_ADD_IMAGE_FLAG_SINGLE, завершите stream вызовом avifEncoderFinish и сохраните полученные bytes своим IO-кодом.
Для декодирования создайте avifDecoder, назначьте IO через avifDecoderSetIOFile либо другой поддерживаемый IO path, вызовите avifDecoderParse и затем avifDecoderNextImage.
Если приложению нужен RGB(A), создайте avifRGBImage, выделите pixels и выполните avifImageYUVToRGB.
В конце освободите выделенные RGB pixels и уничтожьте encoder/decoder/image в соответствии с ownership выбранных объектов.

Важные параметры. API не обязан читать PNG/JPEG: эти file readers относятся к apps. В собственном приложении вы можете декодировать любой source format внешней библиотекой и передать libavif готовые pixels.

Проверка результата. Для encoder проверяйте avifResult каждого этапа и повторно разбирайте созданный buffer decoder. Для decoder сверяйте dimensions, depth, frame count и metadata до использования pixels.

Типичная ошибка. Перенести CLI-модель в API и ожидать функцию «open WebP file» внутри libavif. Библиотечный interface работает на уровне AVIF и image buffers.

Безопасный откат. При интеграционном сбое оставьте старый production codec path доступным за feature flag, пока AVIF-path не пройдёт тесты на память, некорректные input и совместимость выходных файлов.

Сквозной сценарий: PNG → AVIF → анализ → PNG

Цель. Получить минимальный воспроизводимый маршрут, который подтверждает наличие encoder и decoder и отделяет создание AVIF от его проверки.

Подготовка. Поместите test.png в пустой рабочий каталог. Не используйте единственный экземпляр важного файла.

Проверьте инструменты командами avifenc —version и avifdec —version.
Создайте AVIF: avifenc -q 70 -s 6 —no-overwrite test.png test.avif.
Разберите контейнер: avifdec —info test.avif.
Декодируйте контрольную копию: avifdec test.avif test-roundtrip.png.
Сверьте dimensions, alpha и ожидаемый цвет. При lossy quality 70 пиксельное совпадение с исходником не является целью; оценивается качество и корректность выбранных параметров.
Только после такой проверки переносите тот же набор options в shell script, CI или C API.

Важные параметры. —no-overwrite защищает от незаметной замены старого результата, а —info позволяет увидеть структуру до дальнейшего преобразования.

Проверка результата. В каталоге должны остаться test.png, test.avif и test-roundtrip.png; test.avif должен разбираться без ошибок.

Типичная ошибка. Сразу запускать массовый shell loop, не зафиксировав working command на одном типичном изображении.

Безопасный откат. Удалите derivatives и вернитесь к test.png. Оригинальный файл не перезаписывался.

Чек-лист перед экспортом, сохранением или публикацией

Цель. Отделить технически валидный AVIF от результата, который действительно подходит конкретному продукту.

Зафиксируйте libavif version и доступный codec backend.
Проверьте dimensions, bit depth, YUV format, alpha и range через avifdec —info.
Для цветокритичных изображений убедитесь, что CICP/ICC политика задана намеренно, а не потеряна случайным —ignore-profile.
Решите судьбу Exif/XMP до публикации.
Для sequence проверьте frame order, timing и repetition.
Для progressive/layered/grid убедитесь, что feature поддерживается целевым consumer.
Для gain map проверьте metadata отдельной утилитой.
Не заменяйте исходник AVIF-файлом до визуальной и автоматизированной проверки.
Если input приходит от посторонних пользователей, сохраняйте strict validation и ресурсные лимиты, пока нет обоснованной причины менять их.

Проверка результата. Выходной файл должен проходить ваш decoder test и открываться в реальном целевом приложении, а metadata policy — соответствовать публикационному сценарию.

Типичная ошибка. Проверить только размер файла и считать меньший объём достаточным признаком корректности.

Безопасный откат. Храните versioned source и предыдущий одобренный derivative, чтобы изменение encoder options не превращалось в необратимую миграцию медиатеки.

Плюсы и минусы libavif

Плюсы

Проект решает именно AVIF-задачу на уровне библиотеки и контейнера, поэтому его можно встроить в приложение без запуска внешнего облачного сервиса.
Один API поддерживает AV1-compatible YUV formats, разные bit depth, alpha, image sequences, transforms, ICC/CICP, Exif/XMP и HDR gain map.
Codec backend не зашит единственным вариантом: сборка может использовать aom, rav1e или svt для encoding и aom, dav1d или libgav1 для decoding в поддерживаемых комбинациях.
avifenc и avifdec дают готовую CLI-оболочку для автоматизации JPEG/PNG/Y4M ↔ AVIF без написания собственного front end.
Есть параметры для quality color, quality alpha, speed, thread count, YUV, bit depth, target size и codec-specific options.
Поддерживаются layered/progressive images, grid и image sequence, а не только один статичный кадр.
avifdec имеет strict validation и встроенные ограничения размеров, полезные при обработке внешнего контента.
BSD-2-Clause и отсутствие платных редакций упрощают включение библиотеки в собственный build при соблюдении лицензий всех зависимостей.
Основные операции выполняются локально и не требуют учётной записи, subscription API или передачи исходных изображений в облако.

Минусы

Графического интерфейса нет: пользователю без навыков терминала или разработки придётся выбирать другой класс программ.
Готовый avifenc не является универсальным image converter и принимает только JPEG, PNG и Y4M; WebP, TIFF и другие источники требуют внешнего decoder либо собственного API-кода.
Source build требует сознательно выбрать AV1 codec backend; по умолчанию ни один backend не включён.
Набор codecs и часть возможностей зависят от того, как собран конкретный пакет, поэтому команда, работающая в одной системе, может не иметь выбранного backend в другой.
Для CLI-приложений нужны JPEG, PNG и Zlib, а отдельный JPEG gain-map path зависит от libxml2.
—target-size может заметно замедлять encoding; документация указывает потенциальное увеличение времени до семи раз.
—jobs ускоряет одну задачу за счёт worker threads, но не даёт встроенного менеджера независимой пакетной очереди, каталогов, приоритетов и повторов после сбоя.
Высокая гибкость color metadata и YUV settings увеличивает риск получить формально валидный файл с неверной интерпретацией цвета при плохо настроенном pipeline.
Совместимость progressive/layered/grid/gain-map content нужно проверять в конечном viewer: корректное создание container feature не гарантирует, что каждое стороннее приложение её отображает.

Кому подойдёт

Разработчикам приложений. Когда требуется нативное AVIF encode/decode через C API и контроль над memory, metadata, color conversion и backend.
Инженерам backend и CI. avifenc/avifdec удобно включать в shell, build pipeline или media service, если orchestration независимых файлов выполняется внешней системой.
Разработчикам графических библиотек. libavif подходит как специализированный AVIF-layer рядом с отдельными decoders JPEG/WebP/TIFF и собственным image model.
Специалистам по форматам и HDR. Layered images, sequences, grids и gain map дают доступ к возможностям контейнера, которые простые пользовательские конвертеры часто скрывают.
Проектам с локальной обработкой. Изображение можно кодировать и декодировать без обязательной передачи во внешний сервис, что упрощает контроль над приватными файлами.
Командам, которым важна воспроизводимая конфигурация. Versioned library, явный codec backend и фиксированные CLI options можно закрепить в build manifest и regression tests.

Кому не подойдёт

Пользователю, которому нужно окно с предпросмотром. У libavif нет GUI, drag-and-drop, галереи и визуального сравнения до/после. Для такого сценария логичнее смотреть фоторедакторы для ПК с AVIF-поддержкой в конкретной версии.
Тем, кому нужен универсальный converter десятков форматов. avifenc напрямую ограничен JPEG/PNG/Y4M, а avifdec — JPEG/PNG/Y4M на выходе.
Тем, кто не хочет управлять build dependencies. При source build нужно выбрать codec backend, а для apps обеспечить дополнительные библиотеки.
Командам, которым нужен SaaS workflow. Пользователей, ролей, облачных проектов, shared storage, history и web dashboard в libavif нет.
Тем, кому нужна мобильная программа. Android JNI binding — компонент для разработчика, а не готовый редактор для телефона.
Задачам с интеллектуальным ретушированием. libavif не генерирует изображения, не удаляет объекты и не применяет AI enhancement; она кодирует, декодирует и описывает AVIF.

Сравнение с другими аналогами

Сравнивать libavif полезно не с облачными «сжимателями картинок», а с инструментами, которые реально могут стоять в программном pipeline. Ниже используются единые критерии: основная задача, платформа, порог освоения, форматы, автоматизация, модель оплаты, ограничения и подходящий сценарий.

Инструмент	Задача	Платформа и порог освоения	Форматы	Автоматизация	Модель оплаты	Главное ограничение	Когда выбирать
libheif	Работа с HEIF-family контейнерами через библиотеку и CLI	Кроссплатформенный исходный проект; требует понимания codec plugins и CLI/API	HEIF/HEIC, AVIF и другие поддерживаемые HEIF codecs	Library API и heif-enc/heif-dec/heif-info	Open source, отдельного SaaS-тарифа нет	Более широкий контейнерный scope означает больше вариантов codecs/dependencies	Когда кроме AVIF нужен HEIC/HEIF и единый HEIF-oriented stack
ImageMagick	Универсальные преобразования и обработка изображений	Windows/macOS/Linux и другие системы; CLI богатый и заметно шире одного формата	Более 100 основных image formats; AVIF присутствует среди read/write formats при соответствующей сборке	CLI, scripts, batch pipelines	Open source, платного режима экспорта нет	AVIF — один из многих форматов; конкретная codec support зависит от build/delegates	Когда одновременно нужны resize, crop, compositing и конвертация многих типов файлов
libvips	Программная обработка изображений в библиотечном pipeline	Кроссплатформенная library с bindings; порог выше, чем у GUI	Через heifload/heifsave работает с HEIF-family изображениями, включая AV1-oriented saving	API, bindings и command-line ecosystem	Open source, обязательной подписки нет	Это общий image-processing engine, поэтому AVIF настройки являются частью более крупного API	Когда AVIF нужно встроить в pipeline resize/thumbnail/processing, а не только кодировать контейнер

libavif против libheif. libavif уже по области ответственности: проект сосредоточен на AVIF. libheif охватывает несколько форматов внутри HEIF ecosystem и поэтому подходит приложению, которому одновременно нужны HEIC и AVIF. Узкая специализация libavif выгодна, когда лишние HEIF codecs не нужны и команда хочет максимально прямую AVIF API-модель.

libavif против ImageMagick. ImageMagick ближе к готовому универсальному CLI-комбайну: одна команда может объединять изменение размеров, операции с каналами и конвертацию. libavif даёт более непосредственный доступ к AVIF-specific features и library structures, но не заменяет общий редакционный pipeline. Для массового преобразования разнотипных файлов без разработки ImageMagick чаще требует меньше внешней обвязки.

libavif против libvips. libvips ориентирован на общую image processing architecture и особенно полезен там, где format encode — только финальная стадия масштабирования, crop или thumbnail pipeline. libavif уместнее как специализированная зависимость, когда приложению нужен AVIF container/API без большого набора операторов обработки.

Типичные проблемы и диагностика

1. avifenc или avifdec не находятся после установки

Симптом: оболочка отвечает, что команда не найдена. Возможная подтверждённая причина: установлен только library target, потому что AVIF_BUILD_APPS по умолчанию выключен, либо каталог готовых binaries не добавлен в PATH. Диагностика: проверьте состав установленного пакета и наличие файлов avifenc/avifdec. Исправление: установите пакет с apps или пересоберите libavif с AVIF_BUILD_APPS=ON; для готовых Windows binaries используйте каталог релиза. Проверка результата: avifenc —version и avifdec —version должны завершаться выводом версии.

2. Библиотека собрана, но encoder или decoder не может работать с AV1

Симптом: нужный codec отсутствует либо операция сообщает, что подходящего codec backend нет. Возможная подтверждённая причина: source build не включает ни один AV1 codec по умолчанию. Диагностика: сравните avifenc —version/—help и avifdec —version/—help с ожидаемой конфигурацией. Исправление: включите подходящий AVIF_CODEC_AOM, AVIF_CODEC_DAV1D, AVIF_CODEC_LIBGAV1, AVIF_CODEC_RAV1E или AVIF_CODEC_SVT в поддерживаемой роли и пересоберите. Проверка результата: выбранный backend должен появиться в списке доступных codecs и выполнять соответствующую encode/decode операцию.

3. Выбранный —codec не существует в конкретном бинарнике

Симптом: команда с -c aom, rav1e, svt, dav1d или libgav1 отклоняется, хотя это имя встречается в документации. Возможная подтверждённая причина: допустимые значения зависят от codecs, enabled at build time. Диагностика: посмотрите help/version именно того бинарника, который запускается из PATH. Исправление: используйте auto-selection либо пересоберите/переустановите пакет с требуемым backend. Проверка результата: новый вызов должен принимать -c и завершать операцию без ошибки unavailable codec.

4. avifenc не принимает WebP, TIFF или другой источник

Симптом: входной файл не распознаётся как поддерживаемый avifenc input. Возможная подтверждённая причина: CLI документирует JPEG, PNG и Y4M, а не произвольный набор raster formats. Диагностика: сверьте формат с avifenc —help и убедитесь, что расширение соответствует реальному содержимому. Исправление: декодируйте source внешней библиотекой/утилитой в PNG/Y4M либо передайте готовые pixels через C API. Проверка результата: промежуточный supported input должен открываться avifenc и давать AVIF, который читает avifdec —info.

5. —lossless выдаёт предупреждение или roundtrip не соответствует ожиданию

Симптом: avifenc предупреждает, что settings/input не позволяют lossless, либо пользователь получает отличие после RGB↔YUV conversion. Возможная подтверждённая причина: lossless зависит не только от одного qcolor, а от совокупности color/alpha и представления пикселей. Диагностика: изучите предупреждение —lossless, YUV format, alpha quality и путь color conversion. Исправление: используйте именно —lossless и устраните параметр, о котором сообщает утилита, вместо механического повышения -q. Проверка результата: encoder не должен предупреждать о нарушении lossless settings; пиксельную идентичность проверяйте после декодирования в подходящий lossless raster.

6. Цвет или яркость после конвертации выглядят иначе

Симптом: AVIF технически читается, но целевое приложение показывает иной цвет. Возможная подтверждённая причина: потерян или неверно задан ICC/CICP, YUV range либо subsampling; другой chroma upsampling также влияет на восстановление RGB. Диагностика: сравните avifdec —info, наличие профиля, CICP, full/limited range и YUV format исходного pipeline. Исправление: не используйте —ignore-profile без причины, явно задайте корректные color properties и согласуйте range между producer и consumer. Проверка результата: повторное декодирование в целевом приложении должно интерпретировать профиль и range одинаково с контрольным workflow.

7. После вывода в JPEG исчез alpha или сокращается bit depth

Симптом: прозрачность потеряна, а high-bit-depth AVIF превращён в 8-bit raster. Возможная подтверждённая причина: JPEG output avifdec всегда 8-bit и не является форматом для сохранения alpha. Диагностика: проверьте source depth/alpha через —info и формат конечного файла. Исправление: для контрольного вывода используйте PNG и при необходимости -d 16. Проверка результата: PNG должен сохранить требуемую глубину output path и прозрачность, доступную из AVIF.

8. avifdec отклоняет очень большое изображение

Симптом: файл упирается в size/dimension constraint. Возможная подтверждённая причина: decoder по умолчанию ограничивает total pixels значением 268435456 и dimension значением 32768. Диагностика: сопоставьте dimensions контейнера с этими лимитами. Исправление: для доверенного файла лимиты можно менять соответствующими avifdec options, но для внешнего непроверенного input безопаснее сохранить защитные значения и отклонить чрезмерный файл. Проверка результата: контролируемый trusted input проходит decode при новом лимите, а сервис по-прежнему ограничивает неизвестные oversized files.

9. Файл читается только с —no-strict

Симптом: стандартный decode отклоняет контейнер, non-strict mode его принимает. Возможная подтверждённая причина: AVIF не проходит strict validation, которую —no-strict специально отключает. Диагностика: сохраните diagnostics стандартного decoder и установите producer/version файла. Исправление: предпочтительно пересоздать AVIF корректным encoder; non-strict использовать только для ограниченной совместимости с доверенным материалом, а не как default для внешних uploads. Проверка результата: исправленный файл должен декодироваться без —no-strict.

10. JPEG gain map не конвертируется

Симптом: avifgainmaputil сообщает, что JPEG gainmap conversion unavailable. Возможная подтверждённая причина: утилита собрана без libxml2. Диагностика: проверьте build configuration и наличие AVIF_ENABLE_JPEG_GAIN_MAP_CONVERSION. Исправление: добавьте libxml2 и пересоберите apps с поддержкой этой функции. Проверка результата: команда convert больше не должна завершаться сообщением о недоступной реализации, а созданный AVIF должен содержать gain map.

11. Кодирование с —target-size занимает существенно дольше

Симптом: тот же source обрабатывается заметно дольше, чем в quality mode. Возможная подтверждённая причина: —target-size выполняет подбор ради точного target file size; документация предупреждает о замедлении до семи раз. Диагностика: сравните одинаковый backend и source с target-size и без него. Исправление: если строгий byte budget не нужен, используйте qcolor/other quality settings; для обязательного budget учитывайте этот режим в capacity planning. Проверка результата: без target-size pipeline возвращается к обычному quality-based времени, а с ним результат соответствует заданной цели по размеру.

FAQ о libavif

Можно ли подавать изображение в avifenc через stdin?

Да. Параметр —stdin переключает ввод с файловых путей на стандартный поток. По умолчанию такой поток трактуется как Y4M; при другом допустимом типе нужно задать —input-format jpeg, png или y4m. Значение auto для stdin не используется, потому что утилите требуется явный либо предусмотренный по умолчанию формат потока.

Что именно делает —raw-color в avifdec?

Этот параметр относится к JPEG output и выводит raw RGB values вместо умножения цвета на alpha при сохранении в непрозрачный формат. Для Y4M он не применяется. Опция полезна в специальном compositing workflow, но не является общим переключателем «правильного цвета».

Можно ли управлять только степенью сжатия PNG при декодировании?

Да. avifdec имеет —png-compress со шкалой 0–9: 0 означает отсутствие PNG compression, 9 — максимальный уровень, а без явного значения используется встроенный default libpng. Этот параметр влияет на упаковку PNG, а не на качество уже декодированных AVIF pixels.

Может ли avifdec извлечь все кадры image sequence?

Параметр —index принимает не только числовой индекс от 0, но и all для декодирования всех frames. В режиме -i/—info утилита декодирует все frames и выводит информацию вместо сохранения raster output.

Как avifdec выбирает слой progressive image?

Для progressive processing используется —progressive. После его включения —index выбирает layer в progressive order. Без явного index применяется 0, то есть первый frame/layer по правилам этой опции.

Чем automatic chroma upsampling отличается от best?

avifdec предоставляет automatic, fastest, best, nearest и bilinear для YUV 4:2:0/4:2:2. Это варианты алгоритма восстановления chroma resolution при переходе к RGB. Названия описывают режим выбора, но не задают универсальный benchmark; сравнивать их нужно на изображениях, где цветовые границы действительно чувствительны к upsampling.

Когда avifenc использует SharpYUV?

—sharpyuv включает sharp RGB-to-YUV420 conversion, когда такая возможность поддерживается сборкой. Для Y4M и для output, который не является YUV 4:2:0, параметр игнорируется. Это специализированная настройка этапа RGB→YUV, а не AV1 quality preset.

Зачем avifenc нужен разделитель — перед именами файлов?

Двойной дефис завершает разбор options; всё после него трактуется как file names. Это особенно полезно, когда имя input начинается с дефиса и иначе могло бы быть принято за параметр командной строки.

Что означает default auto-selection codec?

Если -c не указан, avifenc или avifdec выбирает backend из тех codecs, которые реально включены в binary. Конкретный набор определяется build time, поэтому reproducible pipeline, которому принципиален один backend, должен фиксировать сборку и проверять доступность нужного имени.

Можно ли считать C99-совместимые headers доказательством, что libavif 1.4.2 собирается как C99?

Нет. В release 1.4.2 компиляция самой библиотеки требует C11, хотя публичные headers сохраняют C99 compatibility. Это позволяет C99 client code включать API headers, но не отменяет C11 requirement при сборке libavif из исходников.

Итог: когда выбирать libavif

libavif рациональна, когда AVIF является частью программного продукта, сервера, графической библиотеки или воспроизводимого CLI pipeline. В этих сценариях ценность дают C API, раздельное управление encoder/decoder backend, color/alpha/metadata, sequences, grid/layered structures и gain map. Отсутствие cloud account здесь не недостаток, а следствие архитектуры: приложение само определяет storage, orchestration и policy входных данных.

Для разового ручного преобразования изображений libavif требует больше технической подготовки, чем GUI-конвертер. Если нужны десятки source formats, resize и compositing в одной готовой CLI-среде, уместнее ImageMagick. Если продукт одновременно работает с HEIC и AVIF, шире охват libheif. Если AVIF — только один output большого image-processing pipeline с масштабированием и bindings, стоит сравнить libvips.

Для разработки главными критериями выбора остаются три вещи: нужный AV1 backend, требования к container features и контроль совместимости конечного consumer. Stable 1.4.2 уже даёт полный базовый путь от avifImage/avifEncoder до avifDecoder и CLI, а точность результата зависит от осознанных color, metadata, bit depth и quality settings. Поэтому libavif лучше рассматривать не как «конвертер AVIF», а как специализированный building block, вокруг которого команда строит собственный проверяемый процесс.