# VGMDB Log+Cue Folder Renamer

> **Status:** Active
> **Category:** File Organization
> **Language:** Python 3
> **Script file:** `VGMDB-LOG+CUE FOLDER RENAMER.py`

## Purpose

Scans a directory tree for album folders, detects `.log` and `.cue` files inside them, and appends the appropriate tag — `(Log)`, `(Cue)`, or `(Log+Cue)` — to each folder name, inserting it just before the trailing `[CatalogNumber]` bracket. Includes a full undo mode and generates a colour-coded Excel report.

## Requirements

### Dependencies

```bash
pip install openpyxl
```

## Input

| Item | Description | Example |
|------|-------------|---------|
| Working directory | Run from the parent folder that contains your album folders | `cd "D:\Music\FLAC"` |
| Album folders | Any subfolder whose name ends with a `[CatalogNumber]` bracket | `Artist - Album [GNCA-7163]` |
| `.log` / `.cue` files | Located in the album folder root or in a `Data/` subfolder | `GNCA-7163.log` |

## Output

| Item | Description |
|------|-------------|
| Renamed folders | Folder name updated with `(Log)`, `(Cue)`, or `(Log+Cue)` before the catalog bracket |
| Moved files | Any `.log` / `.cue` files found at album root are moved into a `Data/` subfolder |
| Renamed files | Lone `.log` / `.cue` files are renamed to match the catalog number (e.g. `GNCA-7163.log`) |
| `music_tagger_undo.json` | Records all operations so the run can be fully reversed |
| `music_tagger_report.xlsx` | Excel report with one row per folder; colour-coded by status |

## Usage

Place the script anywhere accessible, then run it **from the directory that contains your album folders**:

```bash
cd "D:\Music\FLAC"
python "VGMDB-LOG+CUE FOLDER RENAMER.py"
```

You will be prompted to choose a mode:

```
1.  Search and fix folders
2.  Undo last run
```

## Examples

```bash
# Example 1 — Run in the current directory, tag all qualifying album folders
cd "D:\Music\FLAC"
python "VGMDB-LOG+CUE FOLDER RENAMER.py"
# Enter: 1

# Example 2 — Undo the previous run
python "VGMDB-LOG+CUE FOLDER RENAMER.py"
# Enter: 2
```

### Folder name transformations

| Before | Files found | After |
|--------|-------------|-------|
| `Artist - Album [GNCA-7163]` | 1 `.log` | `Artist - Album (Log) [GNCA-7163]` |
| `Artist - Album [GNCA-7163]` | 1 `.log` + 1 `.cue` | `Artist - Album (Log+Cue) [GNCA-7163]` |
| `Artist - Album (2010)(OST) [CAT-001]` | 1 `.cue` | `Artist - Album (2010)(OST)(Cue) [CAT-001]` |
| `Artist - Album (Log) [CAT-001]` | `.log` + `.cue` found | `Artist - Album (Log+Cue) [CAT-001]` (tag replaced) |

### Excel report status colours

| Status | Meaning |
|--------|---------|
| Tagged | Tag added for the first time |
| Tag Updated | Existing tag replaced with a corrected one |
| Already Tagged | Correct tag was already present; no changes made |
| Manual Review | Multiple `.log` or `.cue` files found; folder tagged but files left alone |
| Skipped | No `.log` or `.cue` files found |
| Error | Folder could not be renamed |

## Notes

- The script operates on the **current working directory** at launch — there is no path argument. Run it from the correct location.
- Album folders are identified by the presence of a trailing `[...]` bracket in their name. Folders without one are ignored.
- When exactly one `.log` or `.cue` file is found, it is renamed to match the catalog number (e.g. `GNCA-7163.log`). If multiple files are found, they are left untouched and flagged for manual review.
- The undo file (`music_tagger_undo.json`) is overwritten on each new run. Perform any undo before running again if you need to reverse the previous session.
- `openpyxl` is required; the script exits with an error if it is not installed.

## Related Scripts

- [vgmdb-restructure](vgmdb-restructure.md) — extracts VGMdb URLs and album metadata from a folder tree