How MixMan writes tags and preserves curation

A track can have several plausible answers

A music library can learn a track's tempo from an analyzer, its title from a download provider, its genre from a catalog lookup, and its mood from an audio model. A listener may then correct any of those suggestions. MixMan needs to keep those contributions useful while preserving the distinction between an observation, a shared library value, and a person's preference.

The important detail in the current system is that provenance and priority are separate. Provenance records which source last claimed a field. Each job still applies its own publication rules. Having provenance does not, by itself, guarantee that every later writer will respect the same hierarchy.

The flow below describes the implementation examined in October 2026. The proposed precedence policy near the end is a separate design direction.

How tracks enter the review queue

Uploads and provider imports create review items before those items become library tracks. Media identity and deduplication keep repeated acquisitions from becoming independent copies of the same audio. Acquisition history records where the media came from; field provenance records who supplied particular metadata. Uploading a file does not make its embedded tags human-authored metadata.

After ingestion, the scheduler chooses applicable work. Queen Mary runs when enabled. OpenL3 runs when its embedding is absent. Missing required core metadata can trigger file-tag extraction and MusicBrainz lookup. Some jobs can execute concurrently, so their placement in the queue is not a reliable way to express trust.

flowchart TD
    Input[Upload or provider import] --> Review[Review item]
    Review --> Schedule[Select applicable jobs]
    Schedule --> QM[Queen Mary]
    Schedule --> Catalog[File tags and MusicBrainz]
    QM --> Publish[Publish eligible fields]
    Catalog --> Publish
    QM -->|Required gaps remain| AI[OpenAI with QM hints]
    AI --> Publish
    Publish --> Gate[Human review and approval]
    Gate --> Library[Library track]

The QM-to-OpenAI dependency applies when analysis hints are enabled. OpenAI is otherwise eligible to run directly. A terminal QM failure can also schedule legacy BPM, key, and energy fallbacks. Those branches are omitted from the diagram to keep the main path readable.

Scheduling is selective. Missing optional Mood or Colour alone does not necessarily trigger OpenAI: the automatic decision checks missing required fields. Restarting the server also does not automatically schedule every analysis missing from older review items.

What each job can write

Completing an analysis and publishing its suggestions are different operations. Queen Mary stores a versioned result containing measurements, feature evidence, diagnostics, and quality warnings. Publishing projects selected results into the familiar shared metadata fields.

These are current defaults, not a universal safety guarantee. File-tag enrichment can replace human metadata even though missing core fields were the reason it was scheduled. Explicit overwrite_all modes in enrichment and QM also permit replacement of human values. QM's normal blank-filling behavior does not protect human-owned blank fields consistently with MusicBrainz and OpenAI, and legacy analyzers do not share all the newer publication safeguards.

The ordinary OpenAI path does not automatically outrank Queen Mary. If QM fills Energy first, OpenAI's normal preserve-existing policy can leave that value in place. Waiting for QM makes its measurements available as hints; it does not grant OpenAI permission to replace the resulting tags.

Rebuilding QM analysis normally marks earlier OpenAI enrichment stale. A subsequent OpenAI job is still conditional on the remaining required gaps. Neither the stale marker nor a completed-job marker guarantees that every desired field received a fresh, useful result.

What field provenance means

For each claimed field, MixMan retains a source such as user, queen_mary, musicbrainz, or openai, along with a timestamp and any additional publication details. That makes it possible to distinguish curated values from identified machine output when the writer preserves the information.

An explicit human set operation claims ownership even when the submitted value matches the existing value. An explicit clear operation removes both the value and its provenance claim, allowing later automation to fill the field again. Clearing therefore means releasing the field; it is different from deliberately keeping an owned field empty.

Provenance is not a complete edit history. Historical full-record saves and supplied defaults can claim more fields than a person deliberately changed. A user marker should be preserved as an ownership claim, but should not be counted as proof that the user independently edited that value. Missing provenance likewise does not establish that a populated value is disposable.

Personal preferences sit above shared defaults

Shared metadata describes the track for the library. Personal preferences describe how a particular listener wants to use it. Favour and the DJ-specific preference fields belong to that personal layer. Genre, Energy, Mood, and Colour can also have personal overrides backed by shared defaults.

flowchart TD
    Jobs[Eligible machine publications] --> Shared[Shared metadata]
    Human[Human shared edits] --> Shared
    Shared --> Resolve[Resolve values for the listener]
    Personal[Personal overrides] --> Resolve
    Resolve --> View[Effective track values]

For fields with shared defaults, an explicit personal override wins when MixMan resolves that listener's view. Without an override, the shared value supplies the default. Personal-only fields remain unset when the listener has not supplied them. Machine analysis should not invent a listener's Favour.

For example, a listener can keep a personal Energy assessment while the shared Energy default changes through an eligible publication. The raw QM measurement can remain available independently of both values. Those are three useful representations with different purposes.

Embeddings follow a separate path

Queen Mary features and OpenL3 embeddings are distinct representations with different dimensions and meanings. Generating one does not populate the other. In the review vector recommendation path examined here, retrieval still uses OpenL3 rather than QM similarity features.

flowchart LR
    Audio[Audio] --> Embedding[OpenL3 embedding]
    Embedding --> Index[Review vector index]
    Index --> Candidates[Vector candidates]

That distinction matters when investigating surprising recommendations. A successful QM job can improve stored analysis and eligible metadata without repairing missing OpenL3 vectors or changing which representation review retrieval uses. Analysis coverage, published tag coverage, and recommendation-index coverage need separate checks.

A proposed priority policy for future enrichment

The direction is to resolve authority per field, independently of which job finishes first. Human ownership should remain protected, personal overrides should remain separate, and populated values with unknown provenance should stay protected pending deliberate resolution.

The opt-in review backfill implementation is a bounded step toward that policy. It protects human fields, personal preferences, and populated unknowns; allows QM to replace recognized machine values within its six published fields; and allows selected OpenAI jobs to supersede QM semantic values. It does not change routine job defaults. Its implementation is tracked in the scoped backfill pull request, while the configurable precedence enhancement tracks the broader design.

The useful long-term contract is straightforward: keep provider observations available, apply an explicit publication policy, and preserve the listener's decisions. Then a better analyzer can improve the library without silently acquiring authority over every tag it encounters.