Tag write-back
The opt-in mirror of app-managed track data into file tags: what each container gets, what is lossy, and how to verify a change.
library.db is the source of truth for track information. Write-back is the optional second half. When the user turns on Settings → Library → File tags, Mixar also writes values into each file’s own tags. Other software (Rekordbox, Serato, Traktor, Mixxx, Mixed In Key) then sees those values where the container has a mapping for them; see Lossiness and conflicts.
It is the only place Mixar modifies a music file, so it is opt-in, field-scoped, idempotent, and best-effort.
User-facing manual: Tag write-back (in Library). This page covers internals, the field matrix, and the known limits.
Before you enable it
- Opt-in:
LibraryConfig::tag_write_back(Offby default;TagWriteBack::Onfrom the setting). With it off, no analysis path ever opens a file for writing. - Field-scoped:
TrackTagsis a patch, not a rewrite. Only the fields the caller sets are touched; pictures, ReplayGain, Serato frames, and foreign keys survive untouched. A blank string or a non-finite BPM is reportedAbsentand written nowhere. - Idempotent: a field already carrying the wanted value is left alone. A file with nothing to change is never rewritten (no mtime churn, no re-padding on every analyze).
- Best-effort: an unwritable file is logged and skipped; the library row is already committed.
- Refused shape (
FieldWrite::Refused, file left byte-identical): native.stem.mp4containers, multi-track MP4s whosestemmanifest Mixar does not own. - Clearing a tag is not expressible yet:
TrackTagsusesNonefor “leave alone”, so removing a field needs that added to the patch type first.
Run a write
Implementation: codec::write_track_tags (lofty) for the format matrix, called by library::tags::write_back_track_tags from LibraryManager::persist_file_analysis and the SaveBeatGrid worker handler.
- Turn on Settings → Library → File tags (
LibraryConfig::tag_write_back,TagWriteBack::On). - Analyze a track, or save its beat grid. These are the two paths that reach the writer; the values come from
library::tags::app_managed_tags, listed below. The beat-grid path then replaces the BPM with the grid’s own value. - Check the file in another reader against the library row, allowing for the lossy cases below (a fractional BPM on ID3v2, BPM and key on APE). Because the write is idempotent, a field already at the wanted value is left alone and a second run changes nothing.
Neither write path runs on the audio callback. The beat-grid path plans the write while holding the library lock, then performs the file I/O after releasing it.
Fields per container
| ID3v2 (mp3/wav/aiff/aac) | Vorbis comments (flac/ogg/opus) | MP4 ilst (m4a) |
APE (ape/wv/mpc) | |
|---|---|---|---|---|
| Title | TIT2 |
TITLE |
©nam |
Title |
| Artist | TPE1 |
ARTIST |
©ART |
Artist |
| Album | TALB |
ALBUM |
©alb |
Album |
| Genre | TCON |
GENRE |
©gen |
Genre |
| BPM | TBPM, integer |
BPM, text |
----:com.apple.iTunes:BPM, text |
unsupported |
| Key | TKEY |
INITIALKEY |
----:com.apple.iTunes:initialkey |
unsupported |
| Rating | POPM per email¹ |
RATING, 0.0–1.0 |
rate, 1–5 |
unsupported² |
| Comment | COMM |
COMMENT |
©cmt |
Comment |
| Year | TDRC |
YEAR |
©day |
Year |
| Track no. | TRCK |
TRACKNUMBER |
trkn |
Track |
| Disc no. | TPOS |
DISCNUMBER |
disk |
Disc |
| Color | COLOR |
COLOR |
----:com.apple.iTunes:COLOR |
Color |
¹ ID3v2 keeps the rating in a binary POPM frame keyed by the email of the app
that wrote it. Multiple frames are legal, so Mixar writes one per writer:
MusicBrainz Picard’s frame goes through lofty’s provider
(round(star * 51), giving 51/102/153/204/255), and Traktor, MusicBee and Windows
Media Player get the stepped 1/64/128/196/255 set. Each app reads the frame
carrying its own email, so the same star count reaches all of them at once. A
frame owned by a reader Mixar does not mirror is re-emitted on the stepped set:
a stepped writer (Serato, MediaMonkey, foobar2000) keeps its exact byte, while a
51-scale one keeps its star. Each mirrored frame keeps its play counter.
² APE has no rating key in lofty’s (or TagLib’s) mapping table, so the field is
reported Unsupported on .ape/.wv/.mpc.
MP4’s rate atom keeps the scale Mixar has always written: the star count
itself (4). Serato 4 writes a RATE/rate value whose scale has not been
verified against a real file, so the writer is unchanged and the reader accepts
both conventions (a value of 1–5 is the star count, 20–100 is treated as a
percentage). A literal uppercase RATE atom is not read: only rate is in
lofty’s atom map, and no fixture has shown RATE in the wild.
A per-app Vorbis rating (RATING:<email>=N, which Picard writes) cannot be
written back through lofty’s generic tag: its writer would put lofty’s internal
email|stars|counter text under plain RATING. Any save that rewrites the file
therefore folds such an alias into the plain normalized RATING (0.8 = four
stars) instead, keeping the star count every reader understands at the cost of
the per-app key.
Reading is deliberately wider than writing. Vorbis RATING stays raw text, so it
accepts normalized 0.0–1.0 (Quod Libet/Picard), stars 1–5, a 0–100 scale, or
a raw POPM byte above 100 (204 = four stars; 6–19 fit no scale and are
rejected). POPM frames and MP4 rate go through lofty’s rating
providers: a known email is read on its own scale and every other email
(including an empty one) on the linear 51 scale, whose thresholds also land on
the right star for the stepped 1/64/128/196/255 writers. Two edges are
inherent: lofty’s StarRating has no “unrated” value, so a stored 0 reads as
one star; and several mirrored frames that disagree resolve in a fixed order,
with Traktor’s frame first.
The mapping matches the TagLib property table, so the keys are the ones MusicBrainz Picard, Mixxx, and the DJ tools above already read and write. Mixxx writes the same Vorbis BPM + INITIALKEY pair and the same two MP4 freeform atoms.
What the library mirrors today is BPM, key, rating, comment, year, track/disc
number and colour label: library::tags::app_managed_tags is the one place
that decides it. Title/artist/album/genre are file-derived today (a missing title
falls back to the file name), so passing the library row would stamp filename
guesses into untagged files. A track editor that owns those values extends that
one function; the writer already handles them. Derived fields (duration, sample
rate, channels, bitrate) are never written: they describe the audio, not user
intent.
Lossiness and conflicts
- ID3v2
TBPMis an integer frame, so a fractional BPM is rounded (FieldWrite::Rounded). Mixxx and Mixed In Key round too.library.dbkeeps the exact value, so a rescan that prefers the tag can land up to 0.5 BPM away from the stored beat grid. - MP4 gets the freeform
BPMatom, nottmpo. The freeform field is what Mixed In Key, Serato, and Traktor write and what Mixxx reads first.tmpois an integer atom, which lofty cannot emit from a text tag. Readers that look only attmpowill not see Mixar’s BPM. - APE tags have no BPM/key mapping in the TagLib/lofty table. Those two fields are reported
Unsupportedon.ape,.wv, and.mpc(the text fields work). - Legacy aliases are not updated. Only the recommended keys in the table above are written. A Vorbis file that carries the older
KEY(orTEMPO) alias keeps its stale value, and the same goes for MP4’s----:com.apple.iTunes:KEY. A reader that prefers the alias overINITIALKEY/BPMwill see the old number. Mixxx additionally updatesKEYwhen it is present. Aliases in the wild: Vorbis keyINITIALKEY(Rekordbox, Serato, Traktor, Mixxx) vsKEY(VirtualDJ, Denon Engine DJ), and Vorbis BPMBPM(MusicBrainz) vsTEMPO(Mixxx ≤ 2.0). MP4 key----:com.apple.iTunes:initialkeyvs----:com.apple.iTunes:KEY(Rapid Evolution), and MP4 BPM----:com.apple.iTunes:BPMvs the integertmpoatom. Mixar reads either key alias, but has no mapping for the older VorbisTEMPO. A file whose BPM lives only there reads as unknown and is re-analyzed.
Cues, loops, and beat grids
Cues, loops, and grids are not written to tags: there is no standardized tag representation. Serato’s proprietary, reverse-engineered field set is the de-facto one, and it is per-format: ID3v2.4 GEOB frames on MP3/AIFF, SERATO_MARKERS_V2 Vorbis comments on FLAC, ----:com.serato.dj:markersv2 atoms on MP4/M4A, its own layout on Ogg Vorbis, sidecar XML for AAC. Mixxx preserves it (it re-emits the frames it parsed, never authors cues). Mixar keeps cues/loops/grids in library.db, as Rekordbox and Traktor do. Rekordbox’s route out of the database is USB export (ANLZ files), tracked in #452. Writing Serato’s frames is tracked in #548.
Verification
cargo test -p codec tag_write: the per-container matrix (text fields, BPM rounding, APE’s missing BPM/key), thePOPMframe per writer with its byte scale, foreign-frame reads, ID3v2/Vorbis/MP4 round trips, idempotency, and the Stem refusal.cargo test -p library --all-features write: analysis and beat-grid write-back against a real WAV, plus the untouched-file case with the setting off.cargo test -p host_flutter --test library_tag_write_back: the whole stack, app setting →LibraryTransport→ worker analysis → file tags, read back with lofty rather than Mixar’s own reader.