# beets-find-brackets

> **Status:** Active
> **Category:** Audio & CUE Tools
> **Language:** Python 3
> **Script file:** `find_brackets.py`

## Purpose

Recursively scans a directory tree and finds all subfolders whose names end with a bracketed expression (e.g. `[2024]`, `[FLAC]`, `[VGMdb]`). Results are written to a plain-text file for review.

## Requirements

### Dependencies

Python standard library only — no `pip` installs required.

```
os, re, sys, pathlib  (all built-in)
```

## Input

| Item | Description | Example |
|------|-------------|---------|
| Root directory | Path to scan, passed as a command-line argument | `/mnt/music` |

If no argument is given, the current working directory is used.

## Output

| Item | Description |
|------|-------------|
| `bracket_folders.txt` | Plain-text list of matching folder paths, one per line, written to the root directory |
| Console output | Count of matches and full list printed to stdout |

### Match pattern

The script matches folders whose name ends with a `[...]` expression — specifically any name where the trailing portion matches `\[.*\]$`. Examples of matched folder names:

```
Artist - Album Title [2019]
Soundtrack [FLAC]
Game OST [VGMdb 12345]
```

## Usage

```bash
# Scan a specific directory
python find_brackets.py /path/to/music/library

# Scan the current working directory
python find_brackets.py
```

## Examples

```bash
# Scan a music library root
python find_brackets.py "D:\Music"

# Output written to D:\Music\bracket_folders.txt
# Console shows:
# Found 42 folder(s). Results written to:
#   D:\Music\bracket_folders.txt
#   D:\Music\Artist - Album [2020]
#   D:\Music\Composer - Soundtrack [FLAC]
#   ...
```

```bash
# If no matches are found
python find_brackets.py /path/to/empty-dir
# No folders containing '[' were found.
```

## Notes

- The output file `bracket_folders.txt` is always written to the **root directory** passed as the argument, not the current working directory.
- The regex matches only trailing bracket groups (`[...]` at the **end** of the folder name). Brackets in the middle of a name (e.g. `[Disc 1] Extras`) are not matched.
- Results are sorted alphabetically before being written.
- If the script exits with `Error: '...' is not a directory`, the provided path does not exist or is a file.
- This tool is read-only — it does not rename or modify any folders.

## Related Scripts

- [beets-cuemaker](beets-cuemaker.md) — Generate CUE sheets for single-file album rips
- [vgmdb-cuefixer](vgmdb-cuefixer.md) — Fix CUE file headers in album folders