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:

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:

{
  "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.