PyOCA — Python‑based extra tool for Mp3Tag

Off-Topic
1

:snake: PyOCA

Cleans and Organizes Credits/Performers for Discogs-Based Tags

:glowing_star: 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: :link: r2407100 :link: r858769

:desktop_computer: User Interface

The GUI includes:

  • :open_file_folder: Open: Select input files
  • :rocket: Start: Process the data
  • :eyes: Preview: View results line-by-line
  • :floppy_disk: Write: Apply tags to audio files
  • :artist_palette: Dark Mode
  • :test_tube: Debug Lite / Debug Full
  • :check_mark: CD mode
  • :check_mark: BoxSet mode

:bullseye: What PyOCA Does

:check_mark: 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

:check_mark: 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.

:droplet: Uses Discogs‑Based Role Matching:

:rainbow:​ Classifies everything into 3 output files

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

  1. :green_square: ♥ Credits.txt
  2. :blue_square: ♦ Musicians.txt
  3. :yellow_square: ✥ Unknown.txt

:dvd: 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.

:gear: 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.

:wrench: 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

:musical_score: 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)

:pushpin: When using the [WS] Discogs Release ID Plus, the filter becomes irrelevant.

:brain: 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.

:eye_in_speech_bubble: 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.

:performing_arts: 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 …)

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

:stethoscope: 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.

    • The following table summarizes all output files and their meaning:
Symbol File Description
:heart: Credits.txt Matched credit roles (from personnel.txt)
:diamond_suit: Musicians.txt Recognized instruments (from instruments.txt)
:club_suit: Merge-Field.txt Optional: merged full tag field (service file)
:spade_suit: 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

:card_file_box: 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

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

:warning: 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.

:puzzle_piece: Additional Features

:pen: 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.
    • :right_arrow_curving_left: No Undo function available.

:label: Supported Tag Formats

File Type: MP3, FLAC, APEv2

:test_tube: Debug Tracker

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

:red_question_mark: 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.

:shield: Software Security

PyOCA contains no viruses or malicious software.

:speech_balloon: For more information, consult the README file.

:inbox_tray: Download

pyoca
pyoca1371×824 66 KB

“Video Tutorial: Practical Guide to PyOCA”

:inbox_tray: [Download]
(190.06 MB file on MEGA)