Skip to content

Installation

Jump to bottom
simonefil edited this page Aug 28, 2026 · 6 revisions

Installation

This page covers installation from a downloaded archive. To run a container instead, see Docker; the image already contains every external tool.

1. Install the external tools

RemuxForge drives three external toolsets. It does not bundle them.

Tool Executables RemuxForge calls Used for Must be installed manually
MKVToolNix mkvmerge, mkvextract, mkvpropedit all muxing, track extraction and in-place metadata edits yes
ffmpeg ffmpeg, ffprobe frame extraction for analysis, audio conversion, video re-encoding only on macOS
MediaInfo CLI mediainfo reading track properties and the metadata catalogue yes

FFmpeg 9 stable and ffprobe are downloaded automatically on Windows x64, Linux x64 and Linux ARM64 when they are not found. This happens in two ways:

  • On demand, using the [ Download ] button in Settings ▸ Tool paths.
  • Automatically during a job. Remux and Split both request ffmpeg with download permitted, so the first run fetches it if it is missing.

The build is stored inside the data directory and the resolved paths are saved to the configuration. If 24bit -> 16bit conversion is requested and the managed build lacks libsoxr, a build that supports it is fetched instead.

On macOS automatic download is disabled. Install the FFmpeg 9 full build manually (brew install ffmpeg-full) or set the path in Settings ▸ Tool paths. The Homebrew formula is keg-only, but RemuxForge detects its standard Intel and Apple Silicon paths.

MKVToolNix and MediaInfo are never downloaded and must always be installed manually. RemuxForge does detect them on PATH, derives mkvextract from the mkvmerge location, and saves what it finds.

Install the MediaInfo CLI package, not the GUI application. The GUI does not provide the mediainfo executable, and Metadata mode cannot scan without it.

Optional Vulkan vision backend

Visual analysis uses the CPU by default. Selecting Vulkan under Settings ▸ Advanced settings ▸ Analysis ▸ Vision backend moves the shared SIFT/RANSAC geometry bootstrap, Deep-analysis dHash computation and Speed-correction matching to the GPU. Frame-sync still performs its short temporal dHash scans on the CPU. Vulkan requires:

  • a Vulkan 1.2 loader;
  • a Vulkan compute device with timeline semaphore support;
  • a working vendor driver or ICD.

The dialog probes the complete Vulkan pipeline when the backend is selected. If initialization fails, it reports the error and returns the setting to CPU; analysis never silently changes backend during a job.

On Windows, install a current GPU driver from NVIDIA, AMD or Intel. The driver package normally provides both the Vulkan runtime and its ICD.

On Linux, install the Vulkan loader and the driver for the GPU. For Debian or Ubuntu with Intel/AMD Mesa drivers:

sudo apt install libvulkan1 mesa-vulkan-drivers

NVIDIA systems use the Vulkan ICD supplied by the proprietary driver. A Vulkan SDK is not required to run RemuxForge.

macOS has no native Vulkan driver. Install the Vulkan SDK for macOS and its MoltenVK runtime, then make the loader and MoltenVK ICD available to the process as described by the SDK installer. CPU visual analysis remains available without MoltenVK.

The Docker image already contains the Vulkan loader and Mesa ICDs. GPU device and driver exposure is configured when the container starts; see Docker.

Installing everything up front is still the simplest route, and it is required on macOS:

# Debian / Ubuntu
sudo apt install mkvtoolnix ffmpeg mediainfo

# Fedora
sudo dnf install mkvtoolnix ffmpeg mediainfo

# Arch
sudo pacman -S mkvtoolnix-cli ffmpeg mediainfo

# macOS (Homebrew)
brew install mkvtoolnix ffmpeg-full media-info

# Windows (winget)
winget install MoritzBunkus.MKVToolNix
winget install Gyan.FFmpeg
winget install MediaArea.MediaInfo.CLI

On Linux the system locale must be UTF-8, otherwise filenames and track titles containing non-ASCII characters are mangled. Check with locale; if LANG is POSIX or C, set something like LANG=en_US.UTF-8.

2. Download the right archive

Platform Architectures
Windows x64
Linux x64, ARM64
macOS x64, ARM64
Docker x64

The releases page provides:

  • RemuxForge.Web: the browser interface, documented throughout this wiki.
  • RemuxForge.Cli: the command-line binary, for scripting. See CLI Reference.
  • RemuxForge Desktop: an MSI installer on Windows and a .dmg containing RemuxForge.app on macOS.

They use the same processing engine and the same Blazor interface. Web and CLI installations beside one another share their configuration directory. Desktop deliberately keeps its settings and runtime data in the operating system's application-data directory, outside the installed application bundle. Uninstalling the desktop package removes the application but preserves this per-user data directory; remove it manually only when you also want to discard settings, presets and diagnostics.

Run the desktop application

  • Windows: run the MSI installer, then start RemuxForge from the Start menu.
  • macOS: open the DMG, copy RemuxForge to Applications, then open it from Finder.

The desktop shell starts a self-contained local WebUI on a random loopback port. It never opens an external browser and does not listen on the LAN. Closing the window requests a cooperative stop of active work before the local server is terminated. Only one desktop instance can run at a time.

3. Run the WebUI

Windows

RemuxForge.Web.exe

Linux / macOS

chmod +x RemuxForge.Web
./RemuxForge.Web

Then open http://localhost:5000.

The server binds 0.0.0.0, so a machine on your LAN can reach it at http://<host>:5000. There is no authentication. Do not expose the port to the internet. Put it behind a reverse proxy with access control if you need remote access.

On macOS, a downloaded binary is quarantined by Gatekeeper and will refuse to start. Clear the attribute once:

xattr -d com.apple.quarantine RemuxForge.Web

Changing the port

Either an environment variable:

REMUXFORGE_PORT=5050 ./RemuxForge.Web

or an argument, which takes precedence:

./RemuxForge.Web --port 5050

4. Verify the external tools

A missing external tool is the most common cause of an operation producing no result. Open Settings ▸ Tool paths.

Each entry shows a status next to it:

Status Meaning
[OK] found and executable
[NOT FOUND] not on PATH and no valid explicit path set
[CLI NOT FOUND] shown for MediaInfo when the GUI package is installed instead of the CLI package
[ERROR] the path exists but the tool failed to run

The dialog covers mkvmerge, mkvextract, mkvpropedit, ffmpeg, ffprobe, mediainfo and the temp folder used for intermediate files. Paths are auto-detected from PATH at first launch; you only need to fill one in if detection failed or you want to pin a specific build.

ffmpeg has a [ Download ] button, which fetches a build into the data directory and sets both paths. It is disabled on macOS. There is no equivalent for MKVToolNix or MediaInfo; those must be installed manually.

Complete this check before any other configuration. A [NOT FOUND] on mediainfo prevents Metadata mode from scanning. A [NOT FOUND] on ffmpeg is less critical on Windows and Linux, where the first job that needs it downloads it, but on macOS it must be resolved manually.

5. Language and theme

Language offers English and Italian. Theme exposes all ten free Radzen themes: Default, Dark, Humanistic, Humanistic Dark, Material, Material Dark, Software, Software Dark, Standard and Standard Dark. Both are saved and restored on the next launch. See WebUI Basics.

The data directory

RemuxForge keeps everything persistent in a folder named .remux-forge. For WebUI and CLI archives it is created next to the executable by default; in the Docker examples its parent is /data.

Desktop uses the native per-user application-data location:

  • Windows: %LOCALAPPDATA%\RemuxForge\.remux-forge
  • macOS: ~/Library/Application Support/RemuxForge/.remux-forge

Override the parent location with:

REMUXFORGE_DATA_DIR=/path/to/data ./RemuxForge.Web

Layout:

<data dir>/.remux-forge/
├── appsettings.json              all settings: tool paths, audio defaults,
│                                 encoding profiles, UI state, advanced tuning
├── presets/
│   └── metadata/                 metadata presets (*.json) created in the WebUI
├── temp/                         intermediate files (overridable in Tool paths)
├── deepanalysis-runs/            per-run configuration, log and result
├── deepanalysis-diagnostics/     JSON dumps, only when diagnostics are enabled
└── framesync-diagnostics/        JSON dumps, only when diagnostics are enabled

Two consequences:

  • Metadata presets are not free-floating files. The preset dropdown lists the contents of presets/metadata/, and the preset editor writes there. There is no preset path picker in the WebUI. The CLI does take an explicit --preset path.
  • .remux-forge contains all persistent state: settings, presets and profiles. Copy that folder to move or back up an installation.

See Settings Reference for the annotated appsettings.json.

Environment variables

Variable Description Default
REMUXFORGE_PORT WebUI HTTP port 5000
REMUXFORGE_DATA_DIR Parent directory for .remux-forge executable directory
REMUXFORGE_LOG_FILE Write a log file to this path disabled

Enable REMUXFORGE_LOG_FILE when more detail than the in-app log panel is required, for example when reporting a bug.

Updating

Download the new archive, stop the old process, replace the binaries, restart. Do not delete .remux-forge. It holds your settings and presets, and new versions read the existing file, filling in defaults for anything new.

Uninstalling

Delete the extracted folder. Delete .remux-forge as well if you do not want to keep your settings and presets. Nothing is written to the registry or to system directories.

Next

Start here

Using the WebUI

Examples

Reference

Clone this wiki locally