optimo

optimo

optimo は、形式に応じた圧縮パイプラインを使用してメディアのサイズを縮小します。

前提条件

optimo は PATH から圧縮ツールを解決し、必要なバイナリが見つからない場合はエラーをスローします。

形式ごとに必要なもの：

• ImageMagick を使用するすべての形式：magick
• SVG パイプライン：svgo
• JPEG の第 2 パス：mozjpegtran または jpegtran
• GIF の第 2 パス：gifsicle
• 動画パイプライン：ffmpeg

クイックスタート（CLI）

単発で実行する場合は npx を使用します。

npx -y optimo public/media

単一ファイルを最適化します：

npx -y optimo public/media/banner.png

画像の EXIF メタデータを保持します：

npx -y optimo public/media/banner.jpg --preserve-exif # long version
npx -y optimo public/media/banner.jpg -p # short version

ドライランを実行します（ファイルは変更されません）：

npx -y optimo public/media/banner.png --dry-run # long version
npx -y optimo public/media/banner.png -d # short version

非可逆圧縮モードを有効にします：

npx -y optimo public/media/banner.jpg --lossy # long version
npx -y optimo public/media/banner.jpg -l # short version

新しい形式に変換して最適化します：

npx -y optimo public/media/banner.png --format jpeg # long version
npx -y optimo public/media/banner.png -f jpeg # short version

動画を最適化します：

npx -y optimo public/media/clip.mp4

動画形式を変換します：

npx -y optimo public/media/clip.mov --format webm

動画の音声トラックをミュートします（デフォルトですでにミュートされています）：

npx -y optimo public/media/clip.mp4 --mute # explicit true
npx -y optimo public/media/clip.mp4 --mute false # keep audio

パーセンテージでサイズを変更します：

npx -y optimo public/media/banner.png --resize 50% # long version
npx -y optimo public/media/banner.png -r 50% # short version

目標ファイルサイズに合わせてサイズを変更します（画像のみ）：

npx -y optimo public/media/banner.png --resize 100kB # long version
npx -y optimo public/media/banner.png -r 100kB # short version

幅を指定してサイズを変更します：

npx -y optimo public/media/banner.png --resize w960 # long version
npx -y optimo public/media/banner.png -r w960 # short version

高さを指定してサイズを変更します：

npx -y optimo public/media/banner.png --resize h480 # long version
npx -y optimo public/media/banner.png -r h480 # short version

最適化した画像をデータ URL として出力します（単一の画像ファイルのみ）：

npx -y optimo public/media/banner.png --data-url # long version
npx -y optimo public/media/banner.png -u # short version

詳細なデバッグを有効にします：

npx -y optimo public/media/banner.heic --dry-run --verbose # long version
npx -y optimo public/media/banner.heic -d -v # short version

パイプライン

optimo は出力形式に応じてパイプラインを選択します。

• .png -> magick.png
• .svg -> svgo.svg
• .jpg/.jpeg -> magick.jpg/jpeg + mozjpegtran.jpg/jpeg（サイズ変更や変換を行わない可逆 JPEG では magick をスキップし、mozjpegtran のみを実行します）
• .gif -> magick.gif + gifsicle.gif
• その他の画像形式（webp、avif、heic、heif、jxl など） -> magick.<format>
• 動画形式（mp4、m4v、mov、webm、mkv、avi、ogv） -> ffmpeg.<format>

モードの動作：

• デフォルト：可逆圧縮を優先するパイプライン
• 画像のデフォルト動作では、ファイルサイズを小さくするためメタデータ／EXIF を削除します
• --lossy / -l：対応している形式で非可逆圧縮と可逆圧縮を実行します
• --mute / -m：動画から音声トラックを削除します（デフォルト：true。音声を保持するには --mute false を渡します）
• --preserve-exif / -p：出力で画像の EXIF メタデータを保持します

推奨ワークフロー

1. --dry-run で対象ファイルを確認します。
2. まず 1 つのファイルで最適化を実行し、その後ディレクトリに適用します。
3. 変換する場合に限り --format を使用します。
4. 寸法やサイズを明示的に制御する必要がある場合に限り --resize を使用します。
5. 動画では --resize 100kB はサポートされない点に注意してください。50%、w960、または h480 を使用します。
6. サポートされていないファイルやバイナリ／フラグの問題を調査する場合は、--verbose を使用します。
7. コミットする前に、バージョン管理システムで出力を確認します。

CLI オプション

• -d、--dry-run：ファイルを書き込まずに、変更内容を表示します。
• -f、--format：出力形式を変換します（jpeg、webp、avif など）。
• -l、--lossy：非可逆圧縮と可逆圧縮のパスを有効にします。
• -m、--mute：動画から音声トラックを削除します（デフォルト：true。音声を保持するには --mute false を使用します）。
• -p、--preserve-exif：画像の EXIF メタデータを保持します（デフォルト：false）。
• -r、--resize：パーセンテージ（50%）、最大ファイルサイズ（100kB、画像のみ）、幅（w960）、または高さ（h480）を指定してサイズを変更します。
• -s、--silent：ファイルごとのログを抑制します。
• -u、--data-url：最適化した画像をデータ URL として返します（単一の画像ファイルのみ）。
• -v、--verbose：デバッグログを出力します（パイプラインの選択、コマンドの実行、エラー）。

プログラムからの API の使用

const optimo = require('optimo')

await optimo.file('/absolute/path/image.jpg', {
  dryRun: false,
  lossy: false,
  preserveExif: false, // default
  format: 'webp',
  resize: '50%',
  onLogs: console.log
})

await optimo.file('/absolute/path/image.jpg', {
  preserveExif: true, // keep EXIF metadata
  onLogs: console.log
})

await optimo.file('/absolute/path/image.jpg', {
  resize: '100kB',
  onLogs: console.log
})

await optimo.file('/absolute/path/image.jpg', {
  resize: 'w960',
  onLogs: console.log
})

const { dataUrl } = await optimo.file('/absolute/path/image.png', {
  dataUrl: true,
  onLogs: console.log
})
// dataUrl is a base64 data URL string (images only, single file)

await optimo.file('/absolute/path/video.mp4', {
  lossy: false,
  mute: false, // true by default for videos
  format: 'webm',
  resize: 'w1280',
  onLogs: console.log
})

const result = await optimo.dir('/absolute/path/images')
console.log(result)
// { originalSize, optimizedSize, savings }

// Utility export
const { formatBytes } = require('optimo')
console.log(formatBytes(1024)) // '1 kB'

動作に関する注意事項

• 変換を行わない実行では、最適化後のファイルが小さくならない場合、元のファイルが保持されます。
• 変換時は新しい拡張子で出力され、（--dry-run を除き）元のファイルは削除されます。
• ディレクトリモードでは、隠しファイルと隠しフォルダー（名前が . で始まるもの）はスキップされます。
• サポートされていないファイルは [unsupported] として報告され、無視されます。
• 動画のデフォルト設定はウェブとの互換性を重視しています（yuv420p、該当する場合は高速起動 MP4）。
• 画像の出力ではデフォルトで EXIF メタデータが削除されます。保持するには --preserve-exif または preserveExif: true を使用します。
• --data-url は単一の画像ファイルでのみサポートされます（動画またはディレクトリモードではエラーがスローされます）。