ConvertX

ConvertX is a self-hosted online file converter that supports over 1,000 formats by orchestrating 20+ industry-standard conversion tools including FFmpeg, ImageMagick, LibreOffice, Pandoc, Calibre, Inkscape, Assimp, and more. It runs entirely on your own infrastructure, giving you full control over your files without sending anything to third-party services.

Built with TypeScript, Bun, and the Elysia web framework, ConvertX provides a clean web UI for uploading files, selecting target formats, and downloading results — individually or as a tar archive. It supports multi-user accounts with JWT authentication, batch processing of multiple files at once, and automated file cleanup after a configurable interval.

Deployment is straightforward via Docker with a single compose.yaml snippet, and the container image bundles all required native binaries. Environment variables control every behavioral aspect from authentication mode to FFmpeg hardware acceleration arguments, making ConvertX adaptable to both personal and organizational use cases.

What You Get

• 1000+ Format Conversions - Orchestrates 20+ best-in-class native tools including FFmpeg (~472 input formats), ImageMagick (245 inputs), Pandoc (43 inputs, 65 outputs), Calibre (26 e-book formats), LibreOffice (41 document formats), and Assimp (77 3D asset formats) through a unified interface.
• Multi-User Accounts with JWT Auth - Supports multiple registered user accounts protected by bcrypt-hashed passwords and JSON Web Token sessions, with a configurable JWT_SECRET and optional unauthenticated access mode for private networks.
• Batch File Processing - Upload and convert multiple files simultaneously in a single job, with configurable concurrency limits via MAX_CONVERT_PROCESS to prevent resource exhaustion on shared servers.
• Docker-Native Deployment - Ships as a single container image on GitHub Container Registry and Docker Hub with all 20+ conversion tool binaries pre-installed, deployable with a three-line compose.yaml configuration.
• Automated File Cleanup - Periodically scans and deletes both uploaded and converted files older than a configurable interval (default 24 hours), keeping storage usage bounded without manual intervention.
• Conversion History with Bulk Deletion - Maintains a per-user job history with file status tracking, supporting individual and bulk multi-select deletion through a dedicated history page.
• FFmpeg Hardware Acceleration - Accepts arbitrary FFMPEG_ARGS and FFMPEG_OUTPUT_ARGS environment variables for input and output, enabling GPU-accelerated video conversion via vaapi, nvenc, or similar hardware backends.
• Startup Dependency Verification - At boot, checks and logs the version of every installed native binary (FFmpeg, Pandoc, ImageMagick, Inkscape, etc.), catching missing dependencies before any conversion request is served.
• Codec-Specific Output Targeting - FFmpeg output format strings like h264.mp4, h265.mkv, and av1.mp4 select specific codecs (libx264, libx265, libaom-av1) rather than relying on FFmpeg’s defaults.
• Flexible Access Control - Environment flags independently toggle open registration (ACCOUNT_REGISTRATION), HTTP access (HTTP_ALLOWED), unauthenticated usage (ALLOW_UNAUTHENTICATED), and history visibility (HIDE_HISTORY) for different deployment scenarios.

Common Use Cases

• Home lab media archiving - A self-hoster converts a library of MKV, AVI, and MOV files to H.265 MP4 using FFmpeg hardware acceleration on their NAS, freeing up storage without re-uploading to cloud services.
• Research document pipeline - An academic researcher converts LaTeX source files to PDF via XeLaTeX, HEIC photos from a field camera to JPEG via libheif, and DOCX drafts to ODT for collaborators using LibreOffice.
• Internal enterprise document processing - A legal team self-hosts ConvertX on a private network with ALLOW_UNAUTHENTICATED enabled, allowing paralegals to batch-convert Outlook MSG files, Word documents, and scanned PDFs without sending client data outside the firewall.
• 3D asset pipeline for a game studio - A technical artist converts OBJ, FBX, and COLLADA source assets to formats required by different rendering engines using Assimp (77 input formats, 23 output formats) from a single web interface.
• E-book format normalization - A digital publisher converts submitted manuscripts from DOCX, RTF, and HTML to EPUB, MOBI, and PDF simultaneously using Calibre, processing batches of 20+ files per job.
• Data format migration - A DevOps engineer converts configuration files between JSON, YAML, TOML, CSV, and XML using the Dasel converter, avoiding custom scripting for one-off migrations.

Under The Hood

Architecture ConvertX is organized as a single Elysia application with each HTTP concern — authentication, upload, history, conversion, download, and job management — encapsulated as a discrete plugin and composed via .use() at the entry point, enforcing strict single-responsibility separation without cross-cutting concerns. The converter layer sits entirely below the routing layer: each of the 20+ converters exports a properties object (declaring from/to extension maps) and a convert() function, registered in a central registry that computes a possibleTargets lookup table at startup for O(1) converter selection at request time. SQLite via Bun’s native driver handles persistence for users, jobs, and file names with explicit schema versioning and WAL mode enabled. All deployment behavior — authentication policies, cleanup intervals, hardware acceleration arguments, and web root path — flows through environment variables, keeping configuration fully decoupled from business logic.

Tech Stack The backend runs on TypeScript with Bun as both runtime and build tool, paired with Elysia for typed HTTP routing, JWT authentication middleware, static asset serving, and HTML response rendering via @elysiajs/html. Server-side templating uses KitaJS/HTML with JSX syntax, eliminating any client-side JavaScript framework or bundler from the stack. Tailwind CSS v4 is used for styling, with @tailwindcss/cli generating a static CSS bundle for production and dynamic JIT generation in development mode. The Docker image is built on Debian testing-slim and bundles all 20+ native conversion binaries — FFmpeg, ImageMagick, GraphicsMagick, Inkscape, LibreOffice, Pandoc, Calibre, Assimp, Vips, libheif, libjxl, resvg, VTracer, Potrace, and others — alongside Bun, producing a self-contained deployment artifact.

Code Quality The codebase maintains a dedicated tests/ directory with per-converter unit test files using Bun’s native test runner. Tests mock execFile via a dependency injection parameter on each convert() function rather than monkey-patching globals, producing deterministic and fast unit tests without spawning real processes. TypeScript strict mode is enforced through tsconfig, and the ExecFileFn type alias ensures the mockable interface is type-checked across all converters. Error handling is explicit throughout: conversion failures are caught, logged with context (input file, converter name, target format), and returned as status strings to prevent server crashes. The linting pipeline combines ESLint with typescript-eslint, Biome for fast static analysis, Knip for dead code elimination, and Prettier for formatting — all enforced in CI.

What Makes It Unique ConvertX’s defining technical characteristic is the converter orchestration model: rather than implementing any conversion logic itself, it defines a normalized { properties, converter } interface and wraps each of 20+ specialized CLI tools behind it, making the entire format graph queryable and extensible without touching the HTTP layer. The pre-computed possibleTargets map built at startup from all registered converter from/to declarations enables instant format compatibility lookups in the UI. Startup-time binary verification across all 20 tools catches missing dependencies before the first HTTP request is served, turning deployment errors into clear log messages rather than runtime failures. The codec-specific FFmpeg output format notation (h264.mp4, av1.mkv) is an ergonomic layer that selects explicit codec libraries rather than relying on FFmpeg’s container-format defaults, giving users meaningful control without exposing raw FFmpeg flags.

Self-Hosting

ConvertX is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This is a strong copyleft license: you can use, modify, and redistribute the software freely, including for commercial internal use, but if you modify the source code and provide it as a network service to others, you must release your modifications under the same AGPL-3.0 terms. For teams running ConvertX strictly for internal use without exposing it as a service to external third parties, the AGPL imposes no practical restrictions on commercial deployment.

Running ConvertX yourself requires a Docker-capable host with sufficient CPU and storage for the container image, which bundles 20+ native conversion binaries and is consequently large. The application manages its own SQLite database and file storage under a mounted volume, so you are responsible for volume backups, database integrity on host restarts, and storage capacity planning as uploaded and converted files accumulate. The automated cleanup runs in-process on a timer, meaning it stops if the container crashes — you should monitor container health and configure the provided /healthcheck endpoint with your orchestration layer. Multi-architecture images (amd64, arm64) are published to both GitHub Container Registry and Docker Hub, simplifying deployment on ARM hosts like Raspberry Pi or Apple Silicon servers.

There is no paid cloud tier or managed version of ConvertX — the project is purely community-driven with no commercial entity behind it. This means there is no vendor support, no SLA, no managed upgrade path, and no cloud backup service. Security updates depend on the maintainer and community contributors releasing new Docker images, so you should subscribe to GitHub releases and update your deployment regularly. The project has an active release cadence with roughly monthly releases and 33 contributors as of mid-2026, which provides reasonable confidence in continued maintenance, but long-term sustainability depends entirely on community involvement.