convertr

Русская версия

Universal file format converter. One binary, 50+ formats, CLI, TUI, Web UI, REST API, and automatic route selection.

convertr wraps pandoc, ffmpeg, LibreOffice, ImageMagick, jq, yq, Tesseract, csvkit, AsciiDoctor, Calibre, pdfcpu, and plugin backends behind one command:

convertr FILE -o OUT

It detects formats, checks installed backends, and picks a conversion route automatically. If no direct route exists, it can chain available tools.

Category	Formats
Documents	MD, DOCX, PDF, ODT, HTML, EPUB, RST, TeX, PPTX
Images	JPG, PNG, WebP, SVG, AVIF, HEIC, GIF
Video	MP4, MKV, WebM, AVI, MOV
Audio	MP3, FLAC, AAC, WAV, OGG
Data	JSON, YAML, TOML, CSV, XLSX
OCR	image to text through Tesseract

Why use it?

• One interface for documents, media, data, OCR, and PDF tools.
• Automatic routing over installed backend capabilities.
• Batch conversion with workers, retry policy, and conflict handling.
• Watch mode for converting files as they change.
• Unicode safety controls for Cyrillic PDF output and strict text-layer checks.
• TUI, built in Web UI, REST API, Docker image, and plugin protocol.

Install

Go

go install github.com/Mark1708/convertr/cmd/convertr@latest

Requires Go 1.25+.

Homebrew

brew install mark1708/tap/convertr

Source

git clone https://github.com/Mark1708/convertr.git
cd convertr
go build -o ~/.local/bin/convertr ./cmd/convertr

Backend tools

Install common conversion tools:

# macOS
./scripts/install-deps-macos.sh

# Debian or Ubuntu
./scripts/install-deps-linux.sh

Check what is available:

convertr version
convertr doctor

doctor prints installed tools, versions, paths, and install hints for missing backends.

First conversion

# Format is inferred from extensions.
convertr report.docx -o report.md

# Target format can be explicit.
convertr notes.md --to pdf -o notes.pdf

# Require Unicode-safe PDF text when Cyrillic is detected.
convertr notes.md --to pdf -o notes.pdf --unicode-mode strict

# Stdin to stdout.
cat data.json | convertr - --from json --to yaml -o -

Common workflows

# Convert a directory recursively.
convertr -r ./docs -o ./out --to md --mkdir

# Use 4 workers and retry failed jobs.
convertr -r ./inbox -o ./outbox --to pdf -j 4 --on-error retry --mkdir

# Preview the plan without writing files.
convertr -r ./docs -o ./out --to md --dry-run

# Prefer higher fidelity routes.
convertr source.docx -o out.pdf --route-policy quality

# Reject lossy route edges.
convertr image.png -o out.webp --avoid-lossy

# Limit route length.
convertr source.md -o out.pdf --max-hops 2

# Watch a directory and convert on every change.
convertr watch ./inbox -o ./outbox --to md

# Inspect formats and the conversion graph.
convertr formats
convertr formats --dot | dot -Tsvg > /tmp/formats.svg

More examples are in docs/workflows.md.

Interfaces

CLI

The CLI is the default interface for single files, batches, watch mode, PDF tools, backend checks, config, and plugins.

convertr --help
convertr backends list
convertr pdf merge -o bundle.pdf a.pdf b.pdf

Full reference: docs/cli.md.

Web UI and REST API

convertr serve
convertr serve --addr 127.0.0.1:8080

The browser UI supports uploads, route preview, Unicode safety selection, downloads, backend status, and PDF tools. Use --api-only when you only need the REST API.

• Web UI guide: docs/web-ui.md
• REST API: docs/api.md

TUI

convertr tui

Use the terminal UI to inspect backend status, preview routes, adjust route policy and Unicode mode on preview screens, and run an interactive conversion. Guide: docs/tui.md.

Docker

Use ghcr.io/mark1708/convertr for the full backend image with CLI, Web UI, and REST API. See docs/docker.md for tags, run commands, volumes, health checks, and image notes.

Configuration

Create a config file:

convertr config init
convertr config print
convertr config validate

Default path: ~/.config/convertr/config.toml. CLI flags override environment variables, which override the config file, which overrides built in defaults.

Common environment overrides:

• CONVERTR_QUALITY
• CONVERTR_WORKERS
• CONVERTR_ON_ERROR
• CONVERTR_ON_CONFLICT

Config fields and backend options are documented in docs/cli.md.

Backends and plugins

convertr removes missing backend capabilities from the graph at startup. Install tools, then run:

convertr doctor
convertr backends status

External plugins are executables named convertr-* in PATH.

convertr plugins list
convertr plugins test

Backend details and plugin protocol: docs/cli.md.

Demo gallery

VHS demo tapes live in docs/demos. Only the CLI basics GIF is committed. Render the full local gallery with:

make demo

More docs

• CLI reference
• Web UI guide
• TUI guide
• Workflows
• REST API
• Docker
• Demo gallery
• Remediation audit
• Contributing
• Security

Contributor checks

make build
make test
make lint

CI also runs go vet, race enabled tests, go build ./..., and govulncheck.

License

MIT, see LICENSE.