From 777d316c0f9ff93fd909812e769bb7e82d4bb95d Mon Sep 17 00:00:00 2001 From: Mathieu Moran Date: Mon, 7 Sep 2026 14:11:09 -0400 Subject: [PATCH] Docs: document PS1 support, cover sources, and new env vars --- README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 47 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a1b0458..f8f57f3 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,8 @@ Native Linux GUI (PySide6) for preserving PSP UMD **games** and **videos** as `.iso` files. It scans your discs, verifies them against the full Redump catalog (Redump DATs), reports what's missing, and retags/renames discs to a canonical scheme. It also fetches cover art and metadata, syncs discs and save-data with a -real PSP, and can pull missing discs from your own Redump 7z archive collection. +real PSP, can pull missing discs from your own Redump 7z archive collection, and +converts PlayStation 1 ISO/CUE/BIN rips into PSP `EBOOT.PBP` homebrew. ![PSP Preservation Tool](img/qt-gui.png) * Use default app theme for Qt. @@ -25,6 +26,9 @@ real PSP, and can pull missing discs from your own Redump 7z archive collection. from the PSP, and dump a UMD to the library. - **Saves** — two-way sync of save-data between the PSP, PPSSPP, and a cloud folder. +- **PS1** — scan a folder of PlayStation 1 discs (ISO/BIN/CUE), read each disc's + serial, convert to PSP `EBOOT.PBP` with a pure-Python popstation converter, + and track already-converted games. - **Settings** — directories, cover-source API keys, store/server config, and misc options. @@ -65,6 +69,10 @@ python3 -m app.main 3. Open the GUI and point **Settings → General → Games/Videos directory** at your disc folders (or set `PSP_GAMES_ROOTS` / `PSP_VIDEO_ROOTS`). +4. (Optional) PS1 conversion — copy any PSN PS1 classic `EBOOT.PBP` to + `data/base.PBP` (it supplies Sony's encrypted loader). Then set the **PS1 + directory**, **PS1 output directory** and **PS1 base.pbp** in + **Settings → General** and use the **PS1** tab (see [PS1 support](#ps1-support)). Discs that aren't in the Redump DATs can be added to `data/supplement.json` (`name`, `region`, `crc32`, `sha1`, `md5`) so the tool still recognizes them. @@ -80,11 +88,13 @@ Discs are matched by hash first (most precise), then serial, then filename. - `data/dats/` — clrmamepro DAT files (games + videos). - `data/supplement.json` — extra discs not in Redump. - `data/credentials.json` — cover/metadata API keys (IGDB, TheMovieDB, - ScreenScraper). Environment variables take precedence. + ScreenScraper, Google Custom Search). Environment variables take precedence. - `data/manual_covers/games|videos/` — your own cover images. - `data/covers/` — checked-in assets: the UMD video/game cover templates, - `libretro-index.json` catalog, `libretro-covers.zip` + `openvgdb-covers.zip` - offline cover bundles, and the legacy cover cache. + `libretro-index.json` + `openvgdb-index.json` catalogs, `libretro-covers.zip` + + `openvgdb-covers.zip` offline cover bundles, and the legacy cover cache. +- `data/base.PBP` — a PSN PS1 classic EBOOT (any game) used as the encrypted + loader when converting PS1 discs to `EBOOT.PBP` (git-ignored, copyrighted). - State dir (`~/.local/state/psp-preserve/` by default, or `$XDG_STATE_HOME/psp-preserve`): - `library.sqlite` — the catalog + library database. - `covers/` — downloaded cover cache. @@ -107,6 +117,8 @@ QSettings under `PSPPreserve`) taking precedence where noted. | `PSP_COVERS_DIR` | `$PSP_STATE_DIR/covers` | cover cache | | `PSP_GAMES_ROOTS` | `/data/umd_games` | comma-separated game disc roots | | `PSP_VIDEO_ROOTS` | `/data/umd_videos` | comma-separated video disc roots | +| `PSP_PS1_ROOTS` | `/data/ps1` | comma-separated PS1 disc roots | +| `PSP_PS1_OUTPUT_DIR` | `/data/ps1_converted` | converted EBOOT.PBP output folder | | `PSP_SCAN_WORKERS` | `1` | parallel hashing workers | | `PSP_STORE_DIR` | `/media/downloads/Sony - PlayStation Portable` | local 7z store folder | | `PSP_STORE_SERVER` | `https://psp.example.com` | store server base URL | @@ -120,9 +132,9 @@ QSettings under `PSPPreserve`) taking precedence where noted. | `PSP_OVGDB_COVERS_URL` | *(empty)* | direct URL for `openvgdb-covers.zip` (else derived from store server) | Cover/metadata keys can also be set as env vars: `IGDB_CLIENT_ID`, -`IGDB_CLIENT_SECRET`, `TMDB_API_KEY`, `SCREENSCRAPER_DEVID`, -`SCREENSCRAPER_DEVPASSWORD`, `SCREENSCRAPER_SSID`, `SCREENSCRAPER_SSPASSWORD`, -`SCREENSCRAPER_SOFTNAME`. +`IGDB_CLIENT_SECRET`, `TMDB_API_KEY`, `GOOGLE_API_KEY`, `GOOGLE_CX`, +`SCREENSCRAPER_DEVID`, `SCREENSCRAPER_DEVPASSWORD`, `SCREENSCRAPER_SSID`, +`SCREENSCRAPER_SSPASSWORD`, `SCREENSCRAPER_SOFTNAME`. ## Cover art @@ -142,8 +154,11 @@ Games are resolved in this order (offline-first, then network): 3:4 key art, so the app composites it into the PSP game cover template (`data/covers/UMD_GAME_COVER_TEMPLATE.png`) to restore the full cover. -UMD **videos** have no public box-art API: they use your manual covers, or a -TheMovieDB poster composited into `data/covers/UMD_COVER_TEMPLATE.png`. +UMD **videos** have no public box-art API. The manual **Scrape…** dialog offers +three sources: TheMovieDB posters, Wikipedia image search (keyless), and Google +Images (needs a Google API key + Search Engine ID in **Settings → Cover +sources**). The pick is composited into `data/covers/UMD_COVER_TEMPLATE.png`. +Manual covers in `data/manual_covers/videos/` always win. ### Offline bundles & auto-download @@ -161,6 +176,25 @@ python3 -m app.openvgdb # OpenVGDB/GameFAQs -> openvgdb-covers.zip (`app.openvgdb` needs `curl_cffi` to pass GameFAQs' Cloudflare challenge.) +## PS1 support + +The **PS1** tab scans a folder of PlayStation 1 rips and converts them into PSP +`EBOOT.PBP` files with a pure-Python popstation converter (no external tools). + +- **Source formats** — `.iso`, `.img`, `.bin` (with a matching `.cue` for + multi-track discs). +- **Serial detection** — reads `SYSTEM.CNF` to derive the game ID (e.g. + `SLUS-00001`) and writes it into `PARAM.SFO` + the PSAR header. +- **base.pbp** — conversion needs a PSN PS1 classic `EBOOT.PBP` (any game) to + supply Sony's encrypted `DATA.PSP` loader. Copy one to `data/base.PBP` and + point **Settings → General → PS1 base.pbp** at it. +- **Output** — `Title (Game ID).pbp` in the **PS1 output directory**. To run on + a PSP, copy each one to `/PSP/GAME//EBOOT.PBP`. + +Configure the folders in **Settings → General** (or `PSP_PS1_ROOTS` / +`PSP_PS1_OUTPUT_DIR`). Current limits: single-disc games only (no multi-disc +PBP), and images are stored uncompressed (LZRC compression is on the roadmap). + ## Store — archive.org and local folder The **Store** tab downloads missing discs from a Redump 7z archive collection @@ -292,6 +326,10 @@ python3 -m app.ingest --dats data/dats --db data/library.sqlite # (re)build the offline cover bundles (see Cover art) python3 -m app.libretro python3 -m app.openvgdb + +# convert one PS1 disc to EBOOT.PBP (CLI) +python3 -m app.ps1_convert --source /path/to/game.cue --title "Game" \ + --game-id SLUS00001 --base-pbp data/base.PBP --out /out/Game.pbp ``` `python3 -m app.scan --json` prints machine-readable results, and `--quick`