How to Build Auditable RetroArch Playlists and Thumbnail Sets

A RetroArch playlist is a catalog, not a preservation database. A polished label or matching box image does not prove that a file is the expected region, revision, or dump. Build the catalog from verified content, keep the preservation copy read-only, and retain enough evidence to reproduce every match.

The safest workflow uses RetroArch’s database-backed scan first, reserves manual scanning for known exceptions, and reviews the resulting .lpl files before accepting a large metadata change.

Step 1: separate preservation masters from play copies

Keep verified masters in a read-only location with a manifest containing filename, system, region, revision, size, and a cryptographic hash. Build playlists from a separate play copy. Patches, archive conversions, header changes, and multi-disc playlist files belong in that working collection, not over the master.

Do not download a replacement merely because a scan fails. An unmatched file can be homebrew, a translation, a different revision, a bad dump, or a format whose identifying data is not where RetroArch expects it. Establish provenance before renaming or transforming it.

Step 2: define one system-sized scan scope

Place one platform’s play copies in a dedicated directory. Separate region or revision only when that distinction is useful to the player. Avoid a single directory containing unrelated systems, firmware, patches, cover art, and extracted archive debris.

Disc-based games need particular care. Preserve the cue sheet and referenced tracks together, and use a correctly constructed .m3u for multi-disc titles when the selected core documents that workflow. Do not zip disc images merely to make a directory look tidy; support varies by core and random-access performance can suffer.

Step 3: update the matching data before scanning

From Main Menu → Online Updater, update Core Info Files and Databases when those updater entries exist in the installed build, then restart RetroArch. Package-maintainer builds can disable or relocate updater functions, so use the package’s supported update path rather than replacing files from an arbitrary mirror.

Record the RetroArch version and database revision or update date. A playlist produced by yesterday’s database can legitimately differ from one produced today; that is why the audit needs a baseline.

Step 4: run a database-backed scan first

Use Import Content → Scan Directory or Scan File for the selected system. RetroArch’s regular scanner identifies content using the Libretro database, including checksums or disc serials where applicable. It is intentionally strict: a visually plausible filename is not sufficient.

Review the resulting playlist and count matched, missing, and unexpected entries. Launch a small sample through the assigned core. If hundreds of unrelated files suddenly appear, quarantine the new playlist and inspect the scan scope instead of hand-correcting every label.

Step 5: investigate every unmatched item

For an unmatched cartridge image, check format, header treatment, region, language, revision, size, and hashes against an authoritative preservation record you are entitled to use. For disc content, inspect cue paths, track order, serial, executable, and the core’s documented supported formats.

Do not remove headers, merge tracks, or convert formats until a verified source explains why. Any transformation should create a new play copy and a log containing the tool/version, exact command, input hash, and output hash. Re-scan the result and preserve the original.

Step 6: use Manual Scan only for known exceptions

Import Content → Manual Scan is appropriate for verified homebrew, translations, hacks, prototypes, or formats deliberately absent from the database. Select the content directory, system name, default core, and supported file extensions deliberately. Enable recursive scanning only when the directory structure requires it.

A manual scan can create a convincing entry for the wrong file because it relies more heavily on filenames and the supplied scan settings. Mark manually curated entries in the external manifest, retain their source/license or patch provenance, and never treat their presence in a playlist as database validation.

Step 7: audit the playlist file itself

RetroArch stores playlists as .lpl JSON. Entries can include path, label, core_path, core_name, crc32, and db_name. Open a copy in a JSON-aware editor and verify that:

• every path resolves to the intended play copy;
• labels distinguish meaningful region or revision variants;
• core name and path refer to an installed, trusted core;
• database attribution is plausible for the system;
• checksum information is retained when the scanner produced it;
• no credential, private directory, or unrelated file leaked into the catalog.

Do not edit while RetroArch is running; it may overwrite the file on exit. Validate JSON syntax after any manual change and retain the previous playlist for rollback.

Step 8: assign cores narrowly

Use a playlist default only when one supported core is appropriate for the collection. Test content before choosing Set Core Association broadly. Arcade software is especially sensitive to the emulator family and matching data set; selecting a newer or differently named core does not make an incompatible ROM set correct.

For exceptions, launch the entry with the required supported core or curate that association without changing unrelated entries. Record the core name/version alongside the content hash so a future failure can be distinguished from database or content drift.

Step 9: download and curate thumbnails safely

Use RetroArch’s official thumbnail updater for the relevant playlist, then inspect several entries from each region/revision group. Thumbnail lookup follows playlist/system naming rules and flexible matching; punctuation and labels can still create misses or wrong artwork.

Back up custom images before running a bulk updater. The official documentation warns that updater activity can overwrite custom thumbnails. Keep custom artwork outside the managed tree as a master and copy it into the expected Named_Boxarts, Named_Snaps, or Named_Titles location only after the playlist label is final.

Use artwork you have the right to store and publish. A box image is descriptive metadata, never evidence that the underlying file is authentic.

Step 10: detect collisions and silent drift

Look for duplicate normalized labels, duplicate paths, one path assigned to multiple systems, and multiple files collapsed onto one thumbnail name. Confirm case sensitivity on the target filesystem: a set that works on a case-insensitive desktop can fail after moving to Linux.

Before any database, core, or RetroArch update, save a timestamped copy of playlists and custom thumbnails. Afterward, perform a structured diff. Review mass relabeling, deleted checksums, changed core paths, and new entries before replacing the known-good catalog.

Step 11: test the user path

Restart RetroArch, open the playlist, and test at least one cartridge title, one archive if supported, one disc title, and every manual-scan category present. Verify label, thumbnail, selected core, launch, in-game save, clean exit, and second launch.

Also test one intentionally missing or unsupported item. A reliable catalog should fail clearly rather than launching an arbitrary core or showing misleading art.

Step 12: preserve a reproducible manifest

Store the playlist backup beside a manifest with RetroArch version, database date, core versions, master and play-copy hashes, transformations, manual exceptions, thumbnail source/license, and test results. Do not include copyrighted game content in that audit bundle.

The catalog is ready when every entry resolves, database matches remain distinguishable from manual curation, core associations survive restart, custom art survives a controlled updater test, and a diff can explain every change. Related: RetroArch 1.0.0.0 Ships Simultaneously on Seven Platforms · Fixing Shader Compilation Stutter in Emulators and RetroArch

Sources: Libretro playlist and thumbnail guide, Libretro database guide, Libretro import-content guide, Libretro starting-content guide, Official Libretro database repository