動作環境・トラブルシューティング

---

動作環境

ランタイム	macOS arm64	macOS x64（Intel）	Linux x86_64	Linux arm64	Windows x64
Node.js 18+	対象	対象	対象	対象	対象
Bun	対象	対象	対象	対象	対象
Deno 2.x	対象	対象	対象	対象	対象

各プラットフォームのバイナリは optional パッケージ（zenpix-darwin-arm64 など）として自動選択されます。「対象」は公開packageとCI workflowの対象を示します。

公開済み1.0.4のoptional packageは、arm64ではRGBA resizeにNEON、x86_64ではSSE2をbuild時に選び、その他はscalarへfallbackします。5環境のworkflowでSIMD版と強制scalar版をbuild・testし、直前のbuild出力をpackしてSHA256一致、runtime依存、Node.js / Bun / Deno API、CLI実変換を検査しました。同じtarballをnpmへ公開し、全packageのregistry metadataとintegrity、macOS arm64のregistry再installとAPI / CLI実変換を確認済みです。

公開済みmacOS 1.0.4はcodecを静的リンクし、macOS 12.0をdeployment targetにしています。Linux 1.0.4はglibc 2.34以上を対象とし、CIでGLIBC_2.34より新しいsymbol参照を拒否します。Windows x64はVC++ Redistributableが必要になる場合があります。

非対応環境:

• Alpine Linux（musl）: glibc 前提のため非対応
• Cloudflare Workers: CPU 制限により非対応
• Windows on ARM64: 公式同梱なし（ZENPIX_LIB で手元ビルドの libpict.dll を指定することで利用可能）

---

npm パッケージ構成

zenpix                      # ルート（JS + CLI）
  ├── zenpix-darwin-arm64   # optional: libpict.dylib（Apple Silicon）
  ├── zenpix-darwin-x64     # optional: libpict.dylib（Intel Mac）
  ├── zenpix-linux-x64      # optional: libpict.so
  ├── zenpix-linux-arm64    # optional: libpict.so（ARM サーバー）
  └── zenpix-win32-x64      # optional: libpict.dll

---

トラブルシューティング

encodeAvif() が常に null を返す

quality / speed が範囲外のとき null を返します：

// NG
encodeAvif(image, { quality: 60, speed: 11 }); // → null

// OK
encodeAvif(image, { quality: 60, speed: 10 }); // → Buffer

Error: Cannot find module 'zenpix-darwin-arm64'

対応していない OS・アーキテクチャです。optional パッケージが入らなかった場合：

npm install zenpix --include=optional

zenpix: decode failed

• HEIC / HEIF → decodeHeic() を使ってください（macOS・Linux のみ対応）
• アニメーション WebP → 非対応
• アニメーション GIF → 先頭フレームのみ RGB 出力

Deno で --allow-ffi が必要

deno run --allow-ffi --allow-read your-script.ts

通常経路では環境変数の権限は不要です。optionalな上書きを使う場合だけ追加します。

ZENPIX_LIB=/path/to/libpict.dylib deno run --allow-ffi --allow-read --allow-env=ZENPIX_LIB your-script.ts

Windows で libpict.dll の読み込みに失敗

VC++ 再頒布可能パッケージ（x64）が必要な場合があります。WSL2 では Linux バイナリが使われます。

---

ローカルビルドのバイナリを使う

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel
# → build/libpict.{dylib,so}

# SIMDを無効にした正解基準build
cmake -S . -B build-scalar -DCMAKE_BUILD_TYPE=Release -DZENPIX_ENABLE_SIMD=OFF
cmake --build build-scalar --parallel
ZENPIX_LIB=/path/to/libpict.dylib node your-script.js

libpict の解決順：ZENPIX_LIB 環境変数 → build/libpict.* → optionalDependencies

ZENPIX_ENABLE_SIMDは既定でON、ZENPIX_BUILD_TESTSとZENPIX_MARCH_NATIVEは既定でOFFです。ZENPIX_MARCH_NATIVEはローカル測定用であり、配布buildでは有効にしません。