Through an analysis of the muOS frontend source code, we have identified the underlying architecture for how muOS manages Collections and Tags.
This document outlines how to programmatically generate Collections to bypass the need for manual core assignment when using custom folder structures (like our "Mood-Based" curation).
muOS relies heavily on the physical directory structure (e.g., /mnt/mmc/ROMS/snes/) to automatically assign RetroArch cores to games when they are booted for the first time.
If you create custom, flat directories (e.g., /mnt/mmc/ROMS/1. The Foundations/) and place a .sfc file inside, muOS automatic detection will fail, and the user will be presented with a confusing menu asking them to manually select a core.
To provide a highly curated frontend experience while preserving seamless, automatic core booting, you must:
- Store the physical ROMs in their standard, expected system directories (e.g.,
/ROMS/snes/). - Generate Collection
.cfgfiles that act as shortcuts to those ROMs.
When a user launches a game via a Collection, muOS reads the system type from the .cfg file and perfectly routes it to the correct core.
Collections are stored on the SD card at the following path:
/mnt/union/MUOS/info/collection/<Collection Name>/
(Note: Always use the /mnt/union/ path on the device as muOS utilizes a union mount combining both SD cards).
Inside this directory, muOS expects one .cfg file per game.
The native naming convention for a collection file is strictly:
<ROM_NAME_WITHOUT_EXTENSION>-<FNV1A_HASH>.cfg
The 8-character Hex string is a 32-bit FNV-1a Hash of the game's absolute file path on the device (e.g., /mnt/union/ROMS/snes/Chrono Trigger (USA).sfc).
While muOS will technically load a file without the hash, providing the correct hash is required for muOS to:
- Show the "Collected" badge icon next to the game in the main library.
- Prevent duplicate collection entries.
- Correctly map scraped box art metadata.
A collection .cfg file is a simple text file consisting of exactly three lines. Line 3 must perfectly match the exact ROM filename (minus extension) for metadata to resolve.
- Line 1: The absolute path to the ROM file on the muOS device (using
/mnt/union/). - Line 2: The short system folder name (this tells muOS which core to load).
- Line 3: The exact raw ROM name (without the extension).
If you want to add Chrono Trigger to a collection called "1. The Foundations", you must first hash the absolute path (/mnt/union/ROMS/snes/Chrono Trigger (USA).sfc), which equals 6A83E737.
You then create the file:
MUOS/info/collection/1. The Foundations/Chrono Trigger (USA)-6A83E737.cfg
Its contents must be:
/mnt/union/ROMS/snes/Chrono Trigger (USA).sfc
snes
Chrono Trigger (USA)
If you build these collections on a Mac and copy them to your SD card (which is formatted as FAT32 or exFAT), you may see "Empty" items scattered throughout your collections menu on the device.
This is caused by macOS attempting to write Extended Attributes to the SD card. Because FAT32 does not support them, macOS generates hidden "AppleDouble" files prefixed with ._ (e.g., ._Super Mario World.cfg) alongside .DS_Store files. muOS attempts to parse these hidden binary files as text collections, resulting in broken UI entries.
The Fix:
You must actively purge these hidden files from the SD card after syncing. In our Taskfile.yml deployment script, we run two critical cleanup commands after rsync:
dot_clean -m /path/to/sd/(Merges and purges AppleDouble._files).find /path/to/sd/ -name '.DS_Store' -delete(Removes standard macOS folder metadata).
Note: Ensure your collection filenames do not contain colons (:), as this will cause the transfer to FAT32 to fail entirely.