The manual

Installing

Install OmaCRT in your home directory, then install the system service that makes the television connector available for leasing. Reboot before starting the launcher. On the desktop lists the installed files and desktop changes.

Requirements

Install RetroArch with the cores you want, mpv, ffmpeg and curl. You also need a Rust toolchain: the installer compiles the programs locally. The system must have systemd and a mounted debugfs.

Run omacrt doctor to check dependencies before and after installation. It reads /etc/os-release and names missing packages for your distribution. It supports pacman, dnf, apt, zypper, apk, xbps and nix. Most checks also work before the project is installed.

Hyprland is required. Use a distribution where Hyprland is available. The Debian stable setup described here is unsupported because it does not package Hyprland.

Install OmaCRT

git clone https://github.com/stefanomainardi/omacrt
cd omacrt

bin/omacrt-install
omacrt setup
sudo bin/omacrt-install --system

An install writes new binaries and leaves the running ones alone. Add --restart to take the television off and on when the install finishes. Without it, the installer names the process still on the old build and the command that puts the new one on the air. The bar panel says the same thing in amber, and carries the buttons that do it.

Reboot, then run:

omacrt library scan ~/Games
omacrt on

Run the first commands from the cloned repository. After the system install, reboot before running the library scan and omacrt on. The steps below explain what each command does.

bin/omacrt-install compiles the project and installs four programs in ~/.local/bin. On Omarchy it also installs two plugin directories under ~/.config/omarchy/plugins. This step needs no privileges and writes only inside your home directory.

On a machine without Omarchy, the installer skips the bar widget, panel, library overlay and Television menu entry. It reports these omissions and writes nothing under ~/.config/omarchy. The television components are installed either way. The project’s Hyprland notes describe keybindings you can use in place of the bar widget.

Run omacrt setup to select the television connector. In a terminal, use the arrow keys to select an output from the map, then press Enter. The initial selection uses the first match in this order:

1. the connector already named in the configuration, if there is one
2. an output whose display identification names a converter it recognises
3. a connected HDMI output the compositor is not using as a desktop monitor
4. the first connected HDMI output

Setup saves the connector and television standard. If you do not specify a standard, it uses the country in your locale. Use --connector to name an output directly or --dry-run to inspect without saving. Replacing a configured connector requires --force.

sudo bin/omacrt-install --system installs a boot-time service that marks the television connector as a non-desktop output. This requires root because it writes to a kernel debug interface. The service restricts its permissions to that task. Stopping it restores the display’s original identification.

omacrt library scan ~/Games indexes your collection in its existing folder layout. How a game gets its mode explains how the scanner identifies each file.

omacrt on applies the modeline, selects the television’s sync mode, routes audio and starts the launcher.

Reboot after installation

Reboot after the system install. Hyprland decides which connectors to offer for leasing when it starts. An override applied later can set the kernel flag while Hyprland still reports the connector as unavailable. Applying the override manually also requires a restart. See When the picture rolls if the television remains dark after rebooting.

Data directories

OmaCRT stores its files in four directories. Each follows the corresponding environment variable if you change it:

Your own RetroArch configuration is not edited. The emulator configuration in the first of those is this project's own file, handed to RetroArch on the command line.

Settings and version changes

OmaCRT saves persistent files through a temporary file and a rename. It keeps the previous version beside the current file. If the current file cannot be parsed, OmaCRT moves it aside as <name>.bad, reads the backup instead and reports the recovery. A truncated file can therefore lose the most recent change, and it does not overwrite the last good backup.

When an older build reads a file from a newer build, it first keeps a copy with the source version in its name. The log reports the copy’s location. The next save uses the older build’s format, while the copy retains any unrecognised keys. To restore those keys, return to the newer build and replace the current file with the saved copy.

Uninstalling

bin/omacrt-install --uninstall
sudo bin/omacrt-install --uninstall-system

The first removes the four programs, both plugin directories and the block it added to Omarchy's menu file. It disables the plugins through Omarchy's own command before removing them, and it stops short of them if the session is locked. On the desktop says why.

The second disables and removes the service and its directory. The connector goes back to being an ordinary desktop output at the next boot.

The four data directories remain so that reinstalling preserves settings and the library scan. Delete them if you also want to remove that data. Game files stay in place. On the desktop lists the three kinds of file the launcher can create inside a collection.