File Wizard

A self-hosted, browser-based utility for file conversion, OCR and audio transcription. It wraps common CLI and Python converters (FFmpeg, LibreOffice, Pandoc, ImageMagick, etc.), plus faster-whisper and Tesseract OCR. Supports 180+ formats out of the box, 700+ formats theoretically and much more can be configured and extended.

Features

• Convert between many file formats; extendable via settings.yml to add any CLI tool.
• OCR for PDFs and images (tesseract / ocrmypdf).
• Audio transcription using Whisper models.
• Simple, responsive dark UI with drag-and-drop and file picker.
• Background job processing with real-time status updates and persistent history.
• /settings page for configuring conversion tools and OAuth (runs without auth in local mode).
• OCR in many languages, selectable per job.
• Delete selected jobs, or remove finished jobs automatically after a number of days.
• CPU-only by default; a cuda image is available for GPU transcription. Images for amd64 and arm64.

Security

Warning: in LOCAL_ONLY mode there is no login: everyone who can reach the port can use the app and change its settings. Keep it on a trusted network or enable OIDC authentication (LOCAL_ONLY=False). The converters process untrusted files, so run the container with only the volumes it needs.

Built-in protections:

• Requests that change state (uploads, settings, deletions) are only accepted from the app's own origin, so other websites you visit cannot drive your instance.
• Conversion command templates are read-only on the settings page. Edit config/settings.yml, or set ALLOW_COMMAND_EDITS=true to edit them in the browser.
• Secrets (OIDC client secret, webhook token) are never sent to the browser; leave the field empty to keep the stored value.
• auth_settings.allowed_users / allowed_domains restrict which accounts of your identity provider may log in (both empty = everyone the provider accepts).

Tech stack

FastAPI, vanilla HTML/JS/CSS frontend.

Installation

Recommended — Docker (pull from Docker Hub)

Images (linux/amd64 and linux/arm64, e.g. Raspberry Pi 4/5 and Apple Silicon):

• loredcast/filewizard:latest — all tools
• loredcast/filewizard:small — without TeX, Inkscape and Docling
• loredcast/filewizard:cuda — transcription on NVIDIA GPUs (amd64 only)

Copy docker-compose.yml from the repo, adjust as needed, then:

docker compose up -d

FileWizard will be available at localhost:6969. The app runs as an unprivileged user; set PUID/PGID to the owner of the mounted folders (Unraid: 99/100, templates in unraid/).

Building the image yourself, GPU setup, publishing to Docker Hub and how the builds are kept reproducible are described in docs/docker.md.

Upgrading from 0.4: docker compose pull && docker compose up -d works with your existing setup. Read the upgrade notes first: the app no longer runs as root, and you can keep your job history. What's new: CHANGELOG.md.

Manual (no Docker)

Needs Python 3.12 and the converters you want to use on the PATH (LibreOffice, Pandoc, Ghostscript, Tesseract, FFmpeg, ...; see the Dockerfile for the full list).

git clone https://github.com/LoredCast/filewizard.git
cd filewizard
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt   # or requirements_small.txt
./run.sh

To update: git pull, run the pip install line again and restart; settings and job history are kept.

Configuration & docs

See the project Wiki for details and examples:
https://github.com/LoredCast/filewizard/wiki

Usage

1. Open http://127.0.0.1:8000.
2. Drag & drop or choose files.
3. Select action: Convert, OCR, or Transcribe.
4. Track job progress in the History table (updates automatically).

Tools Table

Consider spending 30 seconds on the » usage survey « to help improve the app and suggest changes!