[BLOCKER v3.0.0-beta.3] P0 Implement Level-Based Mix Review Evidence Flow for v3.0.0-beta.3

[thunderdew-dawn]

Blocker: Implement Level-Based Mix Review Evidence Flow for v3.0.0-beta.3

Summary

Before v3.0.0-beta.3 can be released publicly, Mix Review needs a clearer, evidence-based structure.

The current Mix Review already provides useful static project/mixer checks and live peak/headroom heuristics, but the product promise should be made safer and more explicit by separating:

• Level 1 – Static Mix Review
• Level 2 – Live Peak Watch
• Level 3 – Rendered Master Evidence
• Level 4 – Stem/Bus Evidence

For v3.0.0-beta.3, Level 1 and Level 2 should be fully functional.
Level 3 and Level 4 should be prepared in GUI, backend, report schema and job structure, but must not implement actual audio analysis yet.

The real audio analysis of rendered master/stem files is developed in a separate repository and will be merged later into the existing runtime/job structure.

Why this blocks v3.0.0-beta.3

Mix Review is one of the core user-facing workflows. For a public beta, it must be clear which findings are:

• static project/mixer checks,
• live/watch-based meter evidence,
• rendered-audio pending,
• stem-audio pending,
• heuristic suggestions,
• or evidence-backed findings.

Without this separation, Mix Review can overclaim, especially around HPF, compressor, EQ clash, masking, low-end and audio quality topics.

This issue blocks v3.0.0-beta.3 because the beta should not ship with ambiguous Mix Review claims.

Scope

Implement now

• Level selector in Control Center.
• Level 1 Static Mix Review.
• Level 2 Live Peak Watch flow.
• Evidence/confidence metadata for findings.
• GUI badges for evidence status.
• Runtime/job placeholders for Level 3 and Level 4.
• Report contract for rendered master and stem/bus evidence.
• Documentation explaining all four levels.
• Tests for the new contracts and fallback behavior.

Do not implement now

• LUFS analysis.
• True Peak analysis.
• Spectrum/band-energy analysis.
• Mono-loss analysis.
• Stereo correlation from rendered audio.
• Kick/bass masking.
• Low-end phase analysis.
• Harshness detection.
• Drop-vs-break energy analysis.
• Stem-level audio analysis.
• Automatic rendering from FL Studio.

These will be integrated later from the external audio analyzer repository.

Desired Mix Review Levels

Level 1 — Static Mix Review

Runs without playback.

Uses:

• mixer snapshot,
• routing,
• track names,
• plugin slots,
• fader values,
• pan values,
• stereo separation,
• mute/solo state,
• template or role heuristics where available.

Allowed findings:

• routing/bus suggestions,
• fader imbalance,
• pan/stereo-separation risk,
• missing HPF as low-confidence suggestion,
• missing compressor/dynamic control as low-confidence suggestion,
• provisional EQ clash from plugin metadata,
• template/role consistency warnings.

Must not claim:

• real LUFS,
• real true peak,
• real spectrum balance,
• real masking,
• real phase correlation,
• real mono compatibility,
• real rendered-audio clipping count.

Level 2 — Live Peak Watch

Guided watch workflow for the loudest section.

User should be able to:

• select Level 2,
• choose capture length between 8 and 60 seconds,
• decide whether they start playback manually or the GUI may start playback,
• optionally select/use a marker,
• start a Watch,
• run Mix Review using fresh Watch evidence.

Allowed findings:

• master headroom from live/watch peaks,
• clipping risk from live/watch peaks,
• hot-track fraction,
• peak imbalance,
• Level 1 findings with appropriate confidence metadata.

If no fresh Watch evidence exists, the report must not fail. It should return a clear next action:

Start Level 2 Watch at the loudest section for 8–60 seconds, then run Mix Review again.

Level 3 — Rendered Master Evidence

Prepare only.

The GUI/backend should allow:

• selecting or referencing a rendered master file,
• preparing/submitting an audio evidence job,
• linking the evidence/job to the Mix Review workflow,
• showing job/evidence status,
• showing expected future checks.

The report should support statuses such as:

• missing,
• pending,
• unavailable,
• external_analyzer_not_installed,
• available.

Expected future checks may be listed, but must not be computed in this repo:

• Integrated LUFS,
• short-term loudness,
• true peak,
• clipping count,
• clipping plateau detection,
• RMS,
• crest factor,
• stereo correlation,
• mono loss,
• band energy,
• low-band side energy,
• harshness band,
• drop-vs-break energy.

Level 4 — Stem/Bus Evidence

Prepare only.

The GUI/backend should allow assigning files to roles such as:

• kick,
• bass,
• sub,
• drums bus,
• percussion bus,
• synth bus,
• lead bus,
• FX bus,
• vocal bus,
• premaster,
• master,
• other.

The report should show per-role evidence status.

Expected future checks may be listed, but must not be computed in this repo:

• kick/bass masking,
• low-end phase,
• stem headroom,
• bus balance,
• sub-side energy per stem,
• FX/reverb low-end leakage,
• transient vs sustain,
• mono compatibility for low-end stems.

Required report metadata

Every Mix Review report should include:

{
  "workflow": "mix_review",
  "mix_review_level": 2,
  "level_label": "Level 2 - Live Peak Watch",
  "analysis_mode": "live_runtime",
  "evidence_mode": "sufficient_watch_window",
  "evidence_summary": {
    "static_snapshot": "available",
    "live_meter": "available",
    "watch_window": "available",
    "rendered_master": "missing",
    "rendered_stems": "missing"
  },
  "capture": {
    "loop_seconds": 16,
    "playback_mode": "user_starts",
    "marker_id": null,
    "marker_name": null,
    "requested_loudest_section": true
  },
  "external_audio_analyzer": {
    "required_for_level_3_4": true,
    "available": false,
    "status": "not_merged_yet"
  }
}

Required finding metadata

Findings should include metadata similar to:

{
  "rule_id": "missing_hpf",
  "evidence_type": "static_snapshot",
  "proof_status": "heuristic",
  "confidence": "low",
  "requires_audio_evidence_for_confirmation": true,
  "mix_review_level": 1
}

Suggested values:

evidence_type

• static_snapshot
• live_meter
• watch_window
• rendered_master
• rendered_stem
• manual_check
• hybrid

proof_status

• evidence_backed
• heuristic
• provisional
• pending_external_analyzer
• manual_check_required
• unavailable

confidence

• low
• medium
• high
• unknown

Heuristic wording changes

Missing HPF

Current behavior should be softened.

Recommended wording:

No EQ was detected on this melodic/vocal-like track. Consider a high-pass only if unwanted low energy is audible or confirmed by rendered/stem evidence.

Missing Compressor

Recommended wording:

Dynamic control is unknown. This track type often benefits from compression, saturation, limiting, volume automation, or bus processing, but no dynamics plugin was detected by name.

EQ Clash

Recommended wording:

Potential overlapping EQ boosts were detected from plugin metadata. This is provisional until confirmed by live context or rendered/stem audio evidence.

Files likely affected

• src/fls_pilot/music/mix_doctor.py
• src/fls_pilot/tools/mix_doctor.py
• src/fls_pilot/control_center.py
• src/fls_pilot/control_center_static/app.js
• src/fls_pilot/control_center_static/index.html
• src/fls_pilot/control_center_static/styles.css
• src/fls_pilot/analysis/audio_schema.py
• src/fls_pilot/runtime/audio_worker.py
• src/fls_pilot/workflows/registry.py
• docs/user-guide/workflows.md
• docs/user-guide/control-center.md
• README.md
• CHANGELOG.md

New files likely needed:

• src/fls_pilot/music/mix_review_levels.py
• src/fls_pilot/packs/psytrance/mix_review_profile.json
• tests/test_mix_review_levels.py
• tests/test_mix_review_level_reports.py
• tests/test_mix_review_audio_evidence_contract.py
• tests/test_mix_review_stem_evidence_contract.py
• tests/test_psytrance_mix_profile.py

Implementation slices

Slice 1 — Mix Review Level Contract

Create:

• MixReviewLevel
• MixReviewOptions
• MixReviewCaptureOptions
• MixReviewAudioEvidenceRequest
• normalize_mix_review_options(raw)

Acceptance:

• default is Level 1,
• string levels are normalized,
• loop seconds are constrained to 8–60,
• Level 3 can represent missing rendered master evidence,
• Level 4 can represent missing stem evidence.

Slice 2 — Backend Report Metadata

Extend Mix Review report contract.

Acceptance:

• fl_review_mix() without arguments still works,
• default report has mix_review_level: 1,
• report contains evidence_summary,
• report contains external analyzer status,
• no audio DSP code is added.

Slice 3 — Level 2 Live Peak Watch Flow

Implement guided Level 2 flow in Control Center.

Acceptance:

• user can select Level 2,
• user can set capture length,
• user can choose playback mode,
• report distinguishes missing/stale/fresh watch evidence,
• fresh watch evidence enables peak/headroom/clipping findings.

Slice 4 — Evidence and Confidence Badges

Add metadata to findings and render it in GUI.

Acceptance:

• heuristic findings are marked visibly,
• static-only reports do not overclaim,
• HPF/compressor/EQ-clash wording is softened.

Slice 5 — Level 3 Rendered Master Placeholder

Prepare rendered master evidence.

Acceptance:

• user can select/reference a rendered master file,
• user can prepare or submit an audio evidence job,
• report shows rendered master status,
• expected future checks are visible,
• no actual audio analysis is performed.

Slice 6 — Level 4 Stem/Bus Placeholder

Prepare stem/bus evidence.

Acceptance:

• user can assign files to stem roles,
• report lists roles and evidence status,
• expected future checks are visible,
• no masking/phase/stem audio analysis is performed.

Slice 7 — Psytrance Mix Review Profile

Add conservative Psytrance guidance.

Acceptance:

• user can select genre_profile=psytrance,
• report shows active profile,
• profile adds low-end/kick-bass/FX guidance,
• no hard genre-specific audio findings appear without evidence.

Slice 8 — Docs and Changelog

Update docs.

Acceptance:

• Level 1–4 are documented,
• Level 3/4 are clearly marked as prepared/pending external analyzer,
• no false product claims.

Test commands

python -m pytest tests/test_mix_review_levels.py
python -m pytest tests/test_mix_review_level_reports.py
python -m pytest tests/test_mix_review_audio_evidence_contract.py
python -m pytest tests/test_mix_review_stem_evidence_contract.py
python -m pytest tests/test_psytrance_mix_profile.py
python -m pytest

Definition of Done

This issue is done when:

• Mix Review can be run as Level 1 from existing clients without changes.
• Control Center can switch between Level 1, Level 2, Level 3 and Level 4.
• Level 2 has a guided watch/playback/marker/capture UX.
• Level 2 can use fresh watch evidence for peak/headroom/clipping findings.
• Level 3 can prepare/link rendered master evidence jobs and show pending/missing/unavailable status.
• Level 4 can prepare/link stem/bus evidence jobs by role and show pending/missing/unavailable status.
• Level 3 and Level 4 do not compute audio features in this repo.
• All reports include explicit evidence and confidence metadata.
• Heuristic findings are visibly marked as heuristic/provisional.
• Docs accurately describe what is available now and what is pending external analyzer integration.
• Relevant tests pass.
• No unsafe FL Studio writes are added.

Labels

Suggested labels:

• blocking
• release-blocker
• v3.0.0-beta.3
• area:mix-review
• area:control-center
• area:workflow-evidence
• type:feature
• priority:P0
• safety
• needs-tests

Milestone

v3.0.0-beta.3

Linked plan

Use the local implementation plan JSON:

fls_pilot_mix_review_level_evidence_vibe_plan.json