convert-rs 0.2.0

Extensible file conversion library with graph routing and optional native tools
Documentation

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:

[dependencies]
convert-rs = "0.1"

Convert a file and copy the result while the report is alive:

use std::fs;
use std::path::PathBuf;

use convert_rs::{ConversionOptions, Converter};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let converter = Converter::new();
    let report = converter
        .convert(
            &[PathBuf::from("input.png")],
            "jpeg",
            &ConversionOptions::default(),
        )
        .await?;
    fs::copy(&report.artifacts[0].path, "output.jpg")?;
    Ok(())
}

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.

cargo run -p convert-rs-cli -- formats
cargo run -p convert-rs-cli -- convert input.png --to jpeg --output output.jpg

Use native tools only for trusted inputs:

cargo run -p convert-rs-cli -- convert input.pdf --to txt \
  --allow-external --output output.txt

The command refuses to overwrite an existing output file. Without --output, it writes returned artifacts to the current directory.

Library

use std::path::PathBuf;

use convert_rs::{ConversionOptions, Converter};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let converter = Converter::new();
    let report = converter
        .convert(
            &[PathBuf::from("input.png")],
            "jpeg",
            &ConversionOptions::default(),
        )
        .await?;
    println!("{}", report.artifacts[0].path.display());
    Ok(())
}

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 selected Plan, final Artifact values, and non-fatal Warning values. 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:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps --locked
cargo test --workspace --all-features --locked
cargo package --workspace --all-features --locked

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.