Docs: document PS1 support, cover sources, and new env vars

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`
+  `libretro-index.json` + `openvgdb-index.json` catalogs, `libretro-covers.zip` +
-  offline cover bundles, and the legacy cover cache.
+  `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`,
+`IGDB_CLIENT_SECRET`, `TMDB_API_KEY`, `GOOGLE_API_KEY`, `GOOGLE_CX`,
-`SCREENSCRAPER_DEVPASSWORD`, `SCREENSCRAPER_SSID`, `SCREENSCRAPER_SSPASSWORD`,
+`SCREENSCRAPER_DEVID`, `SCREENSCRAPER_DEVPASSWORD`, `SCREENSCRAPER_SSID`,
-`SCREENSCRAPER_SOFTNAME`.
+`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
+UMD **videos** have no public box-art API. The manual **Scrape…** dialog offers
-TheMovieDB poster composited into `data/covers/UMD_COVER_TEMPLATE.png`.
+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>/PSP/GAME/<Game ID>/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`