[](https://codecov.io/gh/alucryd/oxyromon)
[](https://crates.io/crates/oxyromon)
[](https://ko-fi.com/alucryd)
oxyROMon 0.22.0
Rusty ROM OrgaNizer
oxyROMon is a cross-platform opinionated CLI ROM organizer written in Rust.
Like most ROM managers, it checks ROM files against known good databases.
It is designed with archiving in mind, so it only supports original and lossless ROM formats.
It can, however, export in various popular lossy formats, leaving the lossless ROM files untouched.
Sorting can be done in regions mode, in so-called 1G1R mode, or both.
Console, computer, and arcade (WIP) systems are supported using Logiqx DAT files.
The first two require No-Intro or Redump DAT files, while the latter uses MAME or FBNeo DAT files.
### Quick start
To create and manage a new system, you need a Logiqx DAT file.
Cartridge-based consoles and older computers can be downloaded from [Dat-o-Matic](https://datomatic.no-intro.org/).
CD-based ones can be downloaded from [Redump](http://redump.org/).
Alternatively, the `download-dats` subcommand can download and import Redump DATs for you because they offer direct links.
MAME DATs can be found on [Progetto-Snaps](https://www.progettosnaps.net/index.php). FBNeo DATs are harder to find; [libretro](https://git.libretro.com/libretro/FBNeo/-/tree/master/dats) has some.
Manually downloaded DATs are then imported using the `import-dats` subcommand.
Once a system has been created, you can import ROMs using the `import-roms` subcommand.
Imported ROMs that check out will be placed in the main folder of their respective system.
Then, the ROMs can be sorted using the `sort-roms` subcommand according to your configuration.
Please add at least one region in the `REGIONS_ALL` or `REGIONS_ONE` list beforehand.
See all configuration options below.
You can also convert ROMs between various formats using the `convert-roms` subcommand, check them later on with the `check-roms` subcommand, or purge them with the `purge-roms` subcommand to empty `Trash` folders or detect and forget manually deleted ROMs.
### Installation
You can grab pre-compiled Linux, Mac, and Windows binaries from the [release page](https://github.com/alucryd/oxyromon/releases).
A docker image is also available on [Docker Hub](https://hub.docker.com/r/alucryd/oxyromon).
If you use Arch Linux, there's a package in the [official repos](https://archlinux.org/packages/extra/x86_64/oxyromon/).
It is also possible to install from crates.io using `cargo install oxyromon`.
Finally, if you're feeling adventurous, you can always build from the source, as shown in the instructions below.
### Compilation
The CLI has no specific requirement, and you can just:
cargo build --release
For Windows, asm-hashes don't work with MSVC toolchain at the moment so you need to build without it:
cargo build --release --no-default-features --features use-rustls
You can also target GNU to solve the asm-hashes issue:
cargo build --release --target x86_64-pc-windows-gnu
For the web UI, you will also need pnpm:
cargo build --release --features server
The build uses rustls by default, but you can also opt for OpenSSL:
cargo build --no-default-features --features use-native-tls
### Features
| feature | description | default |
| -------------- | ---------------------------------------------- | ------- |
| server | build the server subcommand | |
| enable-asm | enable ASM variants of the MD5 and SHA1 hashes | x |
| use-native-tls | use the system OpenSSL library | |
| use-rustls | use rustls | x |
### Configuration
Configuration is done from the command line, and settings are stored in the SQLite database.
The database itself is stored in `${data_dir}/oxyromon` as defined in the [dirs](https://docs.rs/dirs/3.0.1/dirs/fn.data_dir.html) crate.
This may be overwritten using the `OXYROMON_DATA_DIR` environment variable.
Settings can be global or per-system. Per-system settings take precedence over global ones, with automatic fallback to the global value when no system-specific override is set.
Use the `-n/--system` flag with the `config` subcommand to manage system-specific settings.
Available settings:
- `ROM_DIRECTORY`: Full path to your ROM directory, defaults to `${home_dir}/Emulation` as defined in the
[dirs](https://docs.rs/dirs/3.0.1/dirs/fn.home_dir.html) crate
- `TMP_DIRECTORY`: Full path to a temporary directory for file extraction, defaults to
[temp_dir](https://doc.rust-lang.org/std/env/fn.temp_dir.html)
- `PREFER_PARENTS`: Favor parents in the 1G1R election process, defaults to `true`
- `PREFER_REGIONS`: Favor ROMs targeting more or fewer regions in the 1G1R election process, defaults to `none`, valid choices: `none`, `broad`, `narrow`
- `PREFER_VERSIONS`: Favor newer or earlier versions of ROMs in the 1G1R election process, defaults to `new`, valid choices: `none`, `new`, `old`
- `PREFER_FLAGS`: List of ROM flags to favor in the 1G1R election process (eg: `Rumble Version`)
- `DISCARD_FLAGS`: List of ROM flags to discard (eg: `Virtual Console`)
- `DISCARD_RELEASES`: List of ROM releases to discard (eg: `Beta`)
- `LANGUAGES`: List of languages you want to keep, applies only to ROMs that do specify them (eg: `En,Ja`)
- `REGIONS_ALL`: Unordered list of regions for which you want to keep all ROM files (eg: `US,EU,JP`)
- `REGIONS_ONE`: Ordered list of regions for which you want to keep a single ROM file (eg: `US,EU`)
- `REGIONS_ALL_ARCADE`: Unordered list of ROM types you want to place in the main directory (eg: `clone`)
- `REGIONS_ONE_ARCADE`: Unordered list of ROM types you want to place in the 1G1R directory (eg: `bios,parent`)
- `REGIONS_ALL_SUBFOLDERS`: Sort ROMs in subfolders, defaults to `none`, valid choices: `none`, `alpha`
- `REGIONS_ONE_SUBFOLDERS`: Sort 1G1R ROMs in subfolders, defaults to `none`, valid choices: `none`, `alpha`
- `REGIONS_ONE_STRICT`: `true` will elect ROMs regardless of them being available, `false` will only elect available ROMs, defaults to `false`
- `GROUP_SUBSYSTEMS`: Group all system variants in a single directory, defaults to `true`
- `CHD_CD_HUNK_SIZE`: The CHD hunk size in bytes for CDs, defaults to auto, valid range: `16-1048576`
- `CHD_CD_COMPRESSION_ALGORITHMS`: The CHD compression algorithms for CDs, up to 4 can be specified, defaults to auto, valid choices: `none`, `cdfl`, `cdlz`, `cdzl`, `cdzs`
- `CHD_DVD_HUNK_SIZE`: The CHD hunk size in bytes for DVDs, defaults to auto, valid range: `16-1048576`
- `CHD_DVD_COMPRESSION_ALGORITHMS`: The CHD compression algorithms for DVDs, up to 4 can be specified, defaults to auto, valid choices: `none`, `flac`, `huff`, `lzma`, `zlib`, `zstd`
- `CHD_PARENTS`: Enables the CHD parents feature, needs playlists to have been generated, defaults to `false`
- `RVZ_BLOCK_SIZE`: The RVZ block size in KiB, defaults to `128`, valid range: `32-2048`
- `RVZ_COMPRESSION_ALGORITHM`: The RVZ compression algorithm, defaults to `zstd`, valid choices: `none`, `zstd`, `bzip`, `lzma`, `lzma2`
- `RVZ_COMPRESSION_LEVEL`: The RVZ compression level, defaults to `5`, valid ranges: `1-22` for zstd, `1-9` for the other algorithms
- `RVZ_SCRUB`: Enables RVZ scrubbing, applies only to `export-roms`, defaults to `false`
- `SEVENZIP_COMPRESSION_LEVEL`: The 7Z compression level, defaults to `9`, valid range: `1-9`
- `SEVENZIP_SOLID_COMPRESSION`: Toggles 7Z solid compression, defaults to `false`
- `ZIP_COMPRESSION_LEVEL`: The ZIP compression level, defaults to `9`, valid range: `1-9`
Note: `TMP_DIRECTORY` should have at least 8GB of free space to extract those big DVDs.
Example configuration:
```
oxyromon config -l
DISCARD_FLAGS = Aftermarket,Debug
DISCARD_RELEASES = Beta,Proto,Sample,Demo,Hack,Bootleg,Homebrew
GROUP_SUBSYSTEMS = true
PREFER_FLAGS =
PREFER_PARENTS = true
PREFER_REGIONS = none
PREFER_VERSIONS = new
REGIONS_ALL = US,EU,JP
REGIONS_ALL_SUBFOLDERS = none
REGIONS_ONE = US,EU
REGIONS_ONE_STRICT = false
REGIONS_ONE_SUBFOLDERS = none
ROM_DIRECTORY = /home/alucryd/Emulation
RVZ_COMPRESSION_ALGORITHM = zstd
RVZ_COMPRESSION_LEVEL = 5
SEVENZIP_COMPRESSION_LEVEL = 9
SEVENZIP_SOLID_COMPRESSION = false
TMP_DIRECTORY = /tmp
ZIP_COMPRESSION_LEVEL = 9
```
### Directory Layout
${ROM_DIRECTORY}
...
⮡ ${SYSTEM_NAME} # Base directory for each system, allowed regions will be stored here
⮡ 1G1R # Sub directory for 1G1R games
⮡ Trash # Sub directory for trashed games
...
`${SYSTEM_NAME}` is influenced by the `GROUP_SUBSYSTEMS` setting
### External programs
These should be in your `${PATH}` for extra features.
- [7z](https://www.7-zip.org/download.html): 7Z and ZIP support
- [bchunk](https://github.com/extramaster/bchunk): CUE/BIN to ISO support
- [chdman](https://www.mamedev.org/release.html): CHD support
- [ctrtool](https://github.com/3DSGuy/Project_CTR/releases): CIA support
- [dolphin-tool](https://dolphin-emu.org/download/): RVZ support
- [flips](https://github.com/Alcaro/Flips): BPS and IPS support
- [maxcso](https://github.com/unknownbrackets/maxcso/releases): CSO/ZSO support
- [nsz](https://github.com/nicoboss/nsz): NSZ support
- [wit](https://wit.wiimm.de/): WBFS support
- [xdelta3](https://github.com/jmacd/xdelta): XDELTA support
### TODO
- Add more actions to the web UI
- Find a way to automatically download No-Intro DAT files
- Support merged sets for arcade systems
- Craft some unit tests for arcade systems
- Craft some unit tests for NSZ
- Craft some unit tests for IRD and PS3 in general
- Support rebuilding PS3 ISOs using IRD files, if possible, and requested
- Add a metadata scraper in the retroarch format
## oxyromon
Usage: oxyromon [COMMAND]
Commands:
info Print system information
config Query and modify the oxyromon settings
create-dats Create DAT files from directories
import-dats Parse and import Logiqx DAT files into oxyromon
download-dats Download No-Intro and Redump DAT files and import them into oxyromon
import-irds Parse and import PlayStation 3 IRD files into oxyromon
import-patches Import patch files into oxyromon
import-roms Validate and import ROM files or directories into oxyromon
sort-roms Sort ROM files according to region and version preferences
convert-roms Convert ROM files between common formats
export-roms Export ROM files to common formats
rebuild-roms Rebuild arcade ROM sets according to the selected strategy
check-roms Check ROM files' integrity
purge-irds Unassociate games from IRD files
purge-roms Purge trashed, missing, and orphan ROM files
purge-systems Purge systems
generate-playlists Generate M3U playlists for multi-disc games
benchmark Benchmark oxyromon
server Launch the backend server
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help information
-V, --version Print version information
## oxyromon-config
Query and modify the oxyromon settings
The settings can be queried, modified, and deleted from the command line.
All operations are global by default. Use `-y/--system` to scope them to a specific system.
Per-system settings take precedence over global ones, with fallback to the global value.
Usage: oxyromon config [OPTIONS]
Options:
-n, --system Select a system by name (supports % globs)
-l, --list Print the whole configuration
-g, --get Print a single setting
-s, --set Set a single setting
-u, --unset Unset a single setting
-a, --add Add an entry to a list
-r, --remove Remove an entry from a list
-h, --help Print help information
## oxyromon-info
Print system information
Prints the program version, installed dependencies and their version (when possible), as well as some basic system statistics.
Usage: oxyromon info
Options:
-h, --help Print help
## oxyromon-import-dats
Parse and import Logiqx DAT files into oxyromon
The standard Logiqx XML format is supported, this includes Parent-Clone DAT files.
ZIP files such as the No-Intro daily dat-o-matic packs can be imported directly without extracting them first.
All `.dat` files inside the archive will be found, including those nested in subdirectories.
When used with the `-u` flag, only systems that were previously imported will be updated, making it
ideal for keeping your collection in sync with daily releases.
Supported console DAT providers:
- No-Intro
- Redump
Note: Some systems require a header definition to be placed alongside the DAT file.
If not provided, oxyromon will use its own fallback header definition.
Supported arcade DAT providers:
- MAME
Note: MAME DATs are commonly found as separate files for ROMs, CHDs, and others.
It is recommended to turn `GROUP_SUBSYSTEMS` on and give them custom names like `MAME (ROMs)`, `MAME (CHDs)`, etc...
That way they will be physically grouped in a single `MAME` folder and work in MAME out of the box.
Usage: oxyromon import-dats [OPTIONS] ...
Arguments:
... Set the DAT files to import
Options:
-i, --info Show the DAT information and exit
-u, --update Only import DAT files for systems already in the database
-s, --skip-header Skip parsing the header even if the system has one
-f, --force Force import of outdated DAT files
-n, --name Customize the system name
-e, --extension Customize the system extension
-h, --help Print help information
## oxyromon-download-dats
Download No-Intro and Redump DAT files and import them into oxyromon
Redump offers direct downloads, but no summary, whereas No-Intro offers a summary
but no direct downloads. For now, the No-intro counterpart will only tell you if
an update is available, but the Redump one is able to download brand new dats
and update those you've already imported.
Supported DAT providers:
- Redump (Download and update)
- No-Intro (Update check only)
Usage: oxyromon download-dats [OPTIONS]
Options:
-n, --nointro Download No-Intro DAT files
-r, --redump Download Redump DAT files
-u, --update Check for system updates
-a, --all Import all systems
-f, --force Force import of outdated DAT files
-s, --save Save downloaded DAT files to the specified directory
-h, --help Print help information
## oxyromon-create-dats
Create DAT files from directories
This makes it possible to build DAT files from scratch, they can be subsequently imported into oxyromon or any other tool.
If no customization is specified, name and description are set to the directory name, and version is set to the creation datetime (No-Intro style).
Each game name is set to the file name stripped of its extension, all 3 checksums are computed.
Note: Any file in the directory is processed as is, and directories are ignored. It is necessary to use original uncompressed file formats if you plan to import the generated DAT file and use oxyromon's `convert-roms`/`export-roms` commands.
Usage: oxyromon create-dats [OPTIONS] ...
Arguments:
... Set the directories to process
Options:
-n, --name Customize the DAT name
-d, --description Customize the DAT description
-v, --version Customize the DAT version
-a, --author Customize the DAT author
-u, --url Customize the DAT URL
-o, --output