169 lines
7.1 KiB
Markdown
169 lines
7.1 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
sudo dnf config-manager --add-repo https://git.ewenlau.net/ewenlau/convertis/raw/branch/main/repo/gitea-ewenlau.repo
|
|
```
|
|
|
|
On Fedora 41+:
|
|
|
|
```sh
|
|
sudo dnf config-manager addrepo --from-repofile=https://git.ewenlau.net/ewenlau/convertis/raw/branch/main/repo/gitea-ewenlau.repo
|
|
```
|
|
|
|
On SUSE distros:
|
|
|
|
```sh
|
|
sudo zypper addrepo -f https://git.ewenlau.net/ewenlau/convertis/raw/branch/main/repo/gitea-ewenlau.repo
|
|
```
|
|
|
|
Then, install the package:
|
|
|
|
On RedHat/Fedora:
|
|
```sh
|
|
sudo dnf install convertis
|
|
```
|
|
|
|
On SUSE distros:
|
|
```sh
|
|
sudo zypper install convertis
|
|
```
|
|
|
|
#### APT
|
|
|
|
Add the repo:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
sudo apt install convertis
|
|
```
|
|
|
|
If you want to install a specific version, append `=<version-number>-1`. For instance, to install version 0.3.0:
|
|
|
|
```sh
|
|
sudo apt install convertis=0.3.0-1
|
|
```
|
|
|
|
Then install only the plugins you need. Each plugin is a separate package:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
cargo build --release --package convertis
|
|
```
|
|
|
|
Build all plugins when working on the complete workspace, or build one plugin by package name:
|
|
|
|
```sh
|
|
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](LICENSE).
|