refactor: restructure project into a workspace by introducing a plugin API crate and modularizing individual plugin definitions.
This commit is contained in:
Elias Wendland committed
1 parent
2ea317e117
commit
eb76ed1937
43 files changed
+4243
-2296
No files matched your search
@@ -1,111 +1,81 @@
|
||||
# Convertis
|
||||
|
||||
## Description
|
||||
|
||||
Convertis is a CLI tool to convert files from one format to another. It's main design goal is to be able to convert *any* format to *any* other format, including different types, like MP4 to JPEG, MP4 to MP3 and in the future more exotic paths like HTML to JPEG or PNG to ZIP.
|
||||
|
||||
As it attemps to effectively cover an infinite number of possible conversions, it uses a pathfinding algorithm, that may include multiple conversions before reaching the target goal.
|
||||
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
|
||||
|
||||
Convertis can be installed in a few ways.
|
||||
|
||||
Note: Convertis has three different targets "gnu", "musl" and "windows". The "gnu" build targets regular GNU/Linux systems, the "musl" build targets systems using the musl C standard library and the "windows" build targets windows systems. Only the "gnu" build is actively tested.
|
||||
|
||||
### Via repository
|
||||
|
||||
Convertis is available on GNU/Linux for Debian-based systems and Fedora/CentOS-based systems via my gitea repository.
|
||||
|
||||
Packages are published for both the gnu and musl targets, although the gnu build should always be preferred.
|
||||
|
||||
#### RPM
|
||||
|
||||
Add the RPM repo via the .repo file:
|
||||
|
||||
On RedHat distros:
|
||||
Install the engine first:
|
||||
|
||||
```sh
|
||||
dnf config-manager --add-repo https://git.ewenlau.net/ewenlau/convertis/raw/branch/main/repo/gitea-ewenlau.repo
|
||||
sudo apt install convertis
|
||||
# or
|
||||
sudo dnf install convertis
|
||||
```
|
||||
|
||||
On Fedora 41+:
|
||||
Then install only the plugins you need. Each plugin is a separate package:
|
||||
|
||||
```sh
|
||||
dnf config-manager addrepo --from-repofile=https://git.ewenlau.net/ewenlau/convertis/raw/branch/main/repo/gitea-ewenlau.repo
|
||||
sudo apt install convertis-native-image
|
||||
sudo apt install convertis-ffmpeg-video convertis-ffmpeg-audio
|
||||
```
|
||||
|
||||
On SUSE distros:
|
||||
Convenience bundles are available:
|
||||
|
||||
```sh
|
||||
zypper addrepo -f https://git.ewenlau.net/ewenlau/convertis/raw/branch/main/repo/gitea-ewenlau.repo
|
||||
```
|
||||
- `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.
|
||||
|
||||
Then, install the package:
|
||||
When no installed route can perform a conversion, Convertis prints the individual package or packages that provide one.
|
||||
|
||||
On RedHat/Fedora:
|
||||
```sh
|
||||
dnf install convertis-gnu
|
||||
```
|
||||
### Raw release
|
||||
|
||||
On SUSE distros:
|
||||
```sh
|
||||
zypper install convertis-gnu
|
||||
```
|
||||
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`.
|
||||
|
||||
#### APT
|
||||
|
||||
Add the repo:
|
||||
|
||||
```sh
|
||||
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 $distribution $component" | sudo tee -a /etc/apt/sources.list.d/gitea.list
|
||||
sudo apt update
|
||||
```
|
||||
|
||||
Then, install the package:
|
||||
|
||||
```sh
|
||||
sudo apt install convertis-gnu
|
||||
```
|
||||
|
||||
If you want to install a specific version, append =<version-number>-1. For instance, to install version 0.2.0:
|
||||
|
||||
```sh
|
||||
sudo apt install convertis-gnu=0.2.0-1
|
||||
```
|
||||
|
||||
### Manual package install
|
||||
|
||||
You may download a .deb file for Debian-based systems and a .rpm file for Fedora/CentOS-based systems from the releases page. You can then install the package using your system's package manager.
|
||||
|
||||
See <https://git.ewenlau.net/ewenlau/convertis/releases>
|
||||
|
||||
### Binary download
|
||||
|
||||
If you use Windows, do not use a supported linux system or do not want to install any packages, you can download a binary release from the releases page.
|
||||
|
||||
See <https://git.ewenlau.net/ewenlau/convertis/releases>
|
||||
|
||||
## Building
|
||||
|
||||
Building convertis is simple, you just need the Rust toolchain installed:
|
||||
|
||||
```sh
|
||||
cargo build --release
|
||||
```
|
||||
Plugins use an exact-version Rust ABI. A plugin must have been built for the same Convertis release; incompatible libraries are rejected before loading.
|
||||
|
||||
## Usage
|
||||
|
||||
```sh
|
||||
convertis <input> <output> [options]
|
||||
convertis input.png output.ico
|
||||
convertis input.mp4 frames/ --to frames
|
||||
convertis frames/ output.mp4
|
||||
convertis input.png output.txt --option width=120
|
||||
```
|
||||
|
||||
Options are available with the --help flag:
|
||||
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 --help
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
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 exact-version Rust trait used by official plugins. Plugin metadata is checked through a small C-compatible entry point before the Rust factory is called. The official plugin crates are the reference examples; ABI compatibility across Convertis releases is not promised.
|
||||
|
||||
## Platforms
|
||||
|
||||
Version 0.3 supports 64-bit GNU/Linux. Windows and musl builds are intentionally sunset for now.
|
||||
|
||||
## License
|
||||
|
||||
Convertis is licensed under the GNU General Public License v3.0 exclusively. See LICENSE for more details.
|
||||
Convertis is licensed under GPL-3.0-only. See [LICENSE](LICENSE).
|
||||
Reference in new issue
Block a user