ZX Spectrum Frontend Meta Generator

Create your metadata for your favourite emulator backend using the ZXInfo API

Fast, efficient, modern... just like Windows 98^tm

---

Table of contents

• Features
• Build & Install
  • Prerequisites
  • Build
  • Install
  • Arm (RaspberryPi)
• Usage
• Examples
• Game Description/Synopsis
• License

---

Features

• Uses ZXInfo API
• Command Line application
• Zip, 7z archive support
• Progress Bars that range from 0 to 100%!
• Supports all known spectrum roms, such as the TOSEC set
• Supports Linux, MacOS, and Windows
• Supports arm, so can be used on RaspberryPI (under linux e.h. RaspOS)
• Supports image assets such as screenshots and box art
• Uses Wikipedia API and IGDB API to find game synopsis, if available
• Generates for multiple emulator frontends (currently only supports Pegasus, and partial support for LaunchBox)
• A lovely 48k Speccy ASCII art from https://github.com/redcode/ASCII-Art/
• Other features coming at some point in the future

---

Prerequisites

Tools are required for the application to function.

p7zip - to install 7z command, required for archive based file support e.g. zip, 7z, rar

OSX

brew update && brew doctor && brew install p7zip

Debian/Ubuntu

sudo apt-get install p7zip-full

Windows

The easiest way is to visit https://www.7-zip.org/download.html and download the latest 7z-extra (https://www.7-zip.org/a/7z2107-extra.7z is the latest at the time of writing). Then extract and copy 7za.exe into your PATH.

---

Build

NodeJS is required so please install according to their documentation for your system. It should be fully backwards compatible this version was written with NodeJS v16+.

The final complicated executable is build using pkg. Their documentation outlines other options you can use when building.

To build locally:

git clone https://github.com/leemm/zxspectrum-meta-generator.git
npm i
npm run build

To start locally:

npm start -- <switches>

// For example
npm start -- --src ~/Downloads/Games/roms --output '~/Downloads/Games/metadata.pegasus.txt'

To package locally:

npm run package

To deploy your build there is a script. It will install to /usr/local/bin.

npm run install-package

The packaged version can then run as normal from the ./dist directory e.g. ./dist/zxgenerator. See Examples.

If developing there is a helper script increase the version number, as it's in 3 different places. Simply run this to increase the version but keep them in sync:

npm run version -- --type major, minor, or patch

If you wish to add functionality feel free to PR.

---

RaspberryPi

The build and install process is slightly different, but is easy to do.

git clone https://github.com/leemm/zxspectrum-meta-generator.git
npm i
npm run build
npx pkg ./dist/zxgenerator.js --out-path ./dist
npm run install-package

This will build and deploy to /usr/local/bin/zxgenerator.

Install

Ensure you have the tooling you need from prerequisites.

Then download your binary from releases. There are builds for linux (tested on debian based distro), MacOS, and Windows.

Copy the download to your prefered location. For example:

gzip -d ~/Downloads/zxgenerator-linux.gz
cp ~/Downloads/zxgenerator-linux /usr/local/bin/zxgenerator && chmod +x /usr/local/bin/zxgenerator

ARM users, it's recommended you build. Tested on Pi400.

---

Usage

zxgenerator [OPTIONS]

Option	Description	Type	Default	Required?
--launch	Emulator/Script launch path. Game path is automatically added to the end of the process.	string	<retropiepath>/runcommand.sh 0 _SYS_ zxspectrum <game>	No
--src	Root directory of your spectrum tape/disk images.	string		Yes
--output	Destination directory and filename of your meta file.	string		Yes
--assets	Destination directory of media assets.	string	same directory as --output	No
--platform	Generate meta files for your chosen platform. Supported values: pegasus, launchbox. Defaults to pegasus.	string	pegasus	No
-v, --verbose	Turn on debugging output.	boolean	false	No
--verbose-save	Saves the verbose log to the --output directory.	boolean	false	No
--audit-assets	Assets will be audited for missing files, incorrectly ratio'd covers. (Comma-separated) valid values are titles, screens, and covers. Assets will be same directory as --output or via value supplied in --assets.	string		No
--move-failed	Specify a directory to move files that have not been found via the API	string		No
--twitch-client-id	Your Twitch app client id (Used for Game Description/Synopsis optional)	string		No
--twitch-client-secret	Your Twitch app client secret (Used for Game Description/Synopsis optional)	string		No
--version	Print version info.	boolean	false	No
--help	Shows this help screen.	boolean	false	No

---

Game Description

The app can scrape game intro and description from various sources. Wikipedia is used first but the optional IGDB.com API can also be used.

In order to use the IGDB.com API, you must have a Twitch Account.

The IGDB.com API is free for non-commercial usage under the terms of the Twitch Developer Service Agreement.

• Sign Up with Twitch for a free account
• Ensure you have Two Factor Authentication enabled
• Register your application
• Manage your newly created application
• Generate a Client Secret by pressing [New Secret]
• Take note of the Client ID and Client Secret
• Pass these keys as parameters (See Usage)

---

Examples

This is the most basic usage. --src will be recursively scanned for valid spectrum tape/disk images, and the file ~/Downloads/meta.txt will be generated. If ~/Downloads/meta.txt already exists it will be backed up in the format ~/Downloads/meta-YYYYMMDDHHmmss.txt. Assets will be downloaded to the same directory as --output, where a new directory called assets will be created.

zxgenerator --src ~/Downloads/tapes --output '~/Downloads/meta.txt'

Same as basic usage but assets will be downloaded to the directory specified as --assets, ~/Desktop/assets.

zxgenerator --src ~/Downloads/tapes --output '~/Downloads/meta.txt' --assets '~/Desktop/assets'

Same as basic usage but the generated metafile will launch games using '/usr/bin/fuse {path_to_game}'.

zxgenerator --src ~/Downloads/tapes --output '~/Downloads/meta.txt' --launch '/usr/bin/fuse'

Same as basic usage but the generated metafile will be structured for usage in launchbox.

zxgenerator --src ~/Downloads/tapes --output '~/Downloads/meta.txt' --platform 'launchbox'

Same as basic usage but with (very) verbose output.

zxgenerator --src ~/Downloads/tapes --output '~/Downloads/meta.txt' --verbose

Same as basic usage but with (very) verbose output AND the verbose output is saved to a log file instead in the same directory as --output.

zxgenerator --src ~/Downloads/tapes --output '~/Downloads/meta.txt' --verbose --verbose-save

Audit your covers and screenshots directories (~/Desktop/assets'). This will check the images for valid or missing values, including prompting to allow you to download a new cover.

zxgenerator --src ~/Downloads/tapes --output '~/Downloads/meta.txt' --assets '~/Desktop/assets' --audit-assets covers,screens

---

License

This project is licensed under the terms of the ISC license.