https://github.com/thingsiplay/lpled
LPL Editor - RetroArch playlist filter and stream editor
https://github.com/thingsiplay/lpled
Last synced: about 2 months ago
JSON representation
LPL Editor - RetroArch playlist filter and stream editor
- Host: GitHub
- URL: https://github.com/thingsiplay/lpled
- Owner: thingsiplay
- License: mit
- Created: 2025-10-25T14:09:50.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-10-25T14:30:44.000Z (7 months ago)
- Last Synced: 2025-12-13T14:33:23.441Z (6 months ago)
- Language: Rust
- Size: 77.1 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# LPL Editor
RetroArch playlist filter and stream editor.
- Author: [Tuncay D.](https://github.com/thingsiplay)
- Source: [Github](https://github.com/thingsiplay/lpled)
- Package: [Crates.io](https://crates.io/crates/lpled)
- License: [MIT](LICENSE)
## 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.
```bash
$ 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": ""
}
]
}
```
```bash
$ 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](https://docs.libretro.com/guides/roms-playlists-thumbnails/) /
[JSON Playlist
format](https://docs.libretro.com/guides/roms-playlists-thumbnails/#json-playlist-format)
- [Importing Content](https://docs.libretro.com/guides/import-content/)
[RetroArch](https://www.retroarch.com/) 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](https://github.com/thingsiplay/lpled/releases)
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](https://www.rust-lang.org/tools/install) -> Install Rust compiler
and toolchain
- On Windows only: **Microsoft Visual Studio Build Tools** (`msvc`):
[Download](https://visualstudio.microsoft.com/visual-cpp-build-tools/) ->
Install with "_Desktop development with C++_" option enabled (MS account login
is not required)
#### Build
##### Option 1: Automatic compile and install from Crates io
```bash
cargo install lpled
```
##### Option 2: Manually compile from Github
```bash
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](https://github.com/cross-rs/cross?tab=readme-ov-file) -> cross
compile to other platforms
- **Podman** `podman` | [podman](https://podman.io/) -> container system used
by Cross on Linux
- **Zip** (`zip`) -> needed to create the Zip package for Windows
```bash
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:
```bash
rustc --print target-list
```
Run script to build all targets and create packages for distribution:
```bash
bash build.sh
```
## Usage
```bash
Usage: lpled [OPTIONS] [FILE]...
```
Let's break down following command to its components:
```bash
lpled -f --write "output.lpl" "playlist.lpl"
```
```text
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.
```bash
# 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](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.
```bash
$ 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](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](https://docs.libretro.com/guides/roms-playlists-thumbnails/) at
Libretro Docs: Official Libretro documentation explaining basics of what
playlists are and how to work with them in RetroArch.
- [RetroArch Playlist
Editor](https://www.marcrobledo.com/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.