Skip to content

Home

Jump to bottom
Julien Clauzel edited this page Jul 14, 2026 · 37 revisions

ZX-Next-Unite

ZX-Next-Unite by Julien Clauzel, based on:

  • HDFM-GOOEY by em00k, and
  • NextSync by Jari Komppa (with the Sync4 extensions by Julien Clauzel).

A cross-platform (Windows, Linux, macOS) graphical front-end that unites two great ZX Spectrum Next tools in a single utility — Hdfm-Gooey and NextSync — and adds a built-in browser for discovering ZX Spectrum / Spectrum Next software across several online archives (GetIt, ZXDB/ZXInfo, zxArt and itch.io).

  • The SD Card tab targets CSpect and MAME users: mount an HDF image, copy content in and out with a simple file explorer, then launch the emulator — no command-line options to memorise.
  • The NextSync tab is for real hardware owners (KS1, KS2 or clones with an ESP Wi-Fi module): push content from your PC to the Next over the network.

Just want to install it? See the Installation page.

Contents

Licensing

ZX-Next-Unite is licensed under the MIT license.

It is a Qt application built with PySide6 and pygame-ce on top of Qt 6, which retains its GPLv2/LGPL licensing (see the LICENSE file). It optionally uses itch-dl by Dragoon Aethis (MIT, © 2022) to power the itch.io tab. Like PySide6 and pygame-ce, itch-dl is not bundled with a standard Python install and must be installed separately (pip install -r REQUIREMENTS.txt); the itch.io tab only appears when it is installed.

Videos

Older Py-Hdfm-Gooey videos:

The SD Card / emulator tab

The first tab is aimed at CSpect and MAME users and developers. You mount an HDF image (think of it as an ISO that contains everything the machine needs to boot) and upload/download content using a built-in file explorer. Once your content is on the image, launch CSpect or MAME directly from the app. Key settings such as screen size are adjustable in the UI, so you never need to remember emulator command-line options.

See Installation → Optional components for how to set up CSpect, MAME, hdfmonkey and the system images.

The NextSync tab

The second tab is for real-hardware owners whose Next has an ESP (Wi-Fi) module. Jari Komppa's NextSync protocol synchronises a folder from your PC/Mac/Linux machine to the Next over the network. ZX-Next-Unite implements the server side that listens for the Next; your Next runs a dot command that connects to it (by default over TCP port 2048).

  • Current command: .sync4 — the Sync4 protocol: faster transfers and bidirectional sync (.sync4 -send <file|dir> pushes files back from the Next to the PC). Speed hints -slow, -default, -fast replace the old syncfast/syncslow commands.
  • Legacy command: .sync — the older PC → Next-only command still works.

Typical usage: open the NextSync tab, select the folder to sync, and click Start NextSync server. The first run, enable Sync once so the server stops after a single sync while you verify things. Then run .sync4 on the Next. Once the first full sync completes, a SyncPoint file records what has been sent so subsequent runs only transfer what changed. syncignore.txt lets you exclude file types from syncing (see Jari's documentation).

📖 Full step-by-step setup, IP configuration and building the dot from source: Installation → NextSync.

Online libraries: GetIt, ZXDB, zxArt

Three tabs let you search and download ZX Spectrum / Spectrum Next software directly from public community archives. ZX-Next-Unite is only a front-end client: it queries each service's public API and downloads from the URLs those APIs return (see the legal disclaimer).

Tab What it is API base used
🌍 GetIt Browse and download software published for the Spectrum Next. https://zxnext.uk
🌍 ZXDB / ZXInfo.dk The largest open database of ZX Spectrum software (search titles, view screenshots and inlays). Data via the ZXInfo API; project at github.com/zxdb/ZXDB. https://api.zxinfo.dk/v3
🌍 ZXArt.ee The zxart.ee gallery/archive of ZX Spectrum art, music and productions (demos, games, graphics). https://zxart.ee/api

An optional itch.io tab also appears when itch-dl is installed and you have entered your itch.io API key — it browses your collections/owned games and installs selected items. Anything you download can then be copied to your HDF image or synced to your Next.

Keyboard shortcuts

The three built-in file explorers (the SD Card local explorer, the SD Card disk-image explorer and the NextSync local explorer) share the usual editing shortcuts. Copy / Cut / Paste work across all three explorers and also exchange with the operating-system clipboard (e.g. copy in Windows Explorer, then paste into the disk image, and vice-versa):

  • Ctrl+C — Copy the selected file(s)/folder(s) to the shared clipboard.
  • Ctrl+X — Cut the selection (moved to the destination on the next paste).
  • Ctrl+V — Paste into the selected folder (or the folder currently shown).
  • F2 — Rename the selected file or folder.
  • Delete — Delete the selected file or folder (disk-image and NextSync explorers).

In the picture (gallery) item viewer — opened by double-clicking an item in the GetIt, ZXDB, zxArt or itch.io tabs:

  • Esc — Close the viewer and return to the gallery.
  • Left / Right arrows — Show the previous / next screenshot.

Installation

On Windows, the easiest route is to download the latest ZX-Next-Unite-v8.x executable from the Releases page (plus the .sync4 dot command if you want NextSync) — no Python required.

On any platform you can run from source: install a recent Python (3.13 recommended), clone the repo, install the dependencies, and run:

git clone https://github.com/jclauzel/ZX-Next-Unite
cd ZX-Next-Unite
python -m pip install -r REQUIREMENTS.txt
python zx-next-unite.py

(On Linux/macOS use python3. Only PySide6 is required; pygame-ce and itch-dl are optional.)

👉 Full instructions — virtual environments, CSpect/MAME/hdfmonkey/Mono setup and troubleshooting — are on the Installation page.

Settings

All options are stored in a single hdfg.cfg file, created automatically in the same directory as the tool. The format is compatible with em00k's original tool but adds more options (including NextSync support). To reset everything, back up and delete hdfg.cfg.

Startup parameters

To force a specific retro animation on startup (requires pygame-ce):

python zx-next-unite.py --anim <walk|c5|ufo|aliens>

aliens spawns Sir Clive's saucer plus the attacking green alien squadron.

Known issues

  • hdfmonkey is required. On startup the app checks your PATH for it. On Windows it can auto-download it; on macOS/Linux you install it manually. If the Windows auto-download fails while your internet works, it is almost always a firewall blocking outbound calls from python.exe (or the app exe) — see Installation → Troubleshooting.
  • PySide6 and a recent Python are required — install these first (see Installation).
  • Non-Windows platforms require you to install/compile hdfmonkey manually and install Mono (to run CSpect, which is .NET-based).
  • Special characters (e.g. single quotes) in filenames on the Next image may not download correctly.
  • ESP / Wi-Fi errors can occur on an unstable connection; reduce the rate with the Slow transfer option (or -slow).
  • Timer messages in the console during NextSync can be safely ignored.
  • If NextSync misbehaves, try Jari Komppa's original command-line nextsync.py first (bundled in the nextsync v1.2 release); ZX-Next-Unite shares the same code base, so if that syncs, this should too.

Source & architecture

ZX-Next-Unite is written in Python (PySide6/Qt 6). The entry point is zx-next-unite.py, which holds the single MainWindow class and all tab/pane UI. The rest is split into focused modules:

File Role
zx-next-unite.py Entry point; MainWindow and all tab/pane UI logic
zxnu_config.py Constants, SETTING_* keys, API base URLs, UI strings, colour defaults and pure helpers
zxnu_workers.py Background threading primitives (signals, HDF task worker, progress dialog)
zxnu_media.py ZX Spectrum SCREEN$ decoder, placeholder rendering, format tags, shared pixmap cache
zxnu_gallery.py Reusable gallery widgets (cells, grid view, animated background)
zxnu_itchio.py Optional itch.io integration (detection, API access, install via itch-dl)
rc_backgrounds.py Auto-generated Qt resource module (do not edit by hand)

The .sync4 dot-command source lives under nextsync/sync. It can be built two ways: the classic SDCC 4.5.0 build (build.ps1, limited to the 8 KB dot size), or the newer z88dk "dotN" build (z88dk/build_dotn.ps1) which lifts that 8 KB limit by paging overflow into extra banks. See Installation → building the dot from source.

Legal disclaimer — third-party content

The author of ZX-Next-Unite does NOT distribute any files, ROMs, games, demos, graphics, music, or any other content obtained through the GetIt, ZXDB, or zxArt integrations.

All content is served exclusively by the respective third-party services listed above. ZX-Next-Unite acts solely as a front-end client that queries their public APIs and downloads files directly from the URLs those APIs return.

It is the sole responsibility of the end user to ensure that any content they download or use through this application complies with the applicable copyright, licensing, and legal requirements in their jurisdiction.

If in doubt, consult the terms of service of the relevant platform and seek appropriate legal advice before downloading or using any content.

The first time you open the GetIt, ZXDB, or zxArt pane, the application displays this disclaimer and asks you to acknowledge it. You can dismiss the dialog to continue using the pane; it reappears on the next visit until you tick "I agree and understand. Do not show this message again", at which point your acknowledgement is saved to hdfg.cfg and the dialog is no longer shown.

ZX-Next-Unite

User Manual

Tools

Online libraries

The rest

Clone this wiki locally