K36S Cleanup

Beta 0.12 - Media Match Fix

This tool removes orphaned gamelist.xml entries and unused media files while keeping valid ROM references intact.

Important Warning

Always create a full backup of your ROMs, gamelist.xml files, and related media before using this tool.

This tool can delete XML entries and media assets. Use it at your own risk and always verify the DRY RUN log before doing a real run.

Target Systems

This tool was primarily developed for K36 and similar clone handhelds running dArkOSRE-R36. Earlier related tools were also used on ArkOS-K36.

It should also work on original ArkOS and dArkOS based setups as long as they use the usual ROM directory layouts.

The shell wrappers and ROM root detection are designed for the typical directory layouts used there, especially paths such as /roms, /roms2, /roms2/roms, /roms1, /userdata/roms, and /storage/roms.

Tool Location

The tool folder should be stored on the same SD card or storage setup that contains the ROM collection you want to process.

The included shell wrappers detect the ROM root automatically from the target system layout. If the tool is placed on a different card or unrelated filesystem, ROM detection and cleanup may fail or point to the wrong location.

Project Contents

Files in this folder:

• K36S Cleanup.sh
• K36S Cleanup DRY.sh
• k36s_cleanup.py
• README.md
• LICENSE

Typical logs:

• cleanup_dry.log
• cleanup_run.log

Recommended Order

Before running K36S Cleanup, create a backup first.

1. Create a full backup of ROMs, gamelist.xml, and media
2. Run K36S Cleanup DRY.sh
3. Check the dry-run log
4. Run K36S Cleanup.sh

Reason: This keeps the cleanup traceable and reduces the risk of deleting something unexpected.

Reboot And Scraping Workflow

If you plan to scrape or rescan metadata after cleanup, use the same cautious reboot workflow as with the duplicate cleanup tools.

Recommended sequence:

1. Create a full backup first
2. Run K36S Cleanup DRY.sh
3. Check the dry-run log
4. Run K36S Cleanup.sh
5. Reboot before scraping
6. Run the scraper
7. Reboot again before regular use
8. Reboot once more after the next start if you notice save or metadata inconsistencies

Important:

• during every reboot, the charger or USB power cable should be disconnected
• if a charger is connected during reboot, saving may fail or behave incorrectly
• this can lead to errors with saves, metadata, or later follow-up operations

What Beta 0.12 Changed

Changes compared to Beta 0.11:

• media cleanup no longer checks only the plain ROM basename
• valid media is also preserved when it is directly referenced in gamelist.xml
• videos with scraper suffixes like -video are detected correctly
• gamelist.xml files are found recursively
• tools, bios, saves, savestates, themes, and similar folders remain excluded

What The Tool Does

• searches recursively for gamelist.xml
• processes systems that contain a gamelist.xml
• removes game entries whose ROM path no longer exists
• keeps media files that are directly referenced in XML
• keeps known filename variants such as ROMNAME-video.mp4
• creates a timestamped backup before rewriting a changed gamelist.xml
• supports a DRY RUN that deletes nothing

ROM Root Detection

The shell wrappers automatically check these paths:

/roms2/roms
/roms2
/roms
/roms1
/userdata/roms
/storage/roms

The first matching directory is used as the ROM root.

Excluded Folders

These folders are skipped during scanning and are not treated as regular system folders:

bios
themes
tools
ports
downloaded_images
bezels
saves
savestates

Nothing should be deleted from such folders.

Media Matching

Media is preserved in two ways:

1. If the file is directly referenced in gamelist.xml
2. If the filename stem matches a valid ROM basename or a known scraper suffix

Currently supported explicit scraper suffix handling includes:

• -video for files inside videos

This prevents valid media from being removed just because the filename is not an exact plain ROM basename.

DRY RUN

The DRY RUN only shows what would be deleted.

Nothing is changed.

Start with:

sh "K36S Cleanup DRY.sh"

Check the log for:

• [DRY]
• removed gamelist.xml entry summaries
• removed media file summaries
• warning messages
• error messages

Only when the result looks correct:

sh "K36S Cleanup.sh"

Risks

Always check the dry-run log before a real run.

Especially critical are:

• systems with broken or incomplete gamelist.xml
• unusual media folder layouts
• manually curated media filenames outside the expected naming scheme
• systems where ROM paths inside XML no longer reflect the real folder layout

Always keep a ROM backup so you can restore the original state if the dry-run review missed something.

If the dry-run output does not look clearly correct, do not start the real run.

Status

Current version:

Beta 0.12 - Media Match Fix

Goal of this version: Keep orphan cleanup conservative so valid media survives even when it uses scraper-specific naming.

License

This project is released under the MIT License.

---

Ziel

Dieses Tool bereinigt verwaiste gamelist.xml-Eintraege und nicht mehr benoetigte Mediendateien, ohne gueltige ROM-Referenzen oder passend benannte Medien unnoetig zu entfernen.

Wichtiger Hinweis

Vor der Benutzung unbedingt eine vollstaendige Sicherung der ROMs, der gamelist.xml-Dateien und der zugehoerigen Medien anlegen.

Dieses Tool kann XML-Eintraege und Mediendateien loeschen. Verwendung auf eigene Gefahr. Vor einem echten Lauf immer zuerst den DRY RUN und das Log pruefen.

Empfohlene Reihenfolge

1. Vollstaendiges Backup von ROMs, gamelist.xml und Medien anlegen
2. K36S Cleanup DRY.sh
3. Dry-Log pruefen
4. K36S Cleanup.sh

Neustart- und Scrape-Ablauf

Wenn nach dem Cleanup noch gescraped oder Metadaten neu aufgebaut werden sollen, denselben vorsichtigen Neustart-Ablauf wie bei den anderen Cleanup-Tools einhalten.

Empfohlene Reihenfolge:

1. Zuerst vollstaendiges Backup anlegen
2. K36S Cleanup DRY.sh
3. Dry-Log pruefen
4. K36S Cleanup.sh
5. Vor dem Scrapen neu starten
6. Scraper laufen lassen
7. Danach erneut neu starten, bevor das System normal weiter benutzt wird
8. Bei Bedarf noch einmal neu starten, falls Speicherstaende oder Metadaten auffaellig sind

Wichtig:

• bei jedem Neustart darf kein Ladegeraet bzw. kein USB-Stromkabel angeschlossen sein
• wenn beim Neustart ein Ladegeraet angeschlossen ist, funktioniert das Speichern unter Umstaenden nicht korrekt
• dadurch koennen Fehler bei Speicherstaenden, Metadaten oder spaeteren Folgeoperationen entstehen

Wichtige Punkte

• rekursive Suche nach gamelist.xml
• nur Systeme mit gamelist.xml werden verarbeitet
• verwaiste game-Eintraege werden entfernt
• direkt referenzierte Medien bleiben erhalten
• bekannte Scraper-Suffixe wie -video werden beruecksichtigt
• vor Schreibvorgaengen wird automatisch ein Backup erstellt
• der DRY RUN loescht nichts

DRY RUN

sh "K36S Cleanup DRY.sh"

Danach das Log pruefen und erst dann:

sh "K36S Cleanup.sh"

---

Credits

This project was created and refined with assistance from ChatGPT for wording, restructuring, and iteration support. The final decisions, testing, and release responsibility remain with the project maintainer.

Hinweis

Dieses Projekt wurde mit Unterstuetzung von ChatGPT bei Formulierungen, Ueberarbeitungen und Iterationen erstellt und verfeinert. Die finale Entscheidung, Pruefung und Verantwortung fuer Releases liegt beim Projektbetreiber.