rommapp_docs/docs/Getting-Started/Configuration-File.md

<!-- trunk-ignore-all(markdownlint/MD033) -->
<!-- trunk-ignore-all(markdownlint/MD041) -->

Below is a breakdown of each section of the `config.yml` file and its purpose. You can find a full example of the file in the [config.example.yml](https://github.com/rommapp/romm/blob/master/examples/config.example.yml) file.

---

## Exclude Section

Control which platforms, ROMs, or files to ignore during scanning.

### Platforms

Exclude entire platforms (folders) from being scanned.

```yaml
exclude:
    platforms: ["ps", "ngc", "gba"]
```

### ROMs

Fine-tune which ROMs or files are excluded.

#### Single File ROMs

Applies to ROMs that are single files (not in subfolders).

- **extensions**: Exclude files by extension
    - Defaults to `["db", "ini", "tmp", "bak", "lock", "log", "cache", "crdownload"]`
- **names**: Exclude files by name or pattern (supports Unix wildcards)
    - Defaults to `[".DS_Store", ".localized", ".Trashes", ".stfolder", "@SynoResource", "gamelist.xml"]`

```yaml
exclude:
    roms:
        single_file:
            extensions: ["xml", "txt"]
            names: ["info.txt", "._*", "*.nfo"]
```

#### Multi-File ROMs

Applies to ROMs stored as folders (multi-disc, with DLC, etc.).

- **names**: Exclude entire folders by name
    - Defaults to `["@eaDir", "__MACOSX", "$RECYCLE.BIN", ".Trash-*", ".stfolder", ".Spotlight-V100", ".fseventsd", ".DocumentRevisions-V100", "System Volume Information"]`
- **parts.names**: Exclude files by name or pattern from within multi-file ROM folders
    - Defaults to `[".DS_Store", ".localized", ".Trashes", ".stfolder", "@SynoResource", "gamelist.xml"]`
- **parts.extensions**: Exclude files by extension from within multi-file ROM folders
    - Defaults to `["db", "ini", "tmp", "bak", "lock", "log", "cache", "crdownload"]`

```yaml
exclude:
    roms:
        multi_file:
            names: ["final fantasy VII", "DLC"]
            parts:
                names: ["data.xml", "._*"]
                extensions: ["xml", "txt"]
```

---

## System Section

Customize how RomM interprets your folder and platform names.

### Custom Folder Names

Map your custom folder names to RomM's recognized platform names.

```yaml
system:
    platforms:
        gc: "ngc" # Treats 'gc' folder as GameCube
        psx: "ps" # Treats 'psx' folder as PlayStation
```

### Versions

Associate a platform with its main version. This also tells RomM to fetch metadata from the main version source.

```yaml
system:
    versions:
        naomi: "arcade"
```

---

## Filesystem Section

Specify the folder name where your ROMs are located if it differs from the default.

If your ROMs folder is named `my_roms` instead of `roms`:

```yaml
filesystem:
    roms_folder: "my_roms"
```

Disable file hash calculation for low power devices (e.g. Raspberry PI).

```yaml
filesystem:
    skip_hash_calculation: true
```

---

## Scan Section

Configure metadata scanning priorities and media assets to download.

### Priority

Customize the order in which metadata providers are queried during scans.

#### Metadata

Controls metadata provider priority order.

**Provider list in default order:**

- `igdb` - IGDB (highest priority)
- `moby` - MobyGames
- `ss` - Screenscraper
- `ra` - RetroAchievements
- `launchbox` - Launchbox
- `gamelist` - ES-DE gamelist.xml
- `hasheous` - Hasheous
- `flashpoint` - Flashpoint Project
- `hltb` - HowLongToBeat (lowest priority)

```yaml
scan:
    priority:
        metadata:
            - "igdb"
            - "ss"
            - "moby"
```

#### Artwork

Controls artwork provider priority order for cover art and screenshots.

**Default:** Same as `priority.metadata`

```yaml
scan:
    priority:
        artwork:
            - "igdb"
            - "ss"
            - "moby"
```

#### Region

Sets preferred region for cover art and game title (Screenscraper only).

**Default:** `["us", "wor", "ss", "eu", "jp"]`

```yaml
scan:
    priority:
        region:
            - "us"
            - "eu"
            - "jp"
```

#### Language

Sets preferred language for cover art and game title (Screenscraper only).

**Default:** `["en", "fr"]`

```yaml
scan:
    priority:
        language:
            - "en"
            - "es"
            - "fr"
```

### Media

Configures which media assets to download (Screenscraper and ES-DE gamelist.xml only).

**Media types:**

- `box2d` - Normal cover art (always enabled)
- `box3d` - 3D box art
- `miximage` - Mixed image of multiple media
- `physical` - Disc, cartridge, etc.
- `screenshot` - Screenshot (enabled by default)
- `title_screen` - Title screen
- `marquee` - Transparent logo
- `fanart` - User uploaded artwork
- `bezel` - Bezel displayed around the EmulatorJS window
- `manual` - Manual in PDF format (enabled by default)
- `video` - Gameplay video (warning: large file size)

```yaml
scan:
    media:
        - box2d
        - screenshot
        - manual
        - bezel
```

### Export gamelist.xml

Automatically generate an ES-DE compatible gamelist.xml file placed in the platform folder for selected/discovered platforms.

```yaml
scan:
    export_gamelist: true
```

---

## EmulatorJS Section

Configure EmulatorJS per-core options and controls.

### Debug

Enable debug mode to log available options to the browser console.

```yaml
emulatorjs:
    debug: true
```

### Cache Limit

Cache limit per ROM in bytes. Set to `null` for unlimited.

```yaml
emulatorjs:
    cache_limit: 52428800 # 50 MB
```

### Disable batch bootup

Skips the step that runs a batch file that sets soundcard information, mounts file systems, and attempts to run an `autorun.bat` file (try this if DOS games fail to boot).

```yaml
emulatorjs:
    disable_batch_bootup: true
```

### Disable auto-unload

The emulator stops/shuts itself down when you navigate to a new page; this setting stops that behaviour (if that's something you want).

```yaml
emulatorjs:
    disable_auto_unload: true
```

### Netplay

Enable [netplay](https://emulatorjs.org/docs4devs/netplay/#website-integration) and configure STUN/TURN servers. We recommend Google's public servers or [Metered's free tier](https://www.metered.ca/stun-turn).

```yaml
emulatorjs:
    netplay:
        enabled: true
        ice_servers:
            - urls: "stun:stun.l.google.com:19302"
            - urls: "stun:stun1.l.google.com:19302"
            - urls: "stun:stun2.l.google.com:19302"
            - urls: "turn:openrelay.metered.ca:80"
              username: "openrelayproject"
              credential: "openrelayproject"
            - urls: "turn:openrelay.metered.ca:443"
              username: "openrelayproject"
              credential: "openrelayproject"
```

<!-- prettier-ignore -->
!!! note
    When netplay is enabled, EmulatorJS loads some assets (including localization files) from the nightly CDN (`https://cdn.emulatorjs.org/nightly/...`). This differs from stable mode, which uses local/bundled assets. Occasional temporary issues (e.g., 404 errors or untranslated UI elements) can occur if the nightly CDN has mismatches, but these usually resolve with the next EmulatorJS stable release integrated into RomM.

### Settings

Configure core-specific settings. Use `default` to apply settings to all cores.

```yaml
emulatorjs:
    settings:
        parallel_n64: # Use the exact core name
            vsync: disable
        snes9x:
            snes9x_region: ntsc
        default: # These settings apply to all cores
            fps: show
```

### Controls

Map keyboard and controller controls for each player.

**Example (2-player SNES):**

```yaml
emulatorjs:
    controls:
        snes9x:
            0: # Player 1
                0: # Button mapping
                    value: x # Keyboard mapping
                    value2: BUTTON_2 # Controller mapping
            1: # Player 2
                0:
                    value: /
                    value2: BUTTON_2
```

See [EmulatorJS documentation](https://emulatorjs.org/docs4devs/control-mapping/) for control mapping details.

---

<!-- prettier-ignore -->
!!! tip
    You can find examples of full binded <a href="https://github.com/rommapp/romm/blob/master/examples/config.batocera-retrobat.yml" target="_blank" rel="noopener noreferrer">batocera</a> or <a href="https://github.com/rommapp/romm/blob/master/examples/config.es-de.example.yml" target="_blank" rel="noopener noreferrer">es-de</a> config files.

<!-- prettier-ignore -->
!!! warning
    Only uncomment or add the lines you need. Any omitted or empty sections will use RomM's defaults.

For a full example, see the <a href="https://github.com/rommapp/romm/blob/master/examples/config.example.yml" target="_blank" rel="noopener noreferrer">config.example.yml</a> file.