feat: add full-context reproduction and clearer controls

README.md

@@ -12,7 +12,7 @@ pinned: false
 
 A custom FastAPI + browser workstation for extracting, reviewing, and now semantically supervising reusable drum samples from an audio file.
 
-The pipeline can isolate a stem with Demucs, detect onsets, classify hits, cluster similar transients, choose representative samples, optionally synthesize alternate samples, and export WAVs, MIDI, reconstruction audio, manifests, and a complete ZIP sample pack. The interactive layer stores user corrections as replayable semantic state beside each run manifest.
+The pipeline can isolate a stem with Demucs, detect onsets, classify hits, cluster similar transients, choose representative samples, optionally synthesize alternate samples, and export WAVs, MIDI, target-stem reconstruction, full-context reproduced audio, manifests, and a complete ZIP sample pack. The interactive layer stores user corrections as replayable semantic state beside each run manifest.
 
 ## Current status
 
@@ -73,6 +73,7 @@ See:
 - `docs/REMAINING_WORK.md`
 - `docs/SUPERVISED_EXPORT_AND_FORCE_ONSET.md`
 - `docs/FIXED_WORKSTATION_UI.md`
+- `docs/REPRODUCED_AUDIO_AND_PARAMETERS.md`
 
 ## Run locally
 
@@ -155,7 +156,7 @@ curl http://127.0.0.1:7860/api/jobs
 | `sample_extractor.py` | Core DSP/sample extraction implementation |
 | `supervised_state.py` | Persistent semantic state, confidence, constraints, events, suggestions, force-onset, restore, undo |
 | `supervised_export.py` | Renders edited semantic state into supervised WAV/MIDI/reconstruction/ZIP artifacts |
-| `web/` | Custom no-build browser frontend with fixed non-scrolling workstation layout, explicit upload/whole-page drag-drop, sidebars, bottom dock, sample-card grid, hidden-audio audition, add-onset mode, and edited export |
+| `web/` | Custom no-build browser frontend with fixed non-scrolling workstation layout, explicit upload/whole-page drag-drop, source/stem/reproduced preview transport, common/advanced parameter separation, sidebars, bottom dock, sample-card grid, hidden-audio audition, add-onset mode, and edited export |
 | `scripts/benchmark_subprocesses.py` | Synthetic benchmark runner for stage timings |
 | `scripts/test_interactive_supervision.py` | Smoke test for supervised state endpoints |
 | `scripts/test_supervised_export_and_force_onset.py` | Smoke test for force-onset, restore, suggestion diffs, and edited exports |
@@ -180,6 +181,7 @@ Each run is stored under `.runs/<job-id>/output/`:
 - `supervised/samples/*.wav` after edited export
 - `supervised/reconstruction.mid` after edited export
 - `supervised/reconstruction.wav` after edited export
+- `source.wav`, `context_bed.wav`, and `target_reconstruction.wav` for source/stem/reproduced A/B previews
 
 Generated runtime directories are ignored by git:
 

app.py

@@ -48,7 +48,7 @@ WEB_DIR = ROOT / "web"
 RUNS_DIR = ROOT / ".runs"
 RUNS_DIR.mkdir(exist_ok=True)
 
-app = FastAPI(title="Drum Sample Extractor", version="12.0.0")
+app = FastAPI(title="Drum Sample Extractor", version="13.0.0")
 app.add_middleware(
     CORSMiddleware,
     allow_origins=["*"],

docs/API.md

@@ -134,7 +134,7 @@ Completed jobs contain:
 | `samples` | Representative sample rows with score, duration, first onset, and playback/download URL. |
 | `hits` | Per-detected-hit review rows with onset, duration, label, cluster, representative flag, and playback/download URL. |
 | `overview` | Decimated envelope and clickable onset markers for waveform display. |
-| `files` | Relative artifact paths. |
+| `files` | Relative artifact paths. Includes `source`, `stem`, `context_bed`, `target_reconstruction`, `reconstruction`, `midi`, and `archive` when available. |
 | `file_urls` | Direct API URLs for top-level artifacts. |
 
 ## `GET /api/jobs/{job_id}/events`
@@ -154,6 +154,18 @@ data: {"id":"58ca0db4ac74","status":"running","stages":[...]}
 
 The stream closes after `complete` or `error`. Completed historical jobs emit one final `job` event and close.
 
+## Top-level artifact meanings
+
+| Key | Path | Meaning |
+|---|---|---|
+| `source` | `source.wav` | Normalized source mix used for source preview. |
+| `stem` | `stem.wav` | Target stem being sampled. |
+| `context_bed` | `context_bed.wav` | Non-target stems/context bed; silent for `stem=all`. |
+| `target_reconstruction` | `target_reconstruction.wav` | Sample-triggered reconstruction of only the target stem. |
+| `reconstruction` | `reconstruction.wav` | Full-context reproduced mix: context bed plus target reconstruction. |
+| `midi` | `reconstruction.mid` | MIDI trigger reconstruction. |
+| `archive` | `sample-pack.zip` | Complete sample pack and reproduction artifacts. |
+
 ## `GET /api/jobs/{job_id}/files/{relative_path}`
 
 Downloads an artifact from a completed job.
@@ -163,6 +175,8 @@ Examples:
 ```bash
 curl -O http://127.0.0.1:7860/api/jobs/58ca0db4ac74/files/sample-pack.zip
 curl -O http://127.0.0.1:7860/api/jobs/58ca0db4ac74/files/reconstruction.mid
+curl -O http://127.0.0.1:7860/api/jobs/58ca0db4ac74/files/reconstruction.wav
+curl -O http://127.0.0.1:7860/api/jobs/58ca0db4ac74/files/target_reconstruction.wav
 curl -O http://127.0.0.1:7860/api/jobs/58ca0db4ac74/files/samples/hihat_open_0.wav
 curl -O http://127.0.0.1:7860/api/jobs/58ca0db4ac74/files/review/hits/hit_00000_kick.wav
 ```
@@ -313,6 +327,7 @@ Response shape:
     "files": {
       "archive": "supervised/sample-pack.zip",
       "midi": "supervised/reconstruction.mid",
+      "target_reconstruction": "supervised/target_reconstruction.wav",
       "reconstruction": "supervised/reconstruction.wav"
     },
     "file_urls": {}

docs/FEATURES.md

@@ -4,7 +4,7 @@ Last updated: 2026-05-12
 
 ## Product goal
 
-Turn an input audio file into a practical drum sample pack: detected hits, grouped sample classes, representative WAVs, optional synthesized alternates, MIDI reconstruction, rendered reconstruction audio, and an inspectable manifest.
+Turn an input audio file into a practical drum sample pack: detected hits, grouped sample classes, representative WAVs, optional synthesized alternates, MIDI reconstruction, target-stem reconstruction, full-context reproduced audio, and an inspectable manifest.
 
 ## Implemented features
 
@@ -14,8 +14,8 @@ Turn an input audio file into a practical drum sample pack: detected hits, group
 | UI | Explicit upload button | Implemented | Top bar contains a visible `Upload audio` control. |
 | UI | Whole-app drag/drop audio upload | Implemented | Dropping files anywhere on the app selects the file and shows a drop overlay during drag. |
 | UI | Fixed non-scrolling workstation layout | Implemented | Body is viewport-locked; tools live in left/right sidebars and a bottom dock; long content scrolls inside panels only. |
-| UI | Minimal custom transport | Implemented | One image-aligned play/time/progress row drives source preview before extraction and stem preview after extraction. |
-| UI | Pipeline controls | Implemented | Stem/model/onset/clustering/MIDI/synthesis/cache controls. |
+| UI | Minimal custom transport | Implemented | One play/time/progress row can audition Source, Stem, or Reproduced previews; completed runs default to Reproduced. |
+| UI | Common vs advanced parameters | Implemented | Common controls show stem, sensitivity, group count, and two presets; advanced model/DSP/export controls are grouped by pipeline stage. |
 | UI | Streaming progress | Implemented | Uses `EventSource` over `GET /api/jobs/{id}/events`, with polling fallback. |
 | UI | Waveform/onset overview | Implemented | Canvas envelope plus clickable onset markers from `manifest.json`. |
 | UI | Result downloads | Implemented | ZIP, MIDI, stem WAV, reconstruction WAV, individual sample WAVs, and per-hit review WAVs. |
@@ -37,9 +37,10 @@ Turn an input audio file into a practical drum sample pack: detected hits, group
 | Pipeline | Representative selection | Implemented | Quality score picks best hit per cluster. |
 | Pipeline | Optional synthesis | Implemented | Weighted aligned average for multi-hit clusters. |
 | Pipeline | MIDI export | Implemented | Quantized or unquantized reconstruction MIDI. |
-| Pipeline | Reconstruction render | Implemented | Renders MIDI-like reconstruction using selected samples. |
+| Pipeline | Target reconstruction render | Implemented | Renders the selected sample representatives from MIDI/onset timing and matches RMS to the target stem. |
+| Pipeline | Full-context reproduced mix | Implemented | Writes `reconstruction.wav` as non-target context bed plus target reconstruction, so separated-stem runs incorporate all other stems. |
 | Pipeline | Per-hit review export | Implemented | Writes every accepted detected hit to `review/hits/*.wav` and records rows in the manifest. |
-| Pipeline | Sample pack ZIP | Implemented | Includes WAVs, index JSON, MIDI, rendered reconstruction. |
+| Pipeline | Sample pack ZIP | Implemented | Includes WAVs, index JSON, MIDI, full-context reproduced mix, and target-stem reconstruction. |
 | Supervision | Edited artifact re-export | Implemented | `supervised_export.py` writes edited samples, MIDI, reconstruction, ZIP, and `supervised/manifest.json`. |
 | Supervision | Force-onset from waveform | Implemented | Adds user-forced hit slices from cached `stem.wav`; UI add-onset mode posts to `/hits/force-onset`. |
 | Supervision | Suppressed-hit restore | Implemented | Restore endpoint and UI button reverse suppression without undoing unrelated edits. |

docs/FIXED_WORKSTATION_UI.md

@@ -12,8 +12,8 @@ The web app should behave like a compact workstation rather than a long document
 |---|---|---|
 | Top bar | App title, explicit `Upload audio` button, selected-file metadata, backend status, primary `Extract Samples` action | Fixed height; no scroll |
 | Left sidebar | Source/drop guidance, selected-hit/sample context, pipeline stages/logs, run history | Sidebar-internal scroll only |
-| Center workspace | Large waveform/transport and representative sample cards | Sample grid scrolls internally when needed |
-| Right sidebar | Core extraction controls, exports, advanced model/DSP settings | Sidebar-internal scroll only |
+| Center workspace | Large waveform, Source/Stem/Reproduced transport, and representative sample cards | Sample grid scrolls internally when needed |
+| Right sidebar | Common extraction controls, exports, and advanced parameters grouped by stage | Sidebar-internal scroll only |
 | Bottom bar | Interactive review/edit tools and raw tables | Panel-internal scroll only |
 
 The document itself is locked with `overflow: hidden`; long content is constrained to the relevant tool panel.
@@ -45,3 +45,11 @@ Static checks added/performed for this pass:
 - Duplicate id check for `web/index.html`
 - Python compile check for active Python files
 - FastAPI extraction smoke test
+
+
+## Pass 9 additions
+
+- The center transport now exposes explicit `Source`, `Stem`, and `Reproduced` preview modes.
+- The right sidebar now separates the normal workflow from advanced tuning.
+- Common controls are limited to stem choice, hit sensitivity, sample group count, and two presets.
+- Advanced parameters are grouped into stem separation, hit detection, grouping, export/cache sections.

docs/PROGRESS.md

@@ -259,3 +259,27 @@ Completed in this pass:
 Outcome:
 
 The UI no longer behaves like a scrollable webpage. It now behaves like a compact desktop-style sample extraction workstation with simple expandable tool panels around a central waveform/sample workspace.
+
+## Pass 9: full-context reproduced audio and clearer parameters
+
+Completed in this pass:
+
+1. Added explicit source/context/reconstruction layers to the pipeline export:
+   - `source.wav`
+   - `stem.wav`
+   - `context_bed.wav`
+   - `target_reconstruction.wav`
+   - `reconstruction.wav`
+2. Changed `reconstruction.wav` to a full-context reproduced mix: non-target context bed plus sample-triggered target reconstruction.
+3. Kept `target_reconstruction.wav` as the isolated sample-only target layer for debugging and focused listening.
+4. Matched the target reconstruction RMS to the target stem before mixing it back into context.
+5. Updated `sample-pack.zip` to include both the full-context reproduced mix and target-stem reconstruction.
+6. Updated supervised edited export so edited packs follow the same audio-layer model under `supervised/`.
+7. Added Source / Stem / Reproduced preview modes to the single transport row; completed jobs default to Reproduced.
+8. Reworked the right sidebar into Common controls vs Advanced parameters.
+9. Grouped advanced parameters by pipeline stage: stem separation, hit detection, grouping, export/cache.
+10. Added `docs/REPRODUCED_AUDIO_AND_PARAMETERS.md`.
+
+Outcome:
+
+The app is easier to understand for normal use: the main right-side controls are now only the few controls users are likely to touch repeatedly, while lower-level DSP/model controls stay available but grouped by stage. Reproduced audio is now useful for musical judgment because separated-stem runs are previewed inside the rest of the mix rather than as an isolated sample-triggered stem only.

docs/REMAINING_WORK.md

@@ -8,12 +8,15 @@ The project is now a usable extraction workstation, not a complete interactive s
 
 ## Highest-priority remaining gaps
 
+Completed since the previous snapshot: reproduced audio now incorporates non-target context stems, and common/advanced parameters are separated in the right sidebar.
+
 1. **Cluster editing**: allow merge, split, relabel, and manual reassignment of groups from the `Review & edit` workbench.
 2. **Waveform editing depth**: add onset drag/shift, hit trim boundaries, and rerun-from-edited-onsets without redoing Demucs.
 3. **Run comparison**: compare two manifests side-by-side for parameter tuning.
 4. **Lower-level progress**: expose internal Demucs/clustering progress where libraries make that possible.
 5. **Frontend engineering hardening**: migrate the frontend to TypeScript after the UX stabilizes and add browser-level tests.
 6. **Benchmark panel**: add an in-app benchmark view that can run synthetic fixtures and compare parameter profiles.
+7. **Reproduction diagnostics**: add source-vs-reproduced A/B error visualization and region ranking.
 
 ## Known constraints
 

docs/REPRODUCED_AUDIO_AND_PARAMETERS.md

@@ -0,0 +1,82 @@
+# Reproduced audio and parameter hierarchy
+
+Last updated: 2026-05-12
+
+## Goal
+
+The preview called “reproduced audio” should be understandable and useful for judging whether the extracted samples reproduce the source. It should not only play the extracted target stem in isolation when the user extracted a separated stem.
+
+## Implemented audio model
+
+The pipeline now writes three different preview layers per run:
+
+| File | Meaning | UI label |
+|---|---|---|
+| `source.wav` | The normalized source mix used as preview context. | Source mix WAV |
+| `stem.wav` | The target audio being sampled, for example the separated drums stem. | Target stem WAV |
+| `context_bed.wav` | The non-target context bed: source mix minus target stem. For `stem=all`, this is silence. | Non-target stems WAV |
+| `target_reconstruction.wav` | The selected sample representatives rendered from MIDI/onset timing, matched to the target stem’s RMS. | Target reconstruction WAV |
+| `reconstruction.wav` | Full-context reproduced mix: `context_bed.wav + target_reconstruction.wav`, soft-limited. | Reproduced mix WAV |
+
+For separated-stem runs, `reconstruction.wav` therefore incorporates the other stems instead of only replaying the drum/sample layer. This makes A/B listening more useful: the user hears the extracted sample layer inside the rest of the track.
+
+## Archive behavior
+
+`sample-pack.zip` now includes:
+
+- `rendered_reproduction_full_mix.wav` — the full-context reproduced mix.
+- `rendered_reconstruction_target_stem.wav` — the sample-only target reconstruction.
+- `rendered_reconstruction.wav` — backwards-compatible alias for the full-context reproduced mix.
+- `reconstruction.mid` — the MIDI trigger reconstruction.
+- `samples/*.wav` — representative samples.
+- `index.json` — sample metadata and reproduction file references.
+
+## Supervised edited export behavior
+
+Edited exports under `supervised/` follow the same model:
+
+- `supervised/target_reconstruction.wav`
+- `supervised/reconstruction.wav`
+- `supervised/sample-pack.zip`
+
+The edited full-context reproduction reuses `context_bed.wav`, so semantic edits affect the sampled target layer while the non-target stems remain available for context.
+
+## UI parameter hierarchy
+
+The right sidebar now separates controls by frequency of use.
+
+### Common controls
+
+These are visible by default:
+
+1. **Stem to sample** — choose the target source, usually `drums` or `all`.
+2. **Hit sensitivity** — tune onset density.
+3. **Sample groups** — choose the approximate maximum number of sample cards.
+4. **Fast preview** preset — full mix + online clustering + no Demucs shifts.
+5. **Best quality** preset — separated drums + batch clustering + conservative thresholds.
+
+### Advanced parameters
+
+Advanced controls are hidden in a collapsed panel and grouped by stage:
+
+- Stem separation: model, shifts, overlap.
+- Hit detection: onset mode, energy floor, gap, padding, min/max duration.
+- Grouping: clustering mode, minimum groups, transient/mel/linkage thresholds.
+- Export and cache: MIDI grid, synthesis, quantization, disk cache, cache clear.
+
+## Preview transport
+
+The single transport row now has explicit preview modes:
+
+- **Source** — original source mix.
+- **Stem** — target stem being sampled.
+- **Reproduced** — full-context reproduced mix after extraction.
+
+After a successful extraction, the transport switches to **Reproduced** by default because that is the most relevant quality check.
+
+## Remaining audio-quality work
+
+- Add a true A/B difference view between `source.wav` and `reconstruction.wav`.
+- Compute per-region reconstruction error and expose the worst mismatch regions.
+- Avoid residual subtraction artifacts by optionally caching explicit Demucs non-target stem sums when the full source separation bundle is available.
+- Add loudness matching using LUFS instead of RMS for longer previews.

docs/SUPERVISED_EXPORT_AND_FORCE_ONSET.md

@@ -11,6 +11,7 @@ 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
 ```
@@ -27,7 +28,7 @@ manifest.json + review/hits/*.wav + supervision_state.json
 | 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/reconstruction links render after export. |
+| UI edited export downloads | Implemented | Edited ZIP/MIDI/target-reconstruction/full-context-reproduction links render after export. |
 
 ## Export behavior
 
@@ -39,7 +40,7 @@ The supervised export builds clusters from current semantic state:
 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, reconstruction WAV, ZIP, and `supervised/manifest.json`.
+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.
@@ -108,3 +109,14 @@ This test verifies:
 - 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.

docs/TASKS.md

@@ -72,7 +72,7 @@ Last updated: 2026-05-12
 | Add pull hit into new cluster | Done | `POST /api/jobs/{job_id}/hits/{hit_id}/pull-out`. |
 | Add cluster lock/unlock | Done | `POST /api/jobs/{job_id}/clusters/{cluster_id}/lock`. |
 | Add suppress hit as bleed/noise | Done | `POST /api/jobs/{job_id}/hits/{hit_id}/suppress`. |
-| Add accept/favorite hit action | Done/Partial | `POST /api/jobs/{job_id}/hits/{hit_id}/review`; artifact re-export still open. |
+| Add accept/favorite hit action | Done | `POST /api/jobs/{job_id}/hits/{hit_id}/review`; supervised re-export honors pinned/favorite representatives. |
 | Add suggestion inbox | Done/Partial | UI/API supports accept/reject; exact diff preview still open. |
 | Add cluster explanation drawer | Done | `GET /api/jobs/{job_id}/explain/cluster/{cluster_id}` plus UI drawer. |
 | Add semantic undo | Done | `POST /api/jobs/{job_id}/undo`. |
@@ -106,3 +106,24 @@ Last updated: 2026-05-12
 | Add explicit upload button | Done | Top bar now has a visible `Upload audio` control. |
 | Make whole-app file dropping work | Done | Window-level drag/drop handlers select dropped files and prevent browser navigation. |
 | Add drag overlay | Done | `globalDropOverlay` appears while dragging files over the app. |
+
+## Pass 9 tasks: reproduced audio and parameter hierarchy
+
+| Task | Status | Notes |
+|---|---:|---|
+| Export normalized source mix | Done | `source.wav` written per run. |
+| Export non-target context bed | Done | `context_bed.wav` is source minus target stem; silent for `stem=all`. |
+| Keep isolated target reconstruction | Done | `target_reconstruction.wav` written per run and per supervised export. |
+| Make reproduced audio incorporate context | Done | `reconstruction.wav` is context bed plus target reconstruction. |
+| Add full-context reproduction to ZIP | Done | `rendered_reproduction_full_mix.wav` plus compatibility alias. |
+| Add target-stem reconstruction to ZIP | Done | `rendered_reconstruction_target_stem.wav`. |
+| Update supervised export audio model | Done | Edited export writes full-context and target-only previews. |
+| Add Source/Stem/Reproduced transport modes | Done | Transport buttons added in `web/index.html` and wired in `web/app.js`. |
+| Separate common controls from advanced parameters | Done | Common controls: stem, sensitivity, sample groups, presets. |
+| Group advanced parameters by pipeline stage | Done | Stem separation, hit detection, grouping, export/cache. |
+
+Remaining follow-up tasks:
+
+- [ ] Add source-vs-reproduced waveform/error comparison.
+- [ ] Add LUFS loudness matching for long previews.
+- [ ] Optionally cache explicit Demucs non-target stem sums instead of residual subtraction.

docs/UI_REPLACEMENT.md

@@ -33,8 +33,8 @@ The UI was first restyled to the supplied minimal reference direction:
 This pass closed the visual fidelity gaps from the previous approximation:
 
 - removed the visible waveform header so the canvas is quiet like the reference image;
-- replaced separate native stem/reconstruction audio controls with one minimal transport row: play button, time, and progress line;
-- moved fast-mode buttons into `Advanced` so the right card now exposes only `Stem`, `Sensitivity`, `Cluster Count`, and `Export Samples`;
+- replaced separate native stem/reconstruction audio controls with one minimal transport row: play button, time, progress line, and Source/Stem/Reproduced preview modes;
+- renamed the right card to `Common controls` and limited it to stem, hit sensitivity, sample groups, plus fast-preview/best-quality presets;
 - collapsed pipeline/history/supervision/tables into one `Review & edit` workbench below the sample cards;
 - hid selected-hit/sample audio elements from the default layout while preserving click-to-audition behavior;
 - tightened card spacing, border radii, font scale, waveform height, and sample-card proportions to better match the supplied image.
@@ -61,8 +61,8 @@ This pass responds to the no-scroll workstation requirement and the missing-uplo
 |---|---|
 | Top bar | App identity, explicit upload button, selected-file metadata, backend status, and one primary purple `Extract Samples` action. |
 | Left sidebar | Source/drop guidance, selected-hit/sample context, pipeline logs, and run history. |
-| Center workspace | Quiet waveform canvas, one custom transport row, and representative sample cards. |
-| Right sidebar | Stem, sensitivity, cluster count, exports, and collapsed advanced DSP/model controls. |
+| Center workspace | Quiet waveform canvas, Source/Stem/Reproduced transport row, and representative sample cards. |
+| Right sidebar | Common controls, exports, and collapsed advanced parameters grouped by stem separation, hit detection, grouping, export, and cache. |
 | Bottom dock | Review/edit semantic supervision tools and raw tables in expandable panels. |
 
 ## Frontend implementation
@@ -89,8 +89,11 @@ The frontend creates a job with `POST /api/jobs`, then polls `GET /api/jobs/{id}
 
 - sample pack ZIP
 - MIDI reconstruction
-- stem WAV
-- reconstruction WAV
+- source mix WAV
+- target stem WAV
+- non-target context bed WAV
+- target reconstruction WAV
+- full-context reproduced mix WAV
 - individual sample WAVs
 
 The run history panel calls `GET /api/jobs` and can reload any completed manifest still present under `.runs/`.
@@ -128,3 +131,17 @@ The current UI now includes:
 - Server-sent-events job progress via `GET /api/jobs/{job_id}/events`, with polling fallback.
 
 This still stops short of destructive editing. The next UI layer should store edits as manifest overlays, then call a re-export endpoint that reuses cached hit audio instead of rerunning Demucs/onset detection.
+
+
+## Pass 9 reproduced audio and parameter hierarchy
+
+This pass made the audio preview and control model more explicit:
+
+- `reconstruction.wav` is now a full-context reproduced mix, not just the sample-triggered target layer.
+- `target_reconstruction.wav` preserves the sample-only target reconstruction for focused inspection.
+- `source.wav`, `stem.wav`, and `context_bed.wav` are exported as explicit layers.
+- The transport has Source, Stem, and Reproduced preview buttons and switches to Reproduced after extraction.
+- The right sidebar now separates Common controls from Advanced parameters.
+- Advanced parameters are grouped by pipeline stage: stem separation, hit detection, grouping, export/cache.
+
+See `docs/REPRODUCED_AUDIO_AND_PARAMETERS.md`.

docs/benchmark-online-preview.json

@@ -8,66 +8,66 @@
       "run_index": 0,
       "clustering_mode": "online_preview",
       "audio_duration_sec": 4.75,
-      "total_duration_sec": 1.88646,
-      "realtime_factor": 0.397149,
-      "hit_count": 13,
-      "cluster_count": 10,
+      "total_duration_sec": 2.619948,
+      "realtime_factor": 0.551568,
+      "hit_count": 14,
+      "cluster_count": 11,
       "stages": [
         {
           "key": "stem",
           "label": "Stem extraction / source load",
-          "duration_sec": 0.011189419999936945,
+          "duration_sec": 0.025709866000397597,
           "status": "done",
-          "detail": "loaded full mix \u00b7 cached"
+          "detail": "loaded full mix \u00b7 cached \u00b7 reproduction uses full mix"
         },
         {
           "key": "bpm",
           "label": "Tempo detection",
-          "duration_sec": 0.09853705299974536,
+          "duration_sec": 0.17244149500038475,
           "status": "done",
           "detail": "120.2 BPM"
         },
         {
           "key": "onsets",
           "label": "Onset detection + slicing",
-          "duration_sec": 1.3858792310002173,
+          "duration_sec": 2.01123834900136,
           "status": "done",
-          "detail": "13 hits"
+          "detail": "14 hits"
         },
         {
           "key": "classification",
           "label": "Spectral rule classification",
-          "duration_sec": 0.014456886000061786,
+          "duration_sec": 0.015600401000483544,
           "status": "done",
-          "detail": "bright:5, hihat_open:7, kick:1"
+          "detail": "bright:4, hihat_closed:1, hihat_open:7, kick:1, mid:1"
         },
         {
           "key": "clustering",
           "label": "Mel fingerprint + transient NCC clustering",
-          "duration_sec": 0.016802669999833597,
+          "duration_sec": 0.08166359800088685,
           "status": "done",
-          "detail": "10 clusters \u00b7 online preview"
+          "detail": "11 clusters \u00b7 online preview"
         },
         {
           "key": "selection",
           "label": "Best representative scoring",
-          "duration_sec": 0.07535981499995614,
+          "duration_sec": 0.02976710500115587,
           "status": "done",
           "detail": "quality-scored representatives"
         },
         {
           "key": "synthesis",
           "label": "Optional sample synthesis",
-          "duration_sec": 0.00036268399981054245,
+          "duration_sec": 0.0003646059994935058,
           "status": "done",
           "detail": "2 synthesized alternates"
         },
         {
           "key": "export",
-          "label": "MIDI, reconstruction, WAV, ZIP export",
-          "duration_sec": 0.28339249200007544,
+          "label": "MIDI, reproduced mix, WAV, ZIP export",
+          "duration_sec": 0.28268050299993774,
           "status": "done",
-          "detail": "10 samples + 13 review hits + MIDI + ZIP"
+          "detail": "11 samples + 14 review hits + MIDI + full-context reproduction + ZIP"
         }
       ]
     },
@@ -78,66 +78,66 @@
       "run_index": 0,
       "clustering_mode": "online_preview",
       "audio_duration_sec": 4.874989,
-      "total_duration_sec": 2.914241,
-      "realtime_factor": 0.597794,
-      "hit_count": 28,
+      "total_duration_sec": 3.096466,
+      "realtime_factor": 0.635174,
+      "hit_count": 29,
       "cluster_count": 12,
       "stages": [
         {
           "key": "stem",
           "label": "Stem extraction / source load",
-          "duration_sec": 0.00999813099997482,
+          "duration_sec": 0.02813513600085571,
           "status": "done",
-          "detail": "loaded full mix \u00b7 cached"
+          "detail": "loaded full mix \u00b7 cached \u00b7 reproduction uses full mix"
         },
         {
           "key": "bpm",
           "label": "Tempo detection",
-          "duration_sec": 0.10688103099982982,
+          "duration_sec": 0.0898798819998774,
           "status": "done",
           "detail": "161.5 BPM"
         },
         {
           "key": "onsets",
           "label": "Onset detection + slicing",
-          "duration_sec": 2.1018096600000717,
+          "duration_sec": 2.39328171499983,
           "status": "done",
-          "detail": "28 hits"
+          "detail": "29 hits"
         },
         {
           "key": "classification",
           "label": "Spectral rule classification",
-          "duration_sec": 0.09064649800029656,
+          "duration_sec": 0.01869549100047152,
           "status": "done",
-          "detail": "bright:12, cymbal:1, hihat_closed:9, hihat_open:3, mid:3"
+          "detail": "bright:12, cymbal:1, hihat_closed:9, hihat_open:3, mid:4"
         },
         {
           "key": "clustering",
           "label": "Mel fingerprint + transient NCC clustering",
-          "duration_sec": 0.049414074000196706,
+          "duration_sec": 0.03839712700028031,
           "status": "done",
           "detail": "12 clusters \u00b7 online preview"
         },
         {
           "key": "selection",
           "label": "Best representative scoring",
-          "duration_sec": 0.23301379500026087,
+          "duration_sec": 0.2286190050017467,
           "status": "done",
           "detail": "quality-scored representatives"
         },
         {
           "key": "synthesis",
           "label": "Optional sample synthesis",
-          "duration_sec": 0.0012726520003525366,
+          "duration_sec": 0.0011234290013817372,
           "status": "done",
           "detail": "5 synthesized alternates"
         },
         {
           "key": "export",
-          "label": "MIDI, reconstruction, WAV, ZIP export",
-          "duration_sec": 0.32063418000007005,
+          "label": "MIDI, reproduced mix, WAV, ZIP export",
+          "duration_sec": 0.29779865499949665,
           "status": "done",
-          "detail": "12 samples + 28 review hits + MIDI + ZIP"
+          "detail": "12 samples + 29 review hits + MIDI + full-context reproduction + ZIP"
         }
       ]
     },
@@ -148,66 +148,66 @@
       "run_index": 0,
       "clustering_mode": "online_preview",
       "audio_duration_sec": 4.874989,
-      "total_duration_sec": 2.480844,
-      "realtime_factor": 0.508892,
+      "total_duration_sec": 2.58942,
+      "realtime_factor": 0.531164,
       "hit_count": 29,
       "cluster_count": 12,
       "stages": [
         {
           "key": "stem",
           "label": "Stem extraction / source load",
-          "duration_sec": 0.010305768999842257,
+          "duration_sec": 0.0707627699994191,
           "status": "done",
-          "detail": "loaded full mix \u00b7 cached"
+          "detail": "loaded full mix \u00b7 cached \u00b7 reproduction uses full mix"
         },
         {
           "key": "bpm",
           "label": "Tempo detection",
-          "duration_sec": 0.1724793140001566,
+          "duration_sec": 0.1129706889987574,
           "status": "done",
           "detail": "120.2 BPM"
         },
         {
           "key": "onsets",
           "label": "Onset detection + slicing",
-          "duration_sec": 1.8014776340000935,
+          "duration_sec": 1.902288953999232,
           "status": "done",
           "detail": "29 hits"
         },
         {
           "key": "classification",
           "label": "Spectral rule classification",
-          "duration_sec": 0.017559420999987196,
+          "duration_sec": 0.018896421999670565,
           "status": "done",
-          "detail": "bright:5, cymbal:1, hihat_closed:20, hihat_open:3"
+          "detail": "bright:4, hihat_closed:23, hihat_open:2"
         },
         {
           "key": "clustering",
           "label": "Mel fingerprint + transient NCC clustering",
-          "duration_sec": 0.043723993000185146,
+          "duration_sec": 0.10450396400119644,
           "status": "done",
           "detail": "12 clusters \u00b7 online preview"
         },
         {
           "key": "selection",
           "label": "Best representative scoring",
-          "duration_sec": 0.16425892699999167,
+          "duration_sec": 0.11157589499998721,
           "status": "done",
           "detail": "quality-scored representatives"
         },
         {
           "key": "synthesis",
           "label": "Optional sample synthesis",
-          "duration_sec": 0.0012976000002709043,
+          "duration_sec": 0.0010697859997890191,
           "status": "done",
-          "detail": "8 synthesized alternates"
+          "detail": "6 synthesized alternates"
         },
         {
           "key": "export",
-          "label": "MIDI, reconstruction, WAV, ZIP export",
-          "duration_sec": 0.2692134119997718,
+          "label": "MIDI, reproduced mix, WAV, ZIP export",
+          "duration_sec": 0.2668189519990847,
           "status": "done",
-          "detail": "12 samples + 29 review hits + MIDI + ZIP"
+          "detail": "12 samples + 29 review hits + MIDI + full-context reproduction + ZIP"
         }
       ]
     }
@@ -215,59 +215,59 @@
   "summary": [
     {
       "stage": "stem",
-      "mean_sec": 0.010498,
-      "median_sec": 0.010306,
-      "min_sec": 0.009998,
-      "max_sec": 0.011189
+      "mean_sec": 0.041536,
+      "median_sec": 0.028135,
+      "min_sec": 0.02571,
+      "max_sec": 0.070763
     },
     {
       "stage": "bpm",
-      "mean_sec": 0.125966,
-      "median_sec": 0.106881,
-      "min_sec": 0.098537,
-      "max_sec": 0.172479
+      "mean_sec": 0.125097,
+      "median_sec": 0.112971,
+      "min_sec": 0.08988,
+      "max_sec": 0.172441
     },
     {
       "stage": "onsets",
-      "mean_sec": 1.763056,
-      "median_sec": 1.801478,
-      "min_sec": 1.385879,
-      "max_sec": 2.10181
+      "mean_sec": 2.10227,
+      "median_sec": 2.011238,
+      "min_sec": 1.902289,
+      "max_sec": 2.393282
     },
     {
       "stage": "classification",
-      "mean_sec": 0.040888,
-      "median_sec": 0.017559,
-      "min_sec": 0.014457,
-      "max_sec": 0.090646
+      "mean_sec": 0.017731,
+      "median_sec": 0.018695,
+      "min_sec": 0.0156,
+      "max_sec": 0.018896
     },
     {
       "stage": "clustering",
-      "mean_sec": 0.036647,
-      "median_sec": 0.043724,
-      "min_sec": 0.016803,
-      "max_sec": 0.049414
+      "mean_sec": 0.074855,
+      "median_sec": 0.081664,
+      "min_sec": 0.038397,
+      "max_sec": 0.104504
     },
     {
       "stage": "selection",
-      "mean_sec": 0.157544,
-      "median_sec": 0.164259,
-      "min_sec": 0.07536,
-      "max_sec": 0.233014
+      "mean_sec": 0.123321,
+      "median_sec": 0.111576,
+      "min_sec": 0.029767,
+      "max_sec": 0.228619
     },
     {
       "stage": "synthesis",
-      "mean_sec": 0.000978,
-      "median_sec": 0.001273,
-      "min_sec": 0.000363,
-      "max_sec": 0.001298
+      "mean_sec": 0.000853,
+      "median_sec": 0.00107,
+      "min_sec": 0.000365,
+      "max_sec": 0.001123
     },
     {
       "stage": "export",
-      "mean_sec": 0.29108,
-      "median_sec": 0.283392,
-      "min_sec": 0.269213,
-      "max_sec": 0.320634
+      "mean_sec": 0.282433,
+      "median_sec": 0.282681,
+      "min_sec": 0.266819,
+      "max_sec": 0.297799
     }
   ]
 }

docs/benchmark-subprocesses.json

@@ -8,66 +8,66 @@
       "run_index": 0,
       "clustering_mode": "batch_quality",
       "audio_duration_sec": 4.75,
-      "total_duration_sec": 2.508936,
-      "realtime_factor": 0.528197,
-      "hit_count": 13,
+      "total_duration_sec": 2.994395,
+      "realtime_factor": 0.630399,
+      "hit_count": 12,
       "cluster_count": 7,
       "stages": [
         {
           "key": "stem",
           "label": "Stem extraction / source load",
-          "duration_sec": 0.010515291000047,
+          "duration_sec": 0.02592192699921725,
           "status": "done",
-          "detail": "loaded full mix \u00b7 cached"
+          "detail": "loaded full mix \u00b7 cached \u00b7 reproduction uses full mix"
         },
         {
           "key": "bpm",
           "label": "Tempo detection",
-          "duration_sec": 0.11277726900016205,
+          "duration_sec": 0.1751658609991864,
           "status": "done",
           "detail": "120.2 BPM"
         },
         {
           "key": "onsets",
           "label": "Onset detection + slicing",
-          "duration_sec": 1.9893157869996685,
+          "duration_sec": 2.1905335589999595,
           "status": "done",
-          "detail": "13 hits"
+          "detail": "12 hits"
         },
         {
           "key": "classification",
           "label": "Spectral rule classification",
-          "duration_sec": 0.013427571999727661,
+          "duration_sec": 0.09557517999928677,
           "status": "done",
-          "detail": "bright:5, hihat_closed:1, hihat_open:6, kick:1"
+          "detail": "bright:5, hihat_open:6, kick:1"
         },
         {
           "key": "clustering",
           "label": "Mel fingerprint + transient NCC clustering",
-          "duration_sec": 0.013959215999875596,
+          "duration_sec": 0.014000580998981604,
           "status": "done",
           "detail": "7 clusters \u00b7 batch quality"
         },
         {
           "key": "selection",
           "label": "Best representative scoring",
-          "duration_sec": 0.09699052199994185,
+          "duration_sec": 0.08321280500058492,
           "status": "done",
           "detail": "quality-scored representatives"
         },
         {
           "key": "synthesis",
           "label": "Optional sample synthesis",
-          "duration_sec": 0.000661541999761539,
+          "duration_sec": 0.0006027010003890609,
           "status": "done",
           "detail": "2 synthesized alternates"
         },
         {
           "key": "export",
-          "label": "MIDI, reconstruction, WAV, ZIP export",
-          "duration_sec": 0.2707521170000291,
+          "label": "MIDI, reproduced mix, WAV, ZIP export",
+          "duration_sec": 0.40873212500082445,
           "status": "done",
-          "detail": "7 samples + 13 review hits + MIDI + ZIP"
+          "detail": "7 samples + 12 review hits + MIDI + full-context reproduction + ZIP"
         }
       ]
     },
@@ -78,66 +78,66 @@
       "run_index": 0,
       "clustering_mode": "batch_quality",
       "audio_duration_sec": 4.874989,
-      "total_duration_sec": 2.562433,
-      "realtime_factor": 0.525628,
-      "hit_count": 30,
-      "cluster_count": 1,
+      "total_duration_sec": 2.802354,
+      "realtime_factor": 0.574843,
+      "hit_count": 23,
+      "cluster_count": 2,
       "stages": [
         {
           "key": "stem",
           "label": "Stem extraction / source load",
-          "duration_sec": 0.009733310000228812,
+          "duration_sec": 0.02253025699974387,
           "status": "done",
-          "detail": "loaded full mix \u00b7 cached"
+          "detail": "loaded full mix \u00b7 cached \u00b7 reproduction uses full mix"
         },
         {
           "key": "bpm",
           "label": "Tempo detection",
-          "duration_sec": 0.18278188500016768,
+          "duration_sec": 0.09380031600085204,
           "status": "done",
           "detail": "161.5 BPM"
         },
         {
           "key": "onsets",
           "label": "Onset detection + slicing",
-          "duration_sec": 1.8905766069997298,
+          "duration_sec": 2.1897132599988254,
           "status": "done",
-          "detail": "30 hits"
+          "detail": "23 hits"
         },
         {
           "key": "classification",
           "label": "Spectral rule classification",
-          "duration_sec": 0.016936135000378272,
+          "duration_sec": 0.017409414000212564,
           "status": "done",
-          "detail": "bright:15, cymbal:1, hihat_closed:10, hihat_open:3, mid:1"
+          "detail": "bright:13, hihat_closed:4, hihat_open:4, kick:1, mid:1"
         },
         {
           "key": "clustering",
           "label": "Mel fingerprint + transient NCC clustering",
-          "duration_sec": 0.09508980800001154,
+          "duration_sec": 0.03413462400021672,
           "status": "done",
-          "detail": "1 clusters \u00b7 batch quality"
+          "detail": "2 clusters \u00b7 batch quality"
         },
         {
           "key": "selection",
           "label": "Best representative scoring",
-          "duration_sec": 0.271814092999648,
+          "duration_sec": 0.26413379800033,
           "status": "done",
           "detail": "quality-scored representatives"
         },
         {
           "key": "synthesis",
           "label": "Optional sample synthesis",
-          "duration_sec": 0.0009019099998113234,
+          "duration_sec": 0.0011682919994200347,
           "status": "done",
-          "detail": "1 synthesized alternates"
+          "detail": "2 synthesized alternates"
         },
         {
           "key": "export",
-          "label": "MIDI, reconstruction, WAV, ZIP export",
-          "duration_sec": 0.09411494899995887,
+          "label": "MIDI, reproduced mix, WAV, ZIP export",
+          "duration_sec": 0.17886992200146778,
           "status": "done",
-          "detail": "1 samples + 30 review hits + MIDI + ZIP"
+          "detail": "2 samples + 23 review hits + MIDI + full-context reproduction + ZIP"
         }
       ]
     },
@@ -148,66 +148,66 @@
       "run_index": 0,
       "clustering_mode": "batch_quality",
       "audio_duration_sec": 4.874989,
-      "total_duration_sec": 2.587342,
-      "realtime_factor": 0.530738,
-      "hit_count": 20,
-      "cluster_count": 4,
+      "total_duration_sec": 2.514399,
+      "realtime_factor": 0.515775,
+      "hit_count": 31,
+      "cluster_count": 3,
       "stages": [
         {
           "key": "stem",
           "label": "Stem extraction / source load",
-          "duration_sec": 0.008843839000292064,
+          "duration_sec": 0.0255989449997287,
           "status": "done",
-          "detail": "loaded full mix \u00b7 cached"
+          "detail": "loaded full mix \u00b7 cached \u00b7 reproduction uses full mix"
         },
         {
           "key": "bpm",
           "label": "Tempo detection",
-          "duration_sec": 0.16997624899977382,
+          "duration_sec": 0.08472461699966516,
           "status": "done",
           "detail": "120.2 BPM"
         },
         {
           "key": "onsets",
           "label": "Onset detection + slicing",
-          "duration_sec": 2.0115367889998197,
+          "duration_sec": 1.905502139001328,
           "status": "done",
-          "detail": "20 hits"
+          "detail": "31 hits"
         },
         {
           "key": "classification",
           "label": "Spectral rule classification",
-          "duration_sec": 0.0954397410000638,
+          "duration_sec": 0.018339307000132976,
           "status": "done",
-          "detail": "bright:3, hihat_closed:14, hihat_open:3"
+          "detail": "bright:4, hihat_closed:25, hihat_open:2"
         },
         {
           "key": "clustering",
           "label": "Mel fingerprint + transient NCC clustering",
-          "duration_sec": 0.02929340799983038,
+          "duration_sec": 0.05202830600137531,
           "status": "done",
-          "detail": "4 clusters \u00b7 batch quality"
+          "detail": "3 clusters \u00b7 batch quality"
         },
         {
           "key": "selection",
           "label": "Best representative scoring",
-          "duration_sec": 0.1620299520000117,
+          "duration_sec": 0.24863046999962535,
           "status": "done",
           "detail": "quality-scored representatives"
         },
         {
           "key": "synthesis",
           "label": "Optional sample synthesis",
-          "duration_sec": 0.0010316440002497984,
+          "duration_sec": 0.0012351730001682881,
           "status": "done",
-          "detail": "2 synthesized alternates"
+          "detail": "3 synthesized alternates"
         },
         {
           "key": "export",
-          "label": "MIDI, reconstruction, WAV, ZIP export",
-          "duration_sec": 0.108677784000065,
+          "label": "MIDI, reproduced mix, WAV, ZIP export",
+          "duration_sec": 0.17784613499861734,
           "status": "done",
-          "detail": "4 samples + 20 review hits + MIDI + ZIP"
+          "detail": "3 samples + 31 review hits + MIDI + full-context reproduction + ZIP"
         }
       ]
     }
@@ -215,59 +215,59 @@
   "summary": [
     {
       "stage": "stem",
-      "mean_sec": 0.009697,
-      "median_sec": 0.009733,
-      "min_sec": 0.008844,
-      "max_sec": 0.010515
+      "mean_sec": 0.024684,
+      "median_sec": 0.025599,
+      "min_sec": 0.02253,
+      "max_sec": 0.025922
     },
     {
       "stage": "bpm",
-      "mean_sec": 0.155178,
-      "median_sec": 0.169976,
-      "min_sec": 0.112777,
-      "max_sec": 0.182782
+      "mean_sec": 0.117897,
+      "median_sec": 0.0938,
+      "min_sec": 0.084725,
+      "max_sec": 0.175166
     },
     {
       "stage": "onsets",
-      "mean_sec": 1.96381,
-      "median_sec": 1.989316,
-      "min_sec": 1.890577,
-      "max_sec": 2.011537
+      "mean_sec": 2.09525,
+      "median_sec": 2.189713,
+      "min_sec": 1.905502,
+      "max_sec": 2.190534
     },
     {
       "stage": "classification",
-      "mean_sec": 0.041934,
-      "median_sec": 0.016936,
-      "min_sec": 0.013428,
-      "max_sec": 0.09544
+      "mean_sec": 0.043775,
+      "median_sec": 0.018339,
+      "min_sec": 0.017409,
+      "max_sec": 0.095575
     },
     {
       "stage": "clustering",
-      "mean_sec": 0.046114,
-      "median_sec": 0.029293,
-      "min_sec": 0.013959,
-      "max_sec": 0.09509
+      "mean_sec": 0.033388,
+      "median_sec": 0.034135,
+      "min_sec": 0.014001,
+      "max_sec": 0.052028
     },
     {
       "stage": "selection",
-      "mean_sec": 0.176945,
-      "median_sec": 0.16203,
-      "min_sec": 0.096991,
-      "max_sec": 0.271814
+      "mean_sec": 0.198659,
+      "median_sec": 0.24863,
+      "min_sec": 0.083213,
+      "max_sec": 0.264134
     },
     {
       "stage": "synthesis",
-      "mean_sec": 0.000865,
-      "median_sec": 0.000902,
-      "min_sec": 0.000662,
-      "max_sec": 0.001032
+      "mean_sec": 0.001002,
+      "median_sec": 0.001168,
+      "min_sec": 0.000603,
+      "max_sec": 0.001235
     },
     {
       "stage": "export",
-      "mean_sec": 0.157848,
-      "median_sec": 0.108678,
-      "min_sec": 0.094115,
-      "max_sec": 0.270752
+      "mean_sec": 0.255149,
+      "median_sec": 0.17887,
+      "min_sec": 0.177846,
+      "max_sec": 0.408732
     }
   ]
 }

docs/interactive-ux/README.md

@@ -12,7 +12,7 @@ The project now has a first supervised-editing foundation layered on top of the
 - The state contains hits, clusters, confidence scores, review queue entries, constraints, events, suggestions, and undo snapshots.
 - The FastAPI backend exposes state, move, pull-out, lock, suppress, review/favorite, suggestion, explanation, and undo endpoints.
 - The browser UI includes an interactive supervision panel with a review queue, cluster board, suggestion inbox, constraint/event log, and cluster explanation drawer.
-- The current supervised layer updates semantic state only. It does not yet rewrite sample WAVs, MIDI, reconstruction audio, or the ZIP after edits.
+- The supervised layer now rewrites edited sample WAVs, MIDI, target reconstruction, full-context reproduced audio, and ZIP artifacts under `supervised/` while preserving original batch outputs.
 
 ## Documents
 

pipeline_runner.py

@@ -149,7 +149,7 @@ STAGE_DEFS = [
     ("clustering", "Mel fingerprint + transient NCC clustering"),
     ("selection", "Best representative scoring"),
     ("synthesis", "Optional sample synthesis"),
-    ("export", "MIDI, reconstruction, WAV, ZIP export"),
+    ("export", "MIDI, reproduced mix, WAV, ZIP export"),
 ]
 
 
@@ -192,6 +192,62 @@ def _normalise_audio(audio: np.ndarray) -> np.ndarray:
     return audio.astype(np.float32)
 
 
+def _mono(audio: np.ndarray) -> np.ndarray:
+    audio = np.asarray(audio, dtype=np.float32)
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+    return audio.astype(np.float32)
+
+
+def _pad_or_trim(audio: np.ndarray, length: int) -> np.ndarray:
+    audio = _mono(audio)
+    if len(audio) == length:
+        return audio
+    if len(audio) > length:
+        return audio[:length]
+    return np.pad(audio, (0, max(0, length - len(audio)))).astype(np.float32)
+
+
+def _load_source_mix(audio_path: str | os.PathLike[str], sr: int) -> np.ndarray:
+    audio, _ = librosa.load(audio_path, sr=sr, mono=True)
+    return _mono(audio)
+
+
+def _common_gain(reference: np.ndarray, fallback: np.ndarray) -> float:
+    peak = float(np.max(np.abs(reference))) if reference.size else 0.0
+    if peak <= 1e-8:
+        peak = float(np.max(np.abs(fallback))) if fallback.size else 0.0
+    return peak if peak > 1e-8 else 1.0
+
+
+def _rms(audio: np.ndarray) -> float:
+    audio = _mono(audio)
+    return float(np.sqrt(np.mean(np.square(audio, dtype=np.float64)))) if audio.size else 0.0
+
+
+def _match_rms(rendered: np.ndarray, reference: np.ndarray, *, min_gain: float = 0.05, max_gain: float = 8.0) -> np.ndarray:
+    rendered_rms = _rms(rendered)
+    reference_rms = _rms(reference)
+    if rendered_rms <= 1e-10 or reference_rms <= 1e-10:
+        return _mono(rendered)
+    gain = float(np.clip(reference_rms / rendered_rms, min_gain, max_gain))
+    return (_mono(rendered) * gain).astype(np.float32)
+
+
+def _soft_limit(audio: np.ndarray, ceiling: float = 0.98) -> np.ndarray:
+    audio = _mono(audio).astype(np.float32)
+    peak = float(np.max(np.abs(audio))) if audio.size else 0.0
+    if peak > ceiling > 0:
+        audio = audio * (ceiling / peak)
+    return audio.astype(np.float32)
+
+
+def _make_reproduction_mix(target_reconstruction: np.ndarray, context_bed: np.ndarray, length: int) -> np.ndarray:
+    target = _pad_or_trim(target_reconstruction, length)
+    context = _pad_or_trim(context_bed, length)
+    return _soft_limit(context + target)
+
+
 MODULE_ROOT = Path(__file__).resolve().parent
 CACHE_DIR = Path(os.environ["DSE_CACHE_DIR"]) if os.environ.get("DSE_CACHE_DIR") else MODULE_ROOT / ".cache"
 STEM_CACHE_DIR = CACHE_DIR / "stems"
@@ -313,20 +369,32 @@ def run_extraction_pipeline(
 
     bpm: float | None = None
     stem_audio: np.ndarray
+    source_audio: np.ndarray
+    context_bed: np.ndarray
     stem_sr: int
     hits: list[Any] = []
     clusters: list[Any] = []
-    rendered: np.ndarray | None = None
+    target_rendered: np.ndarray | None = None
+    reproduced: np.ndarray | None = None
 
     _notify(progress_cb, {"type": "start", "stages": [asdict(s) for s in stages]})
 
     with _timed_stage(stages, "stem", progress_cb) as stage:
-        stem_audio, stem_sr, stem_detail = _load_or_extract_stem(audio_path, params)
-        stem_audio = _normalise_audio(stem_audio)
-        stage.detail = stem_detail
-        _write_audio(out / "stem.wav", stem_audio, stem_sr, subtype="PCM_16")
-
-    audio_duration_sec = len(stem_audio) / stem_sr if stem_sr else 0.0
+        raw_stem_audio, stem_sr, stem_detail = _load_or_extract_stem(audio_path, params)
+        source_raw = _load_source_mix(audio_path, stem_sr)
+        length = max(len(raw_stem_audio), len(source_raw))
+        raw_stem_audio = _pad_or_trim(raw_stem_audio, length)
+        source_raw = _pad_or_trim(source_raw, length)
+        gain = _common_gain(raw_stem_audio if params.stem != "all" else source_raw, source_raw)
+        stem_audio = (raw_stem_audio / gain).astype(np.float32)
+        source_audio = (source_raw / gain).astype(np.float32)
+        context_bed = np.zeros_like(source_audio) if params.stem == "all" else (source_audio - stem_audio).astype(np.float32)
+        stage.detail = stem_detail + (" · reproduction uses full mix" if params.stem == "all" else " · reproduction uses residual non-target stems")
+        _write_audio(out / "source.wav", _soft_limit(source_audio), stem_sr, subtype="PCM_16")
+        _write_audio(out / "stem.wav", _soft_limit(stem_audio), stem_sr, subtype="PCM_16")
+        _write_audio(out / "context_bed.wav", _soft_limit(context_bed), stem_sr, subtype="PCM_16")
+
+    audio_duration_sec = len(source_audio) / stem_sr if stem_sr else 0.0
 
     with _timed_stage(stages, "bpm", progress_cb) as stage:
         bpm = detect_bpm(stem_audio, stem_sr)
@@ -411,7 +479,7 @@ def run_extraction_pipeline(
 
     sample_rows: list[dict[str, Any]] = []
     hit_rows: list[dict[str, Any]] = []
-    files: dict[str, str] = {"stem": "stem.wav"}
+    files: dict[str, str] = {"source": "source.wav", "stem": "stem.wav", "context_bed": "context_bed.wav"}
 
     with _timed_stage(stages, "export", progress_cb) as stage:
         midi_path = out / "reconstruction.mid"
@@ -423,12 +491,16 @@ def run_extraction_pipeline(
                 quantize=bool(params.quantize_midi),
                 subdivision=int(params.subdivision),
             )
-            rendered = render_midi_with_samples(clusters, sr=stem_sr)
+            target_rendered = render_midi_with_samples(clusters, sr=stem_sr)
+            target_rendered = _match_rms(target_rendered, stem_audio)
         else:
-            rendered = np.zeros_like(stem_audio)
+            target_rendered = np.zeros_like(stem_audio)
             midi_path.write_bytes(b"")
 
-        _write_audio(out / "reconstruction.wav", rendered, stem_sr, subtype="PCM_16")
+        reproduced = _make_reproduction_mix(target_rendered, context_bed, max(len(source_audio), len(target_rendered)))
+        _write_audio(out / "target_reconstruction.wav", _soft_limit(target_rendered), stem_sr, subtype="PCM_16")
+        _write_audio(out / "reconstruction.wav", reproduced, stem_sr, subtype="PCM_16")
+        files["target_reconstruction"] = "target_reconstruction.wav"
         files["reconstruction"] = "reconstruction.wav"
         files["midi"] = "reconstruction.mid"
 
@@ -481,14 +553,21 @@ def run_extraction_pipeline(
                 synth_path = samples_dir / f"{cluster.label}__synth.wav"
                 _write_audio(synth_path, cluster.synthesized, stem_sr)
 
-        archive_tmp = build_archive(clusters, bpm or 120.0, stem_sr, midi_path=str(midi_path), rendered_audio=rendered)
+        archive_tmp = build_archive(
+            clusters,
+            bpm or 120.0,
+            stem_sr,
+            midi_path=str(midi_path),
+            rendered_audio=reproduced,
+            target_rendered_audio=target_rendered,
+        )
         files["archive"] = _copy_temp_file(archive_tmp, out / "sample-pack.zip")
         files["archive"] = "sample-pack.zip"
         try:
             os.unlink(archive_tmp)
         except OSError:
             pass
-        stage.detail = f"{len(sample_rows)} samples + {len(hit_rows)} review hits + MIDI + ZIP"
+        stage.detail = f"{len(sample_rows)} samples + {len(hit_rows)} review hits + MIDI + full-context reproduction + ZIP"
 
     duration_sec = time.perf_counter() - started_total
     result = PipelineResult(

sample_extractor.py

@@ -525,9 +525,13 @@ def render_midi_with_samples(clusters,sr=44100):
     pk=np.abs(buf).max(); return (buf/pk*0.9).astype(np.float32) if pk>1e-8 else buf.astype(np.float32)
 def build_sample_map(clusters):
     return {c.midi_note:{'label':c.label,'count':c.count,'duration_ms':int(c.best_hit.duration*1000)} for c in clusters}
-def build_archive(clusters,bpm,sr,midi_path=None,rendered_audio=None):
+def build_archive(clusters,bpm,sr,midi_path=None,rendered_audio=None,target_rendered_audio=None):
     import zipfile,tempfile,io; zp=tempfile.mktemp(suffix='.zip')
     idx={'bpm':round(bpm,1),'sample_rate':sr,'total_clusters':len(clusters),'total_hits':sum(c.count for c in clusters),'samples':{}}
+    if rendered_audio is not None:
+        idx['reproduction_file']='rendered_reproduction_full_mix.wav'
+    if target_rendered_audio is not None:
+        idx['target_reconstruction_file']='rendered_reconstruction_target_stem.wav'
     with zipfile.ZipFile(zp,'w',compression=zipfile.ZIP_STORED) as zf:
         for c in clusters:
             b=c.best_hit; fn=f"samples/{c.label}.wav"; buf=io.BytesIO()
@@ -544,7 +548,11 @@ def build_archive(clusters,bpm,sr,midi_path=None,rendered_audio=None):
         if midi_path and os.path.exists(midi_path): zf.write(midi_path,'reconstruction.mid')
         if rendered_audio is not None:
             rb=io.BytesIO(); sf.write(rb,rendered_audio,sr,format='WAV',subtype='PCM_16')
+            zf.writestr('rendered_reproduction_full_mix.wav',rb.getvalue())
             zf.writestr('rendered_reconstruction.wav',rb.getvalue())
+        if target_rendered_audio is not None:
+            tb=io.BytesIO(); sf.write(tb,target_rendered_audio,sr,format='WAV',subtype='PCM_16')
+            zf.writestr('rendered_reconstruction_target_stem.wav',tb.getvalue())
     return zp
 
 # ─── Auto-tuner with locking ─────────────────────────────────────────────────

scripts/test_api_job.py

@@ -23,3 +23,5 @@ for _ in range(60):
 print(json.dumps({'status':job['status'], 'error':job.get('error'), 'hit_count': job.get('result',{}).get('hit_count'), 'files': job.get('result',{}).get('file_urls')}, indent=2))
 assert job['status']=='complete', job.get('error')
 assert job['result']['hit_count'] > 0
+for key in ['source', 'stem', 'context_bed', 'target_reconstruction', 'reconstruction', 'midi', 'archive']:
+    assert key in job['result']['file_urls'], key

scripts/test_supervised_export_and_force_onset.py

@@ -89,7 +89,7 @@ def main() -> int:
     assert export["kind"] == "supervised-export"
     assert export["hit_count"] == state["summary"]["hit_count"] - state["summary"].get("suppressed_hit_count", 0)
     assert export["cluster_count"] >= 1
-    for key in ["archive", "midi", "reconstruction"]:
+    for key in ["archive", "midi", "target_reconstruction", "reconstruction"]:
         url = export["file_urls"][key]
         file_response = client.get(url)
         file_response.raise_for_status()

supervised_export.py

@@ -123,6 +123,54 @@ def _write_audio(path: Path, audio: np.ndarray, sr: int, subtype: str = "PCM_16"
     sf.write(path, audio, sr, subtype=subtype)
 
 
+def _mono(audio: np.ndarray) -> np.ndarray:
+    audio = np.asarray(audio, dtype=np.float32)
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+    return audio.astype(np.float32)
+
+
+def _pad_or_trim(audio: np.ndarray, length: int) -> np.ndarray:
+    audio = _mono(audio)
+    if len(audio) == length:
+        return audio
+    if len(audio) > length:
+        return audio[:length]
+    return np.pad(audio, (0, max(0, length - len(audio)))).astype(np.float32)
+
+
+def _rms(audio: np.ndarray) -> float:
+    audio = _mono(audio)
+    return float(np.sqrt(np.mean(np.square(audio, dtype=np.float64)))) if audio.size else 0.0
+
+
+def _match_rms(rendered: np.ndarray, reference: np.ndarray, *, min_gain: float = 0.05, max_gain: float = 8.0) -> np.ndarray:
+    rendered_rms = _rms(rendered)
+    reference_rms = _rms(reference)
+    if rendered_rms <= 1e-10 or reference_rms <= 1e-10:
+        return _mono(rendered)
+    return (_mono(rendered) * float(np.clip(reference_rms / rendered_rms, min_gain, max_gain))).astype(np.float32)
+
+
+def _soft_limit(audio: np.ndarray, ceiling: float = 0.98) -> np.ndarray:
+    audio = _mono(audio).astype(np.float32)
+    peak = float(np.max(np.abs(audio))) if audio.size else 0.0
+    if peak > ceiling > 0:
+        audio = audio * (ceiling / peak)
+    return audio.astype(np.float32)
+
+
+def _read_optional_audio(path: Path) -> tuple[np.ndarray | None, int | None]:
+    if not path.exists():
+        return None, None
+    audio, sr = sf.read(path, dtype="float32", always_2d=False)
+    return _mono(audio), int(sr)
+
+
+def _make_reproduction_mix(target_reconstruction: np.ndarray, context_bed: np.ndarray, length: int) -> np.ndarray:
+    return _soft_limit(_pad_or_trim(context_bed, length) + _pad_or_trim(target_reconstruction, length))
+
+
 def export_supervised_state(
     output_dir: str | os.PathLike[str],
     job_id: str,
@@ -159,20 +207,39 @@ def export_supervised_state(
     files: dict[str, str] = {}
     samples: list[dict[str, Any]] = []
 
+    context_bed, context_sr = _read_optional_audio(out / "context_bed.wav")
+    source_audio, source_sr = _read_optional_audio(out / "source.wav")
+    stem_audio, stem_file_sr = _read_optional_audio(out / "stem.wav")
+    if context_sr:
+        sr = int(context_sr)
+    elif source_sr:
+        sr = int(source_sr)
+    elif stem_file_sr:
+        sr = int(stem_file_sr)
+    source_length = len(source_audio) if source_audio is not None else max((len(context_bed) if context_bed is not None else 0), sr)
+    if context_bed is None:
+        context_bed = np.zeros(source_length, dtype=np.float32)
+    if stem_audio is None:
+        stem_audio = np.zeros(source_length, dtype=np.float32)
+
     midi_path = export_dir / "reconstruction.mid"
     if clusters:
         export_midi(clusters, str(midi_path), bpm=bpm, quantize=quantize, subdivision=int(subdivision))
-        rendered = render_midi_with_samples(clusters, sr=sr)
+        target_rendered = render_midi_with_samples(clusters, sr=sr)
+        target_rendered = _match_rms(target_rendered, stem_audio)
         if synthesize:
             for cluster in clusters:
                 if cluster.count >= 2:
                     cluster.synthesized = synthesize_from_cluster(cluster)
     else:
         midi_path.write_bytes(b"")
-        rendered = np.zeros(sr, dtype=np.float32)
+        target_rendered = np.zeros(source_length, dtype=np.float32)
 
+    rendered = _make_reproduction_mix(target_rendered, context_bed, max(source_length, len(target_rendered)))
+    _write_audio(export_dir / "target_reconstruction.wav", _soft_limit(target_rendered), sr, subtype="PCM_16")
     _write_audio(export_dir / "reconstruction.wav", rendered, sr, subtype="PCM_16")
     files["midi"] = "supervised/reconstruction.mid"
+    files["target_reconstruction"] = "supervised/target_reconstruction.wav"
     files["reconstruction"] = "supervised/reconstruction.wav"
 
     for cluster in sorted(clusters, key=lambda item: item.count, reverse=True):
@@ -197,7 +264,14 @@ def export_supervised_state(
         if cluster.synthesized is not None:
             _write_audio(out / f"supervised/samples/{cluster.label}__synth.wav", cluster.synthesized, sr, subtype="PCM_24")
 
-    archive_tmp = build_archive(clusters, bpm, sr, midi_path=str(midi_path), rendered_audio=rendered)
+    archive_tmp = build_archive(
+        clusters,
+        bpm,
+        sr,
+        midi_path=str(midi_path),
+        rendered_audio=rendered,
+        target_rendered_audio=target_rendered,
+    )
     archive_rel = "supervised/sample-pack.zip"
     shutil.copyfile(archive_tmp, out / archive_rel)
     try:

web/app.js

@@ -17,6 +17,7 @@ let activeJobId = null;
 let selectedHitIndex = null;
 let selectedSampleIndex = null;
 let forceOnsetMode = false;
+let previewMode = "source";
 let audioContext = null;
 
 const palette = ["#9b72ef", "#4f7df2", "#42b8b4", "#ef9343", "#ea5ca9", "#6d9be8", "#8abc59", "#805fe6"];
@@ -58,9 +59,24 @@ function fmtClock(seconds) {
 }
 
 function transportAudio() {
-  const stem = $("stemAudio");
-  const source = $("sourcePreview");
-  return stem?.src ? stem : source;
+  const candidates = {
+    source: $("sourcePreview"),
+    stem: $("stemAudio"),
+    reproduction: $("reconAudio"),
+  };
+  const selected = candidates[previewMode];
+  if (selected?.src) return selected;
+  return candidates.reproduction?.src || candidates.source?.src ? (candidates.reproduction?.src ? candidates.reproduction : candidates.source) : candidates.stem;
+}
+
+function setPreviewMode(mode) {
+  const previous = transportAudio();
+  if (previous && !previous.paused) previous.pause();
+  previewMode = mode;
+  for (const button of document.querySelectorAll("[data-preview-mode]")) {
+    button.classList.toggle("active", button.dataset.previewMode === previewMode);
+  }
+  updateTransport();
 }
 
 function updateTransport() {
@@ -78,9 +94,10 @@ function updateTransport() {
 }
 
 function pauseNonTransportAudio() {
-  for (const id of ["hitAudio", "sampleAudio", "reconAudio"]) {
+  const keep = transportAudio();
+  for (const id of ["sourcePreview", "stemAudio", "reconAudio", "hitAudio", "sampleAudio"]) {
     const el = $(id);
-    if (el && !el.paused) el.pause();
+    if (el && el !== keep && !el.paused) el.pause();
   }
 }
 
@@ -683,7 +700,7 @@ async function undoLastEdit() {
 
 function renderEditedExport(exportPayload) {
   const fileUrls = exportPayload?.file_urls ?? {};
-  const labels = { archive: "Edited sample pack ZIP", midi: "Edited MIDI", reconstruction: "Edited reconstruction WAV" };
+  const labels = { archive: "Edited sample pack ZIP", midi: "Edited MIDI", reconstruction: "Edited reproduced mix WAV", target_reconstruction: "Edited target reconstruction WAV" };
   $("editedDownloads").innerHTML = Object.entries(fileUrls)
     .map(([key, url]) => `<a href="${esc(url)}" download>${esc(labels[key] ?? key)}</a>`)
     .join("");
@@ -729,11 +746,25 @@ function renderResult(job) {
   $("resultSummary").textContent = `${result.hit_count} hits → ${result.cluster_count} samples · BPM ${result.bpm ?? "—"} · ${fmtSec(result.duration_sec)} total · ${rtf}× realtime · ${mode}`;
 
   const fileUrls = result.file_urls ?? {};
-  const labels = { archive: "Sample pack ZIP", midi: "MIDI", stem: "Stem WAV", reconstruction: "Reconstruction WAV" };
-  $("downloads").innerHTML = Object.entries(fileUrls).map(([key, url]) => `<a href="${esc(url)}" download>${esc(labels[key] ?? key)}</a>`).join("");
+  const labels = {
+    archive: "Sample pack ZIP",
+    midi: "MIDI",
+    source: "Source mix WAV",
+    stem: "Target stem WAV",
+    context_bed: "Non-target stems WAV",
+    target_reconstruction: "Target reconstruction WAV",
+    reconstruction: "Reproduced mix WAV",
+  };
+  const downloadOrder = ["archive", "reconstruction", "target_reconstruction", "midi", "source", "stem", "context_bed"];
+  $("downloads").innerHTML = downloadOrder
+    .filter((key) => fileUrls[key])
+    .map((key) => `<a href="${esc(fileUrls[key])}" download>${esc(labels[key] ?? key)}</a>`)
+    .join("");
+  $("sourcePreview").src = fileUrls.source ?? $("sourcePreview").src ?? "";
   $("stemAudio").src = fileUrls.stem ?? "";
   $("reconAudio").src = fileUrls.reconstruction ?? "";
-  updateTransport();
+  if (fileUrls.reconstruction) setPreviewMode("reproduction");
+  else updateTransport();
 
   renderSamples(result);
   renderHits(result);
@@ -870,8 +901,9 @@ function setFile(file) {
   }
   if (file) {
     $("stemAudio").removeAttribute("src");
+    $("reconAudio").removeAttribute("src");
     $("sourcePreview").src = URL.createObjectURL(file);
-    updateTransport();
+    setPreviewMode("source");
   }
 }
 
@@ -910,12 +942,6 @@ async function boot() {
 $("demucs_model").addEventListener("change", updateStemOptions);
 $("fileInput").addEventListener("change", (event) => setFile(event.target.files?.[0] ?? null));
 $("runButton").addEventListener("click", runExtraction);
-$("useFastButton").addEventListener("click", () => {
-  $("stem").value = "all";
-  $("demucs_shifts").value = 0;
-  $("target_min").value = 4;
-  $("target_max").value = 16;
-});
 $("usePreviewButton").addEventListener("click", () => {
   $("stem").value = "all";
   $("clustering_mode").value = "online_preview";
@@ -924,6 +950,18 @@ $("usePreviewButton").addEventListener("click", () => {
   $("target_max").value = 16;
   $("mel_threshold").value = 0.62;
   $("ncc_threshold").value = 0.72;
+  $("resultSummary").textContent = "Fast preview preset applied: full mix, online grouping, no Demucs shifts.";
+});
+$("useQualityButton").addEventListener("click", () => {
+  if (($("stem").value || "") === "all") $("stem").value = "drums";
+  $("clustering_mode").value = "batch_quality";
+  $("demucs_shifts").value = 1;
+  $("demucs_overlap").value = 0.25;
+  $("target_min").value = 5;
+  $("target_max").value = 20;
+  $("mel_threshold").value = 0.75;
+  $("ncc_threshold").value = 0.80;
+  $("resultSummary").textContent = "Best quality preset applied: separated stem, batch clustering, conservative grouping.";
 });
 
 for (const [id, delta] of [["clusterMinusButton", -1], ["clusterPlusButton", 1]]) {
@@ -963,7 +1001,7 @@ $("targetClusterSelect").addEventListener("change", setActionButtons);
 $("waveform").addEventListener("click", selectNearestWaveformHit);
 $("transportPlayButton").addEventListener("click", () => { toggleTransportPlayback().catch(() => {}); });
 $("transportSeek").addEventListener("input", (event) => seekTransport(event.target.value));
-for (const id of ["sourcePreview", "stemAudio"]) {
+for (const id of ["sourcePreview", "stemAudio", "reconAudio"]) {
   const audio = $(id);
   audio.addEventListener("timeupdate", updateTransport);
   audio.addEventListener("durationchange", updateTransport);
@@ -971,6 +1009,9 @@ for (const id of ["sourcePreview", "stemAudio"]) {
   audio.addEventListener("pause", updateTransport);
   audio.addEventListener("ended", updateTransport);
 }
+for (const button of document.querySelectorAll("[data-preview-mode]")) {
+  button.addEventListener("click", () => setPreviewMode(button.dataset.previewMode));
+}
 
 const dropzone = $("dropzone");
 const globalDropOverlay = $("globalDropOverlay");

web/index.html

@@ -88,6 +88,11 @@
               <button id="transportPlayButton" class="round-play" type="button" aria-label="Play preview">▶</button>
               <span id="transportTime" class="transport-time">0:00 / 0:00</span>
               <input id="transportSeek" class="transport-seek" type="range" min="0" max="1000" value="0" step="1" aria-label="Seek preview" />
+              <div class="preview-tabs" aria-label="Preview source">
+                <button id="previewSourceButton" class="preview-tab active" type="button" data-preview-mode="source">Source</button>
+                <button id="previewStemButton" class="preview-tab" type="button" data-preview-mode="stem">Stem</button>
+                <button id="previewReproductionButton" class="preview-tab" type="button" data-preview-mode="reproduction">Reproduced</button>
+              </div>
             </div>
             <div class="hidden-audio-bank" aria-hidden="true">
               <audio id="sourcePreview"></audio>
@@ -109,26 +114,35 @@
 
         <aside class="sidebar right-sidebar" aria-label="Right tool sidebar">
           <details class="tool-panel control-card" open>
-            <summary><span>Extract</span><small>Core controls</small></summary>
+            <summary><span>Common controls</span><small>The 3 knobs to try first</small></summary>
+            <p class="panel-help">Start here. These controls decide what gets detected, how many groups are produced, and which stem is sampled.</p>
             <div class="control-group">
-              <label>Stem
+              <label>Stem to sample
                 <select id="stem"></select>
+                <small class="field-hint">Use <strong>drums</strong> for separated drum hits, or <strong>all</strong> for fast full-mix prototyping.</small>
               </label>
             </div>
 
             <div class="control-group sensitivity-group">
-              <label for="onset_delta">Sensitivity</label>
+              <label for="onset_delta">Hit sensitivity</label>
               <input id="onset_delta" type="range" min="0.01" max="0.35" step="0.005" />
-              <div class="range-caption"><span>Low</span><span>High</span></div>
+              <div class="range-caption"><span>Fewer hits</span><span>More hits</span></div>
+              <small class="field-hint">Increase when quiet hits are missed; decrease when bleed or ghost transients are over-detected.</small>
             </div>
 
             <div class="control-group">
-              <label>Cluster Count</label>
-              <div class="stepper">
-                <button id="clusterMinusButton" type="button" class="step-button" aria-label="Decrease cluster count">−</button>
-                <input id="target_max" type="number" min="0" max="256" step="1" aria-label="Cluster count" />
-                <button id="clusterPlusButton" type="button" class="step-button" aria-label="Increase cluster count">+</button>
-              </div>
+              <label>Sample groups
+                <div class="stepper">
+                  <button id="clusterMinusButton" type="button" class="step-button" aria-label="Decrease cluster count">−</button>
+                  <input id="target_max" type="number" min="0" max="256" step="1" aria-label="Sample group count" />
+                  <button id="clusterPlusButton" type="button" class="step-button" aria-label="Increase cluster count">+</button>
+                </div>
+                <small class="field-hint">Approximate maximum number of sample cards to produce.</small>
+              </label>
+            </div>
+            <div class="preset-row common-presets">
+              <button id="usePreviewButton" class="ghost-button" type="button">Fast preview</button>
+              <button id="useQualityButton" class="ghost-button" type="button">Best quality</button>
             </div>
           </details>
 
@@ -140,84 +154,99 @@
           </details>
 
           <details class="tool-panel advanced-controls">
-            <summary><span>Advanced</span><small>Model and DSP settings</small></summary>
-            <div class="preset-row">
-              <button id="usePreviewButton" class="ghost-button" type="button">Online preview mode</button>
-              <button id="useFastButton" class="ghost-button" type="button">Fast full-mix mode</button>
-            </div>
-            <div class="control-grid compact-controls">
-              <label>Demucs model
-                <select id="demucs_model"></select>
-              </label>
-              <label>Clustering mode
-                <select id="clustering_mode">
-                  <option value="batch_quality">batch quality</option>
-                  <option value="online_preview">online preview</option>
-                </select>
-              </label>
-              <label>Shifts
-                <input id="demucs_shifts" type="number" min="0" max="8" step="1" />
-              </label>
-              <label>Overlap
-                <input id="demucs_overlap" type="number" min="0" max="0.9" step="0.05" />
-              </label>
-              <label>Onset mode
-                <select id="onset_mode">
-                  <option value="auto">auto / multiband</option>
-                  <option value="percussive">percussive</option>
-                  <option value="harmonic">harmonic</option>
-                  <option value="broadband">broadband</option>
-                </select>
-              </label>
-              <label>Energy threshold dB
-                <input id="energy_threshold_db" type="number" min="-100" max="0" step="1" />
-              </label>
-              <label>Minimum gap seconds
-                <input id="min_gap" type="number" min="0.001" max="1" step="0.005" />
-              </label>
-              <label>Pre-pad seconds
-                <input id="pre_pad" type="number" min="0" max="0.25" step="0.001" />
-              </label>
-              <label>Min duration seconds
-                <input id="min_dur" type="number" min="0.001" max="10" step="0.005" />
-              </label>
-              <label>Max duration seconds
-                <input id="max_dur" type="number" min="0.01" max="10" step="0.1" />
-              </label>
-              <label>NCC threshold
-                <input id="ncc_threshold" type="number" min="0" max="1" step="0.01" />
-              </label>
-              <label>Attack window ms
-                <input id="attack_ms" type="number" min="1" max="250" step="1" />
-              </label>
-              <label>Mel prefilter
-                <input id="mel_threshold" type="number" min="0" max="1" step="0.01" />
-              </label>
-              <label>Linkage
-                <select id="linkage">
-                  <option value="average">average</option>
-                  <option value="complete">complete</option>
-                  <option value="single">single</option>
-                </select>
-              </label>
-              <label>Target min clusters
-                <input id="target_min" type="number" min="0" max="256" step="1" />
-              </label>
-              <label>MIDI grid
-                <select id="subdivision">
-                  <option value="8">8th</option>
-                  <option value="16">16th</option>
-                  <option value="32">32nd</option>
-                  <option value="64">64th</option>
-                </select>
-              </label>
-            </div>
-            <div class="toggles">
-              <label><input id="synthesize" type="checkbox" /> synthesize alternates</label>
-              <label><input id="quantize_midi" type="checkbox" /> quantize MIDI</label>
-              <label><input id="use_disk_cache" type="checkbox" /> disk cache stems/source loads</label>
-            </div>
-            <button id="clearCacheButton" class="ghost-button full-width" type="button">Clear cache</button>
+            <summary><span>Advanced parameters</span><small>Only adjust when the common controls are not enough</small></summary>
+            <p class="panel-help">Advanced controls are grouped by pipeline stage. They are intentionally hidden from the normal extraction loop.</p>
+            <section class="advanced-section">
+              <h4>Stem separation</h4>
+              <div class="control-grid compact-controls">
+                <label>Demucs model
+                  <select id="demucs_model"></select>
+                </label>
+                <label>Shifts
+                  <input id="demucs_shifts" type="number" min="0" max="8" step="1" />
+                </label>
+                <label>Overlap
+                  <input id="demucs_overlap" type="number" min="0" max="0.9" step="0.05" />
+                </label>
+              </div>
+            </section>
+            <section class="advanced-section">
+              <h4>Hit detection</h4>
+              <div class="control-grid compact-controls">
+                <label>Onset mode
+                  <select id="onset_mode">
+                    <option value="auto">auto / multiband</option>
+                    <option value="percussive">percussive</option>
+                    <option value="harmonic">harmonic</option>
+                    <option value="broadband">broadband</option>
+                  </select>
+                </label>
+                <label>Energy threshold dB
+                  <input id="energy_threshold_db" type="number" min="-100" max="0" step="1" />
+                </label>
+                <label>Minimum gap seconds
+                  <input id="min_gap" type="number" min="0.001" max="1" step="0.005" />
+                </label>
+                <label>Pre-pad seconds
+                  <input id="pre_pad" type="number" min="0" max="0.25" step="0.001" />
+                </label>
+                <label>Min duration seconds
+                  <input id="min_dur" type="number" min="0.001" max="10" step="0.005" />
+                </label>
+                <label>Max duration seconds
+                  <input id="max_dur" type="number" min="0.01" max="10" step="0.1" />
+                </label>
+              </div>
+            </section>
+            <section class="advanced-section">
+              <h4>Grouping</h4>
+              <div class="control-grid compact-controls">
+                <label>Clustering mode
+                  <select id="clustering_mode">
+                    <option value="batch_quality">batch quality</option>
+                    <option value="online_preview">online preview</option>
+                  </select>
+                </label>
+                <label>Target min clusters
+                  <input id="target_min" type="number" min="0" max="256" step="1" />
+                </label>
+                <label>NCC threshold
+                  <input id="ncc_threshold" type="number" min="0" max="1" step="0.01" />
+                </label>
+                <label>Attack window ms
+                  <input id="attack_ms" type="number" min="1" max="250" step="1" />
+                </label>
+                <label>Mel prefilter
+                  <input id="mel_threshold" type="number" min="0" max="1" step="0.01" />
+                </label>
+                <label>Linkage
+                  <select id="linkage">
+                    <option value="average">average</option>
+                    <option value="complete">complete</option>
+                    <option value="single">single</option>
+                  </select>
+                </label>
+              </div>
+            </section>
+            <section class="advanced-section">
+              <h4>Export and cache</h4>
+              <div class="control-grid compact-controls">
+                <label>MIDI grid
+                  <select id="subdivision">
+                    <option value="8">8th</option>
+                    <option value="16">16th</option>
+                    <option value="32">32nd</option>
+                    <option value="64">64th</option>
+                  </select>
+                </label>
+              </div>
+              <div class="toggles">
+                <label><input id="synthesize" type="checkbox" /> synthesize alternates</label>
+                <label><input id="quantize_midi" type="checkbox" /> quantize MIDI</label>
+                <label><input id="use_disk_cache" type="checkbox" /> disk cache stems/source loads</label>
+              </div>
+              <button id="clearCacheButton" class="ghost-button full-width" type="button">Clear cache</button>
+            </section>
           </details>
         </aside>
       </main>

web/styles.css

@@ -857,3 +857,75 @@ tr:last-child td { border-bottom: 0; }
   box-shadow: none;
 }
 .transport-row .transport-seek:hover::-moz-range-thumb { opacity: 1; }
+
+/* Pass 9: clearer preview and parameter hierarchy. */
+.transport-row {
+  grid-template-columns: 48px 100px minmax(120px, 1fr) auto;
+  gap: 14px;
+}
+.preview-tabs {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 4px;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: #f7f7fa;
+  white-space: nowrap;
+}
+.preview-tab {
+  border: 0;
+  border-radius: 999px;
+  padding: 7px 10px;
+  background: transparent;
+  color: var(--muted);
+  font-size: 11px;
+  font-weight: 800;
+  cursor: pointer;
+}
+.preview-tab.active {
+  background: #fff;
+  color: var(--accent-strong);
+  box-shadow: 0 2px 8px rgba(18, 21, 30, .06);
+}
+.panel-help,
+.field-hint {
+  display: block;
+  color: var(--muted);
+  font-size: 11px;
+  line-height: 1.4;
+  font-weight: 560;
+}
+.panel-help {
+  margin: 10px 0 4px;
+}
+.field-hint {
+  margin-top: 7px;
+}
+.common-presets {
+  grid-template-columns: 1fr 1fr;
+}
+.advanced-section {
+  margin-top: 14px;
+  padding-top: 12px;
+  border-top: 1px solid rgba(228, 229, 233, .75);
+}
+.advanced-section:first-of-type {
+  border-top: 0;
+  padding-top: 0;
+}
+.advanced-section h4 {
+  margin: 0 0 8px;
+  color: var(--text);
+  font-size: 12px;
+  letter-spacing: -.01em;
+}
+@media (max-width: 920px) {
+  .transport-row {
+    grid-template-columns: 44px 86px minmax(0, 1fr);
+  }
+  .preview-tabs {
+    grid-column: 1 / -1;
+    justify-content: center;
+  }
+}