Normalizing MIDI File Names

A practical, reliable workflow for taming chaotic MIDI libraries

Mechanical‑organ MIDI collections are notoriously unruly. Decades of ad‑hoc editing, inconsistent naming conventions, mixed encodings, and missing metadata make it nearly impossible to search, archive, or reuse these files in a predictable way. This book documents a complete, battle‑tested workflow for transforming a messy folder of MIDI files into a clean, deterministic, human‑verified library with consistent filenames and correct internal metadata.

The process is intentionally modular and human‑in‑the‑loop: scripts do the heavy lifting, but a human curator makes the final decisions. The result is a library that is not only tidy, but trustworthy.

Overview of the Workflow

This normalization pipeline consists of four stages, each with a clear purpose:

1. Extract the Raw Metadata (Initial XLSX)

A metadata‑dump script scans the MIDI folder and extracts every piece of information it can find — filenames, titles, composers, comments, tempo, key, time signature, and more.
The output is an XLSX spreadsheet that captures the true state of the library, including inconsistencies and encoding issues.

2. Normalize the Metadata (Automated Pass)

A second script reads the raw dump and produces a normalized metadata file.
This step repairs mojibake, standardizes formatting, extracts primary composers, and ensures every row has the same structure.
The result is a machine‑clean but not yet human‑clean dataset.

3. Human Review and Cleanup (Curatorial Pass)

A human editor reviews the normalized metadata and corrects anything the scripts cannot infer: ambiguous titles, missing composers, medley names, special cases, and historical quirks.
This curated spreadsheet becomes the authoritative source of truth for the entire library.

4. Rename the MIDI Files (Deterministic Final Pass)

The final script uses the curated metadata to rename the files using a consistent pattern:

composer--title.mid

Composer and title are normalized separately so the double dash (--) is preserved as a semantic separator.
The script also rewrites internal MIDI metadata and produces a dry‑run report before making any changes.

Why This Workflow Works

• Deterministic: Given the same metadata, the output is always identical.
• Human‑verified: The only subjective step is handled by a human, not guessed by a script.
• Safe: Every rename is logged; nothing is overwritten without confirmation.
• Modular: Each stage can be rerun independently.
• Future‑proof: Once metadata is clean, the library can be regenerated at any time.

Summary

This book documents a complete, reliable system for cleaning and standardizing MIDI libraries.
By separating extraction, normalization, human review, and renaming into distinct steps, the workflow remains transparent, reversible, and easy to maintain.
Whether you’re archiving mechanical‑organ rolls, preparing files for playback hardware, or simply trying to make sense of a chaotic folder, this pipeline gives you a clear path from disorder to order.