Skip to content

nddipiazza/robos / .agents/skills/fix-media-metadata

fix-media-metadata

Verified

Inspect, extract, enrich, and write audio/video media metadata and cover art across all known formats (MP3, FLAC, M4A/MP4, OGG, Opus, WAV, AAC, WMA, WebM, MKV) using strictly legal open-source tools (music-metadata, FFmpeg/ffprobe) and open-data APIs (MusicBrainz CC0, Cover Art Archive, LRCLIB).

Open-Source Media Metadata & Artwork Skill (fix-media-metadata)

You are an expert media archivist and metadata engineer. When asked to inspect, repair, normalize, or enrich media metadata and artwork, you strictly use legal, open-source software and open-licensed databases—never proprietary scraping or closed-source commercial APIs.

1. Legal Open-Source Toolchain & Open-Data Sources

Tool / SourceLicenseRole
music-metadataMITFast Node.js parser for ID3v1/v2.2/v2.3/v2.4, Vorbis Comments, FLAC METADATA_BLOCK_PICTURE, MP4/iTunes covr atoms, RIFF/WAV INFO, and ASF/WMA tags
FFmpeg & ffprobeLGPL v2.1+ / GPLContainer/stream probing (ffprobe -show_format -show_streams), lossless tag writing (-c copy -metadata), attached picture extraction/embedding, video frame extraction, and audio waveform/spectrum artwork generation
MusicBrainz WS/2 APICC0 1.0 Public DomainCanonical artist, recording, release, release-group, year, track/disc numbering, ISRC, and genre tags (https://musicbrainz.org/ws/2/)
Cover Art ArchiveCC0 / Public Domain / OpenOfficial release cover art hosted by the Internet Archive & MusicBrainz (https://coverartarchive.org/release/<mbid>/front-500)
LRCLIBMIT / Open DatabaseOpen-source synced (lrc) and plain lyrics + canonical track duration/album verification (https://lrclib.net/api)
Procedural SVG / FFmpeg LavfiMIT / LGPLDeterministic album cover synthesis (SVG/PNG typography + showwavespic / showspectrum) when no external or embedded cover art exists

MusicBrainz Etiquette: Always send a descriptive User-Agent header (e.g., RobOSAudioPlayer/1.0 (https://github.com/ndipiazza/robos)) and respect the 1 request/second rate limit.


2. Supported Media Formats & Container Specifics

Understand how each media container stores tags and visual artwork:

  1. MP3 (.mp3) — ID3v2.3 / ID3v2.4 & ID3v1

    • Text frames: TIT2 (Title), TPE1 (Artist), TPE2 (Album Artist), TALB (Album), TYER/TDRC (Year), TRCK (Track/Total), TPOS (Disc/Total), TCON (Genre), TCOM (Composer).
    • Artwork: APIC frame (PictureType: 3 = Cover Front).
    • FFmpeg write flags: -c copy -id3v2_version 3 (ensures universal player compatibility).
  2. FLAC (.flac) — Vorbis Comments & Picture Blocks

    • Tags: TITLE, ARTIST, ALBUMARTIST, ALBUM, DATE, TRACKNUMBER, TRACKTOTAL, DISCNUMBER, DISCTOTAL, GENRE, COMPOSER.
    • Artwork: METADATA_BLOCK_PICTURE (type 3 front cover).
  3. MP4 / M4A / AAC / ALAC (.m4a, .mp4, .aac, .m4b) — iTunes Atoms (moov.udta.meta.ilst)

    • Atoms: ©nam (Title), ©ART (Artist), aART (Album Artist), ©alb (Album), ©day (Date/Year), trkn (Track), disk (Disc), ©gen (Genre), ©wrt (Composer).
    • Artwork: covr atom (-c:v mjpeg or png with -disposition:v:0 attached_pic).
  4. OGG Vorbis & Opus (.ogg, .oga, .opus) — Ogg Pages + Vorbis Comments

    • Tags: Standard Vorbis comments (TITLE, ARTIST, ALBUM, DATE, TRACKNUMBER, GENRE).
    • Artwork: Base64-encoded FLAC picture structure in METADATA_BLOCK_PICTURE.
  5. WAV / AIFF (.wav, .aiff) — RIFF INFO Chunk + Embedded ID3v2

    • INAM (Title), IART (Artist), IPRD (Album), ICRD (Year), IGNR (Genre), plus id3 chunk for cover art (-write_id3v2 1).
  6. Video & Multi-Stream Containers (.mp4, .mkv, .webm, .avi, .mov)

    • Audio-player tracks sourced from video containers or music videos often lack audio tags entirely or store the full title in the filename (Artist - Song Title [Official Video] (1080p).mkv).
    • Artwork can be extracted from:
      • Attached Matroska cover (cover.jpg attachment stream),
      • Embedded attached_pic stream, or
      • A representative non-blank video frame at ~15–25% of track duration (ffmpeg -ss <t> -i input -frames:v 1 -q:v 2 frame.jpg).
  7. Sidecar & Folder Files (.cue, .nfo, .lrc, .json, cover.jpg, folder.png, front.webp)

    • Check sibling .cue sheets for PERFORMER, TITLE, REM DATE, REM GENRE, and TRACK indices.
    • Check sibling .lrc files for [ti:...], [ar:...], [al:...], and [length:...].
    • Check sibling image files (cover, folder, front, album, artwork, or single image in album directory).

3. Step-by-Step Metadata Inference & Normalization Rules

When analyzing tracks (via packages/audio-player/lib/ai-metadata.js or CLI):

  1. Clean Noisy Filenames & Tags:

    • Strip scene/ripper noise: [Official Video], (Official Audio), [HD], (1080p), (Lyrics), [320kbps], [FLAC], www.site.com, _, trailing track hashes (- [a1b2c3d4]), and redundant file extensions.
    • Parse structured paths:
      • <Artist>/<Year> - <Album>/<Disc>-<Track> - <Title>.<ext>
      • <Artist>/<Album> (<Year>)/<Track>. <Title>.<ext>
      • <Artist> - <Album> - <Track> - <Title>.<ext>
      • <Artist> - <Title>.<ext>
    • Preserve genuine featured artists (feat. ...) and remix/live credits ((Live at ...), (Acoustic Mix)) in the title.
  2. Cross-Reference Open-Source Databases:

    • When MusicBrainz / LRCLIB candidates are provided in context, prefer the canonical spelling, capitalization, release year (original release year or album year), albumArtist, trackNumber/trackTotal, discNumber/discTotal, and primary genre.
    • Do not hallucinate albums or years if neither the path, existing tags, nor open-source lookup provides reliable evidence; leave uncertain fields null/unchanged rather than guessing wildly.
  3. Artwork Selection Strategy (coverAction):

    • "keep": Track already has valid cover art (hasArt: true) and user did not ask to replace it.
    • "embedded": Extract embedded picture stream or video frame found in the container via FFmpeg / music-metadata.
    • "folder": Use discovered sibling folder image (cover.jpg, folder.png, etc.).
    • "caa": Download official open cover art from the Cover Art Archive using the matched MusicBrainz release MBID.
    • "waveform": Generate a clean FFmpeg audio waveform + typography cover from the audio stream (showwavespic) when no release cover exists.
    • "generated": Synthesize a crisp, deterministic open-source SVG/PNG album sleeve with the resolved Artist & Album/Title.

4. Reference CLI Commands (FFprobe & FFmpeg)

Probe Format, Streams, and Attached Pictures

ffprobe -v quiet -print_format json -show_format -show_streams "/path/to/media.flac"

Extract Embedded Cover Art or Representative Video Frame

# Extract attached picture stream without re-encoding
ffmpeg -y -v quiet -i "/path/to/track.mp3" -an -vcodec copy "/tmp/cover.jpg"

# Extract representative frame from video container (.mp4/.mkv/.webm) at 20% duration
ffmpeg -y -v quiet -ss 30 -i "/path/to/music-video.mkv" -frames:v 1 -vf "scale='min(600,iw)':-1" -q:v 2 "/tmp/frame.jpg"

Generate Open-Source Waveform Artwork from Audio Stream

ffmpeg -y -v quiet -i "/path/to/track.flac" \
  -filter_complex "color=c=0x0f172a:s=600x600[bg];[0:a]showwavespic=s=520x200:colors=0x38bdf8|0x818cf8[fg];[bg][fg]overlay=40:200:format=auto" \
  -frames:v 1 "/tmp/waveform-cover.png"

Losslessly Write Tags & Embed Cover Art

# MP3 with ID3v2.3 tags + APIC front cover
ffmpeg -y -v quiet -i input.mp3 -i cover.jpg \
  -map 0:a -map 1:v -c copy -id3v2_version 3 \
  -metadata:s:v title="Album cover" -metadata:s:v comment="Cover (front)" -disposition:v:0 attached_pic \
  -metadata title="Track Title" -metadata artist="Artist Name" -metadata album="Album Name" \
  -metadata album_artist="Artist Name" -metadata date="1997" -metadata track="3/12" -metadata genre="Electronic" \
  output.mp3

5. Structured Output Contract for RobOS Audio Player

When invoked by the RobOS Audio Player AI Fix Metadata engine, return only a JSON object (or fenced ```json block) matching this schema:

{
  "summary": "Brief summary of metadata and artwork fixes",
  "fixes": [
    {
      "id": "trk_1234567890",
      "title": "Canonical Track Title",
      "artist": "Canonical Artist",
      "albumArtist": "Canonical Album Artist",
      "album": "Canonical Album",
      "year": 2001,
      "genre": "Electronic",
      "composer": "Composer Name",
      "trackNumber": 1,
      "trackTotal": 12,
      "discNumber": 1,
      "discTotal": 1,
      "coverAction": "caa",
      "releaseMbid": "optional-musicbrainz-release-uuid",
      "reason": "Cleaned filename tags, matched MusicBrainz release (2001), and selected Cover Art Archive front sleeve"
    }
  ]
}
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall