# PyOCA — Python‑based extra tool for Mp3Tag

**URL:** https://community.mp3tag.de/t/pyoca-python-based-extra-tool-for-mp3tag/70496
**Category:** Off-Topic
**Created:** [January 14, 2026, 6:15pm UTC](https://community.mp3tag.de/t/pyoca-python-based-extra-tool-for-mp3tag/70496 "2026-01-14T18:15:05Z")
**Posts on this page:** 1
**Page:** 1

<div class="post-metadata">

### Author: ![juvalu](https://community.mp3tag.de/letter_avatar_proxy/v4/letter/j/35a633/32.png) [@juvalu](https://community.mp3tag.de/u/juvalu)
#### Post date: [January 14, 2026, 6:15pm UTC](https://community.mp3tag.de/t/pyoca-python-based-extra-tool-for-mp3tag/70496/1 "2026-01-14T18:15:05Z")

</div>

# 🐍 PyOCA

## Cleans and Organizes Credits/Performers for Discogs-Based Tags

🌟 **PyOCA** — (_Python Oriented Credits Assigner_) — is a Python‑based tool with a graphical interface designed for organizing, cleaning, assigning, and optionally writing structured audio credits into music files.  
It is especially useful when working with **role-grouped credit data** , such as:

| Example Inputs |
| --- |
| `Arranged By – Ian Devaney (tracks: 1.1 to 1.17, 2.1 to 2.16, 4.1 to 4.17, 5.1 to 5.16), Lisa Stansfield (tracks: 4.1 to 4.17, 5.1 to 5.16), Richard Darbyshire (tracks: 4.1 to 4.17, 5.1 to 5.16)` |
| `Backing Vocals – Aileen McLaughlin (tracks: 2.1 to 2.16, 3.1 to 3.16, 4.9), Anna Ross (tracks: 2.1 to 2.16, 3.1 to 3.16, 4.9), Lisa Stansfield (tracks: 3.1 to 3.16, 4.1 to 4.17, 5.1 to 5.16)` |

Examples: 🔗 [r2407100](https://www.discogs.com/release/2407100-Clive-Griffin-Clive-Griffin) 🔗 [r858769](https://www.discogs.com/release/858769-Lisa-Stansfield-The-Complete-Collection)

* * *

## 🖥 **User Interface**

The GUI includes:

- 📂 **Open** : Select input files
- 🚀 **Start** : Process the data
- 👀 **Preview** : View results line-by-line
- 💾 **Write** : Apply tags to audio files
- 🎨 Dark Mode
- 🧪 Debug Lite / Debug Full
- ✔ CD mode
- ✔ BoxSet mode

* * *

## 🎯 What PyOCA Does

### ✔ Reads two files exported from Mp3tag

- **Any filenames are accepted**
  - Examples:
    - `your_Field_Credits.txt`
    - `your_Field_Musicians.txt`

These files typically contain long lists of:

- Arrangers, Art Direction, Backing Vocals, Bass, Design, Drums, Engineers, Keyboards, Producers, and more

### ✔ Automatically Parses Them

- Normalizes and formats input entries.
- Merges roles and names for each track.
- Processes track ranges (`Drusilla Harris (tracks: 2.1 to 2.16, 3.1 to 3.16, 4.1 to 4.17`) by assigning credit to each track included within those segments.
- Deduplicates and sorts groups and roles.
- Safely preserves bracketed content and hyphenation (`e.g., [Strings, Horns], Executive‑Producer`).
- Optionally removes _Written-By_.
- Assigns credits to each track by validating contributor roles against two predefined metadata lists.

### 💧 Uses Discogs‑Based Role Matching:

- `🎎 personnel.txt` → credit roles
- `🎸 instruments.txt` → musical instruments
- Discogs reference: [https://www.discogs.com/help/creditslist](https://www.discogs.com/help/creditslist)

### 🌈​ Classifies everything into 3 output files

All saved inside the **main album or BoxSet folder** , not inside CD1/CD2.

1. 🟩 `♥ Credits.txt`
2. 🟦 `♦ Musicians.txt`
3. 🟨 `✥ Unknown.txt`

* * *

### 📀 Full Multi-Disc BoxSet Support

- Automatically detects the **root folder** of multi-disc releases.
- Folder detection matches the pattern: `^(CD|DISC|DISK)\s*\d+\b` (case-insensitive).
- Valid examples: `CD1`, `CD 1 - Remastered`, `CD02`, `Disc 1`, `Disc1 - Live`, `Disk3 - Bonus Tracks`.

* * *

## ⚙ Integration with Mp3Tag

1. In `AppData\Roaming\Mp3tag`, create a folder named `pyOCA`.
2. Copy into it the executable file `PyOCA.exe` and the Discogs matching role files `🎎 personnel.txt` and  
`🎸 instruments.txt`.
3. Open **Mp3tag** and configure the external tool via `Ctrl+O`.
4. Invoke the program via `Ctrl+1` or from the context menu.

* * *

## 🔧 How to Use

1. In **Mp3tag** , export:
  - `your_Field_Credits.txt`
  - `your_Field_Musicians.txt`

2. Launch PyOCA
3. Select **CD Mode** or **BoxSet Mode**
4. **Open** file
5. Click **Start**
6. Review the generated files
7. In **Mp3Tag** , import using: Converter → Text file → Tag (`Alt+4`)
8. (Optional) Click **Write** to update your audio files

### 🎼 **Checkbox: Disable Filter “Written-By”**

- If enabled, roles like Lyrics-By, Music-By, Songwriter-By, Written-By and their variants are **not removed**.
- Also generates `♫ Composer.txt` containing only writing roles
- File is formatted for **Mp3Tag compatibility** (`\\` separator)

📌 When using the **[WS] Discogs Release ID Plus**, the filter becomes irrelevant.

* * *

## 🧠 Input Files Overview

This module processes **two input streams** derived from **Discogs** imports and exported by **Mp3Tag** , each containing raw credit data with heterogeneous syntax patterns.  
**Important:** the filenames are **arbitrary** — users may choose any names they prefer.  
The names used in this documentation (e.g., `≠Field_Credits.txt`, `≠Field_Musicians.txt`) are **examples only**.

👁️‍🗨️ **Essential requirement: PyOCA must receive data whose syntax complies with the structural rules defined for Scenario Formats 1–4. If this requirement is not met, the system will not operate correctly**.

- For this purpose, the attached **[WebScript] Discogs Release ID Plus.src** meets the INPUT conditions.

* * *

## 🎭 PyOCA Scenario Formats (Short Version)

**PyOCA** automatically detects and processes the four most commonly used models for metadata acquisition through _ **WebScript Sources** _:

- `Role – Name,"tracks":"…"`
- `Role: Name (tracks …)`
- `Role – Name (tracks …)`
- `Disc‑Track Role – Name (tracks …)`

👉 All formats are normalized internally into a single consistent structure.  
👉 For a complete explanation of Scenarios 1–4, refer to the documentation included in the package.

* * *

## 🩺 Output Files Overview

- **Output names are predefined to streamline the workflow.**

- All output files are generated inside the detected working root folder (`WORK_BASE_DIR`).

- **The output formatting follows this syntax** : `Role: name\\Role: name_1, name_2\\......`

- _The symbols used in the output filenames serve solely to make them easily identifiable and to ensure they are  
grouped together within the folder structure, typically appearing before the audio files._

| Symbol | File | Description |
| --- | --- | --- |
| ❤ | **Credits.txt** | Matched credit roles (from `personnel.txt`) |
| ♦ | **Musicians.txt** | Recognized instruments (from `instruments.txt`) |
| ♣ | **Merge-Field.txt** | Optional: merged full tag field (service file) |
| ♠ | **Credits-Assigned.txt** | Optional: full cleaned credit line per track |
| ✥ | **Unknown.txt** | Roles that do not match known categories |
| ♫ | **Composer.txt** | Optional: writing-related roles if filter enabled |

* * *

## 🗃 Optional Files

| Contents | Description | Path |
| --- | --- | --- |
| `action folder` | Action package for final cleaning | `AppData\Roaming\Mp3tag\data` |
| `export folder` | Mp3tag export (example configurations) | `AppData\Roaming\Mp3tag` |
| `sources folder` | Discogs Release ID Plus.src | `AppData\Roaming\Mp3tag\data` |

💣 **Warning** : Files in these folders are optional — test them first on a temporary music folder.

⚠ **Discogs Release ID Plus.src is released already configured to work with PyOCA. To customize, rename, or remap the output fields, refer to the corresponding chapter in the included documentation**.

* * *

## 🧩 Additional Features

### 🖊 Tag Writing

If enabled:

- Select output file:

1. `♥ Credits.txt`
2. `♦ Musicians.txt`

- Map them to any tag field (`%your_field%`)
- Tags are written line by line to matching audio files (sorted by name)
- A preview is available before writing, so you can review the changes in advance.
  - ↩ No **Undo** function available.

### 🏷 Supported Tag Formats

File Type: MP3, FLAC, APEv2

* * *

### 🧪 Debug Tracker

| Symbol | File | Mode |
| --- | --- | --- |
| ✿ | `CD‑Debug.txt` / `BoxSet‑Debug.txt` | Lite / Full |

* * *

## ❓ Frequently Asked Questions

### **Does PyOCA Modify My Audio Files Automatically?**

No. You must explicitly enable **Write Tags on Audio Files**.

### **Where Are the Processed Files Saved?**

Always in the **root folder** of your album or BoxSet.

### **Does it support Unicode or special characters?**

Yes. All output filenames and content preserve Unicode characters.

### **Does It Work With Mp3Tag?**

Yes, the tool is designed around **Mp3Tag** workflows, including Discogs‑Based Tags.

* * *

## 🛡 Software Security

**PyOCA** contains no viruses or malicious software.

* * *

## 💬 For more information, consult the README file.

* * *

📥 [Download](https://mega.nz/file/315VFD5T#94xsr47snwmmXkVVVI8D1VPMBpaHrrgKzLBXvZ5cigw)

 ![pyoca](https://community.mp3tag.de/uploads/default/original/3X/7/c/7ca24991da6a49dc698a1224916f843ec9f47af4.png)

“ **Video Tutorial: Practical Guide to PyOCA** ”

📥 [Download]  
([190.06 MB file on MEGA](https://mega.nz/file/2koRgIDa#Rlk4axgK-vccmcZcWSB7kByiCs0n3B4td2InrhTgq40))