7.1 KiB
Convertis
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
Every plugin is independently versioned and published, so updating one converter does not rebuild or replace unrelated plugins.
When no installed route can perform a conversion, Convertis prints the individual package or packages that provide one.
Raw release
The release page contains the raw x86_64-unknown-linux-gnu engine executable. Plugins are released independently through the package repositories when their own source and version change. Plugin .so files can be placed beside the executable, in a plugins/ directory beside it, in ~/.local/lib/convertis/plugins, or in /usr/lib/convertis/plugins.
Plugins use the stable API v2 wire protocol. Plugin and engine release numbers are independent: compatibility is determined by the advertised API, not by matching package or compiler versions. API v1 and its unstable Rust ABI are no longer supported.
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 --plugin-api
convertis --help
--plugin-api prints the API supported by the engine. --list-plugins includes the independent release version, negotiated API, and engine release each loaded plugin was designed against.
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 without building plugins:
cargo build --release --package convertis
Build all plugins when working on the complete workspace, or build one plugin by package name:
cargo build --release --workspace
cargo build --release --package convertis-native-image
The engine is target/release/convertis; plugin libraries are target/release/libconvertis_*.so. Workspace membership uses plugins/*, so a new plugin directory is discovered automatically.
Plugin API
The independently versioned convertis-plugin-api 2.x crate defines the plugin authoring trait and exports it through stable API 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;
- the engine release current when the plugin was last updated;
- 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.
API versions are compatibility contracts, not Convertis or plugin release numbers. API v2 is the sole supported baseline and is kept compatible through additive JSON changes. The official plugin crates are the reference implementations through the export_plugin! macro.
Each plugin declares its own package version and release metadata in its local Cargo.toml; initial plugin releases start at 0.1.0. Gitea Actions discovers changed plugins/* directories and builds, packages, and publishes a plugin only when its version changed and does not contain -dev. Unchanged and development versions are skipped. No workflow matrix or workspace member list needs updating when another plugin directory is added.
At build time, the plugin manifest automatically records the latest stable engine version (or the stable engine version being released in the same revision) as its design target. This is informational: runtime compatibility remains governed by the plugin API version.
Engine releases follow the same rule: the release workflow runs only when the workspace version in Cargo.toml changed and does not contain -dev.
Engine packages provide the virtual capability convertis-plugin-api-2; independently released plugin packages depend on that capability instead of an exact engine package version.
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.