docs/SUPERVISED_EXPORT_AND_FORCE_ONSET.md

Supervised export and force-onset workflow

Last updated: 2026-05-12

Purpose

The batch extraction manifest is immutable. Interactive edits are stored in supervision_state.json. This pass adds the missing rendering step that turns those semantic edits into new downloadable artifacts without rerunning Demucs or onset detection.

manifest.json + review/hits/*.wav + supervision_state.json
→ supervised/manifest.json
→ supervised/samples/*.wav
→ supervised/reconstruction.mid
→ supervised/target_reconstruction.wav
→ supervised/reconstruction.wav
→ supervised/sample-pack.zip

Implemented features

Feature	Status	Files
Edited-state export	Implemented	supervised_export.py, POST /api/jobs/{job_id}/export
Suppressed-hit exclusion	Implemented	Export ignores hits with suppressed=true.
Favorite/pinned representative export	Implemented	Export honors representative_hit_id / favorite hits before quality scoring.
Force-onset from existing stem audio	Implemented	POST /api/jobs/{job_id}/hits/force-onset
Forced-hit review WAV writing	Implemented	review/hits/hit_NNNNN_<label>_forced.wav
Suppressed-hit restore	Implemented	POST /api/jobs/{job_id}/hits/{hit_id}/restore
Exact suggestion diff preview	Implemented	suggestion.diff in state responses and UI diff button.
UI add-onset mode	Implemented	Toggle in supervision header; waveform clicks add forced hits.
UI edited export downloads	Implemented	Edited ZIP/MIDI/target-reconstruction/full-context-reproduction links render after export.

Export behavior

The supervised export builds clusters from current semantic state:

1. Skip suppressed hits.
2. Load hit audio from each hit's file path under the job output directory.
3. Sanitize cluster labels for output filenames.
4. Preserve forced hits and moved/pulled hits through current cluster membership.
5. Pick representatives from semantic representative_hit_id or favorite hits first.
6. Quality-score representatives only for unpinned clusters.
7. Write edited samples, MIDI, target reconstruction WAV, full-context reproduction WAV, ZIP, and supervised/manifest.json.
8. Append a supervised.exported event and latest_export entry to supervision_state.json.

The original manifest.json, original sample-pack.zip, and original samples/*.wav are not modified.

Force-onset behavior

POST /api/jobs/{job_id}/hits/force-onset requires a completed run with stem.wav.

Body:

{
  "onset_sec": 0.123,
  "duration_ms": 160,
  "target_cluster_id": "cluster:0",
  "label": "snare"
}

Rules:

• onset_sec is required.
• duration_ms is optional. If omitted, the system slices until the next active onset or a bounded default duration.
• target_cluster_id is optional. If omitted, a new user cluster is created.
• label is optional. If omitted, the current rule-based classifier labels the slice.
• A short fade-out is applied to avoid clicks.
• The forced hit is marked source="forced", explicit=true, and review_status="accepted".

Suggestion diffs

Open suggestions now include exact previews:

{
  "type": "move-hits",
  "affected_hit_count": 3,
  "hits": [
    {
      "hit_id": "hit:00007",
      "from_cluster_label": "bright_1",
      "to_cluster_label": "snare_user_1",
      "before_suppressed": false,
      "after_suppressed": false
    }
  ],
  "clusters_before": {},
  "clusters_after": {}
}

The frontend exposes this through the Diff button in the suggestion inbox.

Validation

Covered by:

python3 scripts/test_supervised_export_and_force_onset.py

This test verifies:

• suppression and restore,
• forced-hit creation and download,
• suggestion diff presence when suggestions exist,
• supervised export creation,
• artifact download URLs for edited ZIP/MIDI/reconstruction,
• latest export state metadata.

Reproduced-audio update

Supervised export now mirrors the batch export audio model:

• supervised/target_reconstruction.wav is the edited sample-triggered target layer.
• supervised/reconstruction.wav is the edited full-context reproduced mix.
• The full-context mix reuses the original run’s context_bed.wav, then adds the edited target reconstruction.

This keeps the original batch artifacts immutable while making edited exports useful for listening inside the whole track context.