Skip to content

Home

Jump to bottom
Julien Clauzel edited this page Jul 21, 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, and Flask by the Pallets team (BSD-3-Clause) to power the NextSync HTTP bridge — the web server behind the Next's .http dot command. Like PySide6 and pygame-ce, itch-dl and Flask are not bundled with a standard Python install and must be installed separately (pip install -r REQUIREMENTS.txt); the itch.io tab only appears when itch-dl is installed, and the HTTP bridge toggle in Settings is greyed out until Flask 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: .sync5 — the Sync4 protocol: faster transfers and bidirectional sync (.sync5 -send <file|dir> pushes files back from the Next to the PC). Speed hints -slow, -default, -fast replace the old syncfast/syncslow commands.
  • Remote file explorer: .sync5 -listen (short alias: .sync5 -l) — turns the Next into a small remote file server so you can browse and transfer its filesystem from the app (see Remote file explorer below). Press BREAK (Caps Shift + Space) on the Next to stop it — the Next-side equivalent of Ctrl-C.
  • 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 .sync5 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.

Remote file explorer

Beyond folder syncing, the NextSync tab can turn into a two-pane file manager — just like the SD Card tab, but the right-hand pane is your Next's real filesystem (reached over Wi-Fi) instead of a disk image:

[ your PC files ]   ->:  :<-   [ your Next's files ]

How to use it:

  1. Click 🗂 Remote Explorer in the NextSync tab. The log window flips into the two-pane view, and the normal sync controls are replaced by a single ▶ Start NextSync server button.
  2. Click Start NextSync server. A toast reminds you to run .sync5 -listen on your Next; a pulsing green indicator shows the server is live.
  3. On the Next, run .sync5 -listen (or the short alias .sync5 -l). It connects and the right pane fills with the current Next directory.

Then you can:

  • Transfer — select item(s) and use ->: (upload PC → Next) or :<- (download Next → PC), or just drag & drop between the panes (and from your OS file manager onto the Next pane).
  • Navigate — double-click folders, or use Up / Refresh on either pane.
  • Manage — New Folder and Delete (right-click menu or the buttons) create and remove folders/files on the Next.

End the session any of three ways: click ⏹ Stop NextSync server, toggle 🗂 Return to classic sync off, or press BREAK (Caps Shift + Space) on the Next itself — the Next-side equivalent of Ctrl-C. BREAK always lets any in-progress transfer finish first, so no file or directory is left half-written. This uses the same .sync5 command and Wi-Fi connection as a normal sync — nothing else to install.

Tip: launch the app with python zx-next-unite.py -start-remote-explorer-listener to skip steps 1–2 — the Remote Explorer view opens and its listen server starts automatically at startup (using the saved sync root), so the Next only has to run .sync5 -listen.

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-v9.x executable from the Releases page (plus the .sync5 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, itch-dl and flask 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.

The Settings tab also hosts the NextSync HTTP bridge toggle (requires the optional flask package): a small web server that republishes the Remote Explorer's .sync5 -listen session as HTTP routes, so a browser, curl or another Next (via the built-in .http dot command) can drive the connected Next's SD card. Its port — 80 by default — is set in the input box next to the toggle and persisted to hdfg.cfg, as is the maximum number of concurrent connections (default 1, the recommended value to avoid concurrent access — extra requests wait their turn rather than being rejected). Full route reference and call samples: HTTP bridge documentation.

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.

To have the Remote file explorer's listen server running right from startup (using the saved sync root — no clicks needed before running .sync5 -listen on the Next):

python zx-next-unite.py -start-remote-explorer-listener

This forces the Remote Explorer view open for this run only (the saved Settings are not modified). Pairs nicely with the NextSync HTTP bridge for a fully hands-off remote setup.

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 .sync5 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