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.

!magick-tui screenshot

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

$3

Note: Requires Bun to be installed.

``bash


Global install

bun install -g @jsdr/magick-tui

Run once without installing

bunx @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.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
`

$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.dylib

Linux

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

$3

Make sure you have write permissions in the current directory.

$3

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.