Consoul user guide

Consoul is a controller-friendly desktop launcher for an existing emulation setup. It finds ROM files in folders you choose, presents them as a console library, and starts each game with the emulator and command-line arguments you provide.

Consoul does not include emulators, ROMs, BIOS files, or game artwork. Install and test your emulators separately, and only use game files you are legally entitled to use.

Before you begin

You will need:

• Consoul installed on Windows, macOS, or Linux
• One or more working emulators
• ROMs stored in a folder for each console
• The full path to each emulator executable and ROM folder
• Optional console logos, backgrounds, and box art

Test a game directly in its emulator before adding it to Consoul. This makes path, BIOS, core, and controller problems much easier to identify.

Installing the unsigned macOS alpha

The current macOS alpha is not yet signed and notarised with an Apple Developer ID. After copying Consoul.app into your Applications folder, macOS Gatekeeper may prevent it from opening. Until signed builds are available, open your terminal and remove the quarantine attribute from the app:

xattr -dr com.apple.quarantine /Applications/Consoul.app

Now you will be able to open Consoul. Only use this command for a copy of Consoul downloaded from the official Consoul website; removing quarantine bypasses one of macOS's security checks for that app. This step will no longer be necessary once Consoul is signed and notarised.

Configuration is done in JSON

Consoul has no first-run setup wizard (yet). All configuration is stored in consoul.config.json. Edit this file in a plain-text or code editor. Do not use a word processor.

The active configuration file is located at:

• Windows: %APPDATA%\consoul\consoul.config.json
• macOS: ~/Library/Application Support/consoul/consoul.config.json
• Linux: ~/.config/consoul/consoul.config.json

Consoul creates the file on first launch. If you cannot find it, launch Consoul once and close it, then look again. Packaged updates do not overwrite your copy.

When running Consoul from its source code, the active file is consoul-app/consoul.config.json instead.

Consoul watches the active file for changes. Most library, artwork, sorting, sound, window-size, fullscreen, and kiosk changes are applied while the app is open. If a change does not appear, restart Consoul.

JSON rules

• Keep property names and text inside double quotes.
• Separate items with commas, but do not add a comma after the final item.
• Use true and false without quotes.
• On Windows, either use forward slashes (C:/Games/NES) or escape each backslash (C:\\Games\\NES).
• Keep each emulator id unique.
• Make a backup before large edits. Invalid JSON prevents Consoul from loading its configuration.

A minimal configuration

Replace every example path with a path on your own computer:

{
  "app": {
    "fullscreen": true,
    "kiosk": false,
    "width": 1920,
    "height": 1080,
    "autoHideMenuBar": true,
    "sfxEnabled": true,
    "sfx": {
      "navVolume": 0.3,
      "launchVolume": 0.7
    },
    "sortEmulatorsBy": "year"
  },
  "emulators": [
    {
      "display": true,
      "id": "SNES",
      "label": "Super Nintendo",
      "year": "1992",
      "category": "Nintendo",
      "icon": "assets/logos/snes.png",
      "bg": "assets/backgrounds/snes-bg.jpg",
      "boxart": "D:/Consoul/boxart/snes",
      "exec": "C:/Emulators/RetroArch/retroarch.exe",
      "args": ["-f", "-L", "C:/Emulators/RetroArch/cores/snes9x_libretro.dll", "{rom}"],
      "romDir": "D:/Games/SNES",
      "extensions": [".sfc", ".smc", ".zip"],
      "supportsBackArt": true
    }
  ]
}

App settings

The app object controls Consoul itself.

Adding a console or emulator

Add one object to the emulators array for every console you want to show.

Consoul does not search ROM subfolders. It displays matching files alphabetically and removes only the final file extension from each displayed title.

Launch arguments

args must be a JSON array with one command-line argument per item. Consoul replaces an item that is exactly "{rom}" with the selected ROM path.

For a standalone emulator:

"exec": "C:/Emulators/DuckStation/duckstation-qt-x64-ReleaseLTCG.exe",
"args": ["-batch", "-fullscreen", "{rom}"]

For RetroArch, include the core after -L:

"exec": "C:/Emulators/RetroArch/retroarch.exe",
"args": ["-f", "-L", "C:/Emulators/RetroArch/cores/mesen_libretro.dll", "{rom}"]

Arguments vary by emulator and operating system. Check your emulator's command-line documentation. Test the same executable, arguments, and ROM from a terminal if a game will not launch.

ROMs and game names

Place each console's games in its configured romDir. For example:

D:/Games/SNES/
├── Chrono Trigger.sfc
├── Donkey Kong Country.sfc
└── Super Metroid.sfc

With "extensions": [".sfc"], these appear without their file extensions. Multi-file games should use the format you normally launch, such as .cue, .gdi, or .m3u, rather than also listing every track format. This avoids duplicate entries.

Box art

Set boxart to the folder holding front covers. An artwork filename must exactly match the displayed ROM name. Consoul checks .jpg, .png, then .webp.

D:/Consoul/boxart/snes/
├── Chrono Trigger.jpg
├── Donkey Kong Country.png
├── Super Metroid.webp
└── back/
    ├── Chrono Trigger.jpg
    └── Super Metroid.jpg

Capitalisation may matter on macOS. Back covers belong in a back folder inside the front-cover folder; set supportsBackArt to true. If no front cover exists, Consoul uses the configured placeholder, then a built-in placeholder when one is available.

Looking for artwork? Visit the downloads page for links to recommended community box-art packs.

Console logos and backgrounds

icon, bg, and placeholder can reference a bundled Consoul asset with a relative path, or a local image with an absolute path:

"icon": "assets/logos/snes.png",
"bg": "D:/Consoul/backgrounds/snes.jpg",
"placeholder": "D:/Consoul/placeholders/snes.png"

Missing image files do not prevent ROMs from appearing, but the associated visual will be blank or use a fallback.

Controls

Keyboard and mouse

Gamepad

Consoul reads the first connected standard-mapped gamepad.

Controller mapping follows the browser's standard gamepad layout and can differ for non-standard controllers. Configure in-game controls in the emulator itself; Consoul only controls the launcher.

Troubleshooting

Consoul reports a configuration error or does not open

• Validate consoul.config.json with a JSON validator.
• Check for missing commas, trailing commas, unescaped Windows backslashes, or smart quotes.
• Restore your backup and reapply recent changes one at a time.

A console is missing

• Confirm its object is inside the emulators array.
• Confirm display is not set to false.
• Give it a unique id.
• Save the file and allow a moment for Consoul to reload it.

No games are shown

• Confirm romDir exists and uses an absolute path.
• Confirm the games are directly inside that folder, not in subfolders.
• Add the correct extensions, including the leading dot, to extensions.
• Confirm Consoul has permission to read the folder or external drive.
• If the library is on a removable drive, make sure it is connected at the same path.

A game does not launch

• Confirm exec points to the executable itself, not just its folder.
• Confirm args contains an item that is exactly "{rom}".
• Check emulator-specific flags and any RetroArch core path.
• Test the emulator and ROM outside Consoul first.
• Check that BIOS, firmware, and emulator permissions are already configured.

Artwork is missing

• Match the image's base filename to the displayed ROM name exactly.
• Use .jpg, .png, or .webp.
• Confirm boxart points to the front-cover folder.
• Put back covers in the back subfolder and enable supportsBackArt.
• On macOS and Linux, check filename capitalisation.

Changes do not appear

• Confirm you edited the active per-user file, not the template inside the installed application.
• Wait a second for the configuration watcher.
• Restart Consoul if necessary.

Updating Consoul

Your active per-user consoul.config.json is kept separately from the installed application, so installing a newer packaged build does not replace it. Back it up periodically, especially before changing many emulator entries.