Convertis 0.3 is a modular Linux CLI for routing files through independently installed conversion plugins. The base convertis package contains the engine and no converters.

Installation

Via repository

Convertis is available on GNU/Linux for Debian-based systems and Fedora/CentOS-based systems via my Gitea repository.

The repository contains the convertis engine and each official plugin as a separate package.

RPM

Add the RPM repository using the checked-in .repo file. This file configures both the package registry and the correct package-signing key.

On RedHat distros:

sudo dnf config-manager --add-repo https://git.ewenlau.net/ewenlau/convertis/raw/branch/main/repo/gitea-ewenlau.repo

On Fedora 41+:

sudo dnf config-manager addrepo --from-repofile=https://git.ewenlau.net/ewenlau/convertis/raw/branch/main/repo/gitea-ewenlau.repo

On SUSE distros:

sudo zypper addrepo -f https://git.ewenlau.net/ewenlau/convertis/raw/branch/main/repo/gitea-ewenlau.repo

Then, install the package:

On RedHat/Fedora:

sudo dnf install convertis

On SUSE distros:

sudo zypper install convertis

APT

Add the repo:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl https://git.ewenlau.net/api/packages/ewenlau/debian/repository.key -o /etc/apt/keyrings/gitea-ewenlau.asc
echo "deb [signed-by=/etc/apt/keyrings/gitea-ewenlau.asc] https://git.ewenlau.net/api/packages/ewenlau/debian debian main" | sudo tee /etc/apt/sources.list.d/gitea-ewenlau.list
sudo apt update

Then, install the package:

sudo apt install convertis

If you want to install a specific version, append =<version-number>-1. For instance, to install version 0.3.0:

sudo apt install convertis=0.3.0-1

Then install only the plugins you need. Each plugin is a separate package:

sudo apt install convertis-native-image
sudo apt install convertis-ffmpeg-video convertis-ffmpeg-audio

Convenience bundles are available:

convertis-ffmpeg: all FFmpeg plugins, including frame extraction and assembly.
convertis-image: native image, ASCII, ImageMagick, and GraphicsMagick plugins.
convertis-plugins-all: every official plugin.

When no installed route can perform a conversion, Convertis prints the individual package or packages that provide one.

Raw release

The release page contains a raw x86_64-unknown-linux-gnu executable and one ZIP containing all official .so plugins. Extract its plugins/ directory beside the executable. Plugins can also be placed directly beside the executable, in ~/.local/lib/convertis/plugins, or in /usr/lib/convertis/plugins.

Plugins use a version-negotiated wire protocol. A plugin advertises the protocol versions it speaks and an open-ended engine requirement (for example >=0.3.0-dev); the engine selects the newest protocol adapter both sides support. Engine releases are therefore decoupled from plugin releases, and a protocol-v2 plugin built today remains usable by future engines that retain the v2 adapter.

Plugins built for the original protocol v1 are still recognized by a permanent legacy adapter. Because v1 passed Rust trait objects across the dynamic-library boundary, those old binaries must also match the engine's Rust compiler and target. Protocol v2 uses JSON over a C ABI and has no Rust compiler-version coupling.

Usage

convertis input.png output.ico
convertis input.mp4 frames/ --to frames
convertis frames/ output.mp4
convertis input.png output.txt --option width=120

Input formats are detected from file contents. The output extension indicates the requested target and can be overridden with --to. Use --from only when content detection cannot recognize a format.

Frame extraction creates numbered images and .convertis-frames.json, which preserves the source frame rate and timing for the frames-to-video plugin. External frame folders without metadata use lexical ordering and 30 FPS by default.

Useful inspection commands:

convertis --list-plugins
convertis --list-formats
convertis --help

Logging is controlled with --verbose LEVEL (or -v LEVEL). trace records plugin-directory discovery, manifest parsing and protocol negotiation, every format-identification rule, graph construction and route-search decision, option resolution, each plugin request, and filesystem staging/install operations:

convertis -v trace input.png output.webp

Logs go to standard error, so converted bytes written to standard output remain clean. --quiet disables logging.

Use --no-default-plugins with explicit --plugin-dir arguments to run in an isolated plugin environment.

Plugin settings use repeatable --option key=value arguments. A plugin-qualified key such as ffmpeg-frames-to-video.fps=24 can disambiguate settings in a multi-plugin route.

Building

Build the engine and every official plugin:

cargo build --release --workspace

The engine is target/release/convertis; plugins are target/release/libconvertis_*.so.

Plugin API

The workspace crate convertis-plugin-api defines the plugin authoring trait and exports it through stable protocol v2. Its unversioned manifest entry point advertises:

the manifest schema version;
every wire-protocol version implemented by the plugin;
the plugin ID and release version;
an open-ended semantic-version requirement for the engine;
the target platform.

Metadata, availability checks, and conversion requests cross the library boundary as owned JSON messages through versioned C entry points. Returned strings are released by the plugin's matching deallocator, and plugin panics are converted to protocol errors instead of unwinding across the ABI boundary.

Protocol versions are compatibility contracts, not Convertis release numbers. Existing adapters are retained by future engines; incompatible protocol evolution is introduced under a new version and selected through manifest negotiation. New optional JSON fields may be added without requiring a protocol bump. The official plugin crates are the reference implementations through the export_plugin! macro.

Platforms

Version 0.3 supports 64-bit GNU/Linux. Windows and musl builds are intentionally sunset for now.

License

Convertis is licensed under GPL-3.0-only. See LICENSE.