libavif-with-gainmap 0.1.0

package/src/index.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const { normalizeConvertOptions } = require('./options');
+const { AvifGainMapError, runFile } = require('./process');
+const {
+  SUPPORTED_PLATFORM_KEYS,
+  TOOL_GAINMAP_RESIZE,
+  TOOL_GAINMAP_UTIL,
+  assertToolAvailable,
+  getPlatformKey,
+  resolveTool
+} = require('./platform');
+
+function asPath(name, value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty file path.`);
+  }
+  return value;
+}
+
+function pushOption(args, flag, value) {
+  if (value !== undefined && value !== null) {
+    args.push(flag, String(value));
+  }
+}
+
+function buildConvertArgs(input, output, options, forResize) {
+  const args = ['convert'];
+  pushOption(args, '--qcolor', forResize ? options.intermediateQuality : options.quality);
+  pushOption(
+    args,
+    '--qgain-map',
+    forResize ? options.intermediateGainMapQuality : options.gainMapQuality
+  );
+  pushOption(args, '--speed', options.speed);
+  pushOption(args, '--jobs', options.jobs);
+  pushOption(args, '--depth', options.depth);
+  pushOption(args, '--yuv', options.yuv);
+  pushOption(args, '--cicp', options.cicp);
+  pushOption(args, '--clli', options.clli);
+  if (options.swapBase) {
+    args.push('--swap-base');
+  }
+  args.push(input, output);
+  return args;
+}
+
+function buildResizeArgs(input, output, options) {
+  const args = [input, output];
+  pushOption(args, '--qcolor', options.quality);
+  pushOption(args, '--qgain-map', options.gainMapQuality);
+  pushOption(args, '--speed', options.speed);
+  pushOption(args, '--jobs', options.jobs);
+
+  const size = options.size;
+  if (size) {
+    pushOption(args, '--width', size.width);
+    pushOption(args, '--height', size.height);
+    pushOption(args, '--max-width', size.maxWidth);
+    pushOption(args, '--max-height', size.maxHeight);
+  }
+  return args;
+}
+
+async function convertJpegGainMap(input, output, rawOptions = {}) {
+  input = asPath('input', input);
+  output = asPath('output', output);
+
+  const options = normalizeConvertOptions(rawOptions);
+  const utilPath = assertToolAvailable(
+    resolveTool(TOOL_GAINMAP_UTIL, options),
+    TOOL_GAINMAP_UTIL
+  );
+  const resizePath = options.size
+    ? assertToolAvailable(resolveTool(TOOL_GAINMAP_RESIZE, options), TOOL_GAINMAP_RESIZE)
+    : null;
+
+  let tempDir;
+  let intermediate = output;
+  try {
+    if (resizePath) {
+      tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'avif-gainmap-'));
+      intermediate = path.join(tempDir, 'converted.avif');
+    }
+
+    // Resize is a second AVIF encode, so the intermediate conversion defaults to lossless.
+    const convertArgs = buildConvertArgs(input, intermediate, options, Boolean(resizePath));
+    const convert = await runFile(utilPath, convertArgs, options);
+
+    let resize = null;
+    if (resizePath) {
+      const resizeArgs = buildResizeArgs(intermediate, output, options);
+      resize = await runFile(resizePath, resizeArgs, options);
+    }
+
+    return {
+      convert,
+      input: path.resolve(input),
+      output: path.resolve(output),
+      resize,
+      resized: Boolean(resize),
+      tempDir: options.keepTemp ? tempDir : undefined
+    };
+  } finally {
+    if (tempDir && !options.keepTemp) {
+      await fs.rm(tempDir, { force: true, recursive: true });
+    }
+  }
+}
+
+async function runAvifGainMapUtil(args, rawOptions = {}) {
+  if (!Array.isArray(args)) {
+    throw new TypeError('args must be an array.');
+  }
+  const options = normalizeConvertOptions(rawOptions);
+  const utilPath = assertToolAvailable(
+    resolveTool(TOOL_GAINMAP_UTIL, options),
+    TOOL_GAINMAP_UTIL
+  );
+  return runFile(utilPath, args.map(String), options);
+}
+
+module.exports = {
+  AvifGainMapError,
+  SUPPORTED_PLATFORM_KEYS,
+  convert: convertJpegGainMap,
+  convertJpegGainMap,
+  getPlatformKey,
+  runAvifGainMapUtil
+};

package/src/options.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const os = require('node:os');
+
+const DEFAULT_QUALITY = 80;
+const DEFAULT_GAIN_MAP_QUALITY = 60;
+const DEFAULT_SPEED = 6;
+
+function toInteger(name, value) {
+  if (typeof value === 'number' && Number.isInteger(value)) {
+    return value;
+  }
+  if (typeof value === 'string' && /^-?\d+$/.test(value.trim())) {
+    return Number(value);
+  }
+  throw new TypeError(`${name} must be an integer.`);
+}
+
+function integerInRange(name, value, min, max) {
+  const number = toInteger(name, value);
+  if (number < min || number > max) {
+    throw new RangeError(`${name} must be between ${min} and ${max}.`);
+  }
+  return number;
+}
+
+function optionalRange(name, value, min, max, fallback) {
+  if (value === undefined || value === null) {
+    return fallback;
+  }
+  return integerInRange(name, value, min, max);
+}
+
+function positiveInteger(name, value) {
+  const number = toInteger(name, value);
+  if (number < 1) {
+    throw new RangeError(`${name} must be greater than 0.`);
+  }
+  return number;
+}
+
+function optionalChoice(name, value, choices) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  const normalized = String(value);
+  if (!choices.includes(normalized)) {
+    throw new RangeError(`${name} must be one of: ${choices.join(', ')}.`);
+  }
+  return normalized;
+}
+
+function normalizeJobs(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (value === 'all') {
+    return typeof os.availableParallelism === 'function'
+      ? os.availableParallelism()
+      : Math.max(1, os.cpus().length);
+  }
+  return positiveInteger('jobs', value);
+}
+
+function normalizeSize(options) {
+  const width = options.width === undefined ? undefined : positiveInteger('width', options.width);
+  const height = options.height === undefined ? undefined : positiveInteger('height', options.height);
+  const maxWidth =
+    options.maxWidth === undefined ? undefined : positiveInteger('maxWidth', options.maxWidth);
+  const maxHeight =
+    options.maxHeight === undefined ? undefined : positiveInteger('maxHeight', options.maxHeight);
+
+  if ((width || height) && (maxWidth || maxHeight)) {
+    throw new Error('Use width/height or maxWidth/maxHeight, not both.');
+  }
+  if (!width && !height && !maxWidth && !maxHeight) {
+    return null;
+  }
+
+  return { width, height, maxWidth, maxHeight };
+}
+
+function normalizeConvertOptions(options = {}) {
+  const quality = optionalRange('quality', options.quality ?? options.qcolor, 0, 100, DEFAULT_QUALITY);
+  const gainMapQuality = optionalRange(
+    'gainMapQuality',
+    options.gainMapQuality ?? options.qgainMap,
+    0,
+    100,
+    DEFAULT_GAIN_MAP_QUALITY
+  );
+
+  return {
+    binDir: options.binDir,
+    cicp: options.cicp,
+    clli: options.clli,
+    cwd: options.cwd,
+    depth:
+      options.depth === undefined
+        ? undefined
+        : Number(optionalChoice('depth', options.depth, ['8', '10', '12'])),
+    env: options.env,
+    gainMapQuality,
+    intermediateGainMapQuality: optionalRange(
+      'intermediateGainMapQuality',
+      options.intermediateGainMapQuality,
+      0,
+      100,
+      100
+    ),
+    intermediateQuality: optionalRange(
+      'intermediateQuality',
+      options.intermediateQuality,
+      0,
+      100,
+      100
+    ),
+    jobs: normalizeJobs(options.jobs),
+    keepTemp: Boolean(options.keepTemp),
+    platformKey: options.platformKey,
+    quality,
+    signal: options.signal,
+    size: normalizeSize(options),
+    speed: optionalRange('speed', options.speed, 0, 10, DEFAULT_SPEED),
+    swapBase: Boolean(options.swapBase),
+    toolPaths: options.toolPaths,
+    verbose: Boolean(options.verbose),
+    yuv: optionalChoice('yuv', options.yuv, ['auto', '444', '422', '420', '400'])
+  };
+}
+
+module.exports = {
+  DEFAULT_GAIN_MAP_QUALITY,
+  DEFAULT_QUALITY,
+  DEFAULT_SPEED,
+  normalizeConvertOptions,
+  normalizeJobs,
+  normalizeSize
+};

package/src/platform.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TOOL_GAINMAP_UTIL = 'avifgainmaputil';
+const TOOL_GAINMAP_RESIZE = 'avifgainmapresize';
+const TOOL_NAMES = Object.freeze([TOOL_GAINMAP_UTIL, TOOL_GAINMAP_RESIZE]);
+
+const SUPPORTED_PLATFORM_KEYS = Object.freeze([
+  'darwin-arm64',
+  'darwin-x64',
+  'linux-arm64',
+  'linux-x64',
+  'win32-x64'
+]);
+
+function packageRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+function getPlatformKey({ platform = process.platform, arch = process.arch } = {}) {
+  const key = `${platform}-${arch}`;
+  if (!SUPPORTED_PLATFORM_KEYS.includes(key)) {
+    throw new Error(
+      `Unsupported platform ${key}. Supported platforms: ${SUPPORTED_PLATFORM_KEYS.join(', ')}`
+    );
+  }
+  return key;
+}
+
+function executableName(tool, platformKey = getPlatformKey()) {
+  if (!TOOL_NAMES.includes(tool)) {
+    throw new Error(`Unknown native tool "${tool}".`);
+  }
+  return platformKey.startsWith('win32-') ? `${tool}.exe` : tool;
+}
+
+function vendorDir(platformKey = getPlatformKey()) {
+  return path.join(packageRoot(), 'vendor', platformKey);
+}
+
+function resolveTool(tool, options = {}) {
+  if (!TOOL_NAMES.includes(tool)) {
+    throw new Error(`Unknown native tool "${tool}".`);
+  }
+
+  const platformKey = options.platformKey || getPlatformKey();
+  const toolPaths = options.toolPaths || {};
+  if (toolPaths[tool]) {
+    return path.resolve(toolPaths[tool]);
+  }
+
+  const envName =
+    tool === TOOL_GAINMAP_UTIL ? 'AVIF_GAINMAPUTIL_PATH' : 'AVIF_GAINMAPRESIZE_PATH';
+  if (process.env[envName]) {
+    return path.resolve(process.env[envName]);
+  }
+
+  const binDir = options.binDir || process.env.AVIF_GAINMAP_BIN_DIR;
+  if (binDir) {
+    return path.resolve(binDir, executableName(tool, platformKey));
+  }
+
+  return path.join(vendorDir(platformKey), executableName(tool, platformKey));
+}
+
+function assertToolAvailable(toolPath, tool) {
+  if (!fs.existsSync(toolPath)) {
+    throw new Error(
+      `${tool} binary was not found at ${toolPath}. ` +
+        'Run the GitHub Actions release workflow, npm run build:libavif, or set AVIF_GAINMAP_BIN_DIR.'
+    );
+  }
+  return toolPath;
+}
+
+module.exports = {
+  SUPPORTED_PLATFORM_KEYS,
+  TOOL_GAINMAP_RESIZE,
+  TOOL_GAINMAP_UTIL,
+  TOOL_NAMES,
+  assertToolAvailable,
+  executableName,
+  getPlatformKey,
+  packageRoot,
+  resolveTool,
+  vendorDir
+};

package/src/process.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+
+class AvifGainMapError extends Error {
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = 'AvifGainMapError';
+    this.command = detail.command;
+    this.args = detail.args;
+    this.exitCode = detail.exitCode;
+    this.signal = detail.signal;
+    this.stdout = detail.stdout || '';
+    this.stderr = detail.stderr || '';
+    if (detail.cause) {
+      this.cause = detail.cause;
+    }
+  }
+}
+
+function runFile(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: { ...process.env, ...options.env },
+      signal: options.signal,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+      if (options.verbose) {
+        process.stdout.write(chunk);
+      }
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+      if (options.verbose) {
+        process.stderr.write(chunk);
+      }
+    });
+
+    child.on('error', (cause) => {
+      reject(
+        new AvifGainMapError(`Failed to start ${command}: ${cause.message}`, {
+          args,
+          cause,
+          command,
+          stderr,
+          stdout
+        })
+      );
+    });
+
+    child.on('close', (exitCode, signal) => {
+      const result = { args, command, exitCode, signal, stderr, stdout };
+      if (exitCode === 0) {
+        resolve(result);
+        return;
+      }
+      reject(
+        new AvifGainMapError(`${command} exited with code ${exitCode}.`, {
+          ...result
+        })
+      );
+    });
+  });
+}
+
+module.exports = {
+  AvifGainMapError,
+  runFile
+};