convert-rs
convert-rs is a Rust library for routing files through format adapters. It
plans conversions as a graph, prefers integrated Rust adapters, validates every
intermediate artifact, and can discover selected native tools when explicitly
enabled. A small command-line application is included for direct use, but the
library API is the primary interface.
The API is at an initial stage. Conversion support depends on the enabled Cargo features and, for native adapters, the installed external tools.
Library Quick Start
Add the library to an application:
[]
= "0.1"
Convert a file and copy the result while the report is alive:
use fs;
use PathBuf;
use ;
async
Use Converter::discover().await for optional native adapters. Set
Policy::allow_external before converting. Native tools run with the process
permissions and are not a sandbox for hostile input.
Features
- Graph-based route planning with cost ordering and route retry.
- Pure Rust text, data, media, and archive adapters.
- Optional FFmpeg, ImageMagick, Poppler, LibreOffice, and Inkscape adapters.
- Input, output, archive, image, audio, memory, and timeout limits.
- Native tools disabled by policy unless external execution is enabled.
Quick Start
Build with Rust 1.97.1, pinned in rust-toolchain.toml.
Use native tools only for trusted inputs:
The command refuses to overwrite an existing output file. Without --output,
it writes returned artifacts to the current directory.
Library
use PathBuf;
use ;
async
Call Converter::discover() when the external feature is enabled and native
tools are desired. Set Policy::allow_external before conversion. The report
owns a temporary workspace; copy artifacts out while the report is alive.
Library API
The main types are:
Converter: registers adapters, identifies inputs, plans routes, and executes conversions.ConversionOptions: selects a source format, backend, or forced plan for one request.ConversionReport: contains the selectedPlan, finalArtifactvalues, and non-fatalWarningvalues. Its temporary workspace is deleted on drop.Policy: controls bridges, reinterpretation, packaging, external tools, decode-only formats, route count, step count, and graph search work.Limits: bounds input and output bytes, artifacts, decoded pixels, audio samples, archive entries, expansion ratio, memory, and step timeouts.Adapter: the extension point for application-defined formats and conversion operations.
Call Converter::plan before executing a conversion when the application must
inspect route costs or reject lossy and bridge steps. Call Converter::identify
when an application needs the detected format and identification method without
executing a conversion. Use ConversionOptions::backend to require a specific
adapter.
Conversion reports own their files. Read or copy every artifact before dropping the report. A failed route is discarded before the next route is attempted. All successful adapter output is checked for regular-file status, workspace containment, declared format, and output limits.
Cargo Features
| Feature | Adapters and dependencies |
|---|---|
data |
JSON, TOML, and CSV through serde_json, toml, and csv |
media |
Images through image, WAV through hound, FFT through rustfft, audio decoding through symphonia |
archives |
ZIP, TAR, and gzip through zip, tar, and flate2 |
external |
Native process adapters; no additional Rust dependency |
All features are enabled by default in the library and CLI packages.
Native Tools
| Adapter | Binary | Conversions |
|---|---|---|
| FFmpeg | ffmpeg |
Audio and video containers, video frames, still-image clips |
| ImageMagick | convert |
OpenEXR and PSD image conversions to and from raster formats |
| Poppler | pdftotext, pdftoppm |
PDF text extraction and first-page PNG rasterization |
| LibreOffice | soffice |
Office and OpenDocument files to PDF or text |
| Inkscape | inkscape |
SVG to PNG |
The adapter is registered only when its binary can be started. A delegate library required by a native tool may still be missing, in which case that route fails and the planner tries another route. Native tools execute with the current process permissions and are not a sandbox for hostile files.
Supported Formats
Built-in support includes JSON, TOML, CSV, PNG, JPEG, GIF, BMP, TIFF, WebP,
PNM, TGA, ICO, DDS, QOI, HDR, Farbfeld, WAV, ZIP, TAR, gzip, and related
archive routes. Native discovery adds video containers, additional audio
containers, PDF operations, Office and OpenDocument formats, SVG, PSD, and
OpenEXR according to the installed tools. Run convert-rs formats or inspect
Converter::formats() for the exact formats registered by a build.
Format IDs are stable within the library API. Extensions are aliases used for
identification and may differ from the format ID, such as jpg for jpeg.
Development
Check formatting, lints, packaged crates, and the full test matrix locally:
RUSTDOCFLAGS="-D warnings"
Set REQUIRE_NATIVE_TOOLS=1 to require native integration coverage instead of
skipping those tests.
Last Resort
--last-resort enables reinterpretation and archive packaging routes. These
routes can preserve bytes or express them through another representation, but
they do not establish semantic equivalence between unrelated formats. Binary
input that is not valid UTF-8 still fails the text decoder; callers should use
an explicit binary representation or a suitable media bridge when available.
License
AGPL-3.0-or-later. See LICENSE. The graph design is an independent implementation and does not copy source code from other conversion projects.