feat: add spleeter and selected card exports

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, 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.
+The pipeline defaults to Spleeter for lightweight source separation, can fall back to Demucs for quality, can bypass separation entirely for fast full-mix previews, detects onsets, classifies hits, clusters similar transients, chooses representative samples, optionally synthesizes alternate samples, and exports WAVs, MIDI, target-stem reconstruction, full-context reproduced audio, manifests, selected-only packs, and complete ZIP sample packs. The interactive layer stores user corrections as replayable semantic state beside each run manifest.
 
 ## Current status
 
@@ -56,6 +56,12 @@ Implemented:
   - restore suppressed hits,
   - edited sample-pack export,
   - constraint/event log.
+
+- Spleeter source-separation backend selected by default, with `spleeter:4stems`, `spleeter:2stems`, and `spleeter:5stems` support.
+- Optional Demucs backend and automatic Spleeter→Demucs fallback when enabled.
+- True per-card checkbox selection and selected-only export under `selected/`.
+- Persisted `draw another` card action that pins the next representative hit for the cluster.
+- Immediate trim/extend card edits that rewrite preview WAVs under `overrides/hits/` and persist to supervised state.
 - Documentation for features, progress, tasks, API, timing, hit review, realtime suitability, UI, remaining work, and interactive UX.
 - Legacy Gradio apps preserved in `legacy/` for reference only.
 
@@ -64,7 +70,8 @@ Not fully complete yet:
 - No true cached feature-vector local reclustering yet.
 - No cluster merge/split/relabel workflow beyond move/pull-to-new-cluster.
 - No frontend TypeScript build/test harness yet.
-- Demucs remains offline/batch by design.
+- Spleeter progress is coarse-grained; Demucs progress exposes chunk-level work where available.
+- Demucs remains offline/batch by design and is now treated as the higher-cost quality/fallback backend.
 
 See:
 
@@ -92,12 +99,13 @@ uvicorn app:app --host 0.0.0.0 --port 7860
 
 Open `http://127.0.0.1:7860`.
 
-For fast iteration, open `Advanced`, then use `Fast full-mix mode` or set:
+For fast iteration, use the default automatic flow. To bypass source separation entirely, open `Advanced`, use `Fast preview`, or set:
 
+- `Separation engine = none`
 - `Stem = all`
 - `Clustering mode = online_preview`
 
-That bypasses Demucs and uses the near-realtime clustering path.
+That uses the full mix and the near-realtime clustering path. The default engine is Spleeter. Install it separately with `pip install -r requirements-spleeter.txt` in an environment compatible with Spleeter/TensorFlow. If Spleeter is unavailable and fallback is enabled, the app falls back to Demucs.
 
 ## Run checks
 
@@ -109,6 +117,7 @@ python3 scripts/test_interactive_supervision.py
 python3 scripts/test_supervised_export_and_force_onset.py
 python3 scripts/test_progress_contract.py
 python3 scripts/test_param_validation_and_api_errors.py
+python3 scripts/test_selected_export_card_actions.py
 ```
 
 ## Run benchmarks
@@ -125,7 +134,7 @@ The benchmark uses synthetic drum fixtures and `stem=all` so the DSP stages are
 curl http://127.0.0.1:7860/api/config
 
 curl -F 'file=@song.wav' \
-  -F 'params={"stem":"all","clustering_mode":"online_preview","target_min":4,"target_max":12}' \
+  -F 'params={"separation_backend":"spleeter","spleeter_model":"spleeter:4stems","stem":"drums","clustering_mode":"online_preview","target_min":4,"target_max":12}' \
   http://127.0.0.1:7860/api/jobs
 ```
 
@@ -149,6 +158,29 @@ curl -X POST http://127.0.0.1:7860/api/jobs/<job-id>/hits/hit%3A00003/move \
   -d '{"target_cluster_id":"cluster:0"}'
 ```
 
+
+Export selected cards only:
+
+```bash
+curl -X POST http://127.0.0.1:7860/api/jobs/<job-id>/export-selected \
+  -H 'Content-Type: application/json' \
+  -d '{"labels":["kick_0","snare_0"],"synthesize":true}'
+```
+
+Draw another representative for a card:
+
+```bash
+curl -X POST http://127.0.0.1:7860/api/jobs/<job-id>/samples/kick_0/draw
+```
+
+Trim/extend the current representative preview:
+
+```bash
+curl -X POST http://127.0.0.1:7860/api/jobs/<job-id>/samples/kick_0/edit \
+  -H 'Content-Type: application/json' \
+  -d '{"start_offset_ms":-8,"tail_offset_ms":24}'
+```
+
 List active/completed runs:
 
 ```bash
@@ -160,19 +192,30 @@ curl http://127.0.0.1:7860/api/jobs
 | Path | Purpose |
 |---|---|
 | `app.py` | FastAPI app, static UI serving, job API, run history, artifact downloads, supervised editing endpoints |
-| `pipeline_runner.py` | Timed extraction pipeline, real progress contract, disk stem/source cache, batch/online clustering routing |
+| `pipeline_runner.py` | Timed extraction pipeline, Spleeter/Demucs/none separation backends, real progress contract, disk source/stem/context cache, batch/online clustering routing |
 | `sample_extractor.py` | Core DSP/sample extraction implementation, including chunk-progress callback support for Demucs stem extraction |
 | `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 |
+| `supervised_export.py` | Renders edited semantic state into supervised and selected-only WAV/MIDI/reconstruction/ZIP artifacts |
 | `web/` | Custom no-build browser frontend with clean fixed non-scrolling workstation layout, explicit upload/whole-page drag-drop, immediate uploaded waveform rendering, real-progress waveform tinting, source/stem/reproduced preview transport, common/advanced parameter separation, collapsed 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 |
 | `scripts/test_param_validation_and_api_errors.py` | Regression test for browser-style parameter coercion and visible API error details |
+| `scripts/test_selected_export_card_actions.py` | Smoke test for selected-only export, draw-next persistence, and immediate preview timing edits |
 | `docs/interactive-ux/` | Supplied interactive UX docs aligned to current implementation |
 | `docs/` | Review, timing, API, UI, feature, task, progress, and remaining-work documentation |
 | `legacy/` | Previous Gradio apps retained for reference |
 
+## Optional Spleeter backend
+
+Spleeter is the default selected backend because it is much lighter than Demucs for the common path. It is not pinned into `requirements.txt` because TensorFlow/Spleeter compatibility depends on the Python environment. Use:
+
+```bash
+pip install -r requirements-spleeter.txt
+```
+
+Leave `allow_backend_fallback=true` for normal use so missing or failing Spleeter installs automatically fall back to Demucs. Disable fallback only when debugging Spleeter itself.
+
 ## Output per run
 
 Each run is stored under `.runs/<job-id>/output/`:
@@ -187,6 +230,8 @@ Each run is stored under `.runs/<job-id>/output/`:
 - `supervision_state.json`
 - `supervised/manifest.json` after edited export
 - `supervised/sample-pack.zip` after edited export
+- `selected/sample-pack.zip` after selected-card export
+- `overrides/hits/*.wav` after immediate card trim/extend edits
 - `supervised/samples/*.wav` after edited export
 - `supervised/reconstruction.mid` after edited export
 - `supervised/reconstruction.wav` after edited export
@@ -206,7 +251,7 @@ The default UI is now intentionally simple:
 3. Upload and extraction start automatically.
 4. Automatic tuning chooses practical onset sensitivity and sample-group bounds after the source/stem is available.
 5. Sample cards appear in grouped columns as soon as their WAVs are written.
-6. The user can audition, dismiss, draw another candidate, or trim/extend a card and save that edit as a forced hit.
+6. The user can audition, dismiss, draw another candidate, or trim/extend a card. Draw and timing choices are persisted as semantic overrides and affect selected/edited exports.
 
 Advanced parameters, run history, raw tables, and supervised semantic editing remain available in collapsed panels, but they are no longer required for the common path.
 

app.py

@@ -24,7 +24,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 
-from pipeline_runner import PipelineParams, clear_disk_cache, initial_stages, run_extraction_pipeline
+from pipeline_runner import PipelineParams, SPLEETER_MODELS, SPLEETER_STEMS, SEPARATION_BACKENDS, clear_disk_cache, initial_stages, run_extraction_pipeline
 from sample_extractor import DEMUCS_MODELS, DEMUCS_STEMS, cache_clear
 from supervised_state import (
     accept_suggestion,
@@ -39,9 +39,11 @@ from supervised_state import (
     restore_hit as apply_hit_restore,
     set_hit_review_status,
     suppress_hit as apply_hit_suppression,
+    draw_next_representative as apply_draw_next_representative,
+    edit_hit_timing as apply_hit_timing_edit,
     undo_last as apply_undo,
 )
-from supervised_export import export_supervised_state
+from supervised_export import export_selected_samples, export_supervised_state
 
 ROOT = Path(__file__).resolve().parent
 WEB_DIR = ROOT / "web"
@@ -249,6 +251,9 @@ def health() -> dict[str, str]:
 @app.get("/api/config")
 def config() -> dict[str, Any]:
     return {
+        "separation_backends": SEPARATION_BACKENDS,
+        "spleeter_models": SPLEETER_MODELS,
+        "spleeter_stems": {key: value + ["all"] for key, value in SPLEETER_STEMS.items()},
         "demucs_models": DEMUCS_MODELS,
         "demucs_stems": {key: value + ["all"] for key, value in DEMUCS_STEMS.items()},
         "defaults": asdict(PipelineParams()),
@@ -361,6 +366,62 @@ def _state_payload(job_id: str) -> dict[str, Any]:
 def _json_patch(payload: dict[str, Any] | None) -> dict[str, Any]:
     return dict(payload or {})
 
+
+def _state_for_mutation(job_id: str) -> tuple[Path, dict[str, Any]]:
+    out = _job_output_dir(job_id)
+    try:
+        return out, load_or_create_state(job_id, out)
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=409, detail="Job has no manifest yet; wait until extraction completes") from exc
+
+
+def _cluster_id_for_sample_label(state: dict[str, Any], sample_label: str) -> str:
+    clusters = state.get("clusters", {})
+    exact = [cid for cid, cluster in clusters.items() if str(cluster.get("label")) == str(sample_label)]
+    if exact:
+        return exact[0]
+    # Fall back to a classification/base-name match for labels that have been renamed by user edits.
+    base = str(sample_label).rsplit("_", 1)[0]
+    fuzzy = [cid for cid, cluster in clusters.items() if str(cluster.get("classification") or "") == base]
+    if len(fuzzy) == 1:
+        return fuzzy[0]
+    raise HTTPException(status_code=404, detail=f"Sample label not found in current state: {sample_label}")
+
+
+def _public_sample_from_cluster(job_id: str, state: dict[str, Any], cluster_id: str, label_override: str | None = None) -> dict[str, Any]:
+    clusters = state.get("clusters", {})
+    hits = state.get("hits", {})
+    if cluster_id not in clusters:
+        raise HTTPException(status_code=404, detail=f"Unknown cluster: {cluster_id}")
+    cluster = clusters[cluster_id]
+    active_ids = [hid for hid in cluster.get("hit_ids", []) if hid in hits and not hits[hid].get("suppressed")]
+    if not active_ids:
+        raise HTTPException(status_code=409, detail=f"Cluster {cluster.get('label', cluster_id)} has no active hits")
+    rep_id = cluster.get("representative_hit_id") if cluster.get("representative_hit_id") in active_ids else active_ids[0]
+    hit = hits[rep_id]
+    raw_cluster_id = cluster_id.split(":", 1)[1] if ":" in cluster_id else cluster_id
+    try:
+        raw_cluster_id_value: int | str = int(raw_cluster_id)
+    except ValueError:
+        raw_cluster_id_value = raw_cluster_id
+    file_path = str(hit.get("file") or "")
+    first_onset = min(float(hits[hid].get("onset_sec") or 0.0) for hid in active_ids)
+    return {
+        "label": label_override or cluster.get("label") or str(cluster_id),
+        "classification": cluster.get("classification") or str(cluster.get("label") or "other").rsplit("_", 1)[0],
+        "hits": len(active_ids),
+        "midi_note": cluster.get("midi_note", 60),
+        "score": "edited",
+        "duration_ms": round(float(hit.get("duration_ms") or 0.0), 1),
+        "first_onset_sec": round(first_onset, 4),
+        "representative_hit_index": int(hit.get("index") or 0),
+        "state_hit_id": rep_id,
+        "cluster_id": raw_cluster_id_value,
+        "state_cluster_id": cluster_id,
+        "file": file_path,
+        "url": _job_url(job_id, file_path) if file_path else None,
+    }
+
 @app.get("/api/jobs/{job_id}/events")
 def get_job_events(job_id: str) -> StreamingResponse:
     with jobs_lock:
@@ -422,6 +483,75 @@ def post_supervised_export(job_id: str, payload: dict[str, Any] = Body(default_f
     return {"export": _serialise_export(job_id, export_manifest), "state": _state_payload(job_id)}
 
 
+@app.post("/api/jobs/{job_id}/export-selected")
+def post_selected_export(job_id: str, payload: dict[str, Any] = Body(default_factory=dict)) -> dict[str, Any]:
+    patch = _json_patch(payload)
+    labels = [str(item) for item in patch.get("labels", []) if str(item).strip()]
+    if not labels:
+        raise HTTPException(status_code=400, detail="labels must contain at least one selected sample label")
+    try:
+        export_manifest = export_selected_samples(
+            _job_output_dir(job_id),
+            job_id,
+            selected_labels=labels,
+            synthesize=bool(patch.get("synthesize", True)),
+            quantize=patch.get("quantize"),
+            subdivision=patch.get("subdivision"),
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+    return {"export": _serialise_export(job_id, export_manifest), "state": _state_payload(job_id)}
+
+
+@app.post("/api/jobs/{job_id}/samples/{sample_label:path}/draw")
+def post_draw_sample(job_id: str, sample_label: str) -> dict[str, Any]:
+    try:
+        out, state = _state_for_mutation(job_id)
+        cluster_id = _cluster_id_for_sample_label(state, sample_label)
+        state = apply_draw_next_representative(out, job_id, cluster_id, source="sample-card")
+        return {"sample": _public_sample_from_cluster(job_id, state, cluster_id, label_override=sample_label), "state": public_state(state, url_for=lambda rel: _job_url(job_id, rel))}
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+
+@app.post("/api/jobs/{job_id}/samples/{sample_label:path}/edit")
+def post_edit_sample(job_id: str, sample_label: str, payload: dict[str, Any] = Body(default_factory=dict)) -> dict[str, Any]:
+    patch = _json_patch(payload)
+    try:
+        out, state = _state_for_mutation(job_id)
+        cluster_id = _cluster_id_for_sample_label(state, sample_label)
+        cluster = state.get("clusters", {}).get(cluster_id) or {}
+        active_ids = [hid for hid in cluster.get("hit_ids", []) if hid in state.get("hits", {}) and not state["hits"][hid].get("suppressed")]
+        rep_id = cluster.get("representative_hit_id") if cluster.get("representative_hit_id") in active_ids else (active_ids[0] if active_ids else None)
+        if not rep_id:
+            raise HTTPException(status_code=409, detail=f"Sample {sample_label} has no active representative hit")
+        state = apply_hit_timing_edit(
+            out,
+            job_id,
+            rep_id,
+            start_offset_ms=float(patch.get("start_offset_ms", 0.0)),
+            tail_offset_ms=float(patch.get("tail_offset_ms", 0.0)),
+            source="sample-card",
+        )
+        return {"sample": _public_sample_from_cluster(job_id, state, cluster_id, label_override=sample_label), "state": public_state(state, url_for=lambda rel: _job_url(job_id, rel))}
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+
 @app.post("/api/jobs/{job_id}/hits/force-onset")
 def post_force_onset(job_id: str, payload: dict[str, Any] = Body(default_factory=dict)) -> dict[str, Any]:
     patch = _json_patch(payload)

docs/API.md

@@ -30,8 +30,11 @@ Important response keys:
 
 | Key | Meaning |
 |---|---|
+| `separation_backends` | Supported separation engines: `spleeter`, `demucs`, and `none`. |
+| `spleeter_models` | Supported Spleeter model profiles. |
+| `spleeter_stems` | Valid stems per Spleeter model, plus `all`. |
 | `demucs_models` | Supported Demucs model names. |
-| `demucs_stems` | Valid stems per model, plus `all` for bypassing Demucs. |
+| `demucs_stems` | Valid stems per Demucs model, plus `all`. |
 | `defaults` | Default `PipelineParams`. |
 | `stages` | Pipeline stage definitions. |
 | `clustering_modes` | Human-readable labels for batch and online clustering modes. |
@@ -90,7 +93,7 @@ Example:
 
 ```bash
 curl -F 'file=@song.wav' \
-  -F 'params={"stem":"all","clustering_mode":"online_preview","target_min":4,"target_max":12,"synthesize":true}' \
+  -F 'params={"separation_backend":"spleeter","spleeter_model":"spleeter:4stems","stem":"drums","clustering_mode":"online_preview","target_min":4,"target_max":12,"synthesize":true}' \
   http://127.0.0.1:7860/api/jobs
 ```
 
@@ -211,8 +214,10 @@ Defined in `pipeline_runner.PipelineParams`.
 
 | Parameter | Default | Meaning |
 |---|---:|---|
-| `stem` | `drums` | Demucs source to extract, or `all` to bypass Demucs. |
-| `demucs_model` | `htdemucs_ft` | Demucs model. |
+| `stem` | `drums` | Source/stem to extract, or `all` to bypass source separation. Valid values depend on the selected backend/model. |
+| `separation_backend` | `spleeter` | Source-separation engine: `spleeter`, `demucs`, or `none`. |
+| `spleeter_model` | `spleeter:4stems` | Spleeter model profile used by the default backend. |
+| `demucs_model` | `htdemucs_ft` | Demucs model used when `separation_backend=demucs` or fallback is needed. |
 | `demucs_shifts` | `1` | Test-time shifts for Demucs quality/speed tradeoff. |
 | `demucs_overlap` | `0.25` | Demucs chunk overlap. |
 | `onset_mode` | `auto` | `auto`, `percussive`, `harmonic`, or `broadband`. |
@@ -234,6 +239,65 @@ Defined in `pipeline_runner.PipelineParams`.
 | `subdivision` | `16` | MIDI grid subdivision. |
 | `device` | `cpu` | Torch device for Demucs. |
 | `use_disk_cache` | `true` | Cache decoded full mix/stems by source digest and extraction settings. |
+| `allow_backend_fallback` | `true` | If Spleeter is selected but unavailable/fails, fall back to Demucs instead of failing the job. |
+
+
+## Sample-card action API
+
+These endpoints back the simplified card workflow in the reference-style UI. They mutate `supervision_state.json` and preserve the original batch manifest.
+
+### `POST /api/jobs/{job_id}/export-selected`
+
+Exports only the currently selected representative sample labels into `selected/` artifacts.
+
+Body:
+
+```json
+{"labels":["kick_0","snare_0"],"synthesize":true}
+```
+
+Response shape:
+
+```json
+{
+  "export": {
+    "kind": "selected-sample-export",
+    "files": {"archive": "selected/sample-pack.zip", "midi": "selected/reconstruction.mid"},
+    "file_urls": {}
+  },
+  "state": {}
+}
+```
+
+Rules:
+
+- `labels` must contain at least one visible sample label.
+- Only selected semantic clusters are rendered.
+- Suppressed hits remain excluded.
+- Pinned/drawn representatives are honored.
+- The export is written under `.runs/<job-id>/output/selected/` and does not mutate the original pack.
+
+### `POST /api/jobs/{job_id}/samples/{sample_label}/draw`
+
+Cycles a card to the next active representative hit in that semantic cluster. The chosen hit is persisted as a representative override, so later selected/all edited exports use the same choice.
+
+Response:
+
+```json
+{"sample": {"label": "kick_0", "url": "..."}, "state": {}}
+```
+
+### `POST /api/jobs/{job_id}/samples/{sample_label}/edit`
+
+Applies a timing edit to the current representative and rewrites its preview WAV immediately.
+
+Body:
+
+```json
+{"start_offset_ms":-8,"tail_offset_ms":24}
+```
+
+The backend slices from `stem.wav`, writes `overrides/hits/*_edited.wav`, updates the representative hit in semantic state, and returns a refreshed card row.
 
 ## Interactive supervision API
 
@@ -504,11 +568,11 @@ Example:
   "completed_units": 12.0,
   "total_units": 64.0,
   "stage_key": "stem",
-  "stage_label": "Stem extraction / source load",
+  "stage_label": "Stem separation / source load",
   "stage_fraction": 0.5,
   "stage_work_done": 4,
   "stage_work_total": 8,
-  "basis": "exact completed work units: Demucs chunks when available, otherwise stage boundary units; no time-based estimates"
+  "basis": "exact completed work units: Demucs chunks when available; Spleeter and non-instrumented stages advance only at real stage boundaries; no time-based estimates"
 }
 ```
 
@@ -518,6 +582,7 @@ Semantics:
 - `stage_fraction` is the current stage-local progress when known.
 - `stage_work_done` and `stage_work_total` are exact work-unit counters when a stage exposes work units.
 - Demucs separated-stem extraction exposes exact completed split chunks.
+- Spleeter reports coarse start/complete boundaries because the backend does not expose reliable chunk callbacks here.
 - Non-instrumented stages update at exact stage boundaries only.
 - The API does not provide guessed ETA or interpolated time progress.
 

docs/CARD_SELECTION_EXPORT_AND_EDITING.md

@@ -0,0 +1,72 @@
+# Card selection, selected export, draw-next, and immediate timing edits
+
+Last updated: 2026-05-12
+
+## Goal
+
+The default workflow should feel like reviewing cards rather than configuring a batch pipeline:
+
+```text
+drop audio → cards appear → keep/dismiss/draw/trim → export selected
+```
+
+## Implemented
+
+### Per-card selection
+
+Each visible sample card now has a real checkbox. Newly produced cards are selected by default until the user changes selection manually. After the user clears or changes the selection, the UI respects that manual state.
+
+### Selected-only export
+
+`POST /api/jobs/{job_id}/export-selected` renders only the selected card labels into a separate `selected/` export directory:
+
+- `selected/sample-pack.zip`,
+- `selected/samples/*.wav`,
+- `selected/reconstruction.mid`,
+- `selected/target_reconstruction.wav`,
+- `selected/reconstruction.wav`,
+- `selected/manifest.json`.
+
+The original batch export is left untouched.
+
+### Persisted draw-next
+
+The card “draw another” action now calls:
+
+```text
+POST /api/jobs/{job_id}/samples/{sample_label}/draw
+```
+
+The backend cycles the semantic cluster representative to the next active hit and records that as a pinned representative override. Later selected/edited exports honor this choice.
+
+### Immediate trim/extend preview
+
+Trim/extend actions now call:
+
+```text
+POST /api/jobs/{job_id}/samples/{sample_label}/edit
+```
+
+The backend slices from `stem.wav`, writes an edited preview under `overrides/hits/`, updates the representative hit audio path, and returns a refreshed sample card. The user hears the edited clip immediately.
+
+## Validation
+
+Covered by:
+
+```bash
+python3 scripts/test_selected_export_card_actions.py
+```
+
+The test verifies:
+
+1. extraction succeeds,
+2. selected-only export writes a selected pack,
+3. draw-next returns a playable representative WAV,
+4. trim/extend writes a playable edited override WAV.
+
+## Remaining work
+
+- Add true cluster relabel/merge/split from the card columns.
+- Add batch restore and bulk card operations.
+- Add browser-level tests for checkbox selection and selected export.
+- Add visual diff between original representative and edited representative.

docs/FEATURES.md

@@ -150,3 +150,19 @@ Status: implemented.
 - The default web UI is now a reference-style sample extractor workspace: compact top bar, large waveform, persistent settings panel, grouped sample columns, and bottom selection bar.
 - Users can still just drop audio anywhere; waveform rendering and extraction begin automatically.
 - Expert parameters and semantic editing tools are available without cluttering the default path.
+
+## Selected cards and backend simplification update
+
+Implemented after the reference-image UI pass:
+
+| Area | Feature | Status | Notes |
+|---|---|---:|---|
+| Separation | Spleeter backend | Implemented | Default backend, with `spleeter:4stems` selected by default. |
+| Separation | Demucs backend | Implemented | Explicit higher-cost backend and automatic fallback when enabled. |
+| Separation | No-separation backend | Implemented | Full-mix preview path for fastest iteration. |
+| Export | Per-card selection | Implemented | Cards have real checkbox state; selected count drives `Export Selected`. |
+| Export | Selected-only export | Implemented | `POST /api/jobs/{job_id}/export-selected` writes `selected/sample-pack.zip`. |
+| Cards | Draw another | Implemented | Persists the next representative hit as a semantic override. |
+| Cards | Trim/extend preview | Implemented | Rewrites a playable preview WAV immediately under `overrides/hits/`. |
+| Docs | Separation backend docs | Implemented | See `docs/SPLEETER_AND_SEPARATION_BACKENDS.md`. |
+| Docs | Card action docs | Implemented | See `docs/CARD_SELECTION_EXPORT_AND_EDITING.md`. |

docs/PROGRESS.md

@@ -370,3 +370,21 @@ Validation performed:
 - Added centered file picker/current filename, right-aligned export actions, persistent right settings panel, waveform-first canvas, grouped sample columns, and compact bottom selection bar.
 - Kept automatic drop-to-process behavior and progressive sample-card rendering.
 - Moved secondary pipeline/history/supervision/tables into a compact tools drawer.
+
+
+## Pass 14: selected cards and Spleeter backend
+
+Completed in this pass:
+
+1. Added `spleeter` as the default separation backend, with selectable `spleeter:2stems`, `spleeter:4stems`, and `spleeter:5stems` profiles.
+2. Kept `demucs` as a quality/fallback backend and `none` as the full-mix preview backend.
+3. Added optional `requirements-spleeter.txt` instead of forcing TensorFlow/Spleeter into the base install.
+4. Added per-card checkbox state with manual select-all/clear behavior.
+5. Added selected-only backend export via `POST /api/jobs/{job_id}/export-selected`.
+6. Made `draw another` persist the chosen representative in semantic state.
+7. Made trim/extend rewrite playable preview audio immediately under `overrides/hits/`.
+8. Added `scripts/test_selected_export_card_actions.py`.
+
+Outcome:
+
+The default app now behaves more like a card review tool: drop audio, let Spleeter/fallback separation run, review grouped cards, select/dismiss/draw/trim, and export only the selected pack.

docs/REMAINING_WORK.md

@@ -103,3 +103,20 @@ The default UI is now a cleaner fixed, non-scrolling workstation layout with col
 - Add selected-only backend export so `Export Selected` creates an artifact containing only selected representatives.
 - Replace Unicode icons with a small icon system if exact visual parity is required.
 - Validate with a real browser screenshot comparison against the supplied reference image.
+
+## Closed after selected-card/Spleeter pass
+
+- `Export Selected` now renders a selected-only backend artifact instead of downloading the full generated pack.
+- Sample card checkboxes are real per-card state.
+- Draw-next is persisted as a representative override in `supervision_state.json`.
+- Trim/extend rewrites preview audio immediately and persists the edited representative hit.
+- Spleeter is now the default backend, with Demucs fallback and full-mix preview still available.
+
+## Remaining after selected-card/Spleeter pass
+
+1. Add cluster column merge/split/relabel directly in the card UI.
+2. Add localized high-quality separation refinement: run Demucs or another backend on short candidate regions instead of the entire file.
+3. Investigate AudioSep-like query-guided separation for overlapping drum events as an optional refinement path.
+4. Investigate inpainting for cleaning hit tails/bleed after localization, not for first-pass discovery.
+5. Add browser-level regression tests for drop-to-process, waveform zoom/pan, card selection, selected export, draw-next, and trim/extend.
+6. Add source-vs-stem-vs-reproduced diagnostics for cards where overlaps remain audible.

docs/SPLEETER_AND_SEPARATION_BACKENDS.md

@@ -0,0 +1,96 @@
+# Spleeter and separation backends
+
+Last updated: 2026-05-12
+
+## Decision
+
+The application now defaults to Spleeter:
+
+```json
+{
+  "separation_backend": "spleeter",
+  "spleeter_model": "spleeter:4stems",
+  "stem": "drums",
+  "allow_backend_fallback": true
+}
+```
+
+Spleeter is treated as the normal first-pass separation backend because it is much lighter for the common UX: drop a track, get drum-card candidates quickly, and only escalate to heavier processing when necessary.
+
+Demucs remains available as a higher-cost quality/fallback backend:
+
+```json
+{"separation_backend":"demucs","demucs_model":"htdemucs_ft"}
+```
+
+Full-mix preview remains available for the fastest possible iteration:
+
+```json
+{"separation_backend":"none","stem":"all","clustering_mode":"online_preview"}
+```
+
+## Supported engines
+
+| Backend | Status | Use |
+|---|---:|---|
+| `spleeter` | Default | Lightweight drum/source separation for the common automatic workflow. |
+| `demucs` | Supported | Higher-cost quality backend and fallback when Spleeter is unavailable or insufficient. |
+| `none` | Supported | Bypass source separation and process the full mix. Best for quick UI/debug iteration. |
+
+## Spleeter models
+
+| Model | Stems exposed |
+|---|---|
+| `spleeter:2stems` | `vocals`, `accompaniment`, `all` |
+| `spleeter:4stems` | `vocals`, `drums`, `bass`, `other`, `all` |
+| `spleeter:5stems` | `vocals`, `drums`, `bass`, `piano`, `other`, `all` |
+
+## Installation
+
+Spleeter is optional and intentionally not installed by the main `requirements.txt`, because TensorFlow/Spleeter compatibility can be environment-sensitive.
+
+Install it only when needed:
+
+```bash
+pip install -r requirements-spleeter.txt
+```
+
+For the normal local app, leave `allow_backend_fallback=true`. If Spleeter is unavailable or fails, the job falls back to Demucs and logs that fallback in the stage details. Disable fallback only when actively debugging Spleeter.
+
+## Caching
+
+The disk cache key includes:
+
+- source digest,
+- selected stem,
+- separation backend,
+- Spleeter model,
+- Demucs model,
+- Demucs shifts/overlap.
+
+This avoids accidentally reusing stems from a different engine or model.
+
+## Progress behavior
+
+Demucs exposes chunk progress through the existing extraction callback, so the waveform can advance during stem separation when chunk data is available.
+
+Spleeter does not expose reliable per-chunk progress through the current backend path. The app therefore reports only real start/completion boundaries for Spleeter. It does not interpolate fake progress.
+
+## Future research: localized separation
+
+The recommended next architecture is not “run Demucs on the whole track after Spleeter.” The better path is:
+
+1. Use Spleeter or full-mix onset detection to find candidate hit regions.
+2. Expand each candidate region with context padding.
+3. Run heavier separation only on those short windows.
+4. Stitch or use the refined region only for the card/export preview.
+
+That could make Demucs feasible as a local refinement step instead of an expensive full-track prerequisite.
+
+## Future research: overlapping samples
+
+AudioSep-like text/query-guided separation may be useful for overlaps where source classes matter, for example “kick drum”, “closed hi-hat”, or “snare transient”. It should be investigated as an optional refinement tool, not as the default first-pass extractor.
+
+USEF-TSE and target-speaker-extraction style systems are mostly speech-targeted. They are not a good near-term default for drum sample extraction, but the conditioning pattern is relevant if the app later supports “extract more sounds like this selected example.”
+
+Audio inpainting is more promising for cleaning card tails/gaps and removing overlap residue after a hit has already been localized than for first-pass sample discovery.

docs/TASKS.md

@@ -202,3 +202,25 @@ Next:
 - [x] Preserve existing review/edit tools in a secondary drawer.
 - [ ] Implement true per-card selection and selected-only export artifacts.
 - [ ] Run browser screenshot comparison in an environment that allows localhost rendering.
+
+
+## Selected cards and separation backends
+
+Completed:
+
+- [x] Add Spleeter backend option.
+- [x] Default new jobs to Spleeter `spleeter:4stems` + `drums`.
+- [x] Keep Demucs as explicit quality/fallback backend.
+- [x] Add `none` backend for full-mix preview.
+- [x] Add optional `requirements-spleeter.txt`.
+- [x] Add per-card checkbox selection.
+- [x] Add selected-only backend export.
+- [x] Persist draw-next representative overrides.
+- [x] Rewrite preview audio immediately for trim/extend edits.
+- [x] Add regression smoke test for selected export/card actions.
+
+Next:
+
+- [ ] Add card-column relabel/merge/split actions.
+- [ ] Add browser-level tests for card selection/export/edit flows.
+- [ ] Add localized high-quality separation refinement on short candidate windows.

docs/interactive-ux/PROGRESS.md

@@ -107,3 +107,21 @@ The default UX now follows the interactive-doc direction more closely by hiding
 - waveform zoom/pan supports close inspection without leaving the main flow.
 
 The remaining mismatch is that drawn candidate cards are still frontend candidate previews, not persisted representative-selection constraints. That should be promoted into the semantic state model next.
+
+
+## Pass 14: selected cards and Spleeter backend
+
+Completed in this pass:
+
+1. Added `spleeter` as the default separation backend, with selectable `spleeter:2stems`, `spleeter:4stems`, and `spleeter:5stems` profiles.
+2. Kept `demucs` as a quality/fallback backend and `none` as the full-mix preview backend.
+3. Added optional `requirements-spleeter.txt` instead of forcing TensorFlow/Spleeter into the base install.
+4. Added per-card checkbox state with manual select-all/clear behavior.
+5. Added selected-only backend export via `POST /api/jobs/{job_id}/export-selected`.
+6. Made `draw another` persist the chosen representative in semantic state.
+7. Made trim/extend rewrite playable preview audio immediately under `overrides/hits/`.
+8. Added `scripts/test_selected_export_card_actions.py`.
+
+Outcome:
+
+The default app now behaves more like a card review tool: drop audio, let Spleeter/fallback separation run, review grouped cards, select/dismiss/draw/trim, and export only the selected pack.

docs/interactive-ux/TASKS.md

@@ -131,3 +131,25 @@ The project now has a replayable state/events/constraints foundation plus superv
 - [ ] Persist drawn candidate cards as representative overrides.
 - [ ] Recluster locally after card-level decisions.
 - [ ] Add browser-level tests for the card flow.
+
+
+## Selected cards and separation backends
+
+Completed:
+
+- [x] Add Spleeter backend option.
+- [x] Default new jobs to Spleeter `spleeter:4stems` + `drums`.
+- [x] Keep Demucs as explicit quality/fallback backend.
+- [x] Add `none` backend for full-mix preview.
+- [x] Add optional `requirements-spleeter.txt`.
+- [x] Add per-card checkbox selection.
+- [x] Add selected-only backend export.
+- [x] Persist draw-next representative overrides.
+- [x] Rewrite preview audio immediately for trim/extend edits.
+- [x] Add regression smoke test for selected export/card actions.
+
+Next:
+
+- [ ] Add card-column relabel/merge/split actions.
+- [ ] Add browser-level tests for card selection/export/edit flows.
+- [ ] Add localized high-quality separation refinement on short candidate windows.

pipeline_runner.py

@@ -7,6 +7,8 @@ import hashlib
 import json
 import os
 import shutil
+import subprocess
+import sys
 import tempfile
 import time
 from contextlib import contextmanager
@@ -37,10 +39,20 @@ from sample_extractor import (
 
 ProgressCallback = Callable[[dict[str, Any]], None]
 
+SPLEETER_MODELS = ["spleeter:4stems", "spleeter:2stems", "spleeter:5stems"]
+SPLEETER_STEMS = {
+    "spleeter:2stems": ["vocals", "accompaniment"],
+    "spleeter:4stems": ["vocals", "drums", "bass", "other"],
+    "spleeter:5stems": ["vocals", "drums", "bass", "piano", "other"],
+}
+SEPARATION_BACKENDS = ["spleeter", "demucs", "none"]
+
 
 @dataclass
 class PipelineParams:
     stem: str = "drums"
+    separation_backend: str = "spleeter"
+    spleeter_model: str = "spleeter:4stems"
     demucs_model: str = "htdemucs_ft"
     demucs_shifts: int = 1
     demucs_overlap: float = 0.25
@@ -64,6 +76,7 @@ class PipelineParams:
     device: str = "cpu"
     auto_tune: bool = True
     use_disk_cache: bool = True
+    allow_backend_fallback: bool = True
 
     @classmethod
     def from_mapping(cls, data: dict[str, Any] | None) -> "PipelineParams":
@@ -86,7 +99,7 @@ class PipelineParams:
             "attack_ms",
             "mel_threshold",
         }
-        bool_fields = {"synthesize", "quantize_midi", "auto_tune", "use_disk_cache"}
+        bool_fields = {"synthesize", "quantize_midi", "auto_tune", "use_disk_cache", "allow_backend_fallback"}
 
         def coerce_bool(name: str, value: Any) -> bool:
             if isinstance(value, bool):
@@ -128,11 +141,23 @@ class PipelineParams:
         return params
 
     def validate(self) -> None:
+        if self.separation_backend not in set(SEPARATION_BACKENDS):
+            raise ValueError(f"Unsupported separation backend: {self.separation_backend}")
+        if self.spleeter_model not in SPLEETER_MODELS:
+            raise ValueError(f"Unsupported Spleeter model: {self.spleeter_model}")
         if self.demucs_model not in DEMUCS_MODELS:
             raise ValueError(f"Unsupported Demucs model: {self.demucs_model}")
-        allowed_stems = set(DEMUCS_STEMS.get(self.demucs_model, [])) | {"all"}
+        if self.separation_backend == "demucs":
+            allowed_stems = set(DEMUCS_STEMS.get(self.demucs_model, [])) | {"all"}
+            backend_label = self.demucs_model
+        elif self.separation_backend == "spleeter":
+            allowed_stems = set(SPLEETER_STEMS.get(self.spleeter_model, [])) | {"all"}
+            backend_label = self.spleeter_model
+        else:
+            allowed_stems = {"all"}
+            backend_label = "full mix"
         if self.stem not in allowed_stems:
-            raise ValueError(f"Stem '{self.stem}' is not available for {self.demucs_model}")
+            raise ValueError(f"Stem '{self.stem}' is not available for {backend_label}")
         if self.onset_mode not in {"auto", "percussive", "harmonic", "broadband"}:
             raise ValueError(f"Unsupported onset mode: {self.onset_mode}")
         if self.linkage not in {"average", "complete", "single"}:
@@ -197,7 +222,7 @@ class PipelineResult:
 
 
 STAGE_DEFS = [
-    ("stem", "Stem extraction / source load"),
+    ("stem", "Stem separation / source load"),
     ("auto_tune", "Automatic parameter tuning"),
     ("bpm", "Tempo detection"),
     ("onsets", "Onset detection + slicing"),
@@ -244,7 +269,7 @@ def _progress_payload(stages: list[StageTiming]) -> dict[str, Any]:
         "stage_fraction": round(running_progress, 6),
         "stage_work_done": running.work_done if running else None,
         "stage_work_total": running.work_total if running else None,
-        "basis": "exact completed work units: Demucs chunks when available, otherwise stage boundary units; no time-based estimates",
+        "basis": "exact completed work units: Demucs chunks when available; Spleeter and non-instrumented stages advance only at real stage boundaries; no time-based estimates",
     }
 
 
@@ -371,7 +396,7 @@ def _make_reproduction_mix(target_reconstruction: np.ndarray, context_bed: np.nd
 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"
-CACHE_VERSION = "dse-cache-v2"
+CACHE_VERSION = "dse-cache-v3-separation-backends"
 
 
 def _write_audio(path: Path, audio: np.ndarray, sr: int, subtype: str = "PCM_24") -> None:
@@ -392,6 +417,8 @@ def _stem_cache_path(audio_path: str | os.PathLike[str], params: PipelineParams)
         "version": CACHE_VERSION,
         "source_sha256": _sha256_file(audio_path),
         "stem": params.stem,
+        "separation_backend": params.separation_backend,
+        "spleeter_model": params.spleeter_model,
         "demucs_model": params.demucs_model,
         "demucs_shifts": params.demucs_shifts,
         "demucs_overlap": params.demucs_overlap,
@@ -401,19 +428,109 @@ def _stem_cache_path(audio_path: str | os.PathLike[str], params: PipelineParams)
     return STEM_CACHE_DIR / f"{key}.wav"
 
 
+def _context_cache_path(stem_cache_path: Path) -> Path:
+    return stem_cache_path.with_name(f"{stem_cache_path.stem}.context.wav")
+
+
 def clear_disk_cache() -> None:
     if CACHE_DIR.exists():
         shutil.rmtree(CACHE_DIR)
 
 
-def _load_or_extract_stem(audio_path: str | os.PathLike[str], params: PipelineParams, progress_cb: Callable[[dict[str, Any]], None] | None = None) -> tuple[np.ndarray, int, str]:
-    if params.use_disk_cache:
-        cache_path = _stem_cache_path(audio_path, params)
-        if cache_path.exists():
-            audio, sr = sf.read(cache_path, dtype="float32", always_2d=False)
-            if progress_cb:
-                progress_cb({"fraction": 1.0, "completed_units": 1, "total_units": 1, "detail": f"{params.stem} disk-cache hit"})
-            return np.asarray(audio, dtype=np.float32), int(sr), f"{params.stem} disk-cache hit"
+def _load_spleeter_audio(path: Path, sr: int | None = None) -> tuple[np.ndarray, int]:
+    audio, loaded_sr = librosa.load(path, sr=sr, mono=True)
+    return _mono(audio), int(loaded_sr)
+
+
+def _spleeter_output_file(root: Path, source_stem: str, stem: str) -> Path | None:
+    candidates = [root / source_stem / f"{stem}.wav", root / f"{stem}.wav"]
+    candidates.extend(root.glob(f"**/{stem}.wav"))
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _extract_spleeter_separation(
+    audio_path: str | os.PathLike[str],
+    params: PipelineParams,
+    progress_cb: Callable[[dict[str, Any]], None] | None = None,
+) -> tuple[np.ndarray, int, np.ndarray | None, str]:
+    """Run Spleeter and return target stem plus the sum of non-target stems.
+
+    Progress is deliberately coarse because Spleeter does not expose reliable
+    chunk callbacks through the CLI/Python API. We report start/completion only;
+    the global UI therefore never interpolates fake progress.
+    """
+    if progress_cb:
+        progress_cb({"fraction": 0.0, "completed_units": 0, "total_units": 1, "detail": f"Spleeter {params.spleeter_model} starting"})
+
+    with tempfile.TemporaryDirectory(prefix="dse_spleeter_") as tmp:
+        tmpdir = Path(tmp)
+        commands = [
+            [
+                sys.executable,
+                "-m",
+                "spleeter",
+                "separate",
+                "-p",
+                params.spleeter_model,
+                "-o",
+                str(tmpdir),
+                str(audio_path),
+            ],
+            [
+                "spleeter",
+                "separate",
+                "-p",
+                params.spleeter_model,
+                "-o",
+                str(tmpdir),
+                str(audio_path),
+            ],
+        ]
+        failures: list[str] = []
+        completed = None
+        for cmd in commands:
+            try:
+                completed = subprocess.run(cmd, capture_output=True, text=True, check=False, timeout=60 * 30)
+            except FileNotFoundError as exc:
+                failures.append(str(exc))
+                continue
+            if completed.returncode == 0:
+                break
+            failures.append((completed.stderr or completed.stdout or "Spleeter failed").strip()[-1200:])
+        if completed is None or completed.returncode != 0:
+            raise RuntimeError("; ".join(part for part in failures if part) or "Spleeter failed")
+
+        source_stem = Path(audio_path).stem
+        stems = SPLEETER_STEMS[params.spleeter_model]
+        paths = {stem: _spleeter_output_file(tmpdir, source_stem, stem) for stem in stems}
+        missing = [stem for stem, path in paths.items() if path is None]
+        if missing:
+            raise RuntimeError(f"Spleeter finished but did not write expected stem(s): {', '.join(missing)}")
+        if params.stem not in paths:
+            raise RuntimeError(f"Spleeter model {params.spleeter_model} does not provide stem '{params.stem}'")
+
+        target, sr = _load_spleeter_audio(paths[params.stem])  # type: ignore[arg-type]
+        context_parts: list[np.ndarray] = []
+        for name, path in paths.items():
+            if name == params.stem or path is None:
+                continue
+            part, _ = _load_spleeter_audio(path, sr=sr)
+            context_parts.append(_pad_or_trim(part, len(target)))
+        context = np.sum(np.stack(context_parts), axis=0).astype(np.float32) if context_parts else None
+
+    if progress_cb:
+        progress_cb({"fraction": 1.0, "completed_units": 1, "total_units": 1, "detail": f"Spleeter {params.spleeter_model} complete"})
+    return target.astype(np.float32), sr, context, f"{params.stem} via {params.spleeter_model}"
+
+
+def _extract_demucs_separation(
+    audio_path: str | os.PathLike[str],
+    params: PipelineParams,
+    progress_cb: Callable[[dict[str, Any]], None] | None = None,
+) -> tuple[np.ndarray, int, np.ndarray | None, str]:
     audio, sr = extract_stem(
         str(audio_path),
         stem=params.stem,
@@ -423,12 +540,50 @@ def _load_or_extract_stem(audio_path: str | os.PathLike[str], params: PipelinePa
         overlap=float(params.demucs_overlap),
         progress_cb=progress_cb,
     )
-    detail = f"{params.stem} via {params.demucs_model}" if params.stem != "all" else "loaded full mix"
+    return audio, sr, None, f"{params.stem} via Demucs {params.demucs_model}"
+
+
+def _load_or_extract_separation(audio_path: str | os.PathLike[str], params: PipelineParams, progress_cb: Callable[[dict[str, Any]], None] | None = None) -> tuple[np.ndarray, int, str, np.ndarray | None]:
+    if params.stem == "all" or params.separation_backend == "none":
+        audio, sr = librosa.load(audio_path, sr=44100, mono=True)
+        if progress_cb:
+            progress_cb({"fraction": 1.0, "completed_units": 1, "total_units": 1, "detail": "loaded full mix"})
+        return _mono(audio), int(sr), "loaded full mix", None
+
+    cache_path = _stem_cache_path(audio_path, params)
+    context_cache = _context_cache_path(cache_path)
+    if params.use_disk_cache and cache_path.exists():
+        audio, sr = sf.read(cache_path, dtype="float32", always_2d=False)
+        context = None
+        if context_cache.exists():
+            context_audio, context_sr = sf.read(context_cache, dtype="float32", always_2d=False)
+            context = _pad_or_trim(_mono(context_audio), len(_mono(audio))) if int(context_sr) == int(sr) else _mono(librosa.resample(_mono(context_audio), orig_sr=int(context_sr), target_sr=int(sr)))
+        if progress_cb:
+            progress_cb({"fraction": 1.0, "completed_units": 1, "total_units": 1, "detail": f"{params.stem} disk-cache hit"})
+        return np.asarray(audio, dtype=np.float32), int(sr), f"{params.stem} disk-cache hit", context
+
+    context: np.ndarray | None = None
+    if params.separation_backend == "spleeter":
+        try:
+            audio, sr, context, detail = _extract_spleeter_separation(audio_path, params, progress_cb=progress_cb)
+        except Exception as exc:
+            if not params.allow_backend_fallback:
+                raise
+            if progress_cb:
+                progress_cb({"fraction": 0.0, "completed_units": 0, "total_units": 1, "detail": f"Spleeter unavailable; falling back to Demucs: {exc}"})
+            audio, sr, context, demucs_detail = _extract_demucs_separation(audio_path, params, progress_cb=progress_cb)
+            detail = f"Spleeter unavailable ({exc}); fallback {demucs_detail}"
+    elif params.separation_backend == "demucs":
+        audio, sr, context, detail = _extract_demucs_separation(audio_path, params, progress_cb=progress_cb)
+    else:
+        raise ValueError(f"Unsupported separation backend: {params.separation_backend}")
+
     if params.use_disk_cache:
-        cache_path = _stem_cache_path(audio_path, params)
         _write_audio(cache_path, audio, sr, subtype="PCM_16")
+        if context is not None:
+            _write_audio(context_cache, context, sr, subtype="PCM_16")
         detail += " · cached"
-    return audio, sr, detail
+    return audio, sr, detail, context
 
 
 
@@ -605,7 +760,7 @@ def run_extraction_pipeline(
                 work_total=event.get("total_units"),
             )
 
-        raw_stem_audio, stem_sr, stem_detail = _load_or_extract_stem(audio_path, params, progress_cb=_stem_progress)
+        raw_stem_audio, stem_sr, stem_detail, separated_context = _load_or_extract_separation(audio_path, params, progress_cb=_stem_progress)
         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)
@@ -613,8 +768,9 @@ def run_extraction_pipeline(
         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")
+        context_bed = np.zeros_like(source_audio) if params.stem == "all" else (_pad_or_trim(separated_context, length) / gain if separated_context is not None else (source_audio - stem_audio)).astype(np.float32)
+        context_detail = "full mix" if params.stem == "all" else ("separated non-target stems" if separated_context is not None else "residual non-target stems")
+        stage.detail = stem_detail + f" · reproduction uses {context_detail}"
         _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")

requirements-spleeter.txt

@@ -0,0 +1,3 @@
+# Optional Spleeter backend.
+# Install in a dedicated Python environment compatible with Spleeter/TensorFlow.
+spleeter

scripts/test_selected_export_card_actions.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Smoke-test card selection semantics, selected-only export, draw-next, and immediate clip edits."""
+from __future__ import annotations
+
+import io
+import json
+import sys
+import time
+import zipfile
+from pathlib import Path
+from urllib.parse import quote
+
+import soundfile as sf
+from fastapi.testclient import TestClient
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from app import app  # noqa: E402
+from synth_generator import generate_test_song  # noqa: E402
+
+
+def wait_for_job(client: TestClient, job_id: str) -> dict:
+    for _ in range(120):
+        payload = client.get(f"/api/jobs/{job_id}").json()
+        if payload["status"] in {"complete", "error"}:
+            return payload
+        time.sleep(0.1)
+    raise TimeoutError(job_id)
+
+
+def main() -> int:
+    song = generate_test_song(pattern_name="funk", bars=1, bpm=124, add_bass=False)
+    buf = io.BytesIO()
+    sf.write(buf, song.drums_only, song.sr, format="WAV")
+    buf.seek(0)
+
+    client = TestClient(app)
+    response = client.post(
+        "/api/jobs",
+        files={"file": ("cards.wav", buf, "audio/wav")},
+        data={"params": json.dumps({"stem": "all", "clustering_mode": "online_preview", "target_min": 3, "target_max": 10})},
+    )
+    response.raise_for_status()
+    job_id = response.json()["id"]
+    job = wait_for_job(client, job_id)
+    assert job["status"] == "complete", job.get("error")
+    samples = job["result"]["samples"]
+    assert samples, "expected at least one sample"
+    labels = [sample["label"] for sample in samples[: min(2, len(samples))]]
+
+    selected = client.post(f"/api/jobs/{job_id}/export-selected", json={"labels": labels})
+    selected.raise_for_status()
+    selected_payload = selected.json()["export"]
+    assert selected_payload["kind"] == "selected-sample-export"
+    assert selected_payload["selected_labels"] == sorted(labels)
+    archive_response = client.get(selected_payload["file_urls"]["archive"])
+    archive_response.raise_for_status()
+    with zipfile.ZipFile(io.BytesIO(archive_response.content)) as zf:
+      names = zf.namelist()
+      assert any(name.endswith(".wav") for name in names), names
+
+    label = labels[0]
+    draw = client.post(f"/api/jobs/{job_id}/samples/{quote(label, safe='')}/draw", json={})
+    draw.raise_for_status()
+    drawn = draw.json()["sample"]
+    assert drawn["label"] == label
+    assert drawn["url"]
+    drawn_audio = client.get(drawn["url"])
+    drawn_audio.raise_for_status()
+    assert drawn_audio.content[:4] == b"RIFF"
+
+    edit = client.post(f"/api/jobs/{job_id}/samples/{quote(label, safe='')}/edit", json={"start_offset_ms": 5, "tail_offset_ms": 30})
+    edit.raise_for_status()
+    edited = edit.json()["sample"]
+    assert edited["label"] == label
+    assert "overrides/hits" in edited["file"], edited
+    edited_audio = client.get(edited["url"])
+    edited_audio.raise_for_status()
+    assert edited_audio.content[:4] == b"RIFF"
+
+    print(json.dumps({
+        "status": "ok",
+        "job_id": job_id,
+        "selected_labels": labels,
+        "drawn_representative_hit_index": drawn["representative_hit_index"],
+        "edited_file": edited["file"],
+        "archive": selected_payload["files"]["archive"],
+    }, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

supervised_export.py

@@ -178,6 +178,9 @@ def export_supervised_state(
     synthesize: bool = True,
     quantize: bool | None = None,
     subdivision: int | None = None,
+    selected_labels: set[str] | list[str] | None = None,
+    export_dir_name: str = "supervised",
+    kind: str = "supervised-export",
 ) -> dict[str, Any]:
     """Create edited artifacts from ``supervision_state.json``.
 
@@ -188,13 +191,22 @@ def export_supervised_state(
     state = load_or_create_state(job_id, out)
     recompute_scores(state)
 
-    export_dir = out / "supervised"
+    safe_export_dir_name = "".join(ch if ch.isalnum() or ch in {"-", "_"} else "_" for ch in str(export_dir_name or "supervised")).strip("_") or "supervised"
+    export_prefix = safe_export_dir_name
+    selected_label_set = {str(label) for label in selected_labels} if selected_labels else None
+
+    export_dir = out / safe_export_dir_name
     if export_dir.exists():
         shutil.rmtree(export_dir)
     samples_dir = export_dir / "samples"
     samples_dir.mkdir(parents=True, exist_ok=True)
 
     clusters = _state_to_clusters(out, state)
+    if selected_label_set is not None:
+        clusters = [cluster for cluster in clusters if cluster.label in selected_label_set]
+        missing = sorted(selected_label_set - {cluster.label for cluster in clusters})
+        if missing:
+            raise ValueError(f"Selected sample label(s) not found in current state: {', '.join(missing)}")
     bpm = float(manifest.get("bpm") or 120.0)
     sr = int(manifest.get("sample_rate") or 44100)
     params = manifest.get("params") or {}
@@ -238,13 +250,13 @@ def export_supervised_state(
     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"
+    files["midi"] = f"{export_prefix}/reconstruction.mid"
+    files["target_reconstruction"] = f"{export_prefix}/target_reconstruction.wav"
+    files["reconstruction"] = f"{export_prefix}/reconstruction.wav"
 
     for cluster in sorted(clusters, key=lambda item: item.count, reverse=True):
         best = cluster.best_hit
-        sample_file = f"supervised/samples/{cluster.label}.wav"
+        sample_file = f"{export_prefix}/samples/{cluster.label}.wav"
         best.save(str(out / sample_file))
         quality = sample_quality_score(best.audio, best.sr, cluster.label.rsplit("_", 1)[0])
         samples.append(
@@ -262,7 +274,7 @@ 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")
+            _write_audio(out / f"{export_prefix}/samples/{cluster.label}__synth.wav", cluster.synthesized, sr, subtype="PCM_24")
 
     archive_tmp = build_archive(
         clusters,
@@ -272,7 +284,7 @@ def export_supervised_state(
         rendered_audio=rendered,
         target_rendered_audio=target_rendered,
     )
-    archive_rel = "supervised/sample-pack.zip"
+    archive_rel = f"{export_prefix}/sample-pack.zip"
     shutil.copyfile(archive_tmp, out / archive_rel)
     try:
         os.unlink(archive_tmp)
@@ -282,7 +294,7 @@ def export_supervised_state(
 
     active_hits = [hit for hit in state.get("hits", {}).values() if not hit.get("suppressed")]
     export_manifest = {
-        "kind": "supervised-export",
+        "kind": kind,
         "job_id": job_id,
         "created_at": now(),
         "duration_sec": round(time.perf_counter() - started, 6),
@@ -293,6 +305,7 @@ def export_supervised_state(
         "hit_count": len(active_hits),
         "suppressed_hit_count": sum(1 for hit in state.get("hits", {}).values() if hit.get("suppressed")),
         "cluster_count": len(clusters),
+        "selected_labels": sorted(selected_label_set) if selected_label_set is not None else None,
         "quantize_midi": bool(quantize),
         "subdivision": int(subdivision),
         "samples": samples,
@@ -308,7 +321,8 @@ def export_supervised_state(
     state.setdefault("exports", []).append(
         {
             "created_at": export_manifest["created_at"],
-            "path": "supervised/manifest.json",
+            "path": f"{export_prefix}/manifest.json",
+            "kind": kind,
             "hit_count": export_manifest["hit_count"],
             "cluster_count": export_manifest["cluster_count"],
             "suppressed_hit_count": export_manifest["suppressed_hit_count"],
@@ -333,3 +347,26 @@ def export_supervised_state(
     state_path.write_text(json.dumps(state, indent=2, sort_keys=True), encoding="utf-8")
 
     return export_manifest
+
+
+def export_selected_samples(
+    output_dir: str | os.PathLike[str],
+    job_id: str,
+    *,
+    selected_labels: list[str] | set[str],
+    synthesize: bool = True,
+    quantize: bool | None = None,
+    subdivision: int | None = None,
+) -> dict[str, Any]:
+    if not selected_labels:
+        raise ValueError("selected_labels must contain at least one sample label")
+    return export_supervised_state(
+        output_dir,
+        job_id,
+        synthesize=synthesize,
+        quantize=quantize,
+        subdivision=subdivision,
+        selected_labels=set(map(str, selected_labels)),
+        export_dir_name="selected",
+        kind="selected-sample-export",
+    )

supervised_state.py

@@ -904,3 +904,117 @@ def public_state(state: dict[str, Any], url_for: Callable[[str], str] | None = N
         "suggestions": open_suggestions[:50],
         "review_queue": review_queue(state, review_limit),
     }
+
+
+def pin_representative(output_dir: str | Path, job_id: str, cluster_id: str, hit_id: str, source: str = "user") -> dict[str, Any]:
+    """Persistently choose a representative hit for a cluster/card."""
+    state = load_or_create_state(job_id, output_dir)
+    clusters = state.get("clusters", {})
+    hits = state.get("hits", {})
+    if cluster_id not in clusters:
+        raise KeyError(f"Unknown cluster: {cluster_id}")
+    if hit_id not in hits:
+        raise KeyError(f"Unknown hit: {hit_id}")
+    if hit_id not in clusters[cluster_id].get("hit_ids", []):
+        raise ValueError(f"Hit {hit_id} is not a member of {cluster_id}")
+    _push_undo(state)
+    for hid in clusters[cluster_id].get("hit_ids", []):
+        if hid in hits:
+            hits[hid]["is_representative"] = (hid == hit_id)
+    clusters[cluster_id]["representative_hit_id"] = hit_id
+    hits[hit_id]["favorite"] = True
+    hits[hit_id]["review_status"] = "favorite"
+    hits[hit_id]["explicit"] = True
+    _constraint(state, "pin-representative", {"hit_id": hit_id, "cluster_id": cluster_id}, source=source)
+    _event(state, "cluster.representative_pinned", {"hit_id": hit_id, "cluster_id": cluster_id}, source=source)
+    recompute_scores(state)
+    return _write_state(output_dir, state)
+
+
+def draw_next_representative(output_dir: str | Path, job_id: str, cluster_id: str, source: str = "user") -> dict[str, Any]:
+    """Cycle a cluster/card to the next available non-suppressed candidate."""
+    state = load_or_create_state(job_id, output_dir)
+    clusters = state.get("clusters", {})
+    hits = state.get("hits", {})
+    if cluster_id not in clusters:
+        raise KeyError(f"Unknown cluster: {cluster_id}")
+    cluster = clusters[cluster_id]
+    active_ids = [hid for hid in cluster.get("hit_ids", []) if hid in hits and not hits[hid].get("suppressed")]
+    if not active_ids:
+        raise ValueError(f"Cluster {cluster_id} has no active hits")
+    current = cluster.get("representative_hit_id")
+    if current in active_ids:
+        next_id = active_ids[(active_ids.index(current) + 1) % len(active_ids)]
+    else:
+        next_id = active_ids[0]
+    return pin_representative(output_dir, job_id, cluster_id, next_id, source=source)
+
+
+def edit_hit_timing(
+    output_dir: str | Path,
+    job_id: str,
+    hit_id: str,
+    *,
+    start_offset_ms: float = 0.0,
+    tail_offset_ms: float = 0.0,
+    source: str = "user",
+) -> dict[str, Any]:
+    """Rewrite one hit preview from stem.wav and persist the timing edit.
+
+    ``start_offset_ms`` trims from the front when positive and extends earlier when
+    negative. ``tail_offset_ms`` extends when positive and trims the tail when
+    negative. The selected hit's file path is replaced so cards and supervised
+    exports immediately use the edited audio.
+    """
+    import numpy as np
+    import soundfile as sf
+    import librosa
+
+    out = Path(output_dir)
+    state = load_or_create_state(job_id, out)
+    hits = state.get("hits", {})
+    if hit_id not in hits:
+        raise KeyError(f"Unknown hit: {hit_id}")
+    hit = hits[hit_id]
+    stem_path = out / "stem.wav"
+    if not stem_path.exists():
+        raise FileNotFoundError("stem.wav is required for timing edits")
+    audio, sr = sf.read(stem_path, dtype="float32", always_2d=False)
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+    audio = np.asarray(audio, dtype=np.float32)
+
+    original_onset = _safe_float(hit.get("onset_sec"))
+    original_duration = max(0.02, _safe_float(hit.get("duration_ms"), 100.0) / 1000.0)
+    start_offset = _safe_float(start_offset_ms) / 1000.0
+    tail_offset = _safe_float(tail_offset_ms) / 1000.0
+    new_onset = max(0.0, original_onset + start_offset)
+    new_duration = max(0.02, original_duration - start_offset + tail_offset)
+    start = max(0, int(round(new_onset * sr)))
+    end = min(len(audio), start + int(round(new_duration * sr)))
+    if end <= start:
+        raise ValueError("Edited sample range is outside the available stem audio")
+    segment = audio[start:end].copy()
+    fade_len = min(int(0.003 * sr), len(segment) // 4)
+    if fade_len > 0:
+        segment[-fade_len:] *= np.linspace(1, 0, fade_len)
+    rms = float(np.sqrt(np.mean(segment**2))) if len(segment) else 0.0
+    spectral_centroid = float(librosa.feature.spectral_centroid(y=segment, sr=sr).mean()) if len(segment) >= 32 else 0.0
+    safe_label = _safe_file_component(hit.get("label") or "edited")
+    rel_file = f"overrides/hits/hit_{_safe_int(hit.get('index')):05d}_{safe_label}_edited.wav"
+    full_path = out / rel_file
+    full_path.parent.mkdir(parents=True, exist_ok=True)
+    sf.write(full_path, segment, sr, subtype="PCM_24")
+
+    _push_undo(state)
+    hit["onset_sec"] = round(new_onset, 6)
+    hit["duration_ms"] = round((len(segment) / sr) * 1000.0, 1)
+    hit["rms_energy"] = round(rms, 6)
+    hit["spectral_centroid_hz"] = round(spectral_centroid, 1)
+    hit["file"] = rel_file
+    hit["explicit"] = True
+    hit["review_status"] = "accepted"
+    _constraint(state, "edit-hit-timing", {"hit_id": hit_id, "start_offset_ms": round(_safe_float(start_offset_ms), 3), "tail_offset_ms": round(_safe_float(tail_offset_ms), 3)}, source=source)
+    _event(state, "hit.timing_edited", {"hit_id": hit_id, "file": rel_file, "onset_sec": hit["onset_sec"], "duration_ms": hit["duration_ms"]}, source=source)
+    recompute_scores(state)
+    return _write_state(out, state)

web/app.js

@@ -1,10 +1,10 @@
 const $ = (id) => document.getElementById(id);
 
 const fields = [
-  "stem", "demucs_model", "clustering_mode", "demucs_shifts", "demucs_overlap", "onset_mode", "onset_delta",
+  "stem", "separation_backend", "spleeter_model", "demucs_model", "clustering_mode", "demucs_shifts", "demucs_overlap", "onset_mode", "onset_delta",
   "energy_threshold_db", "pre_pad", "min_dur", "max_dur", "min_gap", "ncc_threshold",
   "attack_ms", "mel_threshold", "linkage", "target_min", "target_max", "subdivision",
-  "synthesize", "quantize_midi", "auto_tune", "use_disk_cache"
+  "synthesize", "quantize_midi", "auto_tune", "use_disk_cache", "allow_backend_fallback"
 ];
 
 let config = null;
@@ -27,6 +27,9 @@ let autoRunToken = 0;
 let dismissedSampleKeys = new Set();
 let extraDrawnSamples = [];
 let sampleEdits = new Map();
+let selectedSampleKeys = new Set();
+let sampleOverrides = new Map();
+let userChangedSampleSelection = false;
 let waveZoom = 1;
 let waveOffset = 0;
 
@@ -353,6 +356,8 @@ function setSelectOptions(select, values, labels = null) {
 }
 
 function populateConfig() {
+  if ($("separation_backend")) setSelectOptions($("separation_backend"), config.separation_backends ?? ["spleeter", "demucs", "none"], { spleeter: "Spleeter (default)", demucs: "Demucs", none: "No separation / full mix" });
+  if ($("spleeter_model")) setSelectOptions($("spleeter_model"), config.spleeter_models ?? ["spleeter:4stems"]);
   setSelectOptions($("demucs_model"), config.demucs_models);
   setSelectOptions($("clustering_mode"), Object.keys(config.clustering_modes ?? { batch_quality: "", online_preview: "" }), config.clustering_modes);
   const defaults = config.defaults;
@@ -367,13 +372,23 @@ function populateConfig() {
 }
 
 function updateStemOptions() {
-  const model = $("demucs_model").value || config.defaults.demucs_model;
-  const stems = config.demucs_stems[model] ?? ["drums", "bass", "other", "vocals", "all"];
+  const backend = $("separation_backend")?.value || config.defaults.separation_backend || "spleeter";
+  let stems = ["drums", "bass", "other", "vocals", "all"];
+  if (backend === "spleeter") {
+    const model = $("spleeter_model")?.value || config.defaults.spleeter_model || "spleeter:4stems";
+    stems = config.spleeter_stems?.[model] ?? stems;
+  } else if (backend === "demucs") {
+    const model = $("demucs_model")?.value || config.defaults.demucs_model;
+    stems = config.demucs_stems?.[model] ?? stems;
+  } else {
+    stems = ["all"];
+  }
   const current = $("stem").value || config.defaults.stem;
   setSelectOptions($("stem"), stems);
   $("stem").value = stems.includes(current) ? current : stems[0];
 }
 
+
 function collectParams() {
   const params = {};
   const defaults = config?.defaults ?? {};
@@ -701,11 +716,30 @@ function sampleType(sample) {
 
 function visibleSamples(result) {
   const base = [...(result?.samples ?? []), ...extraDrawnSamples];
-  return base
+  const merged = base.map((sample) => {
+    const key = sampleKey(sample);
+    return { ...sample, ...(sampleOverrides.get(key) || {}) };
+  });
+  return merged
     .map((sample) => ({ ...sample, _key: sampleKey(sample), _type: sampleType(sample), _edit: sampleEdits.get(sampleKey(sample)) || { startMs: 0, tailMs: 0 } }))
     .filter((sample) => !dismissedSampleKeys.has(sample._key));
 }
 
+function ensureSelectionForSamples(samples) {
+  if (userChangedSampleSelection) return;
+  for (const sample of samples) {
+    if (!sample._key) continue;
+    if (!dismissedSampleKeys.has(sample._key) && !selectedSampleKeys.has(sample._key) && sample._autoSelected !== false) {
+      selectedSampleKeys.add(sample._key);
+    }
+  }
+}
+
+function selectedVisibleSamples(samples = visibleSamples(lastResult || { samples: [] })) {
+  return samples.filter((sample) => selectedSampleKeys.has(sample._key));
+}
+
+
 function groupedSamples(samples) {
   const preferred = ["kick", "snare", "hihat", "cymbal", "tom", "perc", "other"];
   const map = new Map();
@@ -721,14 +755,38 @@ function groupedSamples(samples) {
   });
 }
 
-function updateSelectedExportCount(count) {
+function updateSelectedExportCount(_count = null) {
+  const visible = visibleSamples(lastResult || { samples: [] });
+  const selected = selectedVisibleSamples(visible);
+  const count = selected.length;
   const text = `${count} Selected`;
   if ($("selectedCountTop")) $("selectedCountTop").textContent = `(${count})`;
   if ($("selectedCountBottom")) $("selectedCountBottom").textContent = text;
-  if ($("exportSelectedButton")) $("exportSelectedButton").disabled = count === 0 || !lastResult;
+  if ($("exportSelectedButton")) $("exportSelectedButton").disabled = count === 0 || !activeJobId;
   if ($("exportAllButton")) $("exportAllButton").disabled = !lastResult;
 }
 
+function setSampleSelected(sample, selected) {
+  userChangedSampleSelection = true;
+  const key = sample._key || sampleKey(sample);
+  if (selected) selectedSampleKeys.add(key);
+  else selectedSampleKeys.delete(key);
+  updateSelectedExportCount();
+}
+
+function selectAllVisibleSamples() {
+  userChangedSampleSelection = true;
+  for (const sample of visibleSamples(lastResult || { samples: [] })) selectedSampleKeys.add(sample._key);
+  renderSamples(lastResult || { samples: [] });
+}
+
+function clearSampleSelection() {
+  userChangedSampleSelection = true;
+  selectedSampleKeys.clear();
+  renderSamples(lastResult || { samples: [] });
+}
+
+
 function updateControlOutputs() {
   const pct = Math.round((Number($("onset_delta")?.value || 0) / 0.35) * 100);
   if ($("sensitivityOutput")) $("sensitivityOutput").textContent = Number.isFinite(pct) ? `${pct}%` : "Auto";
@@ -739,7 +797,9 @@ function updateControlOutputs() {
 }
 
 async function dismissSample(sample) {
-  dismissedSampleKeys.add(sample._key || sampleKey(sample));
+  const key = sample._key || sampleKey(sample);
+  dismissedSampleKeys.add(key);
+  selectedSampleKeys.delete(key);
   renderSamples(lastResult || { samples: [] });
   const index = sample.representative_hit_index;
   if (activeJobId && index !== undefined && index !== null) {
@@ -751,32 +811,29 @@ async function dismissSample(sample) {
   }
 }
 
-function drawAnotherSample(type) {
-  const used = new Set([...(lastResult?.samples ?? []), ...extraDrawnSamples].map((sample) => Number(sample.representative_hit_index)).filter(Number.isFinite));
-  const hit = (lastResult?.hits ?? [])
-    .filter((item) => sampleType(item) === type || sampleType({ classification: item.label }) === type)
-    .filter((item) => !used.has(Number(item.index)))
-    .sort((a, b) => Number(b.rms_energy || 0) - Number(a.rms_energy || 0))[0];
-  if (!hit) {
-    showError("No more candidates", new Error(`No additional ${type} candidates are available yet.`), "Try adding a missing onset on the waveform or rerun with higher sensitivity.");
+async function drawAnotherSample(type, sample = null) {
+  if (!activeJobId) {
+    showError("No active extraction", new Error("Run extraction before drawing replacement cards."));
     return;
   }
-  extraDrawnSamples.push({
-    label: `${type}_draw_${hit.index}`,
-    classification: type,
-    hits: 1,
-    score: "candidate",
-    duration_ms: hit.duration_ms,
-    first_onset_sec: hit.onset_sec,
-    representative_hit_index: hit.index,
-    cluster_id: hit.cluster_id,
-    file: hit.file,
-    url: hit.url,
-    _drawn: true,
-  });
-  renderSamples(lastResult || { samples: [] });
+  const sourceSample = sample || visibleSamples(lastResult || { samples: [] }).find((item) => item._type === type);
+  if (!sourceSample?.label) {
+    showError("No card to redraw", new Error(`No ${type} card exists yet. Try a higher sensitivity or force a missing onset.`));
+    return;
+  }
+  try {
+    const payload = await jsonApi(`/api/jobs/${encodeURIComponent(activeJobId)}/samples/${encodeURIComponent(sourceSample.label)}/draw`, {});
+    const key = sampleKey(sourceSample);
+    sampleOverrides.set(key, { ...payload.sample, _autoSelected: true });
+    selectedSampleKeys.add(key);
+    renderSupervisionState(payload.state);
+    renderSamples(lastResult || { samples: [] });
+  } catch (error) {
+    showError("No more candidates", error, "Try adding a missing onset on the waveform or rerun with higher sensitivity.");
+  }
 }
 
+
 function updateSampleEdit(sample, patch) {
   const key = sample._key || sampleKey(sample);
   const current = sampleEdits.get(key) || { startMs: 0, tailMs: 0 };
@@ -787,25 +844,39 @@ function updateSampleEdit(sample, patch) {
   renderSamples(lastResult || { samples: [] });
 }
 
+async function persistSampleEdit(sample, patch) {
+  if (!activeJobId || !sample?.label) return;
+  const key = sample._key || sampleKey(sample);
+  const current = sampleEdits.get(key) || { startMs: 0, tailMs: 0 };
+  const next = {
+    startMs: Math.max(-120, Math.min(250, Number(current.startMs || 0) + Number(patch.startMs || 0))),
+    tailMs: Math.max(-250, Math.min(500, Number(current.tailMs || 0) + Number(patch.tailMs || 0))),
+  };
+  sampleEdits.set(key, next);
+  const payload = await jsonApi(`/api/jobs/${encodeURIComponent(activeJobId)}/samples/${encodeURIComponent(sample.label)}/edit`, {
+    start_offset_ms: next.startMs,
+    tail_offset_ms: next.tailMs,
+  });
+  sampleOverrides.set(key, { ...payload.sample, _autoSelected: true });
+  selectedSampleKeys.add(key);
+  sampleEdits.set(key, { startMs: 0, tailMs: 0 });
+  renderSupervisionState(payload.state);
+  renderSamples(lastResult || { samples: [] });
+}
+
 async function saveSampleEdit(sample) {
   if (!activeJobId) return;
   const edit = sampleEdits.get(sample._key || sampleKey(sample));
   if (!edit) return;
-  const start = Math.max(0, Number(sample.first_onset_sec || 0) + Number(edit.startMs || 0) / 1000);
-  const duration = Math.max(25, Number(sample.duration_ms || 100) - Number(edit.startMs || 0) + Number(edit.tailMs || 0));
-  const state = await jsonApi(`/api/jobs/${encodeURIComponent(activeJobId)}/hits/force-onset`, {
-    onset_sec: start,
-    duration_ms: duration,
-    label: sample.classification || sample._type || "hit",
-  });
-  renderSupervisionState(state);
-  showError("Edited clip saved", new Error("A forced hit was added from the adjusted card."), "Use Export edited pack to render the edited state.");
+  await persistSampleEdit(sample, { startMs: 0, tailMs: 0 });
 }
 
+
 function renderSamples(result) {
   const samples = visibleSamples(result);
+  ensureSelectionForSamples(samples);
   if ($("sampleCountLabel")) $("sampleCountLabel").textContent = `(${samples.length})`;
-  updateSelectedExportCount(samples.length);
+  updateSelectedExportCount();
 
   const grid = $("samplesGrid");
   if (grid) {
@@ -824,7 +895,8 @@ function renderSamples(result) {
             const edit = sample._edit || { startMs: 0, tailMs: 0 };
             const editLabel = (edit.startMs || edit.tailMs) ? ` · edit ${edit.startMs >= 0 ? "+" : ""}${edit.startMs}ms/${edit.tailMs >= 0 ? "+" : ""}${edit.tailMs}ms` : "";
             return `
-              <article class="sample-card ${absoluteIndex === selectedSampleIndex ? "selected" : ""}" style="--card-color: ${esc(color)}" data-sample-card="${absoluteIndex}">
+              <article class="sample-card ${absoluteIndex === selectedSampleIndex ? "selected" : ""} ${selectedSampleKeys.has(sample._key) ? "checked" : ""}" style="--card-color: ${esc(color)}" data-sample-card="${absoluteIndex}">
+                <label class="sample-select" title="Include in Export Selected"><input type="checkbox" data-sample-select="${absoluteIndex}" ${selectedSampleKeys.has(sample._key) ? "checked" : ""} /> <span></span></label>
                 <button class="sample-play-zone" type="button" data-sample-audition="${absoluteIndex}">
                   <canvas class="sample-wave" data-wave-url="${esc(sample.url)}" data-wave-color="${esc(color)}"></canvas>
                   <span class="sample-card-footer">
@@ -833,10 +905,11 @@ function renderSamples(result) {
                   </span>
                 </button>
                 <div class="sample-card-actions">
-                  <button type="button" data-sample-dismiss="${absoluteIndex}">Dismiss</button>
-                  <button type="button" data-sample-trim-start="${absoluteIndex}">Trim start</button>
-                  <button type="button" data-sample-extend-tail="${absoluteIndex}">Extend tail</button>
-                  <button type="button" data-sample-save-edit="${absoluteIndex}" ${edit.startMs || edit.tailMs ? "" : "disabled"}>Save edit</button>
+                  <button type="button" data-sample-dismiss="${absoluteIndex}" title="Dismiss">Dismiss</button>
+                  <button type="button" data-sample-draw="${absoluteIndex}" title="Draw another">Draw</button>
+                  <button type="button" data-sample-trim-start="${absoluteIndex}" title="Trim start">Trim start</button>
+                  <button type="button" data-sample-extend-tail="${absoluteIndex}" title="Extend tail">Extend tail</button>
+                  <button type="button" data-sample-save-edit="${absoluteIndex}" title="Save timing edit" ${edit.startMs || edit.tailMs ? "" : "disabled"}>Save edit</button>
                 </div>
               </article>
             `;
@@ -853,6 +926,14 @@ function renderSamples(result) {
         renderSamples(result);
       });
     }
+    for (const input of grid.querySelectorAll("[data-sample-select]")) {
+      input.addEventListener("click", (event) => event.stopPropagation());
+      input.addEventListener("change", () => {
+        const sample = samples[Number(input.dataset.sampleSelect)];
+        setSampleSelected(sample, input.checked);
+        renderSamples(result);
+      });
+    }
     for (const button of grid.querySelectorAll("[data-sample-dismiss]")) {
       button.addEventListener("click", (event) => {
         event.stopPropagation();
@@ -863,19 +944,26 @@ function renderSamples(result) {
     for (const button of grid.querySelectorAll("[data-draw-type]")) {
       button.addEventListener("click", (event) => {
         event.stopPropagation();
-        drawAnotherSample(button.dataset.drawType);
+        drawAnotherSample(button.dataset.drawType).catch((error) => showError("Could not draw another sample", error));
+      });
+    }
+    for (const button of grid.querySelectorAll("[data-sample-draw]")) {
+      button.addEventListener("click", (event) => {
+        event.stopPropagation();
+        const sample = samples[Number(button.dataset.sampleDraw)];
+        drawAnotherSample(sample._type, sample).catch((error) => showError("Could not draw another sample", error));
       });
     }
     for (const button of grid.querySelectorAll("[data-sample-trim-start]")) {
       button.addEventListener("click", (event) => {
         event.stopPropagation();
-        updateSampleEdit(samples[Number(button.dataset.sampleTrimStart)], { startMs: 10 });
+        persistSampleEdit(samples[Number(button.dataset.sampleTrimStart)], { startMs: 10 }).catch((error) => showError("Could not trim sample", error));
       });
     }
     for (const button of grid.querySelectorAll("[data-sample-extend-tail]")) {
       button.addEventListener("click", (event) => {
         event.stopPropagation();
-        updateSampleEdit(samples[Number(button.dataset.sampleExtendTail)], { tailMs: 20 });
+        persistSampleEdit(samples[Number(button.dataset.sampleExtendTail)], { tailMs: 20 }).catch((error) => showError("Could not extend sample", error));
       });
     }
     for (const button of grid.querySelectorAll("[data-sample-save-edit]")) {
@@ -1341,6 +1429,9 @@ function clearRunViews() {
   dismissedSampleKeys = new Set();
   extraDrawnSamples = [];
   sampleEdits = new Map();
+  selectedSampleKeys = new Set();
+  sampleOverrides = new Map();
+  userChangedSampleSelection = false;
   $("downloads").innerHTML = "";
   $("editedDownloads").innerHTML = "";
   $("supervisionSummary").textContent = "No interactive state loaded.";
@@ -1422,10 +1513,14 @@ async function boot() {
 }
 
 $("dismissErrorButton").addEventListener("click", clearError);
+if ($("separation_backend")) $("separation_backend").addEventListener("change", updateStemOptions);
+if ($("spleeter_model")) $("spleeter_model").addEventListener("change", updateStemOptions);
 $("demucs_model").addEventListener("change", updateStemOptions);
 $("fileInput").addEventListener("change", (event) => setFile(event.target.files?.[0] ?? null));
 $("runButton").addEventListener("click", () => runExtraction({ automatic: false }));
 $("usePreviewButton").addEventListener("click", () => {
+  $("separation_backend").value = "none";
+  updateStemOptions();
   $("stem").value = "all";
   $("clustering_mode").value = "online_preview";
   $("demucs_shifts").value = 0;
@@ -1436,6 +1531,8 @@ $("usePreviewButton").addEventListener("click", () => {
   $("resultSummary").textContent = "Fast preview preset applied: full mix, online grouping, no Demucs shifts.";
 });
 $("useQualityButton").addEventListener("click", () => {
+  $("separation_backend").value = "demucs";
+  updateStemOptions();
   if (($("stem").value || "") === "all") $("stem").value = "drums";
   $("clustering_mode").value = "batch_quality";
   $("demucs_shifts").value = 1;
@@ -1587,15 +1684,36 @@ for (const button of document.querySelectorAll("[data-zoom-command]")) {
   button.addEventListener("click", () => zoomWaveformAround($("waveform").getBoundingClientRect().left + $("waveform").getBoundingClientRect().width / 2, button.dataset.zoomCommand === "in" ? 1.35 : 1 / 1.35));
 }
 if ($("openToolsButton")) $("openToolsButton").addEventListener("click", () => { const drawer = $("toolsDrawer"); drawer.hidden = !drawer.hidden; });
-if ($("selectAllSamplesButton")) $("selectAllSamplesButton").addEventListener("click", () => updateSelectedExportCount(visibleSamples(lastResult || { samples: [] }).length));
-if ($("clearSelectionButton")) $("clearSelectionButton").addEventListener("click", () => updateSelectedExportCount(0));
+if ($("selectAllSamplesButton")) $("selectAllSamplesButton").addEventListener("click", selectAllVisibleSamples);
+if ($("clearSelectionButton")) $("clearSelectionButton").addEventListener("click", clearSampleSelection);
 function clickArchiveDownload() {
+  const url = lastResult?.file_urls?.archive;
+  if (url) { window.location.href = url; return; }
   const link = $("downloads")?.querySelector('a[href*="sample-pack"], a[download], a');
   if (link) link.click();
   else showError("Nothing to export yet", new Error("Run extraction first; sample-pack ZIP appears when processing completes."));
 }
+
+async function exportSelectedSamples() {
+  if (!activeJobId) {
+    showError("Nothing selected", new Error("Run extraction first."));
+    return;
+  }
+  const samples = selectedVisibleSamples();
+  const labels = samples.map((sample) => sample.label).filter(Boolean);
+  if (!labels.length) {
+    showError("Nothing selected", new Error("Select at least one sample card."));
+    return;
+  }
+  const payload = await jsonApi(`/api/jobs/${encodeURIComponent(activeJobId)}/export-selected`, { labels, synthesize: true });
+  renderEditedExport(payload.export);
+  if (payload.state) renderSupervisionState(payload.state);
+  const archiveUrl = payload.export?.file_urls?.archive;
+  if (archiveUrl) window.location.href = archiveUrl;
+}
 if ($("exportAllButton")) $("exportAllButton").addEventListener("click", clickArchiveDownload);
-if ($("exportSelectedButton")) $("exportSelectedButton").addEventListener("click", clickArchiveDownload);
+if ($("exportSelectedButton")) $("exportSelectedButton").addEventListener("click", () => exportSelectedSamples().catch((error) => showError("Could not export selected samples", error)));
+
 if ($("resetUiButton")) $("resetUiButton").addEventListener("click", () => { populateConfig(); updateControlOutputs(); });
 if ($("groupSimilarToggle")) $("groupSimilarToggle").addEventListener("change", () => { $("clustering_mode").value = $("groupSimilarToggle").checked ? "batch_quality" : "online_preview"; });
 updateControlOutputs();

web/index.html

@@ -142,6 +142,8 @@
           <details class="settings-section advanced-fold">
             <summary>Expert pipeline controls</summary>
             <div class="expert-grid">
+              <label>Separation engine<select id="separation_backend"><option value="spleeter">Spleeter (default)</option><option value="demucs">Demucs</option><option value="none">No separation / full mix</option></select></label>
+              <label>Spleeter model<select id="spleeter_model"></select></label>
               <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>
@@ -161,6 +163,7 @@
               <label><input id="quantize_midi" type="checkbox" /> quantize MIDI</label>
               <label><input id="auto_tune" type="checkbox" checked /> automatic parameter tuning</label>
               <label><input id="use_disk_cache" type="checkbox" /> disk cache stems/source loads</label>
+              <label><input id="allow_backend_fallback" type="checkbox" /> fallback to Demucs if Spleeter is unavailable</label>
             </div>
             <div class="preset-row">
               <button id="usePreviewButton" class="secondary-action" type="button">Fast preview</button>

web/styles.css

@@ -86,6 +86,12 @@ button:disabled { cursor: not-allowed; opacity: .48; }
 .draw-card-button { border: 0; background: transparent; color: #596070; font-size: 20px; line-height: 1; padding: 0 2px; }
 .sample-column-list { min-height: 0; overflow-y: auto; padding: 12px; display: flex; flex-direction: column; gap: 10px; }
 .sample-card { position: relative; border: 1px solid color-mix(in srgb, var(--card-color, var(--purple)) 58%, var(--line)); border-radius: 9px; background: var(--panel); box-shadow: 0 8px 20px rgba(18, 21, 28, .05); overflow: hidden; }
+.sample-card.checked { box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--card-color, var(--purple)) 34%, transparent), 0 8px 20px rgba(18, 21, 28, .05); }
+.sample-select { position: absolute; z-index: 2; top: 8px; left: 8px; width: 18px; height: 18px; display: grid; place-items: center; }
+.sample-select input { position: absolute; opacity: 0; pointer-events: none; }
+.sample-select span { width: 16px; height: 16px; border-radius: 4px; border: 1px solid color-mix(in srgb, var(--card-color, var(--purple)) 70%, var(--line)); background: rgba(255,255,255,.92); box-shadow: 0 1px 2px rgba(18,21,28,.1); }
+.sample-select input:checked + span { border-color: transparent; background: var(--purple); }
+.sample-select input:checked + span::after { content: "✓"; display: block; color: #fff; font-size: 11px; line-height: 16px; text-align: center; font-weight: 800; }
 .sample-card.selected { box-shadow: 0 0 0 2px color-mix(in srgb, var(--card-color, var(--purple)) 24%, transparent), 0 10px 26px rgba(18,21,28,.08); }
 .sample-play-zone { width: 100%; border: 0; background: transparent; padding: 0; text-align: left; }
 .sample-wave { width: 100%; height: 74px; display: block; }
@@ -93,13 +99,14 @@ button:disabled { cursor: not-allowed; opacity: .48; }
 .play-dot { width: 14px; height: 14px; display: inline-grid; place-items: center; color: var(--purple); font-size: 10px; }
 .sample-name { display: block; color: #2c303a; font-size: 13px; line-height: 1.2; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .sample-meta { display: flex; justify-content: space-between; color: var(--muted); font-size: 11px; font-variant-numeric: tabular-nums; }
-.sample-card-actions { display: grid; grid-template-columns: repeat(4,1fr); border-top: 1px solid var(--line); }
+.sample-card-actions { display: grid; grid-template-columns: repeat(5,1fr); border-top: 1px solid var(--line); }
 .sample-card-actions button { height: 30px; border: 0; border-right: 1px solid var(--line); background: #fff; color: #3e4350; font-size: 0; }
 .sample-card-actions button::before { font-size: 13px; }
 .sample-card-actions button:nth-child(1)::before { content: "×"; }
-.sample-card-actions button:nth-child(2)::before { content: "◁"; }
-.sample-card-actions button:nth-child(3)::before { content: "▷"; }
-.sample-card-actions button:nth-child(4)::before { content: "⋯"; }
+.sample-card-actions button:nth-child(2)::before { content: "↻"; }
+.sample-card-actions button:nth-child(3)::before { content: "◁"; }
+.sample-card-actions button:nth-child(4)::before { content: "▷"; }
+.sample-card-actions button:nth-child(5)::before { content: "✓"; }
 .sample-card-actions button:last-child { border-right: 0; }
 .empty-drop-state, .empty { color: var(--muted); padding: 18px; font-size: 13px; }