Pure-Go library and CLI for reading and writing audio metadata: tags, embedded pictures, chapters, and synced lyrics. Preservation-first: edits are planned against the parsed native structure, metadata is rewritten only where needed, and audio bytes are copied rather than transcoded.
Read/write: FLAC, Ogg Vorbis, Ogg Opus, Ogg FLAC, MP3, WAV (RF64/BW64), MP4/M4A, raw AAC/ADTS, Matroska/WebM, AIFF/AIFF-C, WavPack, Monkey's Audio, Musepack. Read-only: WMA/ASF.
Public API: github.com/colespringer/waxlabel and
github.com/colespringer/waxlabel/tag. Codec packages are internal.
go get github.com/colespringer/waxlabel # library
go install github.com/colespringer/waxlabel/cmd/waxlabel@latest # CLIRequires Go 1.26+. Library uses only the standard library; CLI uses Cobra.
package main
import (
"context"
"fmt"
"log"
waxlabel "github.com/colespringer/waxlabel"
"github.com/colespringer/waxlabel/tag"
)
func main() {
ctx := context.Background()
doc, err := waxlabel.ParseFile(ctx, "track.flac")
if err != nil {
log.Fatal(err)
}
fmt.Println(doc.Fields().Title)
plan, err := doc.Edit().
Set(tag.Title, "New Title").
Set(tag.Artist, "Lead", "Featured").
Clear(tag.Encoder).
Prepare()
if err != nil {
log.Fatal(err)
}
_, result, err := plan.Execute(ctx, waxlabel.SaveBack())
// Failed write: err != nil AND Committed false. err with Committed true means
// bytes landed but a later step failed; the edit is applied and the plan is spent.
if err != nil && !result.Committed {
log.Fatal(err)
}
if err != nil {
log.Println("warning:", err)
}
fmt.Println("committed:", result.Committed)
}Parse, ParseFile, and OpenSource return an immutable Document with no open
file descriptor. Edit with Document.Edit(), resolve with Editor.Prepare(),
write by executing the Plan. Destinations:
SaveBack()atomically rewrites the parsed file in place (a no-op writes nothing).SaveAsFile(path)writes a complete new file.WriteTo(w, source)streams a complete output to anio.Writer.
waxlabel dump track.flac
waxlabel plan track.flac --set TITLE="New Title"
waxlabel set track.flac --set TITLE="New Title" --add ARTIST=Featured
waxlabel lint track.flac --fix
waxlabel verify track.flac
waxlabel caps --format flac
waxlabel keys
waxlabel copy source.flac dest.m4a
waxlabel diff before.flac after.flac
waxlabel export-picture track.flac -o cover.jpg| Command | Purpose |
|---|---|
dump <file>... |
Tags, audio properties, pictures, chapters, synced lyrics, warnings. --native adds native blocks. |
plan <file>... |
Preview an edit without writing. |
set <file>... |
Apply edits and save. -o writes a new file. |
lint <file>... |
Report metadata issues. --fix applies safe, non-destructive fixes; a legacy container is stripped only when fully redundant with canonical tags. |
verify <file>... |
Tag-independent audio-essence digests. --whole-file hashes every byte. |
clean <dir>... |
List .waxlabel-*.tmp leftovers from interrupted writes; --remove deletes them, --all includes files newer than an hour. |
caps <file>... or caps --format <name> |
What a file or format can store and edit. --format takes an extension or any name caps prints. |
keys |
Canonical tag vocabulary and cardinality. |
copy <source> <dest> |
Overlay source metadata onto dest; report what carries, downgrades, or drops. --strict refuses a non-lossless transfer. |
diff <a> <b> |
Compare canonical tags, pictures, chapters, and synced lyrics, and comment and lyrics descriptions and languages where both formats store them. |
export-picture <file> |
Write one embedded picture to -o FILE. --picture selects by role or index. |
Edits use --set KEY=VALUE, --add KEY=VALUE, --clear KEY, plus picture
(--add-cover, --add-picture, --remove-picture), chapter
(--add-chapter, --clear-chapters), synced-lyric
(--synced-lyrics-file, --add-synced-lyric, --synced-lyrics-lang), and
--output-gain (Ogg Opus header gain). --comment-desc, --comment-lang,
--lyrics-desc and --lyrics-lang give the COMMENT or LYRICS values an
invocation sets or adds a description and language; ID3 stores both, Matroska the
language, and other formats drop them with a warning. Write shaping: --preset, --legacy,
--padding. --id3-multi null|repeat|slash sets how an ID3v2.3 tag stores multiple values:
a new MP3 tag, or an existing v2.3 tag in any container; ID3v2.4 tags ignore it.
See waxlabel <command> --help. --legacy strip (and --preset minimal) removes
ID3v1/Lyrics3/APEv2/stray-ID3 unconditionally; when one holds the only copy of a value, the
plan says so and --strict refuses the write. On WAV and AIFF it moves the LIST/INFO and
native text chunk values into the ID3 chunk and removes those chunks, with the same warning
for a value or item that cannot move.
Read commands accept - for stdin. dump, verify, lint, plan, and set
walk directories with --recursive. Format comes from leading bytes, not extension,
except under --recursive (extension filter first): a valid FLAC named noext is
skipped recursively but works when named directly. An unreadable directory is an
io error for that path (exit 6); the rest of the tree continues. All data commands
accept --json. -o writes atomically and refuses an existing target unless
--overwrite.
lint --json findings include code, severity, and fixable: true for what
--fix is for and removes (an inherited encoder stamp, a redundant legacy
container, and a conflict or extra ENCODER value that goes with either), false
on a file that cannot be written. A rewrite can clear other findings on its way,
such as a duplicate tag block it drops. Exit code reflects the highest-precedence
result. A finding raised from a parse warning carries that warning's code, one of
the WarningCode constants in the package docs; lint's own codes are listed on
Document.Lint.
Every failure has a stable machine code (JSON error envelope code field) and
an exit status:
| Exit | Machine code | Meaning |
|---|---|---|
| 0 | none, or broken-pipe |
Success, or a closed output pipe (... | head) |
| 1 | error, or none |
Unclassified failure; lint found warnings; diff found a difference |
| 2 | usage, invalid-key, needs-file |
Bad invocation, invalid canonical key, or --strict refusal |
| 3 | unsupported-format, unsupported-tag, unsupported-stream, unsupported-alignment, unsupported-fragmentation, picture-too-large, content-too-large |
Unsupported format, or file reads but format refuses the write |
| 4 | invalid-data, or none |
Corrupt file or format violation; lint found an error-severity issue |
| 5 | source-changed |
File changed between read and save-back |
| 6 | not-found, io |
Wrong path, or local I/O failure |
| 7 | input-too-large |
Streamed input exceeded --max-size |
| 130 | canceled, timeout |
Interrupted, or deadline expired |
Multi-file runs exit with the most-severe class (not numeric max):
canceled/timeout > source-changed > invalid-data > input-too-large >
unsupported-format > unsupported-tag > unsupported-stream >
unsupported-alignment > unsupported-fragmentation >
picture-too-large/content-too-large > io > not-found >
usage/invalid-key/needs-file > error > broken-pipe.
A corrupt file (exit 4) outranks a mistyped path (exit 6).
A closed output pipe ends a read early. It never stops a write: set, copy,
lint --fix, clean --remove and export-picture finish, and exit with the
status the work earned.
| Format | Metadata | Notes |
|---|---|---|
| FLAC | read/write | Vorbis comments, FLAC pictures, CHAPTERxxx chapters, SYNCEDLYRICS (LRC); padding fully controllable. Leading ID3v2, trailing ID3v1, APEv2 and Lyrics3 as legacy. |
| Ogg Vorbis / Opus | read/write | Vorbis comments, METADATA_BLOCK_PICTURE, CHAPTERxxx, SYNCEDLYRICS (LRC). Opus also has OpusHead output gain (--output-gain); rebases R128_TRACK_GAIN/R128_ALBUM_GAIN per RFC 7845. Leading ID3v2, trailing ID3v1, APEv2 and Lyrics3 as legacy. Chained and multiplexed files are read-only, and a chained file has no essence digest. |
Ogg FLAC (.oga) |
read/write | Vorbis comments, chapters, legacy tags and read-only cases as above; cover art is a native FLAC PICTURE block, not a comment. |
| MP3 | read/write | ID3v2 (CHAP/CTOC, SYLT); new tags are ID3v2.3. Trailing ID3v1, APEv2 and Lyrics3 as legacy. |
| WAV / RF64 / BW64 | read/write | RIFF LIST/INFO plus embedded id3 ; chunks preserved. RF64/BW64 form kept on save-back; ds64 recomputed. |
| MP4 / M4A / M4B / MOV | read/write | iTunes ilst, mdta keys (ffmpeg +use_metadata_tags, and the moov.meta store Apple's recorders write), classic moov.udta text, cover art, Nero chpl chapters and the QuickTime chapter track (the text or subtitle track a chap reference names, in any track). Fragmented MP4 (moof) is read-only; moov with mvex but no fragment writes normally. |
| Matroska / WebM | read/write | Scoped SimpleTags, segment title, attachments, default-edition chapters. Tags of an attachment, chapter, edition or video track stay out of the file's tags. Beside a TITLE at level 40 or under, the album-level TITLE and ARTIST are ALBUM and ALBUMARTIST. Attachments an edit keeps are copied verbatim. WebM cannot write cover attachments or hidden/disabled chapter flags. |
| AAC (ADTS) | read/write | Front ID3v2 (new tags ID3v2.4) plus ADTS frames. HE-AAC reports played rate, channels, and profile from frames when the header cannot. Trailing ID3v1, APEv2 and Lyrics3 as legacy. |
| AIFF / AIFF-C | read/write | Native text chunks plus embedded ID3 ; chunks preserved. |
| WavPack | read/write | APEv2. Pictures are Cover Art (<role>) items, one per role: taggers agree on the front and back names only, so the other roles follow the convention Mp3tag and Kid3 write, and the names TagLib# and foobar2000 write are read too. Leading ID3v2, trailing ID3v1 and Lyrics3 as legacy. |
| Monkey's Audio | read/write | APEv2 and legacy tags as above; SV3.98+ and older inline header both read. |
| Musepack | read/write | APEv2 for SV7 and SV8. SV8 chapter packets read and preserved, not written. Leading ID3v2, trailing ID3v1 and Lyrics3 as legacy. |
| WMA / ASF | read-only | Content Description, WM/*, WM/Picture, Marker Object chapters. No ASF writes. |
When set authors a structural edit a format cannot store (cover art on WebM,
chapters with no chapter store), it drops that item with a warning and applies the
rest. set --strict promotes drops to failures (exit 2). copy grades each item by what
the destination holds once written: carried means it reads back as the source gives it, and
an item the destination cannot take (a value with a NUL byte, a cover over the format's size
limit, a link picture where only images are stored) is dropped with the reason while the rest
is written. A dropped item is not written at all, and a key only the destination holds stays
as it was. copy --strict refuses a transfer with a lossy or dropped item, or one whose
destination write would itself lose metadata. What the destination already holds as given is
carried and not written again, so a copy onto itself changes nothing. Copy onto a read-only
destination (WMA, fragmented MP4) that lacks an item exits 3 after the per-field report.
Table below is generated from the same capability model as waxlabel caps.
| Format | Pictures | Chapters | Synced Lyrics | Comment and Lyrics Qualifiers |
|---|---|---|---|---|
| AAC (ADTS) | read full, write full · APIC frame | read full, write full · ID3v2 CHAP/CTOC frames | read full, write full · ID3v2 SYLT frame | description, language |
| AIFF | read full, write full · APIC (ID3 chunk) | read full, write full · ID3v2 CHAP/CTOC frames (ID3 chunk) | read full, write full · ID3v2 SYLT frame | description, language |
| FLAC | read full, write full · FLAC PICTURE block | read full, write full · VorbisComment CHAPTERxxx | read full, write full · SYNCEDLYRICS comment (LRC) | none |
| MP3 | read full, write full · APIC frame | read full, write full · ID3v2 CHAP/CTOC frames | read full, write full · ID3v2 SYLT frame | description, language |
| MP4 | read full, write full · covr atom, or the artwork key of an mdta keys store (JPEG/PNG/BMP) | read full, write full · Nero chpl and a QuickTime chapter text track | read none, write none | none |
| Matroska | read full, write full · AttachedFile (image attachment) | read full, write full · Chapters > EditionEntry > ChapterAtom (default edition) | read none, write none | language |
| Monkey's Audio | read full, write full · APEv2 Cover Art item | read none, write none | read none, write none | none |
| Musepack | read full, write full · APEv2 Cover Art item | read full, write none · SV8 chapter packets | read none, write none | none |
| Ogg FLAC | read full, write full · FLAC PICTURE block | read full, write full · VorbisComment CHAPTERxxx | read full, write full · SYNCEDLYRICS comment (LRC) | none |
| Ogg Opus | read full, write full · METADATA_BLOCK_PICTURE | read full, write full · VorbisComment CHAPTERxxx | read full, write full · SYNCEDLYRICS comment (LRC) | none |
| Ogg Vorbis | read full, write full · METADATA_BLOCK_PICTURE | read full, write full · VorbisComment CHAPTERxxx | read full, write full · SYNCEDLYRICS comment (LRC) | none |
| WAV | read full, write full · APIC (id3 chunk) | read full, write full · ID3v2 CHAP/CTOC frames (id3 chunk) | read full, write full · ID3v2 SYLT frame | description, language |
| WMA | read full, write none · WM/Picture descriptor | read full, write none · Marker Object | read none, write none | none |
| WavPack | read full, write full · APEv2 Cover Art item | read none, write none | read none, write none | none |
Some limits are intentional: MP4 and APEv2 covers drop the picture description, ID3 chapters
store no per-chapter language, ID3 stores a comment or lyric written without a
language as eng, and Matroska writes random UIDs, so chapter and
attachment rewrites are not byte-reproducible. Package docs describe them and writes
warn about them.
Input is untrusted: bounded allocation and recursion, fuzz coverage, and human
output that sanitizes terminal-control bytes and invisible/reordering Unicode
(bidi controls, ZWSP, word joiner, BOM, line/paragraph separators, invisible
operators, interlinear annotation marks, tag characters, soft hyphen, Hangul
fillers; joiners and variation selectors print, as emoji need them, so only the
flags spelled with tag characters, such as Scotland's, show as escapes). Line breaks
print as indented continuations only for LYRICS, COMMENT, DESCRIPTION, and
LONGDESCRIPTION; elsewhere as \x0a. A key over 96 bytes and a value over 4 KiB
are elided, and no line runs past 16 KiB (JSON keeps exact values). A file name
that is not UTF-8 shows each invalid byte as \xNN, in JSON file, output,
source, a and b too.
Save-back: temp file in the target directory, fsync, rename. SIGKILL mid-write can
leave the temp; recursive commands note leftovers and waxlabel clean lists or
removes them. SaveBack() refuses with waxerr.ErrSourceChanged when the file
changed since parse: a different file at the path, its size, metadata fingerprint,
mtime, or (Unix) change time, so a chmod or an xattr write counts as a change too;
so does a deleted file. The check runs again after the copy and, through the path,
just before the rename, so a competitor that renamed its own file over the path keeps
it. Concurrent saves of one file run one at a time under an advisory flock (Linux,
macOS, BSD) and the later one refuses; a save that waits on another program's lock
says so after a second. Without the lock (Windows, filesystems that refuse locks) two
saves that both pass the last check can still race to the rename.
A rewrite keeps the replaced file's mode, its owner and group where the caller may
set them, and on Linux its user.* attributes and POSIX access ACL; Windows swaps
the file with ReplaceFile, which keeps its ACL and attributes. A new file's mode
follows the umask. -o without --overwrite also refuses a target created while
the write runs, except at the last moment on a filesystem without hard links (FAT,
exFAT, some network shares). Atomic rename consequences: editing through a symlink rewrites the
target and leaves the link; other hard links keep the old inode; a read-only file
can be replaced when its directory is writable (mode preserved).
MIT.
Mutagen, TagLib, bogem/id3v2, sentriz/go-taglib, and libogg influenced design and test cross-checks. Implementation follows public specifications and does not copy their code.