LPL Editor

RetroArch playlist filter and stream editor.

• Author: Tuncay D.
• Source: Github
• Package: Crates.io
• License: MIT

What is LPL Editor?

"LPL Editor" (or lpled for short) is a command line application written in Rust to view, combine, filter, edit and remix "RetroArch Playlist" files. Add options and patterns to filter content or customize output, inspired by tools like grep and jq. This is not a ROM or media files manager. Games need to be imported into Playlists through RetroArch first.

$ lpled --label "Cotton" "tests/data/history.lpl"
{
  "version": "1.5",
  "default_core_path": "",
  "default_core_name": "",
  "base_content_directory": "/home/tuncay/Emulation/Roms",
  "label_display_mode": 0,
  "right_thumbnail_mode": 0,
  "left_thumbnail_mode": 0,
  "thumbnail_match_mode": 0,
  "sort_mode": 2,
  "items": [
    {
      "path": "/home/tuncay/Emulation/Roms/arcade/arcade_stv/cotton2.zip",
      "label": "Cotton 2 (JUET 970902 V1.000)",
      "core_path": "/home/tuncay/.config/retroarch/cores/kronos_libretro.so",
      "core_name": "Sega - Saturn/ST-V (Kronos)",
      "crc32": "9E20EDA6|crc",
      "db_name": "MAME.lpl"
    },
    {
      "path": "/home/tuncay/Emulation/Roms/pcenginecd/pcenginecd_redump/Fantastic Night Dreams - Cotton (USA).chd",
      "label": "Fantastic Night Dreams - Cotton (USA)",
      "core_path": "/home/tuncay/.config/retroarch/cores/mednafen_pce_libretro.so",
      "core_name": "NEC - PC Engine / SuperGrafx / CD (Beetle PCE)",
      "crc32": "00000000|crc",
      "db_name": ""
    }
  ]
}

$ lpled -F '{label}\n\t{core_name}' --label "Cotton" "tests/data/history.lpl"
Cotton 2 (JUET 970902 V1.000)
        Sega - Saturn/ST-V (Kronos)
Fantastic Night Dreams - Cotton (USA)
        NEC - PC Engine / SuperGrafx / CD (Beetle PCE)

Features

• merge multiple playlists
• search filters with regex support
• sort game entries
• remove duplicate game entries
• check for missing ROM files
• respect default core for "DETECT" values
• output data in color or custom format
• fuzzy finder selection menu
• play game directly with RetroArch
• and more...

What is a RetroArch Playlist?

Libretro Docs:

• ROMS, Playlists, and Thumbnails / JSON Playlist format
• Importing Content

RetroArch brings many emulators adapted as "core" plugins together and manages user configuration in a cohesive environment. Games are organized into "RetroArch Playlists". Playlists show up in the user interface as clickable game entries and contain information such as location of ROM files and their associated cores. These files are regular text data encoded in JSON format with file extension ".lpl". Each data field consist of a "key": "value" pair. In example "label" would be the name of the key and "Fantastic Night Dreams - Cotton (USA)" it's associated value.

Installation

Download (simple)

Get pre-compiled binaries:

1. Go to Releases Page
2. Download the archive file for your operating system
3. Extract and run lpled

Compile from source (advanced)

Compile process downloads lot of library dependencies.

Pre-requisites

• Rustup (rustc and cargo): Download -> Install Rust compiler and toolchain
• On Windows only: Microsoft Visual Studio Build Tools (msvc): Download -> Install with "Desktop development with C++" option enabled (MS account login is not required)

Build

Option 1: Automatic compile and install from Crates io

cargo install lpled

Option 2: Manually compile from Github

git clone https://github.com/thingsiplay/lpled
cd lpled
cargo build --release
cd target/release

Option 3: Cross compilation

First install the required tools for the build script. A Linux environment is expected:

• Cross (cross) | cross -> cross compile to other platforms
• Podman podman | podman -> container system used by Cross on Linux
• Zip (zip) -> needed to create the Zip package for Windows

pacman -S podman zip  # use your distros package manager in place of `pacman -S`
cargo install cross

Look into the build.sh Bash script and adapt it for your needs, especially the TARGETS variable. List available targets with:

rustc --print target-list

Run script to build all targets and create packages for distribution:

bash build.sh

Usage

Usage: lpled [OPTIONS] [FILE]...

Let's break down following command to its components:

lpled -f --write "output.lpl" "playlist.lpl"

               option name
               (expects argument)
                   |
program name       |    argument to option
  |                |         |
-----           -------   ------------
lpled    -f     --write   "output.lpl"      "playlist.lpl"
         --     ----------------------      --------------
          |                                      |
          |                              input filename
      flag option
      (without argument)

Standard operations

When loading files, standard operations are executed and applied to modify data. Original file on disk is not modified by default.

1. Load list of files. Additionally read data or paths from stdin.
2. Apply default values to each game entry: replace "DETECT" in core_name and core_path with their defaults, fill empty label from filename at path and fill empty crc32 with "00000000|crc"
3. Add key origin to each game entry temporary. By default this will be removed before output.
4. Multiple files are merged into single data.
5. Non printable characters are escaped for safe screen output. Note: By default files written to disk are not affected.
6. Final playlist data is printed to stdout.

Default behaviours can be changed with options.

Examples

Note: The #-line is a comment explaining the command.

# Show list of all available options.
lpled --help

# Multiple input files are merged.
lpled "tests/data/fzero.lpl" "tests/data/mario.lpl"

# Add coloring to the data output.
lpled --color "tests/data/mario.lpl"

# Filter entries by Regular Expression.
lpled --find-label "^Co..on" "tests/data/history.lpl"

# Sort by multiple key factors.
lpled --sort "db_name" --sort "label" "tests/data/history.lpl"

# Save any changes to data as a new file.
lpled --write "mario_out.lpl" "tests/data/mario.lpl"

# Output in custom template format.
lpled --template '{path}' "tests/data/mario.lpl"

# Pick menu to select a game entry interactively.
lpled --pick "label" "tests/data/mario.lpl"

# Run and play top most game with RetroArch command.
lpled --launch "retroarch" "tests/data/neogeo.lpl"

See more usage examples at EXAMPLES.md.

What are Templates?

Output can be freely formatted and structured on the fly. Format instructions are given by option --template FORMAT (or -F for short). To access an associated value, put name of key between curly braces { and }, such as "{label}", which loops over each game entry automatically and prints content to screen. Newline "\n" and "\t" can be added for additional formatting. Other text is output literally.

$ lpled --template '{path}' --label "Cotton" "tests/data/history.lpl"
/home/tuncay/Emulation/Roms/arcade/arcade_stv/cotton2.zip
/home/tuncay/Emulation/Roms/pcenginecd/pcenginecd_redump/Fantastic Night Dreams - Cotton (USA).chd

Learn more about this at TEMPLATE.md.

Additional notes, workarounds and quirks

Non printable characters in JSON

There are characters that can't be displayed in RetroArch or in your terminal output. Upon reading the files those characters are encoded as a special Unicode sequence in form of "\u00xx". This is not common at all, but I got a a few files that include such characters. This special encoding makes it more robust to display them on the terminal. However on file output for saving on disk, the data is unchanged and no special encoding is done.

Current state, future plans and contributions

Builds are developed and mainly tested on a Linux machine. The Windows build needs some more testing with real data from real Windows users.

At the current moment, I am not much interested into adding more features. I would consider new features only if either I am interested myself or if its a big deal to others. And only if the implementation isn't too complicated, does not break existing usage or test cases. Exceptions can be made.

If you find a bug, need documentation or have any kind of problems using this tool, please report.

See also

• ROMs, Playlists, and Thumbnails at Libretro Docs: Official Libretro documentation explaining basics of what playlists are and how to work with them in RetroArch.
• RetroArch Playlist Editor by Marc Robledo: A pretty neat third party application in the browser with a graphical user interface. It is simple, it is easy to use, and it can edit entries. Highly recommended to check out.