libavif-with-gainmap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# libavif-with-gainmap
+
+一个准备发布到 npm 的 Node.js 包，用 libavif 把带 gain map 的 JPEG 转成带 gain map 的 AVIF，并支持设置质量和输出尺寸。
+
+## 特性
+
+- 使用 libavif 的 `avifgainmaputil convert` 做 JPEG gain map -> AVIF gain map。
+- 支持 `quality`、`gainMapQuality`、`speed`、`jobs`、`depth`、`yuv` 等编码参数。
+- 支持 `width`/`height` 精确尺寸，或 `maxWidth`/`maxHeight` 等比缩小。
+- GitHub Actions matrix 构筑这些平台的原生工具：`darwin-arm64`、`darwin-x64`、`linux-arm64`、`linux-x64`、`win32-x64`。
+- npm 包运行时按 `process.platform` + `process.arch` 自动选择 `vendor/<platform>-<arch>/` 下的二进制。
+
+## 安装
+
+```sh
+npm install libavif-with-gainmap
+```
+
+发布前需要先运行本仓库的 GitHub Actions release workflow，生成并打包 `vendor/` 下的原生二进制。
+
+## CLI
+
+```sh
+avif-gainmap convert input.jpg output.avif --quality 82 --gain-map-quality 70
+```
+
+调整尺寸：
+
+```sh
+avif-gainmap convert input.jpg output.avif --max-width 1600 --max-height 1200
+avif-gainmap convert input.jpg output.avif --width 1200
+```
+
+常用参数：
+
+```sh
+avif-gainmap convert input.jpg output.avif \
+  --quality 80 \
+  --gain-map-quality 65 \
+  --speed 6 \
+  --jobs all \
+  --depth 10 \
+  --yuv 420
+```
+
+## JS API
+
+```js
+const { convertJpegGainMap } = require('libavif-with-gainmap');
+
+await convertJpegGainMap('input.jpg', 'output.avif', {
+  quality: 82,
+  gainMapQuality: 70,
+  maxWidth: 1600,
+  maxHeight: 1200,
+  jobs: 'all'
+});
+```
+
+如果只给 `width` 或 `height`，另一边会按比例计算。`maxWidth` / `maxHeight` 只会缩小，不会放大。
+
+## 原生工具覆盖
+
+默认使用 npm 包内的二进制。也可以用环境变量覆盖：
+
+- `AVIF_GAINMAP_BIN_DIR`: 同时包含 `avifgainmaputil` 和 `avifgainmapresize` 的目录。
+- `AVIF_GAINMAPUTIL_PATH`: 指向自定义 `avifgainmaputil`。
+- `AVIF_GAINMAPRESIZE_PATH`: 指向自定义 `avifgainmapresize`。
+
+## 构筑
+
+本项目使用 libavif `v1.4.2`，构筑时开启：
+
+- `AVIF_BUILD_APPS=ON`
+- `AVIF_CODEC_AOM=LOCAL`
+- `AVIF_JPEG=LOCAL`
+- `AVIF_LIBXML2=LOCAL`
+- `AVIF_LIBYUV=LOCAL`
+- `AVIF_LIBSHARPYUV=LOCAL`
+- `AVIF_ZLIBPNG=LOCAL`
+
+本地当前平台构筑：
+
+```sh
+npm run build:libavif
+npm run check-prebuilt
+```
+
+完整发布请看 [docs/BUILDING.md](docs/BUILDING.md)。
+
+## 为什么有 `avifgainmapresize`
+
+普通图片 resize 工具通常不了解 JPEG/AVIF gain map 的主图、辅助图和元数据关系，容易丢失或破坏 gain map。这里先用 libavif 官方工具转换，再用一个链接 libavif 的小工具同时缩放 AVIF base image 和 gain map image，最后按目标质量重新编码。

package/bin/avif-gainmap.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+'use strict';
+
+const { convertJpegGainMap } = require('../src');
+const { normalizeJobs } = require('../src/options');
+const { version } = require('../package.json');
+
+function printHelp() {
+  process.stdout.write(`avif-gainmap ${version}
+
+Usage:
+  avif-gainmap convert <input.jpg> <output.avif> [options]
+
+Options:
+  -q, --quality <0-100>            AVIF color quality. Default: 80
+      --gain-map-quality <0-100>   Gain map quality. Default: 60
+      --width <px>                 Exact output width. Height is kept proportional if omitted.
+      --height <px>                Exact output height. Width is kept proportional if omitted.
+      --max-width <px>             Downscale to fit this width.
+      --max-height <px>            Downscale to fit this height.
+      --speed <0-10>               Encoder speed. 0 is slowest, 10 is fastest. Default: 6
+      --jobs <n|all>               Worker threads.
+      --swap-base                  Make the HDR image the AVIF base image.
+      --cicp <P/T/M>               Override input CICP values.
+      --clli <MaxCLL,MaxPALL>      Set alternate image light level information.
+      --depth <8|10|12>            Output bit depth passed to libavif.
+      --yuv <444|422|420|400>      Output YUV format passed to libavif.
+      --keep-temp                  Keep intermediate AVIF when resizing.
+      --verbose                    Stream native tool output.
+  -h, --help                       Show this help.
+      --version                    Show version.
+`);
+}
+
+function readValue(args, index, inlineValue, flag) {
+  if (inlineValue !== undefined) {
+    return [inlineValue, index];
+  }
+  if (index + 1 >= args.length) {
+    throw new Error(`${flag} requires a value.`);
+  }
+  return [args[index + 1], index + 1];
+}
+
+function parseConvertArgs(args) {
+  const options = {};
+  const positional = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const raw = args[i];
+    const eq = raw.indexOf('=');
+    const flag = eq === -1 ? raw : raw.slice(0, eq);
+    const inlineValue = eq === -1 ? undefined : raw.slice(eq + 1);
+
+    switch (flag) {
+      case '-q':
+      case '--quality': {
+        const result = readValue(args, i, inlineValue, flag);
+        options.quality = result[0];
+        i = result[1];
+        break;
+      }
+      case '--gain-map-quality':
+      case '--qgain-map': {
+        const result = readValue(args, i, inlineValue, flag);
+        options.gainMapQuality = result[0];
+        i = result[1];
+        break;
+      }
+      case '--width':
+      case '--height':
+      case '--max-width':
+      case '--max-height':
+      case '--speed':
+      case '--depth':
+      case '--yuv':
+      case '--cicp':
+      case '--clli': {
+        const result = readValue(args, i, inlineValue, flag);
+        const key = flag
+          .replace(/^--/, '')
+          .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+        options[key] = result[0];
+        i = result[1];
+        break;
+      }
+      case '--jobs': {
+        const result = readValue(args, i, inlineValue, flag);
+        options.jobs = normalizeJobs(result[0]);
+        i = result[1];
+        break;
+      }
+      case '--swap-base':
+        options.swapBase = true;
+        break;
+      case '--keep-temp':
+        options.keepTemp = true;
+        break;
+      case '--verbose':
+        options.verbose = true;
+        break;
+      default:
+        if (raw.startsWith('-')) {
+          throw new Error(`Unknown option ${raw}.`);
+        }
+        positional.push(raw);
+    }
+  }
+
+  if (positional.length !== 2) {
+    throw new Error('convert requires <input.jpg> and <output.avif>.');
+  }
+
+  return { input: positional[0], options, output: positional[1] };
+}
+
+async function main(argv) {
+  const command = argv[2];
+  if (!command || command === '-h' || command === '--help') {
+    printHelp();
+    return;
+  }
+  if (command === '--version') {
+    process.stdout.write(`${version}\n`);
+    return;
+  }
+  if (command !== 'convert') {
+    throw new Error(`Unknown command ${command}.`);
+  }
+
+  const { input, output, options } = parseConvertArgs(argv.slice(3));
+  await convertJpegGainMap(input, output, options);
+}
+
+main(process.argv).catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  if (error.stderr) {
+    process.stderr.write(error.stderr);
+  }
+  process.exitCode = 1;
+});

package/docs/API.md

@@ -0,0 +1,47 @@
+# API
+
+## `convertJpegGainMap(input, output, options)`
+
+把带 gain map 的 JPEG 转成 AVIF gain map。
+
+```js
+const { convertJpegGainMap } = require('libavif-with-gainmap');
+
+await convertJpegGainMap('input.jpg', 'output.avif', {
+  quality: 80,
+  gainMapQuality: 60,
+  maxWidth: 1600,
+  maxHeight: 1200
+});
+```
+
+## Options
+
+- `quality`: 主图质量，`0..100`，默认 `80`。
+- `gainMapQuality`: gain map 质量，`0..100`，默认 `60`。
+- `width`: 输出宽度。单独设置时保持比例。
+- `height`: 输出高度。单独设置时保持比例。
+- `maxWidth`: 最大宽度，只缩小不放大。
+- `maxHeight`: 最大高度，只缩小不放大。
+- `speed`: libavif 编码速度，`0..10`，默认 `6`。
+- `jobs`: 线程数，正整数或 `'all'`。
+- `depth`: 输出 bit depth，`8`、`10`、`12`。
+- `yuv`: 输出 YUV 格式，`444`、`422`、`420`、`400`。
+- `swapBase`: 传给 `avifgainmaputil --swap-base`。
+- `cicp`: 传给 `avifgainmaputil --cicp`，格式 `P/T/M`。
+- `clli`: 传给 `avifgainmaputil --clli`，格式 `MaxCLL,MaxPALL`。
+- `binDir`: 自定义二进制目录。
+- `toolPaths`: `{ avifgainmaputil, avifgainmapresize }` 自定义工具路径。
+- `verbose`: 把原生工具输出转发到当前 stdout/stderr。
+
+返回值包含原生工具执行结果：
+
+```js
+{
+  input: '/abs/input.jpg',
+  output: '/abs/output.avif',
+  resized: true,
+  convert: { command, args, stdout, stderr, exitCode },
+  resize: { command, args, stdout, stderr, exitCode }
+}
+```

package/docs/BUILDING.md

@@ -0,0 +1,66 @@
+# 构筑和发布
+
+## GitHub Actions
+
+`.github/workflows/release.yml` 会做三件事：
+
+1. 跑 JS 测试。
+2. 用 matrix 分别构筑五个平台的 libavif 工具：
+   - `linux-x64` on `ubuntu-24.04`
+   - `linux-arm64` on `ubuntu-24.04-arm`
+   - `darwin-x64` on `macos-15-intel`
+   - `darwin-arm64` on `macos-15`
+   - `win32-x64` on `windows-2025`
+3. 汇总 `vendor/<platform>-<arch>/` 后执行 `npm pack`，tag 触发时再 `npm publish`。
+
+发布到 npm 前，在仓库 secrets 里配置：
+
+```text
+NPM_TOKEN=<npm automation token>
+```
+
+然后创建 tag：
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+## 本地构筑当前平台
+
+需要 `git`、`cmake`、`ninja`、`nasm`、Node.js 18+。
+
+```sh
+npm test
+npm run build:libavif
+npm run check-prebuilt
+```
+
+输出目录：
+
+```text
+vendor/<platform>-<arch>/
+  avifgainmaputil(.exe)
+  avifgainmapresize(.exe)
+```
+
+## 可配置环境变量
+
+- `LIBAVIF_VERSION`: 默认 `v1.4.2`。
+- `LIBAVIF_SOURCE_DIR`: 使用已有 libavif 源码目录，而不是自动 clone。
+- `LIBAVIF_BUILD_DIR`: 自定义 CMake build 目录。
+- `LIBAVIF_INSTALL_DIR`: 自定义 CMake install 目录。
+- `LIBAVIF_CMAKE_ARGS`: 追加 CMake 参数。
+- `TARGET_PLATFORM_KEY`: 写入哪个 `vendor/<key>` 目录，默认当前平台。
+
+示例：
+
+```sh
+LIBAVIF_VERSION=v1.4.2 TARGET_PLATFORM_KEY=linux-x64 npm run build:libavif
+```
+
+## 构筑策略
+
+libavif 是 C/C++ 原生项目，不能构筑一个跨所有系统通用的二进制。本仓库选择在 GitHub Actions 上按平台分别构筑，然后把产物放入 npm tarball。运行时由 Node.js 选择当前平台的二进制。
+
+`avifgainmaputil` 来自 libavif；`avifgainmapresize` 是本仓库的很小一层 C helper，通过 public libavif API 解码、缩放、重编码 AVIF gain map。