Skip to content

Exports

Library metadata can be emitted in formats other frontends expect, for setups where this is the library authority and a separate frontend (ES-DE, Batocera, Pegasus) is the actual launcher.

gamelist.xml (ES-DE/Batocera/RetroBAT)

ES-DE, Batocera, and compatibles look for a gamelist.xml in each platform folder, and these can be generated automatically.

Enable via config.yml

scan:
    gamelist:
        export: true
        media:
            thumbnail: box2d # which media type to use as thumbnail
            image: screenshot # which as full image

With export: true, every scan writes a gamelist.xml into the platform folder, and downloads the selected media into sibling folders (covers/, screenshots/, etc.) that ES-DE expects.

Standard ES-DE/EmulationStation format:

<gameList>
  <game>
    <path>./metroid.nes</path>
    <name>Metroid</name>
    <desc>...</desc>
    <releasedate>19861115T000000</releasedate>
    <developer>Nintendo R&amp;D1</developer>
    <publisher>Nintendo</publisher>
    <genre>Action-Adventure</genre>
    <image>./screenshots/metroid.png</image>
    <thumbnail>./covers/metroid.png</thumbnail>
  </game>
  ...
</gameList>

API endpoint

Trigger an export on demand:

POST /api/export/gamelist-xml
Authorization: Bearer <token>
Content-Type: application/json

{
  "platforms": ["snes", "nes"]   // empty = all
}

Response includes where the files were written.

Using with ES-DE

Once gamelist.xml has been generated and populated covers/ + screenshots/, point ES-DE at the library:

<string name="MediaDirectory" value="/path/to/ROMs/folder" />
<bool name="LegacyGamelistFileLocation" value="true" />
  • MediaDirectory: point it at the ROM folder (same path ES-DE uses for ROMDirectory), so ES-DE looks for media in-place rather than in its own library.
  • LegacyGamelistFileLocation: makes ES-DE write updates back to the same gamelist.xml read on import, rather than its separate config dir.

See also Metadata Providers → gamelist.xml for the import direction (reading gamelist.xml back in).

Pegasus

Pegasus is an alternative gaming frontend with its own metadata format. A metadata.pegasus.txt can be emitted per platform.

Enable via config.yml

scan:
    pegasus:
        export: true

Human-readable text format:

collection: Super Nintendo
shortname: snes
launch: /usr/bin/snes9x "{file.path}"

game: Super Metroid
file: /roms/snes/Super Metroid (USA).sfc
description: ...
developer: Nintendo R&D1
publisher: Nintendo
genre: Action-Adventure
release: 1994-03-19
assets.box: ./covers/Super Metroid.png
assets.screenshot: ./screenshots/Super Metroid.png

API request

POST /api/export/pegasus
Authorization: Bearer <token>
Content-Type: application/json

{
  "platforms": ["snes", "nes"]
}

Re-running on changes

Exports don't auto-rerun on every metadata edit, instead they run:

  • Next scan: exports are part of scan completion when enabled.
  • Manual trigger via the API above

See also