docs/AUTOMATIC_CARD_FLOW_UI.md

# Automatic card-flow UI

Last updated: 2026-05-12

## Goal

Make the default experience simple enough for non-technical users:

```text
drop audio file
→ waveform appears immediately
→ upload and processing start automatically
→ stem separation/progress is visible on the waveform
→ sample cards appear as soon as they are written
→ user keeps, dismisses, draws, or adjusts cards
→ export pack
```

The advanced workstation and supervised-edit tools still exist, but they are no longer the primary path.

## Implemented

- File selection and whole-page drag/drop now start extraction automatically.
- The primary action is now `Reprocess`, not the required first step.
- Browser-side waveform rendering still happens immediately from the uploaded file.
- Backend jobs now expose `partial_samples` while the export stage is still running.
- The pipeline emits a `sample` progress event every time a representative WAV is written.
- The UI renders partial sample cards before the final manifest is complete.
- Sample cards are grouped into type columns such as kick, snare, hihat, cymbal, tom, perc, and other.
- Each type column has a `Draw` action for trying another candidate of that type.
- Sample cards can be dismissed locally; when semantic state is available, the representative hit is also suppressed as a supervised edit.
- Sample cards include simple trim/extend controls:
  - `Trim start` moves the proposed onset later by 10 ms.
  - `Extend tail` adds 20 ms to the proposed duration.
  - `Save edit` creates a forced hit from the adjusted clip timing so edited exports can include it.
- Waveform navigation supports:
  - pinch/trackpad zoom via browser `ctrl/meta + wheel` gesture,
  - sideways scroll panning via horizontal wheel or shift-wheel,
  - waveform clicks mapped through the current zoom window.
- Automatic parameter tuning runs after source/stem loading and before final onset detection.
- `pretty_midi` is now optional at runtime; when unavailable, a compact fallback drum MIDI writer is used.
- BPM detection now falls back to 120 BPM instead of failing on sparse/empty beat events.
- Representative sample scoring was made lightweight to keep the card flow responsive.

## Automatic tuning

`PipelineParams.auto_tune` defaults to `true`.

When enabled, the pipeline analyzes the separated target stem and chooses:

- `onset_delta` from candidate values based on measured onset counts,
- practical `target_min` / `target_max` group bounds based on measured candidate density.

The chosen values are written back into the effective `params` stored in `manifest.json`.

## Progressive result contract

During extraction, active jobs may contain:

```json
{
  "partial_samples": [
    {
      "label": "kick_0",
      "classification": "kick",
      "representative_hit_index": 12,
      "cluster_id": 0,
      "file": "samples/kick_0.wav",
      "url": "/api/jobs/<id>/files/samples/kick_0.wav"
    }
  ]
}
```

`partial_samples` is best-effort and only contains samples already written to disk. Final authoritative results still live under `result.samples` after job completion.

## Remaining gaps

- Drawn replacement cards are currently candidate previews derived from detected hits; promoting them into final sample-pack representatives should become a first-class backend operation.
- Trim/extend edits create forced hits, but the card itself is not destructively rewritten in-place.
- Browser-level tests should cover automatic drop/upload, progressive cards, waveform zoom/pan, dismiss, draw, and save-edit actions.
- A future local reclustering pass should update groups immediately after dismiss/draw decisions.