A powerful, interactive Terminal User Interface for image compression and conversion using ImageMagick
npm install @jsdr/magick-tuiA powerful, interactive Terminal User Interface (TUI) for image compression and conversion using ImageMagick. Easily convert and optimize images to modern formats like WebP and AVIF with an intuitive keyboard-driven interface.
- Interactive TUI - Keyboard-driven interface with intuitive navigation
- Multiple Format Support - Convert images to WebP and AVIF formats
- Quality Control - Choose from quality presets: Low (60), Medium (80), High (90), or Lossless (100)
- Image Resizing - Optional width and height resizing (no upscaling)
- Real-time Preview - See file sizes, dimensions, and conversion status in real-time
- Batch Operations - Process multiple images in your current directory
- Wide Format Support - Input: JPG, JPEG, PNG, WebP, AVIF, HEIC, HEIF, TIFF, BMP, GIF
- Bun runtime
- ImageMagick (for image processing)
Note: Requires Bun to be installed.
``bashGlobal install
bun install -g @jsdr/magick-tui
$3
Download the latest release for your platform and add it to your PATH:
#### macOS (Apple Silicon)
`bash
curl -L https://github.com/Jensderond/magick-tui/releases/latest/download/magick-tui-darwin-arm64 -o magick-tui
chmod +x magick-tui
mkdir -p ~/.local/bin
mv magick-tui ~/.local/bin/
`#### Linux (x64)
`bash
curl -L https://github.com/Jensderond/magick-tui/releases/latest/download/magick-tui-linux-x64 -o magick-tui
chmod +x magick-tui
mkdir -p ~/.local/bin
mv magick-tui ~/.local/bin/
`Note: Make sure
~/.local/bin is in your PATH. Add this to your ~/.bashrc or ~/.zshrc:
`bash
export PATH="$HOME/.local/bin:$PATH"
`$3
`bash
git clone https://github.com/Jensderond/magick-tui.git
cd magick-tui
bun install
`Usage
$3
`bash
bun start
`Or for development with hot reload:
`bash
bun run dev
`The interface is intuitive and too easy to explain—just launch it and explore!
Output
Converted images are saved in the same directory as the original file with the format appended to the filename:
`
input.jpg
├── input.webp (from WebP conversion)
└── input.avif (from AVIF conversion)
`How It Works
1. Scans the current directory for supported image formats
2. Displays file information including size and dimensions
3. Lets you select output formats, quality, and optional resizing
4. Uses ImageMagick to efficiently convert and compress images
5. Updates the file list to show newly created files
Technologies
- Solid.js - Reactive UI framework
- OpenTUI - Terminal UI library
- ImageMagick - Image processing
- Bun - JavaScript runtime
Tips & Best Practices
- Quality Selection: Use "Medium" (80) for a good balance of quality and file size
- AVIF Format: Modern format with excellent compression, best for newer browsers
- WebP Format: Wider browser support, good compression ratio
- Resizing: Always downscale images; upscaling is not permitted
- Batch Processing: Process images one at a time for better control
FFI Mode (Performance)
MagickTUI uses Bun's FFI (Foreign Function Interface) to directly interface with
libMagickWand for improved performance. This provides 1.5-4x faster operations compared to shell execution.$3
- FFI Mode (Default): Directly calls ImageMagick's C library for faster image processing
- Shell Fallback: Automatically falls back to the
magick CLI if FFI fails to load$3
- ImageMagick 7.x with
libMagickWand library installed
- Supported Platforms:
- macOS ARM64 (Apple Silicon)
- Linux x86-64$3
| Variable | Default | Description |
|----------|---------|-------------|
|
MAGICK_USE_FFI | true | Enable FFI mode (set to false for shell-only) |
| MAGICK_WAND_LIBRARY_PATH | (auto-detect) | Override the library path |$3
`bash
Use FFI (default)
bun run src/index.tsxForce shell mode
MAGICK_USE_FFI=false bun run src/index.tsxCustom library path
MAGICK_WAND_LIBRARY_PATH=/custom/path/libMagickWand.so bun run src/index.tsx
`$3
Based on benchmarks, FFI mode provides:
- Dimension reading: ~2-4x faster
- Image conversion: ~1.5-2x faster
Run benchmarks yourself:
`bash
bun test src/utils/__tests__/performance.bench.ts
`Troubleshooting
$3
Ensure ImageMagick is properly installed and in your system PATH. Try:
`bash
which magick # Check if ImageMagick is installed
`$3
If you see FFI-related errors, the libMagickWand library may not be in the expected location:
`bash
macOS (Homebrew)
ls /opt/homebrew/lib/libMagickWand-7.Q16HDRI.dylibLinux
ls /usr/lib/x86_64-linux-gnu/libMagickWand-7.Q16HDRI.so
`You can set a custom path:
`bash
export MAGICK_WAND_LIBRARY_PATH=/path/to/libMagickWand.dylib
`Or disable FFI mode to use shell execution:
`bash
export MAGICK_USE_FFI=false
``MIT
Contributions are welcome! Feel free to open issues or submit pull requests.