dj-metadata-tag-editor

name	dj-metadata-tag-editor
description	Toolkit for implementing and debugging advanced media metadata editing in DJ Metadata Fixer. Use when adding manual tag fields, mapping tags across MP3/MP4/MKV/WebM, improving metadata validation, fixing rename collisions, or refining per-file processing UX.
license	Complete terms in LICENSE.txt

DJ Metadata Tag Editor Skill

When to Use This Skill

• Add or modify manual metadata fields in the GUI.
• Map additional fields to MP3/MP4 tag formats.
• Implement best-effort metadata support for MKV/WebM.
• Add or improve validation for BPM, key, year, track, rating.
• Investigate metadata write failures or rename collisions.

Prerequisites

• Python environment with Mutagen installed.
• ffmpeg available in PATH for video/container metadata writes.

Workflow

1. Identify requested fields and whether each is portable or app-only.
2. Update model/mapping in metadata_engine.py.
3. Update editor UX in app.py with validation and clear errors.
4. Keep existing process flow compatible.
5. Validate with representative files and summarize limitations.

Field Strategy

• Portable fields: artist, title, album, genre, year/date, track, comment, composer, grouping, bpm, key.
• Extended fields: remix, remixer, label, rating (best-effort).
• App-only fields: play stats, gain, color, custom user fields.

Troubleshooting

• ffmpeg metadata failure: inspect stderr and fallback to app-only storage for unsupported keys.
• MP4 atom mismatch: verify atom keys and value types.
• ID3 duplication issues: replace/update relevant frames instead of unbounded adds.
• Rename failure: check path permissions and collision checks.