A cross-platform audio and video converter GUI (Windows/Linux/macOS) built with PyQt6 + FFmpeg. Features a modern Glassmorphism UI design.
- Batch Queue: Add many files, convert all at once
- Audio & Video Support: Convert between nearly any audio and video formats FFmpeg supports
- Smart Video Compression: Reduce video file size by 5-10x while maintaining quality using H.265/HEVC
- Two-Pass Encoding: Optional two-pass encoding for optimal quality/size ratio
- Parallel Processing: Parallel encodes with per-codec thread caps and optional Rust adaptive scheduling (RAM/load aware)
- Presets System: Save and load custom conversion presets (audio and video)
- Preset Template Library: Curated Podcast / Speech / Music / Archive / Video templates (browse/apply in GUI; CLI
list-templates/apply-template) - Metadata Management: Copy or strip metadata, per-file overrides
- Multi-Language Support: Full internationalization with 11 languages
- System Tray: Minimize to tray with conversion notifications
- Real-time Progress: Progress tracking with elapsed/ETA/speed and visual progress bars
- Headless CLI: Batch convert from the terminal (
python -m handforge) without a GUI or display - Companion / shared workstation: Opt-in local HTTP + mobile/desktop/Quest web UI + Android/GrapheneOS WebView scaffold to monitor and control queue/active jobs on the LAN (
handforge serve/ Preferences → Companion); preview, LAN preset share, analytics report; control writes require a shared token - Watch-folder:
handforge watchpolls inbox directories and auto-converts new stable media
# 1) Project venv + install (Windows: python -m venv .venv && .\.venv\Scripts\Activate.ps1)
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
# 2) Ensure FFmpeg is installed and on PATH
# Windows: winget install ffmpeg
# Linux: sudo apt install ffmpeg
# macOS: brew install ffmpeg
# 3) Run the GUI
python -m handforge.app
# Or convert headlessly (no display required)
handforge convert input.mp3 --preset "MP3 192k" -o ./output
handforge list-presets
handforge list-templates --category Podcast -v
handforge apply-template podcast-aac-128See docs/desktop.md for Windows / Linux / macOS install and post-install GUI/CLI usage. Platform reference: docs/installation.md.
Optional native scheduler (reduces peak RAM under heavy batches):
cd native/handforge_scheduler && cargo build --releaseDesktop (install → first convert): docs/desktop.md.
GUI: Add files to the queue, select a preset, and start conversion. Details: docs/usage.md.
CLI (same conversion stack, headless): docs/cli.md.
python -m handforge convert ./folder --preset "AAC 256k" --output-dir ./out --parallel 2Audio: mp3, m4a/aac, opus, ogg/vorbis, flac, alac, wav, aiff, wma, ac3/eac3, ape, tta, wavpack, mp2, amr, caf, au, mka and more
Video: mp4, mkv, avi, mov, wmv, flv, webm, m4v, 3gp, ogv, mts, m2ts, ts, and more
Key settings (full reference: docs/configuration.md):
| Setting | Description | Default |
|---|---|---|
parallel |
Max parallel encodes (hard ceiling) | 2 |
adaptive_parallel |
Lower concurrency from free RAM/load | true |
output_dir |
Default output directory (may be a local cloud sync folder) | ~/HandForge_Output |
cloud_roots |
Local sync / mount folders for pick-up and save | [] |
rclone_remote |
Optional default rclone remote name | "" |
performance_analytics |
Opt-in local batch metrics (~/.handforge/analytics/) |
false |
companion_enabled |
Opt-in companion HTTP + shared workstation web UI | false |
companion_host / companion_port |
Companion bind (default localhost:8765; LAN + control writes need token) | 127.0.0.1 / 8765 |
watchfolder_dirs / watchfolder_interval_seconds |
Hotfolder paths + poll interval for handforge watch |
[] / 5 |
default_video_quality |
Default video quality preset | medium |
default_video_codec |
Default video codec | libx264 |
language |
Interface language (None = auto-detect) | None |
- Start here: docs/examples/example-01.md
- More examples: docs/examples/
High-level overview: HandForge uses a modular architecture with UI (PyQt6), core (orchestrator, models, settings), and utility (FFmpeg integration) layers. See docs/architecture.md for details.
Planned milestones live in ROADMAP.md. For changes, see CHANGELOG.md.
We welcome PRs! Please read CONTRIBUTING.md and follow the PR template. Run pytest (requires FFmpeg on PATH for integration tests) before opening a PR.
Please report vulnerabilities via SECURITY.md.
This project is licensed under the MIT License - see the LICENSE file for details.
For support, please see SUPPORT.md or contact contact@voxhash.dev.
HandForge - Audio & Video conversion made simple
© 2026 VoxHash Technologies