AutoSync

AutoSync (Mode 1)

AutoSync extracts game ZIPs from a source folder (NAS or local drive) into a local staging folder, then registers the extracted games with TeknoParrot.

---

When to use it

Use AutoSync when your games are stored as ZIP files -- for example, on a NAS running the TeknoParrot Collection. If your games are already extracted, use Register (mode 2) instead.

---

Supplementary games folder

AutoSync supports a second, optional ZIP source called the supplementary folder. Use it for a separate library of extra or regional games that you keep apart from your main collection.

On the first AutoSync run (or whenever no supplementary folder is configured), the script asks:

  Supplementary games folder (optional)
  Point directly at the folder containing the Supplementary .zip files, not a parent folder.
  Example: W:\ROMS\TeknoParrot Supplementary
  Path (or press Enter to skip):

Press Enter to skip. If you enter a valid path the folder is saved to config and used on every subsequent AutoSync run. Both sources are then presented in a single combined game picker so you select from the entire library at once.

The supplementary folder:

• Extracts into the same staging folder as the main collection
• Must not overlap the main ZIP source folder or the staging folder
• Must not be inside the TeknoParrot folder
• Is not prompted in Unattended mode -- set it interactively first

To remove it later: press N at the "Use these settings?" prompt on the next run, which re-runs the config questions including the supplementary prompt.

---

Staging folder rules

The script enforces these rules to keep your library healthy:

• Local drive recommended. Network drives are allowed -- the script runs a write-speed benchmark and warns if throughput is too low for smooth extraction or gameplay. You can still proceed if you accept the risk.
• Must not be inside the TeknoParrot folder
• Must not overlap the ZIP source folder
• Must have enough free space -- the script warns if the drive has less than ~1.5x the total ZIP size and asks before continuing

Example: D:\TeknoParrotGames

---

Preview / dry-run mode

After the folder prompts, the script asks:

  Run in PREVIEW mode first? No changes will be written -- this just shows
  what AutoSync/Register would do. (Y/N)

Answer Y to see exactly which games would extract (and why -- new, changed on NAS, etc.) and which would register, with zero files written. No backup is created, and the follow-up offers (LaunchBox direct integration/HyperSpin export, thumbnail download, GPU fix) are skipped since there's nothing yet to act on.

To always preview without being asked, pass -DryRun on the command line. Combine with -Unattended to preview a scheduled run with no prompts at all.

When the preview finishes, the script asks "Apply these changes for real now?" -- answer Y to immediately re-run the same mode for real (no menu, no preview prompt shown again), or N to return to the menu without changing anything.

---

Game selection menu

After entering your folders the script scans both sources, filters out games already extracted, and shows a combined list. When a supplementary library is configured, entries from it are marked [+] and the header shows per-source counts:

347 game(s) already extracted -- not shown.
136 game(s) available to extract (104 collection, 32 supplementary [+]).

Then the selection menu:

Key	Action
A	All unextracted games -- extract everything not yet on disk
L	Browse A-Z paginated list, pick by number
S	Search by keyword, pick by number
D	Done -- proceed with current selection

A vs D with empty queue: Pressing A extracts every unextracted game from both sources. Pressing D with nothing in the queue extracts zero games -- it skips that source entirely. If you select games from the main collection but nothing from supplementary, supplementary extraction is skipped. The header always shows how many games are queued.

You can switch freely between Browse (L) and Search (S) to build up a queue across multiple selections before pressing D.

Browse (L)

Shows unextracted games in alphabetical order, 20 at a time. Supplementary titles are marked [+]. Commands:

Key	Action
Numbers or ranges	1,3,5-7 -- add games to the queue
N	Next page
P	Previous page
B	Back to selection menu
D	Done -- start extracting

Games already queued are marked with *.

Search (S)

Type any part of a game name. Matching unextracted games are shown numbered (supplementary marked [+]). Type numbers or ranges to add them to the queue. Type back to return to the menu or done to finish.

---

Extraction behaviour

A real-time progress bar shows file count and percentage during each game's extraction.

• Naming: Extraction folders use the raw ZIP filename, matching the collection's naming convention. If a game was previously extracted under an older naming convention (spaces vs no spaces between bracket groups), the script recognises the existing folder and does not create a duplicate.

• Metadata ZIPs: Files whose name starts with !TeknoParrot Collection (changelog, readme, game notes) are always skipped.

• Interrupted extractions: If an extraction is cut short (Ctrl+C, power loss, disk error), a .extracting sentinel file is placed next to the game folder at the start and removed only on success. If the sentinel is found on the next run, the incomplete folder is detected and re-extracted from scratch automatically.

---

After extraction

AutoSync proceeds directly into registration. See Register for everything that happens during and after registration.

---

RetroBat / Batocera naming

If RetroBat mode is enabled (set during Setup), games are extracted as GameName.teknoparrot instead of GameName. The script also recognises .parrot and .game suffixes for existing folders.

To switch an existing library to RetroBat naming:

1. Press N at the "Use these settings?" prompt so the RetroBat question appears.
2. Answer Y.
3. Delete TeknoParrot-Manager.syncstate.json from your staging folder to force re-extraction.
4. Re-run -- games are re-extracted with .teknoparrot folder names.

Old folders are never deleted automatically.