# AGM Catalogue Number Extractor

> **Status:** Active
> **Category:** Data Extraction
> **Language:** PowerShell
> **Script files:** `AGMcatpull.ps1`, `AGM Cat Pulling.ps1`

## Purpose

Two PowerShell scripts that scan album folder names for bracketed or parenthesised text (typically catalogue numbers) and export the results to a CSV file. Originally written for AGM (Alchemist Game Music) releases but usable with any folder collection using bracketed naming conventions.

## Requirements

### Dependencies

- Windows PowerShell 5.1 or PowerShell 7+
- No additional modules required

## Input

| Item | Description | Example |
|------|-------------|---------|
| Root directory | A folder whose subfolders use bracketed naming conventions | `E:\AGM\17\[AGM22] Lossless AGM` |

Both scripts scan all subdirectories recursively.

### Expected Folder Naming Conventions

**`AGMcatpull.ps1`** — matches `[bracketed]` text:
```
Artist - Album Title [CATALOG-1234]
[AGM22] Various Artists - Compilation
```

**`AGM Cat Pulling.ps1`** — matches both `[bracketed]` and `(parenthesised)` text, with parentheses taking priority:
```
Artist - Album Title (CATALOG-1234)
Artist - Album Title [CATALOG-1234]
```

## Output

| Item | Description |
|------|-------------|
| CSV file (path set in script) | Two-column CSV with folder path and extracted text |

### Output Columns

**`AGMcatpull.ps1`**

| Column | Contents |
|--------|---------|
| `FolderPath` | Full path to the matched folder |
| `BracketText` | All text found inside `[...]` in the folder name |

**`AGM Cat Pulling.ps1`**

| Column | Contents |
|--------|---------|
| `FolderName` | Full path to the matched folder |
| `CatalogNumber` | Text found inside `(...)` or `[...]` — first match wins |

## Usage

### `AGMcatpull.ps1`

The root path and output CSV path are **hardcoded** in the script. Edit them before running, then:

```powershell
.\AGMcatpull.ps1
```

### `AGM Cat Pulling.ps1`

Root path and output CSV path are also **hardcoded**. Edit them before running, then:

```powershell
.\"AGM Cat Pulling.ps1"
```

## Behaviour Differences

| Feature | `AGMcatpull.ps1` | `AGM Cat Pulling.ps1` |
|---------|-----------------|----------------------|
| Bracket style matched | `[...]` only | `(...)` first, then `[...]` |
| Multiple matches per folder | Yes — all bracket groups | No — first match only |
| Output encoding | ASCII | UTF-8 |
| Output if no matches found | Skips silently | Skips silently |

`AGMcatpull.ps1` uses `[regex]::Matches()` to capture every `[...]` group in a folder name, so a folder with multiple bracket groups (e.g. `[AGM22] Artist [CATALOG-1234]`) will produce multiple output rows. `AGM Cat Pulling.ps1` uses PowerShell's `-match` operator and stops at the first match.

## Examples

```powershell
# AGMcatpull.ps1 — scan a Diverse System archive
# (edit $rootPath and $outputCsv in the script first)
.\AGMcatpull.ps1
# Output: C:\test\script\outputdiv.csv
# Done! Output saved to: C:\test\script\outputdiv.csv

# AGM Cat Pulling.ps1 — scan an AGM lossless archive
# (edit $root and $outputCsv in the script first)
.\"AGM Cat Pulling.ps1"
# Output: C:\test\AGM\Export\17.csv
```

## Notes

- **`AGMcatpull.ps1` hardcoded paths:**
  - Input: `C:\Users\akuma\Downloads\[Audio-4U] Diverse System 5.0 (flac)`
  - Output: `C:\test\script\outputdiv.csv`

- **`AGM Cat Pulling.ps1` hardcoded paths:**
  - Input: `E:\AGM\17\[AGM22] Lossless AGM`
  - Output: `C:\test\AGM\Export\17.csv`

- Both paths must be updated before use on any other machine or for any other collection.
- `AGMcatpull.ps1` uses `-Encoding ASCII`, which will silently drop non-ASCII characters in folder names (e.g. Japanese titles). Use `AGM Cat Pulling.ps1` or switch to `-Encoding UTF8` if your folder names contain non-ASCII text.
- The `Export/` subdirectory contains CSV output files from previous runs against various AGM volumes (volumes 8–17 and some named collections).

## Related Scripts

- [VGMdb Nicotine Shares](vgmdb-nicotineshares.md) — also extracts catalogue numbers from folder names, but from a JSON share export rather than a live directory
- [VGMdb HTML Data Extractors](extract.md) — extracts catalogue numbers from VGMdb HTML pages