magick-tui

A 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.

Features

• 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

Requirements

• Bun runtime
• ImageMagick (for image processing)

Installation

Option 1: Install via Bun (Recommended)

Note: Requires Bun to be installed.

# Global install
bun install -g @jsdr/magick-tui

# Run once without installing
bunx @jsdr/magick-tui

Option 2: Download Pre-built Binary

Download the latest release for your platform and add it to your PATH:

macOS (Apple Silicon)

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)

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:

export PATH="$HOME/.local/bin:$PATH"

Option 3: Install from Source (Development)

git clone https://github.com/Jensderond/magick-tui.git
cd magick-tui
bun install

Usage

Start the Application

bun start

Or for development with hot reload:

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.

How It Works

• 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

Requirements for FFI Mode

• ImageMagick 7.x with libMagickWand library installed
• Supported Platforms:
  • macOS ARM64 (Apple Silicon)
  • Linux x86-64

Environment Variables

| 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 |

Usage Examples

# Use FFI (default)
bun run src/index.tsx

# Force shell mode
MAGICK_USE_FFI=false bun run src/index.tsx

# Custom library path
MAGICK_WAND_LIBRARY_PATH=/custom/path/libMagickWand.so bun run src/index.tsx

Performance

Based on benchmarks, FFI mode provides:

• Dimension reading: ~2-4x faster
• Image conversion: ~1.5-2x faster

Run benchmarks yourself:

bun test src/utils/__tests__/performance.bench.ts

Troubleshooting

ImageMagick Not Found

Ensure ImageMagick is properly installed and in your system PATH. Try:

which magick  # Check if ImageMagick is installed

FFI Library Not Found

If you see FFI-related errors, the libMagickWand library may not be in the expected location:

# macOS (Homebrew)
ls /opt/homebrew/lib/libMagickWand-7.Q16HDRI.dylib

# Linux
ls /usr/lib/x86_64-linux-gnu/libMagickWand-7.Q16HDRI.so

You can set a custom path:

export MAGICK_WAND_LIBRARY_PATH=/path/to/libMagickWand.dylib

Or disable FFI mode to use shell execution:

export MAGICK_USE_FFI=false

Permission Denied

Make sure you have write permissions in the current directory.

Disk Space Issues

Ensure you have enough free disk space for the converted images. Converted files are created in the same directory.

License

MIT

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.